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/Runner-problem-params · L-261017-9b22f2 (#1458)

Louis Choquel70656b666881
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 3a0324fd1..e0382c013 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:f12599081f3831f2ebae7ad28de4e2436c382329d3854286f89152335a63b0b5"
-reviewed_by = "Claude Opus 5.5"
-reviewed_at = "2026-10-18T18:18:07Z"
-rationale = "clean-pass: the merge of the base's review fixes (init's pipelex.config.file_missing, an OSError naming no file as runtime.unexpected, a lone bundle file's tree listed before it is read) into this branch's hosted-run problem reporting; each side had already brought docs/tools/cli/agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md in line with its own changes, and the merged docs carry both."
+digest = "sha256:e697942345f3ef2a23b12d9c8e04b92e534335ce22bdffe43b60b20ac7533b09"
+reviewed_by = "Louis Choquel"
+reviewed_at = "2026-10-19T11:06:53Z"
+rationale = "clean-pass: absorbing Runner-speaks-problem, which carries pipelex#1457's agent CLI reading of the runner's problem, keeps this branch's install refusal reasons (package_name_invalid, manifest_missing) in installed_methods.py; docs/tools/cli/agent-cli.md takes #1457's Markdown wording and keeps this branch's method.identifier_invalid item and params facts, and nothing else is stale."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -132,7 +132,7 @@ rationale = "clean-pass: the merge of the base's review fixes (init's pipelex.co
"pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"
"pipelex/cli/error_handlers.py" = "blob:b0bbfbb058ef764de90c7f1ba09093a7616f43c6"
"pipelex/cli/exceptions.py" = "blob:5c66f20b0a06c8ae8c20b94f92e2c30b78f5b6c5"
-"pipelex/cli/installed_methods.py" = "blob:1de9b36e7717786fe0454af69011e05ef50610ba"
+"pipelex/cli/installed_methods.py" = "blob:7e7f289d50ca6bc446b6891cbc846dc4a8cee6e2"
"pipelex/cli/judged_target.py" = "blob:8d3f3b3359992feeeca2bd4acd1d404262cbaf87"
"pipelex/cli/method_resolver.py" = "blob:54fe2e6036b637c2e298f18bbfd10cfc616ef4a8"
"pipelex/cli/readiness.py" = "blob:6d185324ed0784663e1dc78d1194a28312c54798"
diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.toml
index 7e2e8ec64..8429e36ba 100644
--- a/.drift/acks/hub-layering-convention.toml
+++ b/.drift/acks/hub-layering-convention.toml
@@ -1,10 +1,10 @@
contract = "hub-layering-convention"
-digest = "sha256:dd59159853d97c98d62d3fcb2c38c8f0b4a10807033c5ac43a17a13bcaa37e85"
+digest = "sha256:8c80e6112b26f2f0dec72bbf6639cfc7dca269641dc6f097f7770a85a125a3fc"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-17T05:54:29Z"
-rationale = "real-catch: runtime_hub.py gains get_error_console, the stderr console a CLI prints a failure's report through; docs/contribute/hub-layering.md lists it beside get_console. No import crosses the boundary."
+reviewed_at = "2026-10-19T10:49:47Z"
+rationale = "clean-pass: absorbing Runner-speaks-problem keeps this branch's interpreter_hub.py, get_selectable_own_pipe_refs and get_required_pipe's referring_pipe_code, beside its runtime_hub.py's get_error_console; docs/contribute/hub-layering.md lists both and says what referring_pipe_code is for. No import crosses the boundary."
[trigger_files]
"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:fda2237457fe0b6830ff2ae8f720698735bec4c3"
-"pipelex/interpreter_hub.py" = "blob:e1a4b941820aeb8affbb6c70b7f81eb29e4cc191"
+"pipelex/interpreter_hub.py" = "blob:8572e31eafdfa9eb5ecde01326ef51a971f86b2e"
"pipelex/runtime_hub.py" = "blob:48f34feea22c29a56910f4a2fbb317a1d0a1e492"
diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.toml
index 5f496f0ff..35a7835d4 100644
--- a/.drift/acks/pipelex-kernel-docs.toml
+++ b/.drift/acks/pipelex-kernel-docs.toml
@@ -1,8 +1,8 @@
contract = "pipelex-kernel-docs"
-digest = "sha256:21a9e03e80e78e4fd5f4f99418986cf26be098028e711c01acc0e4489cfff2d5"
+digest = "sha256:a52db63964b074d919322e0d8d3490a2ad96776d82dfbedb5b2798be1f1279ae"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-17T06:47:23Z"
-rationale = "real-catch: prompt_assembly now gives each prompt image the input it came from as input_name, which a failed fetch names; pipelex-kernel.md now says each file handed over carries it."
+reviewed_at = "2026-10-18T08:55:09Z"
+rationale = "real-catch: the kernel's judgment now locates a refused question on the field it is written in; pipelex-kernel.md now names question and questions.<name>.question beside the prompt fields."
[trigger_files]
"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"
@@ -14,12 +14,12 @@ rationale = "real-catch: prompt_assembly now gives each prompt image the input i
"pipelex/kernel/func_ops.py" = "blob:7bac824ea53a9571bf3f21855100dc3277f0ab4f"
"pipelex/kernel/func_results.py" = "blob:a7425a0ddc21571f23c53b92f5d7559ffdd08b71"
"pipelex/kernel/img_gen_ops.py" = "blob:42858061ef4a9a162bb79281a5a44799268613d4"
-"pipelex/kernel/img_gen_prompt.py" = "blob:c653190d40e4323f763b9da511bd55a4a1646888"
+"pipelex/kernel/img_gen_prompt.py" = "blob:d26439e199c1b8197cd3c4e9819d4b6ba5e5c456"
"pipelex/kernel/img_gen_results.py" = "blob:46b4ca11c70d906ae6d58ce66461f9b3414f1bfa"
-"pipelex/kernel/judgment_ops.py" = "blob:6bf523ecd35390e76a8150755a71295d24977698"
+"pipelex/kernel/judgment_ops.py" = "blob:4bc8e3a4adad2c299da1aa1cdb46a7eab3906a04"
"pipelex/kernel/judgment_results.py" = "blob:4dbbcb204309265999de59a179f4420a0f83be93"
"pipelex/kernel/llm_ops.py" = "blob:730c080684a1f3c1bb90d599105b1789eb6ee10a"
-"pipelex/kernel/llm_prompt_content.py" = "blob:f996cead6e7789494f01f69c128ae71d6dcf8466"
+"pipelex/kernel/llm_prompt_content.py" = "blob:bca49e1446b37a9748e4259f19a235770f24f054"
"pipelex/kernel/llm_results.py" = "blob:6e3b8a2878b5bb284ece5fac10262fb59ac2029d"
"pipelex/kernel/memory_ops.py" = "blob:7fbbfaaec99f9712d8e215520cb02e26aad3fb40"
"pipelex/kernel/pipelex_kernel.py" = "blob:c7d40db1572aaca00d1c04a1039f5e3e564d6f87"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e6e14723e..ef6eb7b28 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,12 +17,16 @@
- **Validation warnings as problem items**: `warning_problem_items()` in `pipelex.pipeline.validation_errors` gives a valid report's warnings as problem items, each under the code its type names, a hint lint's `method.hint_invalid` naming its hint from the new `ValidationErrorItem.hint_key` and located at the declaration the hint is on, a concept at `concept.<Concept>`, a field of its structure at `concept.<Concept>.structure.<field>`, a pipe's input at the pipe and the input, and `root_escape_of()`, whose `RootEscape` gives both the reason a path leaving its root is refused and its `rule`, and `path_refusal_error()` in `pipelex.core.bundle_resources.bundle_resource`, which builds the refusal of a submitted file's path from that escape, with its code and its parameters, the `rule` of `security.input_path_refused` or the field `resources` of `request.invalid`.
- **The security event**: a refusal coded in the `security.` or `pipelex.security.` family fails its run under that code and logs one record on its own logger, `pipelex.errors.security_event`, at warning level, with the message `A security rule refused a request` and `event.name` set to `pipelex.security.refusal`, naming the code, its domain, the kind of target refused, the class of destination when the rule knows it (`loopback`, `private`, `link_local`, `metadata`, `scheme`, `foreign_storage_key`, which the caller's problem states as the registry's `private`, since its sentence reads the class as a word), the run, the request and each of the run's extras as `run.extras.<key>`, which the API server reads off a request's `analytics_groups` as soon as its JSON body is parsed, on the diagnostic routes as on the run routes, and never the URL, path, template or any input value. The process that raises a refusal logs it, once: the pipe run for a refusal raised while it executes, its delivery included, the validation sweep for one a dry run meets before its pipe run starts, such as while its mock inputs are built, the runner for one before the run exists and for one raised in its own process that no pipe run logged, and the API server for one answered before any run, the refusals it authors itself included (a reserved object key, a callback URL the SSRF rule refuses, a resource path or a method file path leaving the method: absolute, naming a drive or a network share, or climbing with `..`, read with either separator, while a path of the wrong shape, empty or holding a backslash or a colon, logs none and is `request.invalid` as a key of `resources` or a file submitted beside a method, and `method.package_invalid` with the reason `invalid_tree_path` as a key of `files` or a member of `bundle_b64`), which keep their response, while a failure rebuilt from another process's report is never logged again, since the orchestrator that rebuilds it marks it, and no event names a run id a request body chose; `pipelex.errors.security_event` gives a host `emit_security_event()`, `mark_security_event_emitted()` and `log_security_event()`, and a raise site states the class of destination with `PipelexError.with_security_target_class()`.
+- **`pipelex.test_extras.required_params_sweep`**: `spy_on_problem_warnings`, set before a test, and `assert_problems_carried_required_params`, run after it, fail a test that builds a problem or an item lacking a parameter its code requires, unless the test carries the `builds_problems_without_required_params` marker with its reason, and the library's unit tests and the API server's run under them.
+
+- **`pipelex.request.dependency_key_mismatch`**: a dependency a run or validation request keys by another address than the one its own `METHODS.toml` declares, such as its repository's address alone, is refused with this 422 code, whose `key` and `address` parameters give the key sent and the address to key it by, where it was a generic `request.invalid`.
+
### Changed
- **The problem document replaces `ErrorReport` (Breaking)**: every `PipelexError` answers a problem document, `PipelexError.to_problem(view=...)` building a `PipelexProblem` (`pipelex.errors.problem`), where it built an `ErrorReport`: its `type`, `title`, `status`, `domain`, `retry` and `next_step` are its code's, its `type` the code's page (`https://mthds.ai/errors/<code>` for a core code, `https://docs.pipelex.com/errors/<code>` for a Pipelex code), its `detail` and its step are rendered from the code's templates and the parameters the error gives, the code's title standing in for a sentence a missing parameter leaves unrendered, a refusal of several faults lists them in `errors`, and the Pipelex members `request_id`, `run_error` and `diagnostics` join the standard's. A problem never writes a member a model declares as `null`, while a `null` an extension member or a free-form object holds is written as it was read, `to_wire()` writes back every problem a reader accepts however deeply an extension member nests, a parameter of a type its code does not declare, an infinite or `NaN` number and a value that is neither a JSON scalar nor a list of them included, is dropped and logged rather than raise in place of the error, and an item never carries a parameter its code keeps for the operator, whoever built it, the caller reading an item whose code this process does not know with no parameter and a generic sentence. `ErrorReport`, `TracedFailure` and the graph's `ErrorSpec` are gone, and `error_type` is no member of a problem: the operator reads the error's class as `diagnostics.error_class`.
- **The reader's identity picks the view of a failure (Breaking)**: a problem is read in the caller's view, its sentences rendered from the parameters a caller may read, or in the operator's, which adds `diagnostics` (the error's class and message, its causes, the model, the provider's answer, a migration, the runtime version and the trace) and the operator's own next step; `DisclosureMode`, the `ERROR_DISCLOSURE` setting and `caller_facing_message` are gone, and `caller_view_of()` projects an operator's problem to the caller's, giving a code this process's registries do not hold the generic step of its kind, `report` for an operator's code. The runner answers the operator's view to a request carrying its static API key (`AUTH_MODE=api_key`) or reaching it through a trusted proxy (`AUTH_MODE=none` with `TRUST_FORWARDED_IDENTITY_HEADERS=true`), which owes its own callers their caller view, and the caller's view to every other request, and a webhook receives the view its target's `problem_view` names, the caller's by default, the problem built only for a run that has a webhook and never replacing the run's own error when it cannot be built.
- **The runner answers each code's HTTP status (Breaking)**: an error response's status is its code's, from the error registry, where it followed the error's domain and a table of per-class overrides, so `provider.unavailable` answers 502, `provider.timeout` 504, `model.unavailable` 501, a method that cannot be fetched (`method.fetch_failed`) 502 where it answered 422, and a fetched method declaring Python structures (`pipelex.deployment.python_structures_refused`) 422 where it answered 403; `Retry-After` rides a 429 alone, and an exception that is not a Pipelex error answers `runtime.unexpected`, a 500.
-- **An input refusal names the input and what is wrong with it**: a refusal of a run's inputs carries the input in `params.input` and `location.input`, with the facts its code declares, the expected and provided counts of `input.wrong_multiplicity`, the declared and provided concepts of `input.wrong_concept` and the field at fault of `input.invalid` when the concept's structure names one, so its `detail` names the input and its fault.
+- **An input refusal names the input and what is wrong with it**: a refusal of a run's inputs carries the input in `params.input` and `location.input`, with the facts its code declares, the expected and provided counts of `input.wrong_multiplicity`, the declared and provided concepts of `input.wrong_concept` and the field at fault of `input.invalid` when the concept's structure names one, so its `detail` names the input and its fault; a refused file, whether its url is blank or malformed, its storage reference names nothing, its data URL or local path cannot be read, the run may not read it, or its format is one its input or its model cannot take, names the run's input as `input` and the path down to the file as `location.field`, such as `documents[1]`, or `documents[1].url` for its url, which `input.invalid` also gives as its `field`. A CSV table input refused before it is read says what happened: a url that does not parse is `input.file_unreadable`, a url that is not a local path `request.unsupported` with the reason `remote_table_url`, and a concept with no structure class `method.concept_invalid`, where each was an `input.invalid` about the concept's structure, and every CSV refusal, before or while the table is read, is located on the input in `location.input`.
- **A run failure's problem names its pipe and path**: the problem of a run that failed inside a pipe carries the failing pipe and the pipes leading to it as `location.pipe` and `location.path`, and fills the `pipe` parameter of a code that declares one, while a failure of the entry pipe before any step carries no location. The location also keeps what the errors between the run and its root fault know, such as the field and the file a pipe met an unknown model at, and the diagnostics keep the model and the backend a worker attributed the failure to on an error above the root fault, an inner router's stand-in for a foreign exception included. A parameter a wrapper above the error whose code the problem reports gave, and its code declares, fills the one that error gave none of, and the items a wrapper gave follow that error's own.
- **A graph node's error is its problem (Breaking)**: a failed node of a `GraphSpec`, and the trace event that ended its pipe, carry the problem in the caller's view in `error`, located at the node's pipe and path, and the stack trace, when the graph's data inclusion asks for it, in `error_stack`, capped at the same length on both, where `error` held `error_type`, `message`, `stack` and `caller_facing`.
- **Plugin API v9 (Breaking)**: an HTTP-error mapper registered with `add_http_error_mapper(exc_type_provider=..., to_pipelex_error=...)` returns the `PipelexError` a transport exception stands for, where `to_error_report` returned a report, and a bundle validator's `validate_bundles` returns a `BundleValidationFailure`, the refusal's problem in the operator's view with its validation items, as its invalid verdict, and a host plugin's carrier of a problem recovered across a transport boundary overrides `PipelexError.recovered_problem()` to return it rather than overriding `to_problem()`, which a located run failure no longer reads as a carrier; `PLUGIN_API_VERSION` moves to 9, so a plugin declaring `targets_api = 8` is refused at discovery with `PluginApiVersionMismatchError`.
@@ -30,12 +34,12 @@
- **A run failure reports its root fault's code (Breaking)**: the root fault a run failure's problem reports is the first error down its cause chain that declares a code of its own, and its code, title, type, domain and retry verdict are the problem's, with no `runtime` floor on the domain; a consumer that branched on the wrapper's `error_type` branches on `code`. A `PipeFunc` whose function raised reads `pipe.function_raised` whatever it raised, a coded error of a helper the function called included, which rides as the cause, while a failure of the executor running it, such as its timeout, keeps its own code, and an exception an executor lets through that is not a Pipelex error, such as an out-of-process executor's transport failure, reads `runtime.unexpected`. A failure below an exception that is not a Pipelex error lends the error above it no code, fact, location or advice.
- **The runner's own refusals are coded problem documents (Breaking)**: every error response of the API server, a 404 for a path no route serves, a 405 and a 413 included, is a problem document carrying a registry `code`, and the API's `ErrorType` is gone with the `error_type`, `error_domain`, `retryable` and `instance` members, the `tree_refusal`, `missing_blobs` and `mismatched_blobs` members becoming the code's parameters or the operator's diagnostics. A field the runner refuses is `request.invalid` naming it as `params.field`, with one item in `errors` per refused field up to a bound, which the operator's `diagnostics.message` keeps too, saying how many more faults there were, a rule over several fields naming the one to change, such as the second of two selectors sent or `mthds_sources` beside a `method_ref`, a body or a part of one it cannot parse `request.malformed` with a `reason`, a size limit `request.too_large` with its `limit` and the `size` in bytes, an encoded value measured by the bytes it carries, and a method tree it cannot read `method.package_invalid` with a `reason`, the standard's tree refusal code or one of the runner's own, one per rule and one per limit, so an archive past its member count reads `bundle_too_many_files`, while a body refused beyond its schema on `/v1/execute` or `/v1/start` (a bundle sent with `mthds_contents`, `method_ref` beside a bundle, `resources` or `dependencies` without their files, no run source, a hosted-only field such as `method_id`) answers a `PipelexRequestError` carrying `request.invalid` or `request.unsupported`; the API's `ProblemDocument` schema documents `code`, and `request_id`, taken from `X-Request-ID` or minted, is what correlates a response with the server's log.
- **The runner's refusals answer their code's status (Breaking)**: an orchestration-mode override the deployment forbids is a 422 where it was a 403, custom Python on a deployment that is not sandbox-hosted a 501 where it was a 403, `/v1/start` on a blocking-only deployment a 501 `runtime.unsupported` where it was a 400, a registry-form `method_ref` a 422 `request.unsupported` where it was a 501, invalid base64 and a client gone mid-upload a 422 where they were a 400, an archive past its file-count or decompressed-size ceiling and too many `resources` a 422 where they were a 413, a blob past the per-file limit a 413 where it was a 422, a forwarded `X-User-Id` that is not path-safe a 422 `request.invalid` naming the header where it was a 400, a body FastAPI could not parse, holding bytes that are not UTF-8 or an integer past Python's digit limit, a 422 `request.malformed` with the reason `not_utf8` or `integer_too_long` where it was a 400, while the framework's own refusals, plain `{"detail": …}` bodies until now, keep their status under a code whose required parameters the runner can fill, a 400 as `request.malformed` with the reason `unreadable`, a 401 as `auth.missing_credential` keeping its `WWW-Authenticate` challenge, a 403 as `auth.invalid_credential`, a 413 as `request.malformed` with the reason `too_large`, a 429 as `runtime.unavailable` keeping its `Retry-After`, and any other, such as a 415, as `request.malformed` with the reason `unreadable`, a `read_scope` a `jwt` caller may not read a 403 `auth.forbidden` whose `requirement` is `read_scope_under_caller` where it was a 403 `ReadScopeForbidden`, and a token whose claims the runner cannot use a 500 where it was a 401; a 401 carries `WWW-Authenticate: Bearer` only where the deployment reads a bearer token (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`), so behind a trusted proxy a missing `X-User-Id` is a 401 asking for no token.
-- **Damaged stored bytes are a damaged stored file, never retried**: bytes the API server's blob store holds under a hash that do not hash to it, or are not the size it holds them at, answer a 500 `pipelex.storage.damaged`, a new code of the Pipelex error registry, naming the kind of storage, whose verdict is not to retry, since a retry reads the same damaged object, and which `/v1/execute`, `/v1/start` and `/v1/validate` declare in their OpenAPI responses; the server's line naming the object to remove, `Stored blob bytes do not match their hash`, carries `blob_sha256`, `blob_size_bytes`, `read_size_bytes` and `storage_scheme`.
+- **Damaged stored bytes are a damaged stored file, never retried**: bytes the API server's blob store holds under a hash that do not hash to it, or are not the size it holds them at, answer a 500 `pipelex.storage.damaged`, a new code of the Pipelex error registry, naming the kind of storage, `plugin` for a storage plugin's own, whose verdict is not to retry, since a retry reads the same damaged object, and which `/v1/execute`, `/v1/start`, `/v1/validate`, `/v1/resolve`, `/v1/codegen`, `/v1/pipe-io` and `PUT /v1/blobs/{sha256}` declare in their OpenAPI responses; the server's line naming the object to remove, `Stored blob bytes do not match their hash`, carries `blob_sha256`, `blob_size_bytes`, `read_size_bytes` and `storage_scheme`.
- **The `/validate` Markdown presents the verdict's items (Breaking)**: the opt-in `rendered_markdown` of an invalid verdict is rendered from the problem items its `errors` holds, in the same view, each under its code's title with its code, location, sentence, suggestions and suggested fix, so a caller reads no wording its view of the items leaves out, where it rendered the validation items' own messages; `pipelex.pipeline.validation_render.render_invalid_verdict_markdown(items=..., message=...)` replaces `render_invalid_validation_markdown(report)`.
- **The diagnostic routes' verdicts carry problem items (Breaking)**: the invalid arm of `/v1/validate`, `/v1/resolve`, `/v1/codegen` and `/v1/pipe-io` carries `errors`, one problem item per finding with its `code`, `detail`, `params` and `location` and a suggested fix naming its file as `file`, where it carried `validation_errors`, the valid arm's `warnings` are problem items too, and a top-level member a verdict has no value for, such as `default_pipe_ref` or `graph_spec`, is absent rather than `null`. The OpenAPI artifact no longer publishes `ValidationErrorItem` or pipelex's `SuggestedFix`, and names every schema reachable from the standard's problem item with a `Problem` prefix, such as `ProblemSuggestedFix` and `ProblemSetKeyOp`.
-- **Pipe selection refusals carry the code of their case**: an entry pipe the selector names but no closure declares reads `request.pipe_not_found`, a bare selector matching pipes in several domains `request.pipe_ambiguous`, a request with no selector over a closure declaring no `main_pipe`, or several, `request.pipe_unspecified`, naming the declared ones as its `candidates`, a manifest `main_pipe` the closure lacks `method.pipe_unresolved`, and one it declares in several domains `method.ref_ambiguous`, all still a 422, a dependency's `alias->code` matching pipes in several of its domains naming them as `candidates` too; a run of a method on disk with no pipe named refuses several declared `main_pipe`s and a manifest `main_pipe` several bundles define the same way.
-- **`PipeIOContractError` is the method's (Breaking)**: a structure that cannot be projected into its IO contract answers a 422 carrying `method.concept_invalid`, where it answered a 500.
-- **Storage and remote-file failures say whose they are**: an S3 or GCS refusal of the deployment's credentials (`AccessDenied`, an invalid or expired key, `Forbidden`) carries `pipelex.config.credential_refused`, a bucket that does not exist `pipelex.config.invalid` and missing credentials `pipelex.config.credential_missing`, apart from an outage, `pipelex.storage.unavailable`; a remote file that times out, refuses the connection or answers a 5xx, 408, 425 or 429 is `input.url_unreachable`, which a retry may cure, and any other failed fetch `input.file_unreadable`.
+- **Pipe selection refusals carry the code of their case**: an entry pipe the selector names but no closure declares reads `request.pipe_not_found`, offering as its `suggestions` only pipes the caller may select, the method's own for a bare or domain-qualified code, never a pipe of the server's own library directories, and for an `alias->…` code the pipes that dependency exports, a bare selector matching pipes in several domains `request.pipe_ambiguous`, a request with no selector over a closure declaring no `main_pipe`, or several, `request.pipe_unspecified`, naming the declared ones as its `candidates`, a manifest `main_pipe` the closure lacks `method.pipe_unresolved`, naming the `main_pipe` declaration as its `pipe` and the nearest declared pipes as its `candidates`, and one it declares in several domains `method.ref_ambiguous`, all still a 422, a dependency's `alias->code` matching pipes in several of its domains naming them as `candidates` too; a run of a method on disk with no pipe named refuses several declared `main_pipe`s and a manifest `main_pipe` several bundles define the same way.
+- **`PipeIOContractError` is the method's (Breaking)**: a structure that cannot be projected into its IO contract answers a 422 carrying `method.concept_invalid`, naming the concept and the finding, where it answered a 500.
+- **Storage and remote-file failures say whose they are**: an S3 or GCS refusal of the deployment's credentials (`AccessDenied`, an invalid or expired key, `Forbidden`) carries `pipelex.config.credential_refused`, a bucket that does not exist `pipelex.config.invalid` and missing credentials `pipelex.config.credential_missing`, apart from an outage, `pipelex.storage.unavailable`, naming the kind of storage; a remote file that times out, refuses the connection or answers a 5xx, 408, 425 or 429 is `input.url_unreachable`, which a retry may cure, and any other failed fetch `input.file_unreadable`.
- **Builtins raised where a reader sees them are coded classes**: refusals that raised a bare `ValueError`, `RuntimeError`, `ImportError` or `NotImplementedError` raise a coded `PipelexError`, such as `RunParameterError` for a run's metadata, extras or storage scope (still a `ValueError`), `ExportedPipeNotFoundError` and `ExportedPipeAmbiguousError` for a CLI pipe selector, `BundleClosureEmptyError`, `StorageNotConfiguredError`, `UrlSyntaxError`, `LocalFileMissingError` and `UnsupportedImageMimeTypeError`, and the classes that were rooted outside `PipelexError` (`PipeValidationError`, `ConceptValueError`, `QualifiedRefError`, `SemVerError`, `MethodNotFoundError` and the like) join it.
- **Inference failures carry the code their classification picks (Breaking)**: the classification of a provider's failure picks a code with its category, a `ServiceErrorCode` a plugin contributes names its `error_code`, and a category that repeats the call within the run must pick a code that invites a retry; an error built with a category alone reports the category's code (`provider.unavailable` for `TRANSIENT`, `runtime.misconfigured` for `CONFIGURATION`, `provider.quota_exhausted` for `CAPACITY`, `provider.outcome_unknown` for `AMBIGUOUS`). A provider 400 that carries no context-window or content-policy signal is `runtime.unexpected`, answered 500, where it was the caller's 422, and a local extractor's `OSError` is `runtime.unexpected`, no longer repeated within the run.
- **One rule for a request id (Breaking)**: a run's `request_id` holds ASCII letters, digits, `_` and `-` alone, at most 128 of them, the rule the API server applies to an inbound `X-Request-ID`, now one function, `pipelex.system.job_metadata.is_valid_request_id()`, where a run accepted any printable ASCII, a space, a quote or an `=` that could forge a field of a key=value log line or a parameter of a header included; `RunParameterError` no longer quotes the refused value.
@@ -50,6 +54,10 @@
- **A security refusal is never a validation verdict (Breaking)**: a refusal a raise site coded in the `security.` family is let through by the bundle-validation cascade whatever its class, as a `SecurityError` always was, so a `PipeDocGen` step whose `template_file` climbs above its method tree's root fails `validate` and a run with `security.method_path_refused` and logs its security event, where it was a `method.invalid` verdict naming the pipe; a refusal a validation's dry run meets, such as a template the sandbox refuses at render, fails it the same way under its own code, every failure riding its items and the event logged once, where it was an item of an invalid verdict.
- **`mthds` 0.22.1 and `pipelex-sdk` 0.46.0 (Breaking)**: the exact pins move from `mthds==0.22.0` and `pipelex-sdk==0.45.0` to `mthds==0.22.1`, the release whose errors carry the MTHDS problem document read by its registry code, and `pipelex-sdk==0.46.0`, the release built on it; everyone downstream inherits those exact versions.
+- **A problem carries every parameter its code requires**: every problem and item the runtime and the API server build gives each parameter its code's registry entry requires, so its sentences state the occurrence rather than the code's generic wording: a model no catalog knows offers its `suggestions`, an empty list when none is near, an invalid identifier names its `identifier_kind` and `name`, a name declared twice, or a native concept declared again, names the `name` and the `conflict` in one item per bundle, each located on its own file and on the colliding declaration's path, such as `concept.Rating`, in a validation verdict and a run's refusal alike, while a batch item named as its list stays on its pipe and the field it collides on, `input_item_name` or a step's `steps.0.batch_as`, an unresolved concept and a selected pipe the method lacks offer the nearest declared ones, a pipe reference naming nothing the pipe whose body writes it and the nearest pipes it may name, of a dependency only those it exports unless the reference is written in that dependency, and beside a server's own library directories only the pipes of the bundles the request sent, a template the sandbox refuses names what it reached for as `name` when its own source spells it, the format string a `.format` call formats included but no other string literal, and is located on its pipe and the field the template is written in, while a name the run's data chose is withheld and its sentences say the template looked a name up from the run's data, a validation item gives the facts its check knows (the concept a pipe declares and those that would fit, the multiplicity it declares and the one its use expects, the site where an optional value escapes, the path a binding cannot follow), and `method.package_invalid` always gives its `reason`, `tree_unreadable` for a tree that cannot be listed among the new ones. A failure met while running names its facts too: a stored file gone and a storage outage name the kind of storage as `scheme`, which a storage provider's new `storage_kind` gives, `plugin` unless a provider says otherwise, a pipe added twice to a library, a duplicate branch output and a module the tree shadows name the `name` and the `conflict`, a file a model cannot read its `format` and `model`, a remote file that cannot be fetched its `host` or its `reason`, a completion the context window cut, and a prompt a provider refuses as over the context window, its `limit`, a Gemini image a filter refused its `model`, a model a provider does not know or refuses and a waterfall with nothing served the `model_type` and `reason` of `model.unavailable`, a `PipeFunc` past its deadline its `function` and `timeout`, a `PipeJudge` question that reads a file the step's `input` and the concept it `declared`, a requirement whose extra needs a missing or mismatched distribution that distribution with `not_found` or `no_matching_version`, a call to a pipe another domain of the package does not export the `pipe` and the `package`, one item per call located on the bundle, the pipe and the field that write it, and bundles declaring a reserved domain, which a package's `METHODS.toml` refuses as `method.name_conflict` too, or two declarations of one name whose bundles are unknown, one item each, on its own file. `ValidationErrorItem` and `PipesAndConceptValidationErrorData` carry those facts in `params`, and the problem builders log `A problem lacks a parameter its code requires` when a raise site gives fewer, except for a parameter withheld by rule, the refused name a template looked up from the run's data.
+- **A refusal of one fault carries no `errors` list (Breaking)**: a problem whose only item restated its own code, such as `/v1/models/check`'s refusal of a missing `reference` or a template the sandbox refused while validating, carries that item's parameters and location itself and no `errors`; a refusal whose single item has another code, such as `method.invalid` over one fault, keeps its list, and one whose single item carries suggestions or a suggested fix takes that item's parameters and location and keeps the item listed, so its fix reaches the caller.
+- **A model no enabled backend serves is `model.unavailable` (Breaking)**: a method naming a model a catalog of the deployment knows but no backend it enables serves, such as `claude-4.5-haiku` with `anthropic` switched off, answers a 501 `model.unavailable` with the reason `not_served`, located on the pipe and its `model` field, when it is validated and when it runs, where it was the method's `model.unknown` verdict; a switched-off backend's model file that is missing, is not UTF-8 text or does not parse declares nothing and never stops the boot.
+
### Fixed
- **A model deck's own unresolved default or override is the deployment's fault**: a deck default or override naming a model the deck does not define raises `ModelDeckChoiceUnresolvedError`, naming the deck setting and carrying `model.unavailable`, with the reason `not_served`, for a bare handle no backend serves, answered 501, and `pipelex.config.invalid` for a preset, an alias or a waterfall the deck does not define, answered 500, with the deck setting in the operator's diagnostics alone, where it read as the caller's unknown model, and a `PipeJudge` naming no model, whose default is resolved as its method loads, raises it rather than an `unknown_model` verdict item; a bad override is refused when the deck is built, and a handle the deck serves only as another type of model is `model.capability_unsupported`.
diff --git a/api/CLAUDE.md b/api/CLAUDE.md
index 22effd474..74ec940e5 100644
--- a/api/CLAUDE.md
+++ b/api/CLAUDE.md
@@ -206,7 +206,7 @@ async def execute(
Every error is rendered as RFC 9457 `application/problem+json` by the global handlers in `pipelex_api/exception_handlers.py`, and every problem carries a registry `code`, a 404 or a 405 included; there is no `error_type` and no `instance`, and `request_id`, which `RequestIdMiddleware` takes from an inbound `X-Request-ID` or mints, correlates a response with its log lines. **Route handlers do not shape errors themselves** — they call into pipelex and let exceptions propagate. The wire contract is documented at `docs/api-server/error-responses.md`, at the repository root.
- **Domain errors** (pipelex `PipelexError` subclasses) — raise from your code and let them propagate, choosing the error's code and parameters where you raise it (`with_error_code()`, `with_params()`) when its class declares a set. The `PipelexError` global handler builds the error's problem in the operator view, `to_problem(view=ProblemView.OPERATOR)`, and `problem_response` renders it with the status the problem's code declares, in the view the request's identity gives it (`pipelex_api/problem_view.py`: the operator's for the API key and for a request the trusted proxy forwarded, the caller's otherwise). A failure a route receives as a value, such as a validator's refusal that carries no validation items, goes through `problem_response` too. Do not wrap, classify, or re-shape.
-- **The runner's own refusals** are `PipelexError`s too, the classes of `pipelex_api/exceptions.py`, each declaring its code or its set of codes: `RunnerRequestError` (`request.invalid` naming the refused `field`, or the code the raise site chooses: `request.malformed` with a `reason`, `request.too_large` with `limit` and `size`, `request.unsupported`, `request.blobs_missing`, `request.not_found`, `request.method_not_allowed`, and `runtime.unavailable` for a framework 429), `RunnerAuthError` (the `auth.*` codes and `pipelex.deployment.token_claims_invalid`, with the `challenge` its 401 carries), `RunnerMisconfiguredError` (`runtime.misconfigured`, its `component` read by the operator alone), `RequestMethodError` (`method.package_invalid` with a `reason`, a `MethodPackageReason` or the standard's tree refusal code, and a `path` or a `limit`, `method.syntax`, `method.resource_missing`, `security.input_path_refused`), `RequestFieldConflictError` (`request.invalid` from a model validator judging several fields, naming the one to change), `BlobStoreDamagedError` (`pipelex.storage.damaged`, a 500 never retried, which the routes reading held blobs declare as `PROBLEM_500_HELD_BLOBS`), `OrchestrationOverrideForbiddenError`, `CustomCodeRequiresSandboxError`, `ReservedObjectKeyError` and `CallbackUrlRefusedError`. Raise one, choosing the code with `with_error_code()` and giving its parameters with `with_params()`; the message is the operator's and rides `diagnostics` alone, while the caller reads the code's sentence. A new class goes in that module, declares its code in its own body (`tests/unit/test_error_code_gate.py`), and is recorded with the root `make generate-error-identity`. A request the route's model refuses becomes `request.invalid` with one item per refused field (`pipelex_api/request_refusals.py`); a model validator over several fields raises `RequestFieldConflictError` so its item names a field rather than `body`. A typed body is parsed by `JsonBodyRoute` before FastAPI validates it, so a body that does not decode or parse is the caller's `request.malformed`, never FastAPI's bare 400, and its `analytics_groups` are bound on the request right then (`run_extras_binding.py`, which the run routes call too), so the security event of any later refusal names whose request it was. Pick the registry code that fits; the vendored registry is not edited here. **Do not raise `HTTPException` directly** — no route raises one: `handle_http_exception` answers the framework's own, each 4xx keeping its status and its meaning under a code whose required parameters the runner can fill, since the framework names nothing but a status and a header (`framework_refusal`: a 400 or 422 is `request.malformed` with the reason `unreadable`, keeping its status, a 401 `auth.missing_credential` keeping its challenge, a 403 `auth.invalid_credential`, a 404 or 405 from routing, a 413 `request.malformed` with the reason `too_large`, a 429 `runtime.unavailable` naming the rate limiter, keeping its `Retry-After`, any other `request.malformed` with the reason `unreadable`; `tests/unit/test_exception_handlers.py` checks every 4xx fills its code's parameters), never as a 500, and a 5xx as `runtime.unexpected`. A refusal standing in for a framework exception (`_standing_in_for`) is chained from it, so the record's `error.chain` names it.
+- **The runner's own refusals** are `PipelexError`s too, the classes of `pipelex_api/exceptions.py`, each declaring its code or its set of codes: `RunnerRequestError` (`request.invalid` naming the refused `field`, or the code the raise site chooses: `request.malformed` with a `reason`, `request.too_large` with `limit` and `size`, `request.unsupported`, `request.blobs_missing`, `request.not_found`, `request.method_not_allowed`, `runtime.unavailable` for a framework 429, and `pipelex.request.dependency_key_mismatch` with the `key` sent and the `address` a dependency's manifest declares), `RunnerAuthError` (the `auth.*` codes and `pipelex.deployment.token_claims_invalid`, with the `challenge` its 401 carries), `RunnerMisconfiguredError` (`runtime.misconfigured`, its `component` read by the operator alone), `RequestMethodError` (`method.package_invalid` with a `reason`, a `MethodPackageReason` of `pipelex/methods/package_reason.py` or the standard's tree refusal code, and a `path` or a `limit`, `method.syntax`, `method.resource_missing`, `security.input_path_refused`), `RequestFieldConflictError` (`request.invalid` from a model validator judging several fields, naming the one to change), `BlobStoreDamagedError` (`pipelex.storage.damaged` naming the `scheme` of the store, `plugin` for a storage plugin's own, a 500 never retried, which the routes reading held blobs declare as `PROBLEM_500_HELD_BLOBS`), `OrchestrationOverrideForbiddenError`, `CustomCodeRequiresSandboxError`, `ReservedObjectKeyError` and `CallbackUrlRefusedError`. Raise one, choosing the code with `with_error_code()` and giving every parameter the code's registry entry requires with `with_params()`; the message is the operator's and rides `diagnostics` alone, while the caller reads the code's sentence. `tests/unit/conftest.py` fails a test during which a problem or an item is built lacking a required parameter, unless the test carries `@pytest.mark.builds_problems_without_required_params(reason=...)` saying why the fact cannot be known. A new class goes in that module, declares its code in its own body (`tests/unit/test_error_code_gate.py`), and is recorded with the root `make generate-error-identity`. A request the route's model refuses becomes `request.invalid` with one item per refused field (`pipelex_api/request_refusals.py`); a model validator over several fields raises `RequestFieldConflictError` so its item names a field rather than `body`. A typed body is parsed by `JsonBodyRoute` before FastAPI validates it, so a body that does not decode or parse is the caller's `request.malformed`, never FastAPI's bare 400, and its `analytics_groups` are bound on the request right then (`run_extras_binding.py`, which the run routes call too), so the security event of any later refusal names whose request it was. Pick the registry code that fits; the vendored registry is not edited here. **Do not raise `HTTPException` directly** — no route raises one: `handle_http_exception` answers the framework's own, each 4xx keeping its status and its meaning under a code whose required parameters the runner can fill, since the framework names nothing but a status and a header (`framework_refusal`: a 400 or 422 is `request.malformed` with the reason `unreadable`, keeping its status, a 401 `auth.missing_credential` keeping its challenge, a 403 `auth.invalid_credential`, a 404 or 405 from routing, a 413 `request.malformed` with the reason `too_large`, a 429 `runtime.unavailable` naming the rate limiter, keeping its `Retry-After`, any other `request.malformed` with the reason `unreadable`; `tests/unit/test_exception_handlers.py` checks every 4xx fills its code's parameters), never as a 500, and a 5xx as `runtime.unexpected`. A refusal standing in for a framework exception (`_standing_in_for`) is chained from it, so the record's `error.chain` names it.
- **Auth errors** — a 401 carries the `WWW-Authenticate` challenge its `RunnerAuthError` names, `Bearer` from the token and API-key verifiers, and none behind a trusted proxy, which reads no bearer token; `problem_json_response` adds no challenge of its own. A forwarded `X-User-Id` that is not path-safe is a `RunnerRequestError` naming the header, a 422.
- **Logging** — the global handlers emit one structured record per error, with the fixed message `A request ended in an error response` (the key the error stream is selected by; there is no `event` field) and the fields `url.path`, `error.code`, `error.type`, `error.chain`, `error_domain`, `retryable`, `http.response.status_code`, and `user.id` / `pipe_code` / `pipeline_run_id` when the request bound them, plus `error_category` and the diagnostics' `backend_name`, `model_handle`, `provider_status_code` and `provider_request_id` when the failure has them. `error.type` is the class of the exception that escaped, which for an exception that is not a `PipelexError` is that exception's class rather than the stand-in its problem names, and `error.chain` the classes of the exceptions it was raised from or while handling. **No record carries an exception's text or its traceback**: a foreign exception's text can quote a run's inputs or a model's answer, so an `error` record adds `error.frames`, where the deepest exception of the chain was raised, every record adds the problem's operator-only parameters as `error.params.<name>` (the `component` of a `runtime.misconfigured`), and the message rides the operator view's `diagnostics` alone, which only an operator-authenticated request reads. `AnsweredErrorBarrier`, between `RequestIdMiddleware` and the app in `main.py`, stops the exception Starlette's `ServerErrorMiddleware` raises again after the catch-all answered it, so uvicorn never logs its traceback; a failure no handler recorded once a response had started, the catch-all's own, or one sending the barrier's own answer, it records first as `A request failed after its response had started`, by class alone. The record is built from the operator view, and carries no `detail`. The fields travel as `fields=` on the runtime's log call, never interpolated into the message, and `request_id` is not among them: `RequestIdMiddleware` binds it on the runtime's log context, so every record emitted under the request already carries it. The server selects the `json` sink, so a record reaches stderr as one JSON object per line — see `docs/api-server/logging.md` at the repository root. The record's level says who has to act (`record_level_of`, from the final HTTP status and the code's domain, the registry's who-must-act): a 4xx logs at `warning` (caller mistakes, the provider-429 passthrough, and the 409 conflict); a 5xx logs at `error`, with frames, only when its domain is `runtime` or `operator`, and at `warning` without frames when it is a 501, what this deployment does not offer, which any caller can ask for again, or when its domain is the caller's; a routing 404 or 405 logs at `debug`, as scanners send them by the thousand. Decide a new level from those two facts, never from a list of codes. A security refusal also logs its security event. Routes should not log errors themselves.
- **Documenting a failure in OpenAPI** — the shared, typed `responses=` declarations live in `pipelex_api/openapi_responses.py` (`ProblemDocument` + one constant per status, such as `PROBLEM_404_METHOD_PACKAGE`, `PROBLEM_409_DUPLICATE_RUN`, `PROBLEM_501_RUN_POLICY` and `PROBLEM_501_START`, each describing the codes it answers). Every auth-wrapped `/v1` route already documents `401`/`413`/`422`/`500` via the composite router's `responses=` (`pipelex_api/routes/__init__.py`, `COMMON_PROBLEM_RESPONSES`); a route declares on its own decorator only the statuses **it alone** can produce. A schema reachable from the standard's `ProblemItem` is published under a `Problem` prefix (`pipelex_api/openapi_schema.py`), so it never takes the name of pipelex's own model of the same name. Never hand-write an error `content` block: `pipelex_api/openapi_schema.py` re-keys the generated schema onto `application/problem+json`, because FastAPI renders a response `model` under the route's response-class media type and offers no per-response override. Adding a new status means adding a constant there and referencing it — then `make openapi-export`.
diff --git a/api/pipelex_api/blob_store.py b/api/pipelex_api/blob_store.py
index 41b6f0453..b1f3fc8d5 100644
--- a/api/pipelex_api/blob_store.py
+++ b/api/pipelex_api/blob_store.py
@@ -81,10 +81,14 @@ MAX_CONCURRENT_BLOB_TRANSFERS = 4
BLOB_DAMAGED_MESSAGE = "Stored blob bytes do not match their hash"
-def problem_scheme_of(*, storage_method: str) -> str | None:
+# The kind of storage a `pipelex.storage.*` problem names for a storage plugin's own backend.
+PLUGIN_STORAGE_SCHEME = "plugin"
+
+
+def problem_scheme_of(*, storage_method: str) -> str:
"""The kind of storage a `pipelex.storage.*` problem names for a configured storage method, as the registry spells it.
- `None` for a storage plugin's own method, which the registry's kinds do not list.
+ `plugin` for a storage plugin's own method, whose kind the registry cannot list.
"""
match storage_method:
case StorageMethod.LOCAL:
@@ -97,13 +101,13 @@ def problem_scheme_of(*, storage_method: str) -> str | None:
return "gcs"
case _:
# An external storage plugin's method token: the configured method is an open string.
- return None
+ return PLUGIN_STORAGE_SCHEME
class RunnerBlobStore:
"""The blobs and tree listings of one caller's scope, over the deployment's storage provider."""
- def __init__(self, *, scope: str, storage: StorageProviderAbstract, scheme: str | None) -> None:
+ def __init__(self, *, scope: str, storage: StorageProviderAbstract, scheme: str) -> None:
"""Build the blob store of one scope.
Args:
diff --git a/api/pipelex_api/bundle.py b/api/pipelex_api/bundle.py
index 56198e426..72479fe02 100644
--- a/api/pipelex_api/bundle.py
+++ b/api/pipelex_api/bundle.py
@@ -18,9 +18,10 @@ from io import BytesIO
from mthds.protocol.problem.registry import CoreCode, RequestMalformedReason
from pipelex import log
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.tools.log.error_fields import error_fields
-from pipelex_api.exceptions import MethodPackageReason, RequestMethodError, RunnerRequestError
+from pipelex_api.exceptions import RequestMethodError, RunnerRequestError
from pipelex_api.limits import MAX_BUNDLE_FILES, MAX_BUNDLE_TOTAL_BYTES, base64_decoded_size
# The request field the archive rides, which the refusals of its encoding name.
diff --git a/api/pipelex_api/exception_handlers.py b/api/pipelex_api/exception_handlers.py
index eac0b2b99..bc66f7d77 100644
--- a/api/pipelex_api/exception_handlers.py
+++ b/api/pipelex_api/exception_handlers.py
@@ -440,9 +440,9 @@ async def handle_unexpected_error(request: Request, exc: Exception) -> Response:
failure: the caller reads the code's own sentences and never the exception's
text, and a request the operator authenticated reads its class in
`diagnostics`, never its text either, which can carry anything of a run's
- data. Neither a traceback nor the exception's text reaches the response or
- the log: the operator's record names the chain's classes and the frames it
- was raised through, correlated by request id.
+ data. Neither a traceback nor the exception's text reaches the response or the
+ log: the operator's record names the chain's classes and the frames it was
+ raised through, correlated by request id.
This handler also covers a failure *inside* another handler: Starlette's
`ServerErrorMiddleware` wraps the others, so such a failure still lands here
diff --git a/api/pipelex_api/exceptions.py b/api/pipelex_api/exceptions.py
index 59c3bd884..1de00b289 100644
--- a/api/pipelex_api/exceptions.py
+++ b/api/pipelex_api/exceptions.py
@@ -14,7 +14,7 @@ code its class declares with ``with_error_code`` and gives the code's parameters
``detail`` and ``next_step`` are the code's sentences, while the message stays the operator's, in ``diagnostics``.
"""
-from enum import StrEnum, unique
+from enum import StrEnum
from typing import Any
from mthds.protocol.problem.models import ProblemLocation
@@ -106,12 +106,14 @@ class RunnerRequestError(PipelexError):
that this runner does not hold, ``request.not_found`` and ``request.method_not_allowed`` for a request no route
serves, and ``runtime.unavailable``, naming the rate limiter as its ``dependency``, for a request a rate limit in
front of a route refused, which only the web framework's own refusal answers
- (``pipelex_api.exception_handlers.framework_refusal``).
+ (``pipelex_api.exception_handlers.framework_refusal``). A dependency keyed by another address than its manifest
+ declares is ``pipelex.request.dependency_key_mismatch``, which names the address to key it by.
"""
error_code = ErrorCodeSet(
default=CoreCode.REQUEST_INVALID,
others=(
+ PipelexErrorCode.REQUEST_DEPENDENCY_KEY_MISMATCH,
CoreCode.REQUEST_MALFORMED,
CoreCode.REQUEST_TOO_LARGE,
CoreCode.REQUEST_UNSUPPORTED,
@@ -200,20 +202,17 @@ class BlobStoreDamagedError(PipelexError):
The object stored under the hash is damaged: storage holds it, but not the bytes the runtime stored. No caller
can repair that, no upload of theirs changes it, and a retry reads the same damaged object, which stays until the
operator removes it: ``pipelex.storage.damaged``, a 500 whose verdict is not to retry and whose step is to report
- it. ``scheme`` is the kind of storage the deployment runs, ``None`` for a storage plugin whose kind the registry does
- not list.
+ it. ``scheme`` is the kind of storage the deployment runs, ``plugin`` for a storage plugin's own.
"""
error_code = PipelexErrorCode.STORAGE_DAMAGED
- def __init__(self, message: str, *, scheme: str | None) -> None:
+ def __init__(self, message: str, *, scheme: str) -> None:
super().__init__(message)
self.scheme = scheme
@override
def problem_params(self) -> dict[str, Any]:
- if self.scheme is None:
- return {}
return {"scheme": self.scheme}
@@ -266,37 +265,6 @@ class ReservedObjectKeyError(PipelexError):
return {"keys": self.keys}
-@unique
-class MethodPackageReason(StrEnum):
- """The `reason` of a `method.package_invalid` this runner raises itself, one member per rule and one per limit.
-
- Beside them, a refusal of the standard's tree rule gives the standard's own refusal code (`TreeRefusalCode`) as its
- reason. A limit's refusal also gives its `limit`, and each limit has its own reason, so a caller reads which one the
- method passed: a tree's, a request's or a `bundle_b64` archive's.
- """
-
- # The limits of one method tree.
- TOO_MANY_FILES = "too_many_files"
- FILE_TOO_LARGE = "file_too_large"
- TREE_TOO_LARGE = "tree_too_large"
- # The limits of a request's trees together.
- TOO_MANY_DEPENDENCIES = "too_many_dependencies"
- METHOD_TOO_LARGE = "method_too_large"
- # The limits of a `bundle_b64` archive, on its members and on its decompressed size.
- BUNDLE_TOO_MANY_FILES = "bundle_too_many_files"
- BUNDLE_TOO_LARGE = "bundle_too_large"
- # The method's own tree holds no `.mthds` bundle.
- NO_BUNDLE = "no_bundle"
- # The manifest of a shipped package or of a dependency tree.
- MANIFEST_MISSING = "manifest_missing"
- MANIFEST_INVALID = "manifest_invalid"
- PACKAGE_NAME_INVALID = "package_name_invalid"
- # Two dependencies a reference could not tell apart.
- DEPENDENCY_ADDRESS_COLLISION = "dependency_address_collision"
- # A fetched package holds a file whose name is not UTF-8 text.
- FILE_NAME_NOT_UTF8 = "file_name_not_utf8"
-
-
class RequestMethodError(PipelexError):
"""A method the request carries, or names by address, that the runner refuses to read as a method.
diff --git a/api/pipelex_api/method_source.py b/api/pipelex_api/method_source.py
index 6382a00d7..b3049273d 100644
--- a/api/pipelex_api/method_source.py
+++ b/api/pipelex_api/method_source.py
@@ -51,8 +51,8 @@ from pipelex.libraries.method_trees import list_package_method_tree
from pipelex.methods.exceptions import MethodFetchError
from pipelex.methods.fetching import FetchedMethodPackage, MethodProvenance
from pipelex.methods.method_ref import parse_method_ref
+from pipelex.methods.package_reason import MethodPackageReason
-from pipelex_api.exceptions import MethodPackageReason
from pipelex_api.method_cache import get_method_clone_cache
from pipelex_api.method_tree_request import (
RequestMethod,
diff --git a/api/pipelex_api/method_tree_request.py b/api/pipelex_api/method_tree_request.py
index 3e525fc58..0f96d28c9 100644
--- a/api/pipelex_api/method_tree_request.py
+++ b/api/pipelex_api/method_tree_request.py
@@ -55,7 +55,9 @@ from mthds.protocol.problem.registry import CoreCode, MethodResourceMissingReaso
from pipelex.cli.installed_methods import PROVENANCE_FILENAME
from pipelex.config import is_pipe_func_sandbox_hosted
from pipelex.core.bundle_resources.bundle_resource import SUBMITTED_FILES_FIELD, root_escape_of
+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.libraries.written_trees import WRITTEN_METHOD_TREES, write_method_tree
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.methods.structures_check import ensure_no_structured_content_in_library_sources, ensure_no_structured_content_python
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipeline.exceptions import MethodEntryError
@@ -65,7 +67,7 @@ from pipelex.pipeline.validate_bundle_translation import translate_to_validate_b
from pipelex_api.blob_store import RunnerBlobStore
from pipelex_api.bundle import decode_bundle_archive
from pipelex_api.bundle_resources import refuse_two_files_under_one_path
-from pipelex_api.exceptions import CustomCodeOrigin, CustomCodeRequiresSandboxError, MethodPackageReason, RequestMethodError, RunnerRequestError
+from pipelex_api.exceptions import CustomCodeOrigin, CustomCodeRequiresSandboxError, RequestMethodError, RunnerRequestError
from pipelex_api.limits import (
MAX_METHOD_DEPENDENCIES,
MAX_METHOD_REQUEST_TOTAL_BYTES,
@@ -579,8 +581,9 @@ async def read_request_method(*, documents: TreeDocuments, blob_store: RunnerBlo
Each dependency tree's manifest must declare the address it is keyed by.
- Raises (as problem documents): the refusals of `read_request_tree`, and a 422 `request.invalid` naming
- `dependencies` for dependencies without `files` or a dependency keyed by another address than its manifest's.
+ Raises (as problem documents): the refusals of `read_request_tree`, a 422 `request.invalid` naming `dependencies`
+ for dependencies without `files`, and a 422 `pipelex.request.dependency_key_mismatch` naming the address to key it by
+ for a dependency keyed by another address than its manifest's.
"""
if documents.files is None:
if documents.dependencies:
@@ -608,7 +611,11 @@ async def read_request_method(*, documents: TreeDocuments, blob_store: RunnerBlo
declared = dependency_address_of(tree=dependency_tree, fallback_name=dependency_dir_name(address=address), label=label, root=root)
if declared != address:
msg = f"{label} is keyed by an address its {MANIFEST_NAME} does not declare: it declares '{declared}'."
- raise RunnerRequestError(msg, field=DEPENDENCIES_FIELD)
+ raise (
+ RunnerRequestError(msg, field=DEPENDENCIES_FIELD)
+ .with_error_code(PipelexErrorCode.REQUEST_DEPENDENCY_KEY_MISMATCH)
+ .with_params(key=address, address=declared)
+ )
add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=label, root=root)
request_method = RequestMethod(tree=tree, dependencies=dependencies)
ensure_method_within_limits(request_method=request_method, label=_METHOD_LABEL)
diff --git a/api/pipelex_api/routes/pipelex/crate_ops.py b/api/pipelex_api/routes/pipelex/crate_ops.py
index 3eb74dec0..7468530a2 100644
--- a/api/pipelex_api/routes/pipelex/crate_ops.py
+++ b/api/pipelex_api/routes/pipelex/crate_ops.py
@@ -35,6 +35,7 @@ from pipelex.errors.problem import ProblemView
from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_entry_pipe
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe.exceptions import EntryPipeAmbiguousError, EntryPipeNotFoundError, PipeNotFoundError
+from pipelex.libraries.pipe.pipe_suggestions import MAIN_PIPE_DECLARATION
from pipelex.methods.method_ref import looks_like_method_ref
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipeline.exceptions import ValidateBundleError
@@ -233,7 +234,8 @@ class PipeSelectionMiss(NamedTuple):
"""The selector that missed, the request's `pipe_ref` or a declared `main_pipe`; `None` when there was none."""
candidates: list[str] | None = None
- """The qualified refs of the `main_pipe`s the closure declares, when it declares several."""
+ """The qualified refs the refusal offers: the `main_pipe`s the closure declares, when it declares several; the
+ pipes nearest a selector that names none; every pipe of the closure, when it gives no `main_pipe` to start from."""
def resolve_requested_pipe(crate: LibraryCrate, *, pipe_ref: str | None, manifest_main_pipe: str | None) -> RequestedPipe:
@@ -282,15 +284,25 @@ def _raise_selection_refusal(miss: PipeSelectionMiss) -> NoReturn:
several domains is `method.ref_ambiguous`, naming it as the `ref` with its `candidates`, so the refusal
never says a pipe that exists twice does not exist.
"""
+ candidates = miss.candidates or []
match miss.kind:
case PipeSelectionMissKind.NOT_FOUND:
match miss.origin:
case SelectorOrigin.REQUEST:
- raise (EntryPipeNotFoundError(miss.message).with_error_code(CoreCode.REQUEST_PIPE_NOT_FOUND).with_params(pipe=miss.selector))
+ raise (
+ EntryPipeNotFoundError(miss.message)
+ .with_error_code(CoreCode.REQUEST_PIPE_NOT_FOUND)
+ .with_params(pipe=miss.selector, suggestions=candidates)
+ )
case SelectorOrigin.MANIFEST | SelectorOrigin.CLOSURE:
- raise (EntryPipeNotFoundError(miss.message).with_error_code(CoreCode.METHOD_PIPE_UNRESOLVED).with_params(missing=miss.selector))
+ # The reference is the method's `main_pipe` declaration, which no pipe declares: it is the `pipe` naming it.
+ raise (
+ EntryPipeNotFoundError(miss.message)
+ .with_error_code(CoreCode.METHOD_PIPE_UNRESOLVED)
+ .with_params(pipe=MAIN_PIPE_DECLARATION, missing=miss.selector, candidates=candidates)
+ )
case None:
- raise (EntryPipeNotFoundError(miss.message).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED))
+ raise (EntryPipeNotFoundError(miss.message).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED).with_params(candidates=candidates))
case PipeSelectionMissKind.AMBIGUOUS:
match miss.origin:
case SelectorOrigin.REQUEST:
@@ -301,9 +313,7 @@ def _raise_selection_refusal(miss: PipeSelectionMiss) -> NoReturn:
)
case None:
raise (
- EntryPipeAmbiguousError(miss.message)
- .with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED)
- .with_params(candidates=miss.candidates)
+ EntryPipeAmbiguousError(miss.message).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED).with_params(candidates=candidates)
)
case SelectorOrigin.MANIFEST | SelectorOrigin.CLOSURE:
raise (
@@ -342,6 +352,8 @@ def select_default_pipe(crate: LibraryCrate, *, manifest_main_pipe: str | None)
kind=PipeSelectionMissKind.NOT_FOUND,
message="No `pipe_ref` was given and the closure declares no `main_pipe` — name the pipe explicitly.",
origin=None,
+ # With no entry pipe to start from, the request may select any pipe of the closure.
+ candidates=sorted(crate.pipes),
)
if len(candidates) > 1:
joined = ", ".join(sorted(candidates))
@@ -391,7 +403,12 @@ def _select_entry_pipe(selector: str, *, origin: SelectorOrigin) -> RequestedPip
)
except PipeNotFoundError as exc:
return PipeSelectionMiss(
- kind=PipeSelectionMissKind.NOT_FOUND, message=f"{described} not found in {scope}: {exc}", origin=origin, selector=selector
+ kind=PipeSelectionMissKind.NOT_FOUND,
+ message=f"{described} not found in {scope}: {exc}",
+ origin=origin,
+ selector=selector,
+ # The pipes of the closure nearest the selector, which the entry lookup found.
+ candidates=exc.given_params.get("suggestions"),
)
return RequestedPipe(ref=the_pipe.pipe_ref, pipe=the_pipe)
diff --git a/api/pyproject.toml b/api/pyproject.toml
index 2bf19c5c3..e8e7df55d 100644
--- a/api/pyproject.toml
+++ b/api/pyproject.toml
@@ -228,7 +228,10 @@ typeCheckingMode = "strict"
[tool.pytest.ini_options]
addopts = "--import-mode=importlib -ra -m 'not gha_disabled'"
asyncio_default_fixture_loop_scope = "session"
-markers = ["gha_disabled: tests that should not run in GitHub Actions"]
+markers = [
+ "gha_disabled: tests that should not run in GitHub Actions",
+ "builds_problems_without_required_params(reason): the test builds a problem lacking a parameter its code requires on purpose, which the sweep of tests/unit/conftest.py otherwise fails",
+]
minversion = "8.0"
xfail_strict = true
diff --git a/api/tests/unit/conftest.py b/api/tests/unit/conftest.py
index 5a42d71e3..668fdedee 100644
--- a/api/tests/unit/conftest.py
+++ b/api/tests/unit/conftest.py
@@ -9,6 +9,7 @@ from pipelex.methods.method_ref import MethodRef
from pipelex.methods.package_locator import locate_package_in_clone
from pipelex.pipelex import Pipelex
from pipelex.system.runtime import IntegrationMode
+from pipelex.test_extras.required_params_sweep import assert_problems_carried_required_params, spy_on_problem_warnings
from pipelex.test_extras.shared_pytest_plugins import needs_inference_in_pipelex
from pipelex.tools.storage.in_memory_storage_provider import InMemoryStorageProvider
from pytest import FixtureRequest
@@ -18,6 +19,19 @@ from pipelex_api.api_config import get_api_config
from tests.unit._constants import STUB_METHOD_COMMIT_SHA, STUB_METHOD_MANIFEST
[email protected](autouse=True)
+def problems_carry_their_required_params_fixture(request: FixtureRequest, mocker: MockerFixture) -> Generator[None, None, None]:
+ """Fail a test during which a problem or an item was built without a parameter its code requires.
+
+ The sweep of every code the runner emits (`pipelex.test_extras.required_params_sweep`), the library's unit tests
+ running the same one: a test that builds such a problem on purpose says so with the
+ `builds_problems_without_required_params` marker and its reason.
+ """
+ warn_spy = spy_on_problem_warnings(mocker=mocker)
+ yield
+ assert_problems_carried_required_params(warn_spy=warn_spy, keywords=request.keywords)
+
+
@pytest.fixture(autouse=True, name="blob_storage")
def blob_storage_fixture(mocker: MockerFixture) -> InMemoryStorageProvider:
"""Keep each test's blob store in memory: a request's trees are recorded there, and nothing is written to disk."""
diff --git a/api/tests/unit/test_analytics_groups_extras.py b/api/tests/unit/test_analytics_groups_extras.py
index b704f5780..0df35e3eb 100644
--- a/api/tests/unit/test_analytics_groups_extras.py
+++ b/api/tests/unit/test_analytics_groups_extras.py
@@ -145,7 +145,8 @@ class TestAnalyticsGroupsReachTheRun:
body = assert_problem(response, status=422, code="request.invalid")
# The refused field, or a key inside it, which the path names from the field down.
assert body["params"]["field"].split(".")[0] == "analytics_groups", body
- assert [field.split(".")[0] for field in problem_items_fields(body)] == ["analytics_groups"]
+ # A single refused field is the problem itself, with no list restating it.
+ assert "errors" not in body, body
assert orchestrator.run_metadatas == []
def test_a_body_failing_on_two_extras_names_both(self, mocker: MockerFixture) -> None:
diff --git a/api/tests/unit/test_blob_store.py b/api/tests/unit/test_blob_store.py
index 48e07e6db..0b1ae5548 100644
--- a/api/tests/unit/test_blob_store.py
+++ b/api/tests/unit/test_blob_store.py
@@ -296,10 +296,10 @@ class TestProblemScheme:
(StorageMethod.IN_MEMORY, "memory"),
(StorageMethod.S3, "s3"),
(StorageMethod.GCP, "gcs"),
- ("azure", None),
+ ("azure", "plugin"),
],
)
- def test_the_problem_names_the_kind_of_storage_as_the_registry_spells_it(self, storage_method: str, scheme: str | None) -> None:
+ def test_the_problem_names_the_kind_of_storage_as_the_registry_spells_it(self, storage_method: str, scheme: str) -> None:
assert problem_scheme_of(storage_method=storage_method) == scheme
params = problem_of(BlobStoreDamagedError("damaged", scheme=scheme)).get("params")
- assert params == ({"scheme": scheme} if scheme is not None else None)
+ assert params == {"scheme": scheme}
diff --git a/api/tests/unit/test_data.py b/api/tests/unit/test_data.py
index cac74ab15..4a8175d94 100644
--- a/api/tests/unit/test_data.py
+++ b/api/tests/unit/test_data.py
@@ -83,3 +83,134 @@ def rate_limited_failure() -> LLMCompletionError:
).with_error_code(CoreCode.PROVIDER_RATE_LIMITED)
failure.fill_model_and_provider(ProblemTestData.RATE_LIMIT_MODEL, backend_name=ProblemTestData.RATE_LIMIT_BACKEND)
return failure
+
+
+class RequiredParamsTestData:
+ """The methods and trees whose refusals the acceptance of the error contract found without a required parameter."""
+
+ BUNDLE_PATH = "bundle.mthds"
+
+ # A model the vendored inference tree catalogs in `anthropic.toml`, whose backend `backends.toml` disables.
+ UNSERVED_MODEL = "claude-4.5-haiku"
+ UNSERVED_MODEL_MTHDS = f"""\
+domain = "smoke"
+main_pipe = "echo"
+
+[pipe.echo]
+type = "PipeLLM"
+description = "Echo"
+inputs = {{ text = "Text" }}
+output = "Text"
+model = "{UNSERVED_MODEL}"
+prompt = "@text"
+"""
+
+ # A model reference one letter away from a handle the deck serves, so the refusal has a suggestion to offer.
+ NEAR_MODEL = "gpt-4o-mimi"
+ NEAR_MODEL_SUGGESTION = "gpt-4o-mini"
+ NEAR_MODEL_MTHDS = f"""\
+domain = "smoke"
+main_pipe = "echo"
+
+[pipe.echo]
+type = "PipeLLM"
+description = "Echo"
+inputs = {{ text = "Text" }}
+output = "Text"
+model = "{NEAR_MODEL}"
+prompt = "@text"
+"""
+
+ ECHO_MTHDS = """\
+domain = "smoke"
+main_pipe = "echo"
+
+[pipe.echo]
+type = "PipeLLM"
+description = "Echo"
+inputs = { text = "Text" }
+output = "Text"
+prompt = "@text"
+"""
+
+ UNKNOWN_CONCEPT_MTHDS = """\
+domain = "smoke"
+main_pipe = "make_thing"
+
+[concept.Thing]
+description = "A thing"
+
+[pipe.make_thing]
+type = "PipeLLM"
+description = "Make a thing"
+inputs = { text = "Text" }
+output = "Thingg"
+prompt = "@text"
+"""
+
+ TEMPLATE_REFUSED_MTHDS = """\
+domain = "smoke"
+main_pipe = "say"
+
+[pipe.say]
+type = "PipeCompose"
+description = "Say"
+inputs = { text = "Text" }
+output = "Text"
+template = "Talk about {{ text['_owner'] }}"
+"""
+
+ NATIVE_REDECLARATION_MTHDS = """\
+domain = "smoke"
+main_pipe = "echo"
+
+[concept.Rating]
+description = "A rating, declared again"
+
+[pipe.echo]
+type = "PipeLLM"
+description = "Echo"
+inputs = { text = "Text" }
+output = "Text"
+prompt = "@text"
+"""
+
+ DUPLICATE_BUNDLES: ClassVar[dict[str, str]] = {
+ "first/declares.mthds": 'domain = "dup"\n\n[concept]\nDoc = "A document, as the first bundle declares it"\n',
+ "second/declares.mthds": 'domain = "dup"\n\n[concept]\nDoc = "A document, as the second bundle declares it"\n',
+ }
+ # The same collision in a method a run can start: the first bundle names its main pipe.
+ DUPLICATE_RUNNABLE_BUNDLES: ClassVar[dict[str, str]] = {
+ "first/declares.mthds": (
+ 'domain = "dup"\nmain_pipe = "echo"\n\n[concept]\nDoc = "A document, as the first bundle declares it"\n\n'
+ '[pipe.echo]\ntype = "PipeCompose"\ndescription = "Echo"\ninputs = { text = "Text" }\noutput = "Text"\ntemplate = "{{ text }}"\n'
+ ),
+ "second/declares.mthds": 'domain = "dup"\n\n[concept]\nDoc = "A document, as the second bundle declares it"\n',
+ }
+
+ DEPENDENCY_REPOSITORY_ADDRESS = "github.com/invented/probe-lib"
+ DEPENDENCY_ADDRESS = f"{DEPENDENCY_REPOSITORY_ADDRESS}/probe"
+ DEPENDENCY_TREE: ClassVar[dict[str, str]] = {
+ "METHODS.toml": (
+ "[package]\n"
+ 'name = "probe"\n'
+ f'address = "{DEPENDENCY_REPOSITORY_ADDRESS}"\n'
+ 'version = "0.1.0"\n'
+ 'description = "An invented package a request ships beside its method"\n'
+ ),
+ "probe.mthds": (
+ 'domain = "probe_dep"\n\n[pipe.entry]\ntype = "PipeLLM"\ndescription = "Entry"\ninputs = { text = "Text" }\n'
+ 'output = "Text"\nprompt = "@text"\n'
+ ),
+ }
+ CALLER_MTHDS = f"""\
+domain = "caller"
+main_pipe = "call_probe"
+
+[pipe.call_probe]
+type = "PipeSequence"
+description = "Call the probe"
+inputs = {{ text = "Text" }}
+output = "Text"
+steps = [{{ pipe = "{DEPENDENCY_ADDRESS}->probe_dep.entry", result = "out" }}]
+"""
diff --git a/api/tests/unit/test_error_responses.py b/api/tests/unit/test_error_responses.py
index 805b80a57..bf7235214 100644
--- a/api/tests/unit/test_error_responses.py
+++ b/api/tests/unit/test_error_responses.py
@@ -24,7 +24,7 @@ from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware, reque
from pipelex_api.routes import router as api_router
from pipelex_api.routes.version import router as version_router
from pipelex_api.security import RequestUser, get_request_user, verify_api_key
-from tests.unit._problems import assert_problem, problem_items_fields
+from tests.unit._problems import assert_problem
USER_A = "aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa"
USER_B = "bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb"
@@ -77,7 +77,8 @@ class TestErrorResponses:
body = assert_problem(response, status=422, code="request.invalid", field="mthds_contents")
assert body["domain"] == "input"
assert body["detail"] == "The request's field 'mthds_contents' does not match the route's schema."
- assert problem_items_fields(body) == ["mthds_contents"]
+ # A single refused field is the problem itself, with no list restating it.
+ assert "errors" not in body, body
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
assert body["retry"] == "no"
diff --git a/api/tests/unit/test_exception_handlers.py b/api/tests/unit/test_exception_handlers.py
index bfbdf50c6..b4049ea79 100644
--- a/api/tests/unit/test_exception_handlers.py
+++ b/api/tests/unit/test_exception_handlers.py
@@ -228,7 +228,7 @@ async def pipeline_run_id_conflict_route() -> None:
# Pipelex raises this from ``add_new_pipeline`` when a submission reuses a ``pipeline_run_id``
# that is still registered; its code, `pipelex.run.already_exists`, declares 409.
msg = "Pipeline some-run-id already exists"
- raise PipelineManagerAlreadyExistsError(msg)
+ raise PipelineManagerAlreadyExistsError(msg).with_params(pipeline_run_id="some-run-id")
@_router.get("/method-package-symlink")
@@ -534,6 +534,9 @@ class TestExceptionHandlers:
}
@pytest.mark.parametrize("case", list(ProblemTestData.RETRY_CASES))
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a crafted retryable failure checks the Retry-After header, which no parameter decides"
+ )
def test_retry_after_header_is_guarded(self, case: str):
"""`Retry-After` rides a 429 alone, and only when the delay is a finite, non-negative number, rounded up."""
_, _, expected_status, expected_header, expected_retry_after = ProblemTestData.RETRY_CASES[case]
@@ -546,6 +549,7 @@ class TestExceptionHandlers:
assert response.json().get("retry_after") == expected_retry_after
@pytest.mark.parametrize(("code", "expected_status"), ProblemTestData.CODE_STATUSES)
+ @pytest.mark.builds_problems_without_required_params(reason="checks the status each code declares, which no parameter decides")
def test_the_status_is_the_one_the_code_declares(self, mocker: MockerFixture, code: ErrorCode, expected_status: int):
"""The response's status, the body's `status` member and the record's are the registry's, one value for all three."""
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
@@ -763,6 +767,7 @@ class TestExceptionHandlers:
(429, 429, "runtime.unavailable", "Retry-After"),
],
)
+ @pytest.mark.builds_problems_without_required_params(reason="a refusal the framework raises carries none of the facts its code names")
def test_a_framework_4xx_keeps_its_meaning(self, mocker: MockerFixture, raised_status: int, status: int, code: str, kept_header: str | None):
# Only a 400 or a 422 is a request the framework could not read: every other 4xx is answered under the code whose
# status and meaning match it, or keeps its status, never as a malformed request.
@@ -1012,6 +1017,7 @@ class TestExceptionHandlers:
("/inference-failure-unattributed", None),
],
)
+ @pytest.mark.builds_problems_without_required_params(reason="an inference failure no backend is attributed to names no provider")
def test_backend_name_is_only_ever_the_backend_the_error_names(self, mocker: MockerFixture, path: str, expected_backend_name: str | None):
"""The provider the SDK's metadata names, `gateway`, is no backend's name: it is never written under `backend_name`, nor under `sdk`."""
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
diff --git a/api/tests/unit/test_method_ref_run.py b/api/tests/unit/test_method_ref_run.py
index d253610c9..3d81236f8 100644
--- a/api/tests/unit/test_method_ref_run.py
+++ b/api/tests/unit/test_method_ref_run.py
@@ -23,6 +23,7 @@ from mthds.protocol.problem.registry import CoreCode
from pipelex.errors.error_codes import ErrorCode, error_code_spec
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.methods.exceptions import MethodFetchError
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.pipeline.pipeline_response import PipelexRunResultStart, RunState
from pytest_mock import MockerFixture
@@ -231,19 +232,21 @@ class TestMethodRefRun:
assert STUB_METHOD_ADDRESS in problem["diagnostics"]["message"]
@pytest.mark.parametrize(
- ("code", "expected_status"),
+ ("code", "params", "expected_status"),
[
- (CoreCode.METHOD_FETCH_FAILED, 502),
- (CoreCode.METHOD_NOT_FOUND, 404),
- (CoreCode.METHOD_PACKAGE_INVALID, 422),
- (PipelexErrorCode.CONFIG_DEPENDENCY_MISSING, 500),
+ (CoreCode.METHOD_FETCH_FAILED, {}, 502),
+ (CoreCode.METHOD_NOT_FOUND, {}, 404),
+ (CoreCode.METHOD_PACKAGE_INVALID, {"reason": MethodPackageReason.MANIFEST_INVALID}, 422),
+ (PipelexErrorCode.CONFIG_DEPENDENCY_MISSING, {}, 500),
],
)
- def test_a_fetch_failure_answers_the_status_of_its_code(self, mocker: MockerFixture, code: ErrorCode, expected_status: int):
+ def test_a_fetch_failure_answers_the_status_of_its_code(
+ self, mocker: MockerFixture, code: ErrorCode, params: dict[str, Any], expected_status: int
+ ):
"""A failed fetch answers whatever code its raise site chose, with that code's status from the error registry."""
fetch_error = MethodFetchError(f"Failed to fetch method '{STUB_METHOD_ADDRESS}': boom").for_method_ref(method_ref=STUB_METHOD_ADDRESS)
stub_cache = mocker.MagicMock()
- stub_cache.pinned_package.side_effect = fetch_error.with_error_code(code)
+ stub_cache.pinned_package.side_effect = fetch_error.with_error_code(code).with_params(**params)
mocker.patch("pipelex_api.method_source.get_method_clone_cache", return_value=stub_cache)
client, _ = _build_client(mocker)
response = client.post("/v1/execute", json={"method_ref": STUB_METHOD_ADDRESS, "inputs": {}})
diff --git a/api/tests/unit/test_method_requirements_refusal.py b/api/tests/unit/test_method_requirements_refusal.py
index 3144ec0ba..e05010f7e 100644
--- a/api/tests/unit/test_method_requirements_refusal.py
+++ b/api/tests/unit/test_method_requirements_refusal.py
@@ -15,7 +15,7 @@ from pathlib import Path
import pytest
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodDependencyMissingKind, MethodDependencyMissingReason
from pipelex.config import get_config
from pipelex.errors.bundle_validation_failure import BundleValidationFailure
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
@@ -264,7 +264,9 @@ class TestMethodRequirementsRefusal:
else:
threads_holding_a_loop.append(True)
msg = "The method needs Python packages."
- raise MethodRequirementsNotMetError(msg, items=[])
+ raise MethodRequirementsNotMetError(msg, items=[]).with_params(
+ kind=MethodDependencyMissingKind.REQUIREMENT, name="pandas", reason=MethodDependencyMissingReason.NOT_FOUND
+ )
mocker.patch(f"{_PIPELINE_NS}.ensure_served_method_requirements_met", side_effect=refuse_after_noting_the_thread)
validator = _UnreachableValidator()
diff --git a/api/tests/unit/test_models_check_route.py b/api/tests/unit/test_models_check_route.py
index 99cb64b64..40a6c66c1 100644
--- a/api/tests/unit/test_models_check_route.py
+++ b/api/tests/unit/test_models_check_route.py
@@ -94,7 +94,7 @@ class TestModelsCheckRoute:
assert report["is_valid"] is False
(item,) = report["errors"]
assert item["code"] == "model.unknown"
- assert item["params"] == {"model": llm_handle, "model_type": "img_gen"}
+ assert item["params"] == {"model": llm_handle, "model_type": "img_gen", "suggestions": []}
assert item["location"]["field"] == "model"
def test_doc_gen_is_a_category_of_the_check(self):
diff --git a/api/tests/unit/test_pipe_io_route.py b/api/tests/unit/test_pipe_io_route.py
index 03f1ee773..036c3b647 100644
--- a/api/tests/unit/test_pipe_io_route.py
+++ b/api/tests/unit/test_pipe_io_route.py
@@ -21,7 +21,7 @@ from fastapi.testclient import TestClient
from mthds.protocol.problem.registry import CoreCode
from pipelex.errors.problem import ProblemView, make_problem
from pipelex.interpreter_hub import get_library_manager
-from pipelex.pipeline.exceptions import PipeIOContractError
+from pipelex.pipeline.exceptions import SCHEMA_UNRENDERABLE_FINDING, PipeIOContractError
from pytest_mock import MockerFixture
from pipelex_api.exception_handlers import register_exception_handlers
@@ -238,7 +238,10 @@ class TestPipeIoRoute:
_assert_keys(body, {"other.shout"})
response = _build_client(as_operator=True).post(PIPE_IO_PATH, json={"method_ref": STUB_METHOD_REF})
# The author's manifest names a pipe the method lacks: the method's fault, not the caller's selector.
- problem = _assert_selection_refusal(response, code=CoreCode.METHOD_PIPE_UNRESOLVED, params={"missing": "echo"})
+ # The refusal names the declaration that holds the reference, the manifest's `main_pipe`, and no pipe is near `echo`.
+ problem = _assert_selection_refusal(
+ response, code=CoreCode.METHOD_PIPE_UNRESOLVED, params={"pipe": "main_pipe", "missing": "echo", "candidates": []}
+ )
assert problem["domain"] == "method"
assert problem["diagnostics"]["error_class"] == "EntryPipeNotFoundError"
message = problem["diagnostics"]["message"]
@@ -377,7 +380,7 @@ class TestPipeIoRoute:
(VALID_MTHDS,),
{"pipe_ref": "smoke.not_a_pipe"},
CoreCode.REQUEST_PIPE_NOT_FOUND,
- {"pipe": "smoke.not_a_pipe"},
+ {"pipe": "smoke.not_a_pipe", "suggestions": []},
("EntryPipeNotFoundError", "not found"),
id="unknown-ref",
),
@@ -385,15 +388,16 @@ class TestPipeIoRoute:
(VALID_MTHDS,),
{"pipe_ref": "smoke.not_a_pipe", "all_pipes": True},
CoreCode.REQUEST_PIPE_NOT_FOUND,
- {"pipe": "smoke.not_a_pipe"},
+ {"pipe": "smoke.not_a_pipe", "suggestions": []},
("EntryPipeNotFoundError", "not found"),
id="unknown-ref-under-all-pipes",
),
pytest.param(
(NO_MAIN_PIPE_MTHDS,),
{},
+ # The caller may select any pipe the method declares.
CoreCode.REQUEST_PIPE_UNSPECIFIED,
- {},
+ {"candidates": ["nomain.echo"]},
("EntryPipeNotFoundError", "declares no `main_pipe`"),
id="no-entry-pipe",
),
@@ -487,7 +491,7 @@ class TestPipeIoRoute:
install_method_package(files={"documents.mthds": NO_MAIN_PIPE_MTHDS}, manifest_toml=STUB_METHOD_MANIFEST_NO_MAIN_PIPE)
client = _build_client()
response = client.post(PIPE_IO_PATH, json={"method_ref": STUB_METHOD_REF})
- _assert_selection_refusal(response, code=CoreCode.REQUEST_PIPE_UNSPECIFIED, params={})
+ _assert_selection_refusal(response, code=CoreCode.REQUEST_PIPE_UNSPECIFIED, params={"candidates": ["nomain.echo"]})
@pytest.mark.parametrize(
("contents", "request_fields"),
@@ -578,7 +582,9 @@ class TestPipeIoRoute:
# described. The library is still torn down.
mocker.patch(
"pipelex_api.routes.pipelex.pipe_io.build_pipe_io_artifacts",
- side_effect=PipeIOContractError(message="Failed to render the JSON Schema for the output of pipe 'smoke.echo'"),
+ side_effect=PipeIOContractError(message="Failed to render the JSON Schema for the output of pipe 'smoke.echo'").with_params(
+ concept="native.Text", finding=SCHEMA_UNRENDERABLE_FINDING
+ ),
)
library_manager = get_library_manager()
open_spy = mocker.spy(library_manager, "open_library")
diff --git a/api/tests/unit/test_pipeline_bundle.py b/api/tests/unit/test_pipeline_bundle.py
index 1407a3e3d..ee06ae88e 100644
--- a/api/tests/unit/test_pipeline_bundle.py
+++ b/api/tests/unit/test_pipeline_bundle.py
@@ -382,7 +382,10 @@ class TestPipelineBundle:
response = client.post("/v1/execute", json={**body, "inputs": {"text": "hi"}})
- assert_problem(response, status=422, code="request.invalid", field="dependencies")
+ problem = assert_problem(response, status=422, code="pipelex.request.dependency_key_mismatch")
+ # The refusal names the key the request gave and the address the manifest declares, which the key must be.
+ assert problem["params"] == {"key": "github.com/invented/elsewhere/probe", "address": VENDORED_PROBE_ADDRESS}
+ assert problem["location"] == {"field": "dependencies"}
assert snapshot == {}, "the runner was reached"
def test_dependencies_without_files_are_refused(self, mocker: MockerFixture):
diff --git a/api/tests/unit/test_pipeline_routes.py b/api/tests/unit/test_pipeline_routes.py
index 2a652dacb..078b025b0 100644
--- a/api/tests/unit/test_pipeline_routes.py
+++ b/api/tests/unit/test_pipeline_routes.py
@@ -14,7 +14,7 @@ from pipelex.base_exceptions import PipelexConfigError
from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
-from pipelex.errors.problem import ProblemView
+from pipelex.errors.problem import MISSING_REQUIRED_PARAMS_MESSAGE, ProblemView
from pipelex.pipeline.pipeline_response import PipelexRunResultStart, RunState
from pipelex.system.job_metadata import JobMetadata, RunMetadata
from pipelex.system.storage_scope import SINGLE_TENANT_USER_ID
@@ -445,17 +445,20 @@ class TestPipelineRoutes:
log_spy.assert_not_called()
start_mock.assert_not_awaited()
+ @pytest.mark.builds_problems_without_required_params(reason="a refusal stating no class of destination has no `target_class` to give")
def test_a_callback_refusal_naming_no_class_leaves_the_parameter_out(self, mocker: MockerFixture):
# A refusal that states no class of destination gives no `target_class`, rather than a `None` for its code to
- # refuse, so no parameter is dropped and logged.
+ # refuse, so no parameter is dropped and logged; the problem logs instead that it lacks the parameter.
warn_spy = mocker.patch("pipelex.errors.problem._warn")
refusal = CallbackUrlRefusedError("callback URL host is not allowed")
assert "target_class" not in refusal.problem_params()
problem = refusal.to_problem(view=ProblemView.OPERATOR)
assert problem.params is not None
assert "target_class" not in problem.params.as_wire()
- dropped = [call for call in warn_spy.call_args_list if "parameter" in call.kwargs["message"]]
+ dropped = [call for call in warn_spy.call_args_list if "gives a parameter" in call.kwargs["message"]]
assert not dropped, dropped
+ lacking = [call.kwargs["fields"]["params"] for call in warn_spy.call_args_list if call.kwargs["message"] == MISSING_REQUIRED_PARAMS_MESSAGE]
+ assert lacking == [["target_class"]], warn_spy.call_args_list
def test_start_rejects_too_many_callbacks(self, mocker: MockerFixture):
client, _, start_mock = _build_client(mocker)
diff --git a/api/tests/unit/test_problem_required_params.py b/api/tests/unit/test_problem_required_params.py
new file mode 100644
index 000000000..46a25d29d
--- /dev/null
+++ b/api/tests/unit/test_problem_required_params.py
@@ -0,0 +1,134 @@
+"""The runner's problems and items carry every parameter their code requires, and a single fault carries no list.
+
+Each case sends a request the acceptance of the error contract found answered without a parameter its code's registry
+entry requires, or with a one-item `errors` list restating the problem, and asserts that the document names what a
+caller acts on: the parameters its sentence and its next step are rendered from, and its location. The autouse fixture
+of `conftest.py` sweeps every other test of this suite for the same class of defect.
+"""
+
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.routes import router as api_router
+from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, UNKNOWN_MODEL_MTHDS
+from tests.unit._problems import assert_problem
+from tests.unit.test_data import RequiredParamsTestData as Data
+
+
+def _build_client() -> TestClient:
+ app = FastAPI()
+ app.include_router(api_router, prefix="/v1")
+ register_exception_handlers(app)
+ return TestClient(app)
+
+
+def _invalid_items(response_body: dict[str, Any], *, code: str) -> list[dict[str, Any]]:
+ """The items of an invalid verdict under one code."""
+ assert response_body["is_valid"] is False, response_body
+ return [item for item in response_body["errors"] if item["code"] == code]
+
+
+class TestProblemRequiredParams:
+ def test_a_model_no_enabled_backend_serves_is_unavailable_on_execute(self):
+ response = _build_client().post("/v1/execute", json={"files": {Data.BUNDLE_PATH: Data.UNSERVED_MODEL_MTHDS}, "inputs": {"text": "x"}})
+ problem = assert_problem(response, status=501, code="model.unavailable")
+ assert problem["params"] == {"model": Data.UNSERVED_MODEL, "model_type": "llm", "reason": "not_served"}
+ assert problem["location"] == {"pipe": "echo", "field": "model", "file": Data.BUNDLE_PATH}
+ assert "errors" not in problem, problem
+
+ def test_a_model_no_enabled_backend_serves_is_unavailable_on_validate(self):
+ # Not a verdict: the method is sound, and this deployment cannot run it.
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: Data.UNSERVED_MODEL_MTHDS}})
+ problem = assert_problem(response, status=501, code="model.unavailable")
+ assert problem["params"] == {"model": Data.UNSERVED_MODEL, "model_type": "llm", "reason": "not_served"}
+ assert problem["location"] == {"pipe": "echo", "field": "model", "file": Data.BUNDLE_PATH}
+
+ def test_a_model_no_catalog_knows_offers_the_nearest_handles(self):
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: Data.NEAR_MODEL_MTHDS}})
+ assert response.status_code == 200, response.text
+ (item,) = _invalid_items(response.json(), code="model.unknown")
+ assert item["params"]["model"] == Data.NEAR_MODEL
+ assert item["params"]["model_type"] == "llm"
+ assert Data.NEAR_MODEL_SUGGESTION in item["params"]["suggestions"], item
+ assert item["location"] == {"pipe": "echo", "field": "model", "file": Data.BUNDLE_PATH}
+
+ def test_a_model_near_no_handle_offers_an_empty_list(self):
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: UNKNOWN_MODEL_MTHDS}})
+ (item,) = _invalid_items(response.json(), code="model.unknown")
+ assert item["params"] == {"model": "no-such-model-in-any-deck", "model_type": "llm", "suggestions": []}
+
+ def test_an_invalid_main_pipe_names_its_kind_and_the_name(self):
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: INVALID_MAIN_PIPE_MTHDS}})
+ assert response.status_code == 200, response.text
+ (item,) = _invalid_items(response.json(), code="method.identifier_invalid")
+ assert item["params"] == {"identifier_kind": "main_pipe", "name": "Not A Valid Pipe Code!"}
+ assert item["location"]["file"] == Data.BUNDLE_PATH
+
+ def test_a_selected_pipe_the_method_lacks_offers_the_nearest(self):
+ body = {"files": {Data.BUNDLE_PATH: Data.ECHO_MTHDS}, "pipe_code": "ecoh", "inputs": {"text": "x"}}
+ response = _build_client().post("/v1/execute", json=body)
+ problem = assert_problem(response, status=422, code="request.pipe_not_found")
+ assert problem["params"] == {"pipe": "ecoh", "suggestions": ["smoke.echo"]}
+ assert "errors" not in problem, problem
+
+ def test_an_unresolved_concept_offers_the_nearest_declared(self):
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: Data.UNKNOWN_CONCEPT_MTHDS}})
+ assert response.status_code == 200, response.text
+ items = _invalid_items(response.json(), code="method.concept_unresolved")
+ assert items, response.text
+ assert items[0]["params"]["concept"].endswith("Thingg"), items
+ assert items[0]["params"]["suggestions"] == ["Thing"], items
+
+ def test_models_check_answers_one_refusal_without_a_list(self):
+ response = _build_client().get("/v1/models/check")
+ problem = assert_problem(response, status=422, code="request.invalid", field="reference")
+ assert "errors" not in problem, problem
+
+ def test_a_template_the_sandbox_refuses_names_what_it_reached_for(self):
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: Data.TEMPLATE_REFUSED_MTHDS}})
+ problem = assert_problem(response, status=422, code="security.template_refused")
+ assert problem["params"] == {"pipe": "say", "name": "_owner"}
+ assert problem["detail"] == "A template of pipe 'say' reached for '_owner', which the template sandbox forbids."
+ assert problem["location"]["pipe"] == "say"
+ assert "errors" not in problem, problem
+
+ def test_a_native_concept_redeclared_names_the_concept_and_the_conflict(self):
+ response = _build_client().post("/v1/validate", json={"files": {Data.BUNDLE_PATH: Data.NATIVE_REDECLARATION_MTHDS}})
+ assert response.status_code == 200, response.text
+ (item,) = _invalid_items(response.json(), code="method.name_conflict")
+ assert item["params"] == {"name": "Rating", "conflict": "native_concept"}
+ assert item["location"] == {"field": "concept.Rating", "file": Data.BUNDLE_PATH}
+
+ def test_a_concept_two_bundles_declare_names_both_bundles(self):
+ response = _build_client().post("/v1/validate", json={"files": Data.DUPLICATE_BUNDLES})
+ assert response.status_code == 200, response.text
+ items = _invalid_items(response.json(), code="method.name_conflict")
+ assert sorted(item["location"]["file"] for item in items) == sorted(Data.DUPLICATE_BUNDLES), items
+ for item in items:
+ assert item["params"] == {"name": "dup.Doc", "conflict": "duplicate_declaration"}, item
+ assert item["location"]["field"] == "concept.Doc", item
+
+ def test_a_run_refused_for_a_native_concept_redeclared_locates_the_declaration(self):
+ body = {"files": {Data.BUNDLE_PATH: Data.NATIVE_REDECLARATION_MTHDS}, "inputs": {"text": "x"}}
+ problem = assert_problem(_build_client().post("/v1/execute", json=body), status=422, code="method.invalid")
+ (item,) = [item for item in problem["errors"] if item["code"] == "method.name_conflict"]
+ assert item["params"] == {"name": "Rating", "conflict": "native_concept"}
+ assert item["location"] == {"field": "concept.Rating", "file": Data.BUNDLE_PATH}
+
+ def test_a_run_refused_for_a_concept_two_bundles_declare_locates_both_declarations(self):
+ body = {"files": Data.DUPLICATE_RUNNABLE_BUNDLES, "inputs": {"text": "x"}}
+ problem = assert_problem(_build_client().post("/v1/execute", json=body), status=422, code="method.invalid")
+ items = [item for item in problem["errors"] if item["code"] == "method.name_conflict"]
+ assert sorted((item["location"]["file"], item["location"]["field"]) for item in items) == [
+ (path, "concept.Doc") for path in sorted(Data.DUPLICATE_RUNNABLE_BUNDLES)
+ ], items
+
+ def test_a_dependency_keyed_by_its_repository_address_names_the_address_to_key_it_by(self):
+ body = {"files": {Data.BUNDLE_PATH: Data.CALLER_MTHDS}, "dependencies": {Data.DEPENDENCY_REPOSITORY_ADDRESS: Data.DEPENDENCY_TREE}}
+ response = _build_client().post("/v1/validate", json=body)
+ problem = assert_problem(response, status=422, code="pipelex.request.dependency_key_mismatch")
+ assert problem["params"] == {"key": Data.DEPENDENCY_REPOSITORY_ADDRESS, "address": Data.DEPENDENCY_ADDRESS}
+ assert problem["location"] == {"field": "dependencies"}
diff --git a/api/tests/unit/test_run_refusals.py b/api/tests/unit/test_run_refusals.py
index 21c58baa2..c35eba29f 100644
--- a/api/tests/unit/test_run_refusals.py
+++ b/api/tests/unit/test_run_refusals.py
@@ -84,7 +84,7 @@ class TestRunRefusals:
{
"code": CoreCode.METHOD_CONCEPT_UNRESOLVED,
"detail": "The method names the concept 'Summry', which no library declares.",
- "params": {"concept": "Summry"},
+ "params": {"concept": "Summry", "suggestions": []},
"location": {"pipe": "echo", "field": "output"},
},
),
@@ -93,7 +93,7 @@ class TestRunRefusals:
{
"code": CoreCode.MODEL_UNKNOWN,
"detail": "The method names the llm model 'no-such-model-in-any-deck', which no catalog knows.",
- "params": {"model": "no-such-model-in-any-deck", "model_type": "llm"},
+ "params": {"model": "no-such-model-in-any-deck", "model_type": "llm", "suggestions": []},
"location": {"pipe": "echo", "field": "model"},
},
),
diff --git a/api/tests/unit/test_validate_caller_identity.py b/api/tests/unit/test_validate_caller_identity.py
index 165f505e7..725f58f17 100644
--- a/api/tests/unit/test_validate_caller_identity.py
+++ b/api/tests/unit/test_validate_caller_identity.py
@@ -172,7 +172,8 @@ class TestValidationCallerIdentity:
body = assert_problem(response, status=422, code="request.invalid")
# The refused field, or a key inside it, which the path names from the field down.
- assert [field.split(".")[0] for field in problem_items_fields(body)] == ["analytics_groups"]
+ # A single refused field is the problem itself, with no list restating it.
+ assert "errors" not in body, body
assert validator.caller_identities == []
def test_validate_failing_on_two_fields_names_both(self, mocker: MockerFixture) -> None:
diff --git a/api/tests/unit/test_validate_dispatch.py b/api/tests/unit/test_validate_dispatch.py
index 135d2abb8..477275a68 100644
--- a/api/tests/unit/test_validate_dispatch.py
+++ b/api/tests/unit/test_validate_dispatch.py
@@ -103,7 +103,7 @@ def _register_stub_for_temporal(mocker: MockerFixture, stub: _StubBundleValidato
class TestValidateDispatch:
def test_non_direct_validators_invalid_verdict_maps_to_200_invalid_report(self, mocker: MockerFixture) -> None:
"""A non-direct validator's returned failure with items is mapped to a 200 InvalidReport, threading the request."""
- bad_ref = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="bad ref")
+ bad_ref = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="bad ref", field_path="main_pipe")
invalid_verdict = BundleValidationFailure(
problem=make_problem(
code=CoreCode.METHOD_INVALID,
@@ -123,7 +123,12 @@ class TestValidateDispatch:
assert body["is_valid"] is False
# The verdict's items, as the validator built them, each with its code, its sentence and its parameters.
assert body["errors"] == [
- {"code": "method.schema_violation", "detail": error_code_spec(CoreCode.METHOD_SCHEMA_VIOLATION).title, "params": {"finding": "bad ref"}}
+ {
+ "code": "method.schema_violation",
+ "detail": "The declaration at 'main_pipe' breaks a rule of the language (bad ref).",
+ "params": {"field_path": "main_pipe", "finding": "bad ref"},
+ "location": {"field": "main_pipe"},
+ }
]
assert body["message"] == error_code_spec(CoreCode.METHOD_INVALID).detail
# The dispatch reached the registered non-direct validator, with the request threaded through.
diff --git a/api/tests/unit/test_validate_errors.py b/api/tests/unit/test_validate_errors.py
index b1378ca44..94507e6c9 100644
--- a/api/tests/unit/test_validate_errors.py
+++ b/api/tests/unit/test_validate_errors.py
@@ -20,6 +20,7 @@ Asserts the in-process wire response via `TestClient`; the conformance HTTP arm
from typing import Any
+import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from mthds.protocol.problem.registry import CoreCode
@@ -100,6 +101,7 @@ def _multi_category_error() -> ValidateBundleError:
field_name="output",
field_path="pipe.summarize.output",
message="Output concept is inadequate.",
+ params={"declared": "Summary", "expected": ["Contract"], "pipe_type": "PipeLLM"},
)
],
)
@@ -183,7 +185,7 @@ class TestValidateErrors:
assert len(items) == 1, items
item = items[0]
assert item["code"] == "model.unknown"
- assert item["params"] == {"model": "no-such-model-in-any-deck", "model_type": "llm"}
+ assert item["params"] == {"model": "no-such-model-in-any-deck", "model_type": "llm", "suggestions": []}
assert item["location"] == {"pipe": "echo", "field": "model", "file": "echo.mthds"}
assert item["detail"] == "The method names the llm model 'no-such-model-in-any-deck', which no catalog knows."
@@ -209,10 +211,14 @@ class TestValidateErrors:
# The union of members across the items covers every member of a problem item and every locator.
assert {key for item in items for key in item} == {"code", "detail", "params", "location"}
assert {key for item in items for key in item.get("location", {})} == {"pipe", "field", "file"}
- undeclared, unresolved, _ = items
+ undeclared, unresolved, mismatched = items
assert undeclared["params"] == {"pipe": "summarize", "variables": ["contract"]}
- assert unresolved["params"] == {"concept": "Summari"}
+ # The concepts the domain declares nearest the one that resolves to nothing are offered in its place.
+ assert unresolved["params"] == {"concept": "Summari", "suggestions": ["Summary"]}
+ # The facts the raise site gave ride the item beside those its locators give.
+ assert mismatched["params"] == {"pipe": "summarize", "declared": "Summary", "expected": ["Contract"], "pipe_type": "PipeLLM"}
+ @pytest.mark.builds_problems_without_required_params(reason="a dry-run failure the sweep could not locate names no pipe")
def test_dry_run_failures_become_one_located_item_per_failing_pipe(self, mocker: MockerFixture):
# A failing dry run is one `dry_run` item per failing pipe, located at the innermost pipe
# that failed (its `pipe_code`, `domain_code` and `source`), never one item holding the whole
@@ -228,8 +234,11 @@ class TestValidateErrors:
domain_code="legal",
source="pipe.mthds",
message="Pipe 'summarize' failed: boom.",
+ params={"variable_path": "contract.title"},
+ ),
+ DryRunFailureErrorData(
+ code=CoreCode.METHOD_WIRING_INVALID, message="Dry run failed: unlocated.", params={"variable_path": "contract"}
),
- DryRunFailureErrorData(code=CoreCode.METHOD_WIRING_INVALID, message="Dry run failed: unlocated."),
],
)
mocker.patch.object(ApiRunner, "validate_verdict", new=mocker.AsyncMock(return_value=_failure_of(failing_dry_run)))
@@ -246,7 +255,7 @@ class TestValidateErrors:
located_item, unlocated_item = items
assert located_item["location"] == {"pipe": "summarize", "file": "pipe.mthds"}
assert located_item["params"]["finding"] == "Pipe 'summarize' failed: boom."
- assert unlocated_item["params"] == {"finding": "Dry run failed: unlocated."}
+ assert unlocated_item["params"] == {"finding": "Dry run failed: unlocated.", "variable_path": "contract"}
assert "location" not in unlocated_item, unlocated_item
def test_non_verdict_failure_is_not_a_200_verdict(self, mocker: MockerFixture):
diff --git a/api/tests/unit/test_validate_render.py b/api/tests/unit/test_validate_render.py
index a8bf9f686..8d988f17f 100644
--- a/api/tests/unit/test_validate_render.py
+++ b/api/tests/unit/test_validate_render.py
@@ -55,7 +55,7 @@ class _InvalidVerdictValidator:
methods_dirs: Sequence[Path] | None, # noqa: ARG002
read_scope: str | None, # noqa: ARG002
) -> BundleValidationFailure:
- located_item = make_problem_item(code=CoreCode.METHOD_SCHEMA_VIOLATION)
+ located_item = make_problem_item(code=CoreCode.METHOD_SCHEMA_VIOLATION, params={"field_path": "pipe.echo", "finding": "it is not a pipe"})
# Built by hand, as a stored record read back may be, with a parameter only the operator reads.
read_back_item = ProblemItem.model_validate(
{
diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.md
index c35402111..d773cce68 100644
--- a/docs/api-server/error-responses.md
+++ b/docs/api-server/error-responses.md
@@ -49,9 +49,9 @@ A failure the runtime raised looks like this, in the caller view:
- `retry` — whether repeating the same request can succeed: `yes`, as for an inference provider's rate limit; `no`; or `outcome_unknown`, when the request may have taken effect. A client retries blindly only on `yes`.
- `retry_after` — on a code whose verdict is `yes`, the delay in seconds the provider asked for before a retry. A `429` also carries it as a `Retry-After` header, rounded up.
- `next_step` — what the reader does next: its `kind`, such as `change_input`, `change_method`, `change_model`, `wait`, `retry`, `fix_configuration` or `report`, and its `detail`, a sentence rendered from the code's template. The step is the reader's own, so the caller view and the operator view of one failure can give different steps.
-- `params` — the facts the code's sentences name, by the registry's names, such as the failing `pipe` or the `model` a method named. A parameter only the operator may read never rides here.
+- `params` — the facts the code's sentences name, by the registry's names, such as the failing `pipe` or the `model` a method named. Every parameter the code's registry entry requires rides here, so the sentences state this occurrence rather than the code's generic wording, and a list a code requires, such as the `suggestions` of `request.pipe_not_found`, is given empty when nothing is near. Those suggestions name only pipes the caller may select: the method's own pipes for a bare or domain-qualified code, and for an `alias->…` code the pipes that dependency exports, never its private ones; the `candidates` of `method.pipe_unresolved` for a reference into a dependency are likewise only that package's exported pipes, its private ones included only for a reference written in the package itself. Beside the server's own library directories, the method's own pipes are those of the bundles the request sent: a pipe of the server's library is never offered, as its files are never named. A parameter only the operator may read never rides here.
- `location` — where the fault is: on a run failure the failing `pipe` and its `path` from the entry pipe, and elsewhere an `input`, a `field`, a batch `item`, an `attempt`, or a `file` with its `line` and `column`. See [Run failures](#run-failures-the-root-fault-located-at-the-failing-pipe).
-- `errors` — one item per fault, for a refusal of several at once: each with its own `code`, `detail`, `params` and `location`, and on a method that does not validate the `suggestions` and `suggested_fix` of its validation item. See [Structured validation errors](#structured-validation-errors).
+- `errors` — one item per fault, for a refusal of several at once: each with its own `code`, `detail`, `params` and `location`, and on a method that does not validate the `suggestions` and `suggested_fix` of its validation item. A refusal of one fault carries no list: the item that would restate the problem's own code gives the problem its parameters and its location instead. When that item carries `suggestions` or a `suggested_fix`, which only an item has members for, it gives the problem its parameters and location all the same and stays the list's one item, so the fix is never lost. See [Structured validation errors](#structured-validation-errors).
- `pipeline_run_id` — the run the problem belongs to.
**Pipelex's members:**
@@ -68,6 +68,7 @@ A refusal the runner authors itself, before the runtime is asked anything, is a
- Any other refusal the framework raises keeps its status and its meaning, under a code whose required parameters the runner can fill: the framework says nothing about a refusal but its status and a header, so a code whose parameters it cannot know gives way to one whose parameters it can. A `401` is `auth.missing_credential`, keeping the `WWW-Authenticate` challenge it was raised with; a `403` is `auth.invalid_credential`, since `auth.forbidden` names a `requirement` the framework does not; a `404` is `request.not_found`, and a `405` `request.method_not_allowed`, keeping its `Allow`; a `413` is `request.malformed` with the reason `too_large`, since `request.too_large` states a `limit` and a `size` the framework does not; and a `429` is `runtime.unavailable`, whose verdict invites a retry, keeping its `Retry-After`, since `account.rate_limited` states a `limit` and a `window` the framework does not. Any other `4xx`, such as a `415`, is `request.malformed` with the reason `unreadable`. Each answers with the status it was raised with, whichever status its code declares. A `5xx` the framework raises is its own fault, `runtime.unexpected`.
- A request past one of this runner's size limits is `request.too_large`, a **413** whose `limit` and `size` parameters give the limit and what the request carried, always in bytes: an encoded value, a file of `resources` or a `bundle_b64` archive, is measured by the bytes its encoded length carries, read before it is decoded.
- A method tree the runner refuses to read as a method is `method.package_invalid`, whose `reason` names the rule the tree breaks and whose `path` or `limit` says where or how far.
+- A dependency the request keys by another address than the one its own `METHODS.toml` declares, such as its repository's address alone, is `pipelex.request.dependency_key_mismatch`, a **422** whose `key` parameter is the key the request used and whose `address` is the declared address the dependency must be keyed by.
The members the runner's refusals used to carry are gone: no refusal carries an `error_type`, `error_domain`, `retryable` or `instance`. The request's path is not echoed, since `request_id`, which the runner takes from an inbound `X-Request-ID` or mints, is what correlates a response with the server's records.
@@ -114,8 +115,8 @@ Each item is one fault:
|---|---|
| `code` | The registry code of the fault: the code its type maps to, such as `method.input_undeclared` for an input a pipe reads but does not declare, `model.unknown` for a model the deck does not define, `method.syntax` for a TOML syntax error or `method.dependency_missing` for a package the method calls and no one supplied. A `dry_run` item's code is its failure's own, and an item no stage classified takes `method.schema_violation`, or the code of the refusal behind it. |
| `detail` | The code's sentence, rendered from the item's parameters, or the code's title when the item lacks a parameter the sentence names. A program branches on `code`, never on a sentence. |
-| `params` | The facts the item's locators give the code, by the registry's names: the `pipe`, the `variables` it reads, the `concept` or `model` it names, the `model_type`, a `finding` quoting the validation's own account. |
-| `location` | Where the fault is: the `pipe`, the `field` within the bundle, and the `file` with its 1-based `line` and `column` when the parser stopped there. On the in-memory submit path the `file` is the matching `mthds_sources[i]` (see [Sourcing submitted files](pipe-validate.md)), so it is absent when the caller sent no sources. Beside a server's own library directories, an item never names one of their files, nor a template file one of their `PipeDocGen` steps names. |
+| `params` | Every parameter the item's code requires, by the registry's names: the facts its locators give, such as the `pipe`, the `variables` it reads, the `concept` or `model` it names, the `model_type` and a `finding` quoting the validation's own account, and those the check that found the fault knows, such as the concept a pipe declares and those that would fit, the `name` and the kind of `conflict` of a name declared twice, or the declared concepts nearest one that resolves to nothing. |
+| `location` | Where the fault is: the `pipe`, the `field` within the bundle, and the `file` with its 1-based `line` and `column` when the parser stopped there. A name two bundles declare is one item per bundle, each located on its own `file`. On the in-memory submit path the `file` is the matching `mthds_sources[i]` (see [Sourcing submitted files](pipe-validate.md)), so it is absent when the caller sent no sources. Beside a server's own library directories, an item never names one of their files, nor a template file one of their `PipeDocGen` steps names. |
| `suggestions` | On a `model.unknown` item, the deck's close matches of the kind the pipe needs. |
| `suggested_fix` | A structured, deterministic fix for this fault — present only when the fix planner derived one. See [Suggested fixes](#suggested-fixes). |
@@ -243,7 +244,7 @@ The runner's own refusals answer these codes:
- **422** — `request.invalid` for a field the route's rules refuse, `request.malformed` for a body or an encoded part that cannot be parsed, `request.unsupported` for a **registry-form** `method_ref` — not a `github.com/...` address — which no server-side method registry resolves yet (its `reason` is `registry_form_method_ref`; use an address or send the method's tree in `files`), and `pipelex.deployment.orchestration_override_forbidden`, naming the `requested_mode`, for a request asking for an `orchestration_mode` this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`).
- **500** — `runtime.misconfigured`: the runner's own configuration cannot serve the request, such as a missing `API_KEY` or `JWT_SECRET_KEY`, a `PUBLIC_BASE_URL` that is not an HTTP URL, or missing package metadata. Which setting is at fault is the operator's to read, in `diagnostics.params.component`, and in the `error.params.component` of the server's error line whichever view the response took. `pipelex.deployment.token_claims_invalid` is a **500** too: a token whose signature holds carries a `user_id` claim that is missing, unsafe or reserved, which its issuer, not its bearer, must fix.
- **501** — `runtime.unsupported` naming the `capability` `asynchronous execution`: `POST /v1/start` is fire-and-forget by nature, and this deployment's orchestrator is blocking-only (the in-process `direct` default), so it refuses honestly rather than blocking and acking — use `POST /v1/execute` instead. `pipelex.deployment.custom_code_requires_sandbox`: the method holds custom Python `.py` files and this deployment is not sandbox-hosted, so running caller-supplied code in-process is refused; its `origin` says whether the code came in the request's `bundle` or a fetched `package`.
-- **500** — `pipelex.storage.damaged`, naming the kind of storage as `scheme`, on the routes that read files a request names by hash (`POST /v1/execute`, `POST /v1/start`, `POST /v1/validate`, `POST /v1/resolve`, `POST /v1/codegen` and `POST /v1/pipe-io`): the bytes the blob store holds under a hash do not hash to it, or are not the size it holds them at, so the object stored there is damaged. `PUT /v1/blobs/{sha256}` answers it too for an upload whose bytes hash to an object held at another size, since the runner never writes over a blob. Its verdict is not to retry, since a retry reads the same damaged object, and its step is to report it: the operator removes the object the server's line `Stored blob bytes do not match their hash` names under `blob_sha256` (see [Logging](logging.md#blob-store-lines)), after which the blob is uploaded again.
+- **500** — `pipelex.storage.damaged`, naming the kind of storage as `scheme` (`local`, `s3`, `gcs`, `memory`, or `plugin` for a store a storage plugin provides), on the routes that read files a request names by hash (`POST /v1/execute`, `POST /v1/start`, `POST /v1/validate`, `POST /v1/resolve`, `POST /v1/codegen` and `POST /v1/pipe-io`): the bytes the blob store holds under a hash do not hash to it, or are not the size it holds them at, so the object stored there is damaged. `PUT /v1/blobs/{sha256}` answers it too for an upload whose bytes hash to an object held at another size, since the runner never writes over a blob. Its verdict is not to retry, since a retry reads the same damaged object, and its step is to report it: the operator removes the object the server's line `Stored blob bytes do not match their hash` names under `blob_sha256` (see [Logging](logging.md#blob-store-lines)), after which the blob is uploaded again.
A client that disconnects before its request body was received in full is answered `request.malformed` with the reason `body_incomplete`, which only the server's logs show, at warning level, since the client is gone before the answer.
diff --git a/docs/building-methods/pipes/csv-input-and-output.md b/docs/building-methods/pipes/csv-input-and-output.md
index 88c48f3bc..0b641470f 100644
--- a/docs/building-methods/pipes/csv-input-and-output.md
+++ b/docs/building-methods/pipes/csv-input-and-output.md
@@ -166,7 +166,7 @@ The codec defaults to a comma delimiter and UTF-8 encoding. Reads use `utf-8-sig
## Limitations in v1
-- **Local file paths only.** A remote `url` with a tabular suffix — `http(s)://`, `s3://`, `gs://`, a signed URL — is actively rejected with a clear error, never opened. Reading remote tabular files is a deferred follow-up.
+- **Local file paths only.** A remote `url` with a tabular suffix — `http(s)://`, `s3://`, `gs://`, a signed URL — is actively rejected with a clear error, never opened: its problem is `request.unsupported`, naming the input's field as `inputs.<name>` and the reason `remote_table_url`, and never the URL. A `url` that does not parse is `input.file_unreadable`, with the reason `the URL does not parse`. Reading remote tabular files is a deferred follow-up.
- **Not uploaded on a hosted run.** A run on the hosted Pipelex API uploads the local files named at document and image inputs only, so a `.csv` path at a structured-list input reaches the hosted runner as a path on your machine, which it cannot read. Give the rows as a JSON list of objects instead, or run with `--local`. `--save-csv` is refused on a hosted run too (see [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api)).
diff --git a/docs/building-methods/pipes/provide-inputs.md b/docs/building-methods/pipes/provide-inputs.md
index 793d4c3d4..fac3b649f 100644
--- a/docs/building-methods/pipes/provide-inputs.md
+++ b/docs/building-methods/pipes/provide-inputs.md
@@ -223,7 +223,7 @@ When a value cannot be shaped against its declared concept, Pipelex raises a typ
- **Incompatible explicit concept** — an envelope naming a concept that is not compatible with the declaration.
- **Null value** — a top-level `null`; absence is expressed by *omitting* the key, not by providing `null`. (An input declared optional with `?` may simply be left out — see [Understanding Optionality](understanding-optionality.md).)
-That message, with its expected shape, is what the CLIs print and what whoever runs the runtime reads. A caller of the API reads the refusal's [problem document](../../api-server/error-responses.md) instead, whose `params.input` and `location.input` name the input and whose code's sentence is rendered from what is wrong with it: the expected and provided counts of `input.wrong_multiplicity`, the declared and provided concepts of `input.wrong_concept`, the field at fault of `input.invalid` when the concept's structure names one, and the name of `input.unexpected`.
+That message, with its expected shape, is what the CLIs print and what whoever runs the runtime reads. A caller of the API reads the refusal's [problem document](../../api-server/error-responses.md) instead, whose `params.input` and `location.input` name the input and whose code's sentence is rendered from what is wrong with it: the expected and provided counts of `input.wrong_multiplicity`, the declared and provided concepts of `input.wrong_concept`, the field at fault of `input.invalid` when the concept's structure names one, and the name of `input.unexpected`. A refused file is named the same way whatever refuses it, a url that is blank or malformed, a storage reference to nothing, a data URL or a local path that cannot be read, a file the run may not read, an Image holding another kind of file or a format the consuming model cannot read: `input` is the run's input, `documents`, and `location.field` the path down to the file, `documents[1]`, or down to its url, `documents[1].url`, which `input.invalid` also gives as its `field`.
## Input files: JSON or TOML
diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.md
index bf252e789..01b4877ae 100644
--- a/docs/contribute/hub-layering.md
+++ b/docs/contribute/hub-layering.md
@@ -59,7 +59,7 @@ There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as a
| --- | --- |
| container | `InterpreterHub`, `get_interpreter_hub`, `set_interpreter_hub` |
| library manager | `get_library_manager`, `get_library` |
-| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_own_pipes`, `get_required_pipe`, `get_optional_pipe`, `get_required_entry_pipe`, `get_optional_entry_pipe`, `get_pipe_source` |
+| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_own_pipes`, `get_selectable_own_pipe_refs`, `get_required_pipe`, `get_optional_pipe`, `get_required_entry_pipe`, `get_optional_entry_pipe`, `get_pipe_source` |
| current-library contextvar | `set_current_library`, `get_current_library`, `get_current_library_id_or_none`, `clear_current_library`, `scoped_current_library` |
| library dirs | `resolve_library_dirs`, `get_default_library_dirs` |
| pipe router | `get_pipe_router`, `set_pipe_router`, `teardown_current_pipe_router`, `scoped_pipe_router` |
@@ -145,7 +145,7 @@ It is **read-side only**. Managing a library — adding, removing, listing, setu
**There is deliberately no pipe counterpart.** Nothing in core's kernel half resolves a pipe. The two places that follow a pipe reference found *inside* a pipe graph — a condition's mapped pipes, a sequence's last step — live in `pipe_machinery/rendering/`, which is interpreter-layer and calls `interpreter_hub.get_required_pipe` directly; a provider parameter there would buy no closure property. `get_required_pipe` therefore stays on `PipeLibraryAbstract`. Split a read half out when a kernel-layer caller actually needs one, not for symmetry with concepts.
-Pipe resolution comes in two flavours on this hub, and picking the wrong one is a correctness bug rather than a style choice. `get_required_pipe` / `get_optional_pipe` resolve an **in-body** reference — one pipe naming another from inside a method — and are strict: the ref names its own domain or it names nothing. `get_required_entry_pipe` / `get_optional_entry_pipe` resolve a code a **human** supplied at an entry point (a CLI argument, an API request field), where a bare code is still matched across domains. A CLI command on the strict pair is needlessly strict; a controller on the entry pair reopens the cross-domain hole that makes `[exports]` unenforceable.
+Pipe resolution comes in two flavours on this hub, and picking the wrong one is a correctness bug rather than a style choice. `get_required_pipe` / `get_optional_pipe` resolve an **in-body** reference — one pipe naming another from inside a method — and are strict: the ref names its own domain or it names nothing. A caller that knows the pipe whose body writes the reference passes it as `referring_pipe_code`, which the refusal names as its `pipe`. `get_required_entry_pipe` / `get_optional_entry_pipe` resolve a code a **human** supplied at an entry point (a CLI argument, an API request field), where a bare code is still matched across domains. A CLI command on the strict pair is needlessly strict; a controller on the entry pair reopens the cross-domain hole that makes `[exports]` unenforceable.
One caveat on "strict", so nobody relies on it absolutely: a **cross-package** `alias->bare_code` ref is still resolved by searching the aliased entries, because the qualification pass leaves `alias->…` refs alone — it cannot know a dependency's domain layout, so there would be no canonical spelling to migrate such a ref to. That search is alias-scoped and cannot reach a host pipe, so it does not reopen the hole; it is a deferral to the packaging design, not an exception to the rule.
diff --git a/docs/errors/index.md b/docs/errors/index.md
index 09ab37b0b..c2b185ba8 100644
--- a/docs/errors/index.md
+++ b/docs/errors/index.md
@@ -58,6 +58,14 @@ Pipelex's extensions to runs.
|---|---|---|---|---|
| [`pipelex.run.already_exists`](pipelex/run/already_exists.md) | A run with this id already exists | `input` | `no` | `409` |
+## pipelex.request { #pipelex-request }
+
+Refusals of a request's shape that name a fact no core code carries.
+
+| Code | Title | Domain | Retry | Status |
+|---|---|---|---|---|
+| [`pipelex.request.dependency_key_mismatch`](pipelex/request/dependency_key_mismatch.md) | A dependency is keyed by another address than its manifest declares | `input` | `no` | `422` |
+
## pipelex.storage { #pipelex-storage }
Pipelex's storage addresses and uploads.
diff --git a/docs/errors/pipelex/request/dependency_key_mismatch.md b/docs/errors/pipelex/request/dependency_key_mismatch.md
new file mode 100644
index 000000000..efdee337b
--- /dev/null
+++ b/docs/errors/pipelex/request/dependency_key_mismatch.md
@@ -0,0 +1,54 @@
+---
+title: "pipelex.request.dependency_key_mismatch"
+description: "A dependency is keyed by another address than its manifest declares: what the Pipelex error code pipelex.request.dependency_key_mismatch means, who must act and what to do."
+---
+
+# pipelex.request.dependency_key_mismatch
+
+**A dependency is keyed by another address than its manifest declares**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.request.dependency_key_mismatch` |
+| Family | [`pipelex.request`](../../index.md#pipelex-request): Refusals of a request's shape that name a fact no core code carries. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `input`: the caller acts, by changing the request or its inputs |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `422` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+A request ships each package its method calls by address in `dependencies`, keyed by the package's full address: the address its `METHODS.toml` declares, followed by a slash and the package's name. This dependency is keyed by another address, such as its repository address alone, so the method's calls cannot reach it.
+
+## What to do
+
+Key the dependency by `params.address`, the full address its manifest declares, as the method's calls name it.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, the caller, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `change_input` | Key the dependency by '`{address}`', the address its manifest declares, then send the request again. |
+| Any other reader | `change_input` | Pass this to the caller, who must key the dependency '`{key}`' by '`{address}`'. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> The dependency keyed '`{key}`' declares the address '`{address}`', which must be its key.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `key` | `identifier` | The key the request gives the dependency in `dependencies`. |
+| `address` | `identifier` | The full address the dependency's manifest declares, its repository address followed by its package name, which its key must be. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/errors/pipelex/storage/damaged.md b/docs/errors/pipelex/storage/damaged.md
index 4da3b3c89..014eed31e 100644
--- a/docs/errors/pipelex/storage/damaged.md
+++ b/docs/errors/pipelex/storage/damaged.md
@@ -45,7 +45,7 @@ Every parameter is present on every occurrence of the code.
| Name | Type | Description |
|---|---|---|
-| `scheme` | one of `local`, `s3`, `gcs`, `memory` | The kind of storage that holds the damaged file. |
+| `scheme` | one of `local`, `s3`, `gcs`, `memory`, `plugin` | The kind of storage that holds the damaged file: one Pipelex ships, or `plugin` for a storage plugin's own. |
## See also
diff --git a/docs/errors/pipelex/storage/not_found.md b/docs/errors/pipelex/storage/not_found.md
index 32fc8688c..94f645eac 100644
--- a/docs/errors/pipelex/storage/not_found.md
+++ b/docs/errors/pipelex/storage/not_found.md
@@ -45,7 +45,7 @@ Every parameter is present on every occurrence of the code.
| Name | Type | Description |
|---|---|---|
-| `scheme` | one of `local`, `s3`, `gcs`, `memory` | The kind of storage that no longer holds the file. |
+| `scheme` | one of `local`, `s3`, `gcs`, `memory`, `plugin` | The kind of storage that no longer holds the file: one Pipelex ships, or `plugin` for a storage plugin's own. |
## See also
diff --git a/docs/errors/pipelex/storage/unavailable.md b/docs/errors/pipelex/storage/unavailable.md
index 4ed1cd71b..828f8a32a 100644
--- a/docs/errors/pipelex/storage/unavailable.md
+++ b/docs/errors/pipelex/storage/unavailable.md
@@ -45,7 +45,7 @@ Every parameter is present on every occurrence of the code.
| Name | Type | Description |
|---|---|---|
-| `scheme` | one of `local`, `s3`, `gcs`, `memory` | The kind of storage that failed. |
+| `scheme` | one of `local`, `s3`, `gcs`, `memory`, `plugin` | The kind of storage that failed: one Pipelex ships, or `plugin` for a storage plugin's own. |
## See also
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index e8a450edc..ccc0e3ae6 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -97,7 +97,7 @@ 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 — the problem `method.invalid` with `is_valid: false`, its faults in `errors` — and exit code `1`, never a no-verdict failure and exit code `2`, which is kept for failures of the tool or its environment. Each item carries its own `code`, the sentence that code renders as its `detail`, its `params`, its `location` (its `pipe`, its `field`, its `file`, and for a TOML syntax error its 1-based `line` and `column`) and, when there is one, its `suggested_fix`. A pipe whose dry run fails gives one item per failing pipe, coded by its failure and located at the innermost pipe that failed and is not allowed to fail (its file whenever the pipe is in your files; a validator of submitted content beside a host's library directories names only that content's files), with the sentence the failure's code renders for a caller, never the failure's own text, 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 of its own, located at its pipe and its file. An undeclared concept gives a `method.concept_unresolved` item whose `params.concept` names it. A pipe naming a model the model deck does not define gives one `model.unknown` item located at the pipe's `model` field, its `params` naming the reference as written and its `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 `unsafe, confirm before applying` beside its fix code, where a safe fix is labelled `safe`. Any other refusal of your input with no code of its own gives one item with the refusal's code, 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. In Markdown the items are listed one per line under `### Errors`, each with its code, its sentence, its location, its suggestions and its suggested fix. See [Error Model](../../under-the-hood/error-model.md).
+ A refusal of your input raised while the bundle is loaded or validated is answered with the invalid verdict — the problem `method.invalid` with `is_valid: false`, its faults in `errors` — and exit code `1`, never a no-verdict failure and exit code `2`, which is kept for failures of the tool or its environment. Each item carries its own `code`, the sentence that code renders as its `detail`, its `params`, its `location` (its `pipe`, its `field`, its `file`, and for a TOML syntax error its 1-based `line` and `column`) and, when there is one, its `suggested_fix`. A pipe whose dry run fails gives one item per failing pipe, coded by its failure and located at the innermost pipe that failed and is not allowed to fail (its file whenever the pipe is in your files; a validator of submitted content beside a host's library directories names only that content's files), with the sentence the failure's code renders for a caller, never the failure's own text, 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 of its own, located at its pipe and its file. An undeclared concept gives a `method.concept_unresolved` item whose `params.concept` names it. A pipe code or an input name that breaks the naming rules gives a `method.identifier_invalid` item whose `params.name` names it, and an item whose check knows facts its location does not hold, such as the concept a pipe declares and those that would fit, or the name two bundles both declare, gives them in its `params`, by the names the error registry gives them. A pipe naming a model the model deck does not define gives one `model.unknown` item located at the pipe's `model` field, its `params` naming the reference as written and its `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 `unsafe, confirm before applying` beside its fix code, where a safe fix is labelled `safe`. Any other refusal of your input with no code of its own gives one item with the refusal's code, 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. In Markdown the items are listed one per line under `### Errors`, each with its code, its sentence, its location, its suggestions and its suggested fix. See [Error Model](../../under-the-hood/error-model.md).
!!! 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 findings 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. Four 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)); the [intent-hint](../../building-methods/concepts/intent-hints.md) lints (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`); and the warnings of a [`PipeDocGen`](../../building-methods/pipes/pipe-operators/PipeDocGen.md#office-template-files) step's template check (`template_check_warning`), found by the engine in the step's office template file during the dry run, as a `dry_run` item that also carries `template_file` (the file as the step names it) and `template_location` (the place in it, in the engine's words, absent when the engine names none). Every whole-bundle validate channel — this CLI, the bare CLI 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 <code>` carries the template-check warnings alone: one pipe has no flow context to lint in, but what its dry run found is about that pipe. `validate bundle`/`validate method` with `--pipe` keep it, and it stays bundle-wide there — the slice narrows the dry run, not the validation.
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index d217f21e4..9af56919f 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -70,6 +70,10 @@ No declared member is ever written as `null`. The model's serializer drops every
`PipelexError.to_problem(view=...)` is the entry point. `make_problem()` builds a problem from a code and `make_problem_item()` one item of a problem with several faults, both taking everything the code decides from the registries' generated tables.
+**A problem carries every parameter its code requires.** The registry marks each parameter required unless it is optional or read by the operator alone (`ErrorCodeSpec.required_params`), and both builders log `A problem lacks a parameter its code requires`, with the code, the parameters missing and whether a problem or an item lacked them, when a raise site gave fewer: the sentence that names a missing parameter falls back on the code's generic wording, so the log is a raise site to fix, never a state to accept. A raise site gives the facts it holds with `with_params()`, or its class through `problem_params()`; a refusal of a pipe gives its own through `PipeValidationError`, whose parameters reach the validation item (`PipesAndConceptValidationErrorData.params`, `ValidationErrorItem.params`) beside those the item's locators give, and a code whose required parameter is a list, such as `suggestions` or `candidates`, gets it empty when nothing is near. The library's unit tests and the API server's sweep this: an autouse fixture of each (`tests/unit/conftest.py`, `api/tests/unit/conftest.py`) spies on the problem builders' warnings before every test and asserts after it (`pipelex.test_extras.required_params_sweep`), which fails a test during which any problem or item was built lacking a required parameter, unless the test says why with the `builds_problems_without_required_params` marker. The marker is for a test that builds an error by hand with a message alone, or that stops below the layer giving the fact: a pipe's failure location fills `pipe`, and a worker's public call fills `model` and `provider`, so a test of a provider's private call or of a render outside any pipe lacks them by design. One parameter is withheld on purpose: a template refusal (`security.template_refused`) of a name the run's data chose, such as `{{ topic[topic.text] }}`, carries no `name`, since that name is the run's input, and its sentences come from a wording keyed by the code and the parameter it lacks (`_WITHHELD_PARAM_SENTENCES` in `pipelex/errors/problem.py`), saying the template looked a name up from the run's data and the sandbox refused it, rather than from the generic fallback. No raise site is at fault for a parameter withheld by rule, so the builders do not log that the problem lacks it (`missing_required_params()` leaves it out), and the sweep below does not need the marker for it; any other parameter such a problem lacks is still logged.
+
+**A refusal of one fault carries no `errors` list.** When the only item of a problem restates the problem's own code, `make_problem()` folds it into the problem: the item's parameters and location become the problem's, and the list is dropped. An item carrying `suggestions` or a `suggested_fix` gives the problem its parameters and location too, but stays the list's one item, since a problem has no member for either. A problem whose single item has another code, such as `method.invalid` over one `method.concept_unresolved`, keeps its list, since the item says what the umbrella does not.
+
### Views: who reads the problem
A problem is one document seen through a **view**, and who reads it picks the view, never a deployment setting. `ProblemView` has two members:
@@ -101,9 +105,9 @@ A message reaches the operator's diagnostics, the error tracker and every log li
- **A location** quotes the keys the value holds where it is a dict, and a key the model does not declare, which are the run's data. Every formatter reads it from `located_validation_errors()`, which reads the error's errors once and walks the schema of the type the error came from, writing only what that schema names, a field, an alias, a position in a list, a union's choice or a tagged union's tag; any other component is written `<key>`, so a refused value under a dict's key reads `entries.<key>.score` and a key a nested model forbids reads `owner.<key>`. The label of a union's choice is read once per validated type and kept with it. A raise site that knows the type it validated passes it as `validated_type`, a model or a `TypeAdapter` over a type that is not one, such as the trace event logs' union of events; without it, or when the error came from another type, an error is written by its reason alone, since nothing then tells a field's name from a key of the value's own. So every site that validates an input into a class it knows refuses it there, located: an explicit envelope `{"concept": …, "content": …}` that its concept's class refuses is refused by the stuff factory as `input.invalid` naming the input and the first refused field, and a transported stuff by its hydration, while the runner's own catch of a `ValidationError` and the stand-in for a foreign one, which know no model, give the reasons alone. Instructor validates a structured generation's answer with a subclass of the requested class that keeps its name, so the generated class's refusal is located by the requested class, a list of objects' wrapper (`make_object_list_schema()`) carrying its name as its title for the same reason. A document no run's data is in, a method author's own or a value Pipelex built for itself such as a dry run's mock, is located as pydantic gives it, by `is_authored_input`.
- **A validator's own sentence** is kept only when it raises `InputFreeValueError` (`pipelex/tools/typing/validation_exceptions.py`), the `ValueError` by which a validator declares that its message names what it expected and never the value. The native contents' validators raise it, a date's, a time's, a number's, an image's and a JSON object's; any other validator's message may quote the value it rejected, so it is written as its type, `value_error`.
- **A URL** is the input's value, and possibly a signed link: a refusal names the input, never the URL, and the scheme only when it is one Pipelex reads, `http`, `https`, `s3`, `gs` or `pipelex-storage`, since any other is the caller's own text too, and a URL that does not parse is refused without the part httpx quotes. The host of a URL that could not be fetched, and the input it belongs to, are facts `RemoteFileFetchError` holds, not parameters its raise site gives: `input.url_unreachable` takes both, and a catch site that codes the failure otherwise, as a provider's file does with `provider.response_invalid`, is given neither, rather than a parameter its code would drop with a warning. The fetch knows the URL alone, so a catch site that knows the input names it with `with_input()`, or wraps the fetch in `fetching_for_input()` (`pipelex/tools/misc/file_fetch_utils.py`): an extract worker does, a prompt's image or document carries the input it came from as its `input_name`, `photos[2]`, which its preparation names, and a document rendered as page views carries it on its assignment.
-- **A table an input gives** is the caller's file: a CSV refusal names the file by the input it was given as, `the CSV file given for input 'people'`, with the row, the field and the column's position, never the file's path, a cell, or a column the concept does not declare, and gives the input as the problem's `input` parameter.
+- **A table an input gives** is the caller's file: a CSV refusal names the file by the input it was given as, `the CSV file given for input 'people'`, with the row, the field and the column's position, never the file's path, a cell, or a column the concept does not declare, and gives the input as the problem's `input` parameter and its `location.input`, which the site that knows the input names with `CsvError.with_input()`, the codec not knowing it: the four sites of `StuffFactory.try_make_csv_list_content`, the three refusals before the table is read and the codec's own refusals it re-raises.
- **A function a `PipeFunc` calls** is named by the class of what it raised, `The function raised KeyError`: its text is the function's own, and `pipe.function_raised` declares no parameter for it. Any other failure of the executor is named by its class, and a Pipelex error by its code too, `PipeFuncExecutionError (runtime.unexpected)`, since an out-of-process executor's error, or a transport's, can carry the function's text in its own.
-- **A template that fails to render** is described by a fixed sentence naming the class Jinja2 or Python raised and the template's line, `the template reads a value that is not defined (UndefinedError, at line 2 of the template)`, never by that exception's text, which quotes what the template reached for, a key of the run's data included, nor by the template source. A name is kept only when the parsed template spells it as a variable or an attribute (`template_spelled_names()` in `pipelex/tools/jinja2/jinja2_rendering.py`), never because the same word appears in the template's text: the variable an undefined names, the attribute the sandbox refused to read, the name it refused to store a callable under in a namespace, the method it refused to call, the method whose call overran the render budget. The sandbox words each refusal with those names and without them (`SandboxRefusalError`), as the render budget words its refusal of a call (`RenderBudgetExceededError`), and a refusal whose names the template does not all spell is written without them, `A template may not read an unsafe name on a 'object' value.`, `calling a method of a 'str' value needs about 1,000,000,000,000`. A template that cannot render as written is described by the kind of fault and its line, `syntax error at line 3.`, never by the token Jinja2 quotes, and a filter or a test its environment lacks is named when the template applies it by that name, `No filter named 'frob' at line 1.`. Parsing a template to find its variables is refused the same way, by the kind of fault and its line. Pipelex's own filters refuse what they were handed without quoting it: an unknown text format by the formats they know, an undefined value given a tag without the tag's name.
+- **A template that fails to render** is described by a fixed sentence naming the class Jinja2 or Python raised and the template's line, `the template reads a value that is not defined (UndefinedError, at line 2 of the template)`, never by that exception's text, which quotes what the template reached for, a key of the run's data included, nor by the template source. A name is kept only when the parsed template spells it as a variable or an attribute (`template_spelled_names()` in `pipelex/tools/jinja2/jinja2_rendering.py`), never because the same word appears in the template's text: the variable an undefined names, the attribute the sandbox refused to read, the name it refused to store a callable under in a namespace, the method it refused to call, the method whose call overran the render budget. The sandbox words each refusal with those names and without them (`SandboxRefusalError`), as the render budget words its refusal of a call (`RenderBudgetExceededError`), and a refusal whose names the template does not all spell is written without them, `A template may not read an unsafe name on a 'object' value.`, `calling a method of a 'str' value needs about 1,000,000,000,000`. A name a replacement field reads in a format string counts as spelled too, but only where the literal is the string a `.format` or `.format_map` call formats, such as the `_x` that `'{0._x}'.format(v)` reads, since the template's own literal wrote the access being refused; a word any other string literal holds, as `mode == 'debug _token'` does, and the plain text outside the expressions never count, so the sandbox and the budget read one rule (`_spells_every_name()`). A template that cannot render as written is described by the kind of fault and its line, `syntax error at line 3.`, never by the token Jinja2 quotes, and a filter or a test its environment lacks is named when the template applies it by that name, `No filter named 'frob' at line 1.`. Parsing a template to find its variables is refused the same way, by the kind of fault and its line. Pipelex's own filters refuse what they were handed without quoting it: an unknown text format by the formats they know, an undefined value given a tag without the tag's name.
- **A structured generation `instructor` gave up on** is classified from what ended its loop. When its re-asks end on a refused answer, the recovered `ValidationError` is written by its reasons, located by the requested class (`extract_openai_metadata()` and its siblings take it as `validated_type`), and any other failure to parse the answer by its class alone, such as the `AssertionError` `instructor`'s OpenAI parser raises with a model's refusal in its text: each worker passes its SDK's own error classes as `sdk_error_types`, and only those keep the text, which is the provider's; when nothing can be recovered, the failure is named by the class of the wrapper's cause, or of the wrapper itself (`describe_instructor_failure()`), never by a text or a representation, since a retry error's is a `Future`'s, a memory address included. `instructor`'s own text, which is the last validation error's and quotes the model's answer, is never used, and no sink writes `instructor`'s log records (see [Logging](../tools/logging.md)).
- **A foreign exception** a pipe raised stands as a `PipelexUnexpectedError` whose message is its class, `KeyError`, never its text, which can be a key of the run's data or a value a function was handed; a `ValidationError` adds its reasons. A failure that follows the pipe's own, a delivery's or the graph tracer's, is logged by its class and its code, never its text, which names the caller's webhook URL or the trace's file, and a webhook's transport failure is named by its class. A trace event log's refusal, and the tracing assembly's errors on the run's output, are written by their reasons, located by the event models' schema.
@@ -199,7 +203,7 @@ The **structured-info invariant is total**: every invalid verdict carries a non-
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`, the template-check locators `template_file` and `template_location` (on a `template_check_warning`, which rides `warnings`), 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.** A caller reads the verdict, its items, their locators and its message, so none of them 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`, a warning found at a pipe of theirs carries no `template_file` (the sweep withholds it, `BundleValidator`'s `source_pipe_refs`), and a message that named one, named the template file a `PipeDocGen` step of theirs names (one whose template the engine's check refuses in the dry run of a caller's pipe that runs it), 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`). The withheld verdict is the same answer otherwise: it keeps the code its raise site chose, such as `request.invalid` for a request naming nothing to validate, and the parameters and items its raise site gave, withheld the same way. Every item of its problem is withheld whole, its sentence, each parameter and its locators, whichever channel each came from: an item no stage classified takes the parameters of the refusal the verdict was built from, its cause, whose `finding`, `file` or `path` the withholding never rewrote otherwise. A name only counts standing on its own, never inside a longer one, and neither a source the caller submitted nor a template file its own content names is ever withheld. A method of those directories that refuses to load is not an item at all: it is the deployment's configuration failing to validate, so `reporting_host_library_faults` in the same module raises it as a `HostLibraryLoadRefusalError`, carrying `pipelex.config.invalid`, which an API answers with its code's 500, the host library's own text riding only the operator's diagnostics. A step can only name its template file relative to its bundle, so no message about one names a path on the host. 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.
+**A verdict names no path on the host.** A caller reads the verdict, its items, their locators and its message, so none of them 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`, a warning found at a pipe of theirs carries no `template_file` (the sweep withholds it, `BundleValidator`'s `source_pipe_refs`), and a message that named one, named the template file a `PipeDocGen` step of theirs names (one whose template the engine's check refuses in the dry run of a caller's pipe that runs it), 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 declared twice is one item per bundle declaring it, so a name the caller's content and a host file both declare is the caller's item alone, naming the host file as `<host library file>`: the host file's item would be located nowhere and say what the caller's already says. The withheld verdict is the same answer otherwise: it keeps the code its raise site chose, such as `request.invalid` for a request naming nothing to validate, and the parameters and items its raise site gave, withheld the same way. Every item of its problem is withheld whole, its sentence, each parameter and its locators, whichever channel each came from: an item no stage classified takes the parameters of the refusal the verdict was built from, its cause, whose `finding`, `file` or `path` the withholding never rewrote otherwise. A name only counts standing on its own, never inside a longer one, and neither a source the caller submitted nor a template file its own content names is ever withheld. A method of those directories that refuses to load is not an item at all: it is the deployment's configuration failing to validate, so `reporting_host_library_faults` in the same module raises it as a `HostLibraryLoadRefusalError`, carrying `pipelex.config.invalid`, which an API answers with its code's 500, the host library's own text riding only the operator's diagnostics. A step can only name its template file relative to its bundle, so no message about one names a path on the host. 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 code is the method's to fix, in the `method` domain, 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, and its message is the sentence the refusal's code renders for a caller (`refusal_detail()`), never the refusal's own message, which is the operator's. 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 fault whose code another actor must fix, the caller's input, the account, the operator or the runtime, a `LibraryError` among them (a library invariant of ours reads `runtime.unexpected`), a `SecurityError`, a `PipeNotFoundError` (which has its own not-found handler) and anything that is not a `PipelexError` still propagate as no verdict, and so does a missing document engine, `pipelex.docgen.engine_unavailable`, which the deployment has to install. The rule therefore reaches exactly the refusals whose code is the method's. A dry run's failures and a pipe run failing outside the sweep become a verdict on the same rule: only when at least one failure is the method's, and none is a security refusal. A refusal a security rule made is never a verdict's item, whichever arm meets it, though many security codes are the method's to fix (`security.method_path_refused`, `security.template_refused`): every arm asks the same question of a code, the method's and no security family's. A dry run meeting one, such as a template the sandbox refuses at render, answers that refusal's code, a security failure's code coming before any other among its failures, every failure riding its items; the pipe run that met it logged its security event, and the sweep marks its own error reported so no boundary logs it twice. A dry run whose every failure belongs to another actor answers its own code, the first of its failures' codes by `first_fault_code()` (a verdict `no` before a retryable one, then the method's, the operator's, the account's, the input's and the runtime's, then the first given), with every failure riding its problem's `errors`, and never reads as an invalid method. The pipe factories' refusals are: `PipeLLMFactoryError`, `PipeComposeFactoryError`, `PipeExtractFactoryError`, `PipeConditionFactoryError` and `PipeParallelFactoryError` are raised only while a pipe is built, about its own blueprint, so each declares a `method` code, `method.template_invalid` or `method.schema_violation`, 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.
@@ -223,7 +227,7 @@ Two spellings live in that one vocabulary, deliberately. The stage enums are sna
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`, the three `hint_*` lints and `template_check_warning` — 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.
-On a problem, each validation item becomes one `errors` item (`problem_item_of()` in `pipelex/pipeline/validation_errors.py`). Its `code` is the code the item's `error_type` maps to (`validation_item_code()`), a dry-run item's is its failure's, and an item no stage classified takes the code of the refusal the verdict was built from when that refusal is the method's, else `method.schema_violation`. Its `detail` is that code's sentence, rendered from the parameters the item's locators give; its `location` holds the item's pipe, field, file, line and column; and its `suggestions` and `suggested_fix` are the item's.
+On a problem, each validation item becomes one `errors` item (`problem_item_of()` in `pipelex/pipeline/validation_errors.py`). Its `code` is the code the item's `error_type` maps to (`validation_item_code()`), a dry-run item's is its failure's, and an item no stage classified takes the code of the refusal the verdict was built from when that refusal is the method's, else `method.schema_violation`. Its `detail` is that code's sentence, rendered from the parameters the item's locators give; its `location` holds the item's pipe, field, file, line and column; and its `suggestions` and `suggested_fix` are the item's. A `method.name_conflict` item about a declaration, a name declared twice or a native concept declared again, is located on the colliding declaration by its path from the bundle's root, such as `concept.Rating` or `pipe.compute_score`, which a duplicate declaration's items and a native concept's redeclaration carry as their `field_path`, beside the file wherever the caller may read it, so a verdict and a run's refusal both point at the table to rename or remove. Such a location names no `pipe`, a duplicate pipe's included: a `field` beside a `pipe` reads from that pipe's table, as `{"pipe": "say", "field": "template"}` does, and a `field` beside none reads from the bundle's root, so a reader joining the two never builds `pipe.compute_score.pipe.compute_score`. A batch item named as its list or as another input of its pipe is no declaration but a name the pipe uses twice, so its item keeps the `pipe` and names the field it collides on inside that pipe's table, `input_item_name` on a `PipeBatch` or `steps.0.batch_as` on a sequence step, which the blueprint-stage error names and the categorizer joins to where pydantic's location puts its table (`_pipe_field_name()` in `pipelex/mthds_parsing/validation_error_categorizer.py`), without the shape tag pydantic routes a step through.
```python
problem = exc.to_problem(view=ProblemView.CALLER)
@@ -677,11 +681,11 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| Quota / billing exhausted | `CAPACITY` → not repeated; `UserAction(CHECK_BILLING)`; `provider.quota_exhausted`, the operator's → HTTP 502 |
| Bad API key | `CONFIGURATION` → not repeated; `provider.credential_refused`, the operator's → HTTP 502 |
| Model or deployment not found (provider HTTP 404) | Raises a dedicated `*ModelNotFoundError` sibling (`LLMModelNotFoundError`, `ImgGenModelNotFoundError`, `ExtractModelNotFoundError`, `SearchModelNotFoundError`) carrying `model.unavailable`, since a method cannot name a provider's raw model id; operator re-raises `PipeOperatorModelAvailabilityError` |
-| Model reference unknown to the deck (a method naming `gpt-5.1`, a mistyped `@alias` or `$preset`) | `ModelChoiceNotFoundError` → `CONFIGURATION` category, but the code `model.unknown`, the method's → **HTTP 422**, whose sentence names the reference and whose `suggestions` parameter carries the deck's close matches, which are all a caller needs to fix the method. A handle the deck serves only as another type of model is `model.capability_unsupported` |
+| Model reference unknown to the deck (a method naming `gpt-5.1`, a mistyped `@alias` or `$preset`) | `ModelChoiceNotFoundError` → `CONFIGURATION` category, but the code `model.unknown`, the method's → **HTTP 422**, whose sentence names the reference and whose `suggestions` parameter carries the close matches of every catalog the deck knows, an empty list when none is near, which are all a caller needs to fix the method. A handle the deck serves only as another type of model is `model.capability_unsupported` |
| The deck's own default or override names a model it does not define | `ModelDeckChoiceUnresolvedError`, naming the deck setting in its message for the operator, never the caller's `model.unknown`: `model.unavailable` → HTTP 501, with the reason `not_served`, for a bare handle no backend serves as the type the step needs, whose caller step offers another model, and `pipelex.config.invalid` → HTTP 500 for a preset, an alias or a waterfall the deck does not define; a bad override is refused when the deck is built |
| Content-policy violation | `CONTENT` → not repeated; `UserAction(CHANGE_INPUT)`; `model.content_refused` → **HTTP 422** |
| Malformed prompt image / bad prompt parameter | `CONTENT` class-level (`PromptImageFormatError`, `LLMPromptParameterError`, …), each with its own code (`input.file_type_unsupported`, `pipe.prompt_empty`, …) |
-| A provider **HTTP 400**, or another 4xx such as the 422 or 413 a gateway may answer, saying the inputs are over what the model can read (OpenAI's `context_length_exceeded` code, which Azure OpenAI and OpenAI-compatible gateways relay, or a provider's own wording, read in the rendered message and in the body, where a raw `httpx` error such as Azure REST's keeps it: OpenAI's "maximum context length" and "exceeds the context window", Anthropic's "prompt is too long" and "exceed context limit", Bedrock's "Input is too long for requested model", Gemini's "exceeds the maximum number of tokens allowed") | `ProviderErrorMetadata.is_context_window_exceeded` → `CONTENT` / `CHANGE_INPUT`, not repeated; `model.context_exceeded`, the caller's → **HTTP 422**. The 400 arm and the other-4xx arm read it, ahead of the content-policy signal, for every family, and a 413 that carries no such signal keeps its payload-size reading, `input.too_large`. A language model's window holds the prompt and the output the request reserves with `max_tokens` together, and Anthropic's "exceed context limit" and OpenAI's "maximum context length" also refuse a request whose `max_tokens`, which may be the deck's default, pushes it over, so the language-model next step names both: shorten the input or lower `max_tokens`, or choose a model with a larger context window. The other families' next steps fit what their model reads: the prompt and its input images for an image model, the document for an extraction model, the inputs for a search or judgment model. Each phrase names the window or the inputs' length, so a 400 about a malformed request matches none of them |
+| A provider **HTTP 400**, or another 4xx such as the 422 or 413 a gateway may answer, saying the inputs are over what the model can read (OpenAI's `context_length_exceeded` code, which Azure OpenAI and OpenAI-compatible gateways relay, or a provider's own wording, read in the rendered message and in the body, where a raw `httpx` error such as Azure REST's keeps it: OpenAI's "maximum context length" and "exceeds the context window", Anthropic's "prompt is too long" and "exceed context limit", Bedrock's "Input is too long for requested model", Gemini's "exceeds the maximum number of tokens allowed") | `ProviderErrorMetadata.is_context_window_exceeded` → `CONTENT` / `CHANGE_INPUT`, not repeated; `model.context_exceeded`, the caller's → **HTTP 422**, whose parameters name the model and, as its `limit`, the context window, but neither the prompt's size nor the window's, which the provider words and never gives as numbers. The 400 arm and the other-4xx arm read it, ahead of the content-policy signal, for every family, and a 413 that carries no such signal keeps its payload-size reading, `input.too_large`. A language model's window holds the prompt and the output the request reserves with `max_tokens` together, and Anthropic's "exceed context limit" and OpenAI's "maximum context length" also refuse a request whose `max_tokens`, which may be the deck's default, pushes it over, so the language-model next step names both: shorten the input or lower `max_tokens`, or choose a model with a larger context window. The other families' next steps fit what their model reads: the prompt and its input images for an image model, the document for an extraction model, the inputs for a search or judgment model. Each phrase names the window or the inputs' length, so a 400 about a malformed request matches none of them |
| Any other provider **HTTP 400** | `CONTENT` / `CHANGE_INPUT`, but `runtime.unexpected` → HTTP 500: a 400 nothing recognises is most likely a request of ours the provider could not take, and only a context-window or a content-policy signal makes it the caller's, `model.context_exceeded` or `model.content_refused` |
| Local file extractor raises a builtin (docling, pypdfium2) | `FileNotFoundError` → `input.reference_not_found`, `ValueError` / `RuntimeError` → `input.file_unreadable`, both `CONTENT` → **HTTP 422**; `OSError` → `UNKNOWN`, `runtime.unexpected` (see `_LOCAL_EXTRACT_BY_TYPE_NAME`) |
| A text completion stops at its output limit or context window (`length`, `max_tokens`, `MAX_TOKENS`, an `incomplete` Responses answer at `max_output_tokens`, `model_context_window_exceeded`, `model_length`), with partial or empty text | Every LLM worker reads the stop before returning text and raises `LLMCompletionTruncatedError` → `CONTENT` / `CHANGE_INPUT`, not repeated: `model.output_truncated`, the method's, at the output limit, which the method's `max_tokens` sets, and `model.context_exceeded`, the input's, at the context window, both → **HTTP 422**. The message, for the operator, names the model, the pipe, the stop value, the output tokens used and the `max_tokens` sent, never the partial text; the caller reads the code's sentence, with the model and the token counts as its parameters. The error's `truncation_limit` tells the output limit from the context window (`model_context_window_exceeded`, `model_length`), and so does its code's next step: a higher `max_tokens` for the first, a shorter input for the second. A gateway in non-strict mode passing each provider's own value through the completions shape is read the same way, since the classifier reads the union of the provider vocabularies |
@@ -695,6 +699,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| The gateway does not allow the model for this account (`model_not_allowed_error`, HTTP 412) | `CONFIGURATION` / `CHANGE_MODEL`, never repeated; the advice names the model handle; `model.unavailable` → HTTP 501 |
| Connection dropped mid-request | `AMBIGUOUS` → not repeated within the run (outcome unknown); `provider.outcome_unknown` → HTTP 502, whose sentence says the work may exist and be billed, and whose step says to run the method again only if a repeat of the work is acceptable |
| A step names, in an inline model setting, a model the deck neither defines nor names | `ModelNotFoundError`, which the lookup raises with `model.unknown` as the method's: **HTTP 422**, with a `change_model` step and a sentence 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 the class's `model.unavailable` → HTTP 501, in the operator's domain, whose caller step offers another model |
+| A method names a model a catalog of this deployment knows but no backend it enables serves (a backend switched off in `backends.toml`, such as `claude-4.5-haiku` with `anthropic` disabled) | `ModelNotFoundError` with `model.unavailable` → **HTTP 501**, the operator's, with the parameters `model`, `model_type` and the `reason` `not_served`, located on the pipe and its `model` field; the deck reads the handles every backend declares, enabled or not (`ModelDeck.is_cataloged_but_unserved`), so this is never the method's `model.unknown`. Validation answers it as no verdict, since the method is sound and this deployment cannot run it, and a run answers it before any pipe runs |
| A `PipeParallel` cannot combine its branch results, or a pipe starts without a required input | The caller's own method or request: `pipe.output_multiplicity`, naming the first branch whose multiplicity differs from its field's, with one item per such branch when there are several, or `input.missing` at the entry pipe and `pipe.input_unresolved` below it → **HTTP 422**, each with its code's step, `change_method` for the method's codes and `change_input` for the input's |
| 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)`; `request.pipe_not_found`, `request.pipe_unspecified` or `request.pipe_ambiguous` → **HTTP 422**. The in-body lookups (`get_optional_pipe` / `get_required_pipe`) keep raising `PipeNotFoundError` / `PipeLibraryError`, whose codes are the method's: a ref written inside a bundle is not the caller's input |
| A template naming a filter or a test that does not exist, found only when it renders | `Jinja2TemplateInvalidError` at the pipe, naming the filter or test and none of the template: `method.template_invalid` → **HTTP 422** for a method's `PipeCondition` expression, `PipeLLM` prompt or `PipeDocGen` template, and `runtime.unexpected` for one of Pipelex's own templates |
diff --git a/docs/under-the-hood/pipe-func-requirements.md b/docs/under-the-hood/pipe-func-requirements.md
index 7be433f46..b67cc838b 100644
--- a/docs/under-the-hood/pipe-func-requirements.md
+++ b/docs/under-the-hood/pipe-func-requirements.md
@@ -106,7 +106,7 @@ For the hosted API, the Daytona sandbox plugin states the package set of the Day
| Error | Code | When |
| --- | --- | --- |
| `MethodRequirementsFileError` | `method.package_invalid` | The file holds a line the standard refuses, naming each, or is not UTF-8 text. |
-| `MethodRequirementsNotMetError` | `method.dependency_missing` | The environment does not meet a requirement, naming each and why, or the deployment refuses the requirements with its own reason, no environment it can build holding them. |
+| `MethodRequirementsNotMetError` | `method.dependency_missing` | The environment does not meet a requirement, naming each and why, or the deployment refuses the requirements with its own reason, no environment it can build holding them. For a requirement not met, its `name` is the distribution that fails the requirement: the one required, or one an extra of it needs, with the `reason` `not_found` when it is missing and `no_matching_version` when the version held is one the requirement refuses. |
| `HostLibraryRequirementsError` | `pipelex.config.invalid` | A method of a host's own library directories, loaded beside a caller's bundles, is refused for its requirements. |
| `PipeFuncPackageSetUnstatedError` | `runtime.misconfigured` | A sandbox-hosted deployment states no package set for its execution mode. |
diff --git a/docs/under-the-hood/pipelex-kernel.md b/docs/under-the-hood/pipelex-kernel.md
index 0ee6917ea..94fa29aa1 100644
--- a/docs/under-the-hood/pipelex-kernel.md
+++ b/docs/under-the-hood/pipelex-kernel.md
@@ -86,7 +86,7 @@ Both façade calls take the concept and the output class the caller wants, defau
| `pipelex.kernel.prompt_references` | `ImageReference` / `ImageReferenceKind`, `DocumentReference` / `DocumentReferenceKind` |
| `pipelex.kernel.*_results` | The typed result envelopes |
-The two operator-specific `assemble_*` functions are there because `run_llm_text` and `run_img_gen` both take a *ready* prompt. A caller that could not build one would be holding an operator it cannot reach, which is what image generation was until `assemble_img_gen_prompt` existed: its only builder was an interpreter-layer blueprint. Both are thin over `pipelex.kernel.prompt_assembly`, the user-prompt assembly PipeLLM, PipeImgGen and PipeJudge share. It owns the part a caller must not re-derive: resolving `ImageReference` and `DocumentReference` out of working memory, numbering the files they name, substituting the `[Image N]` and `[Document N]` tokens for direct, list and dotted references, and handing the files over in the order their tokens number them, since a mismatch mislabels which file the prompt is describing and nothing downstream can detect it. Each file handed over carries the input it came from as its `input_name` (`photos[2]`, the first reference that numbered it), so a failed fetch of its URL names that input and never the URL; an image a filter registered while the template rendered carries none. `assemble_user_prompt` assembles one template into an `AssembledUserPrompt`, its text with its ordered images and documents; `PromptFiles` is the same numbering shared by several templates of one prompt, a PipeLLM's system and user prompts or a PipeImgGen's positive and negative ones, whose references are all registered before the first renders so their tokens number one sequence. A reference whose root input is declared optional and was not given is skipped before numbering, taking no number and handing over no file, so the template's guard renders it out, while an absent required input is refused; the reference carries `is_optional`, which the factories set through the one analysis they share, `analyze_template_file_references` in `pipelex.pipe_operators.shared`, and the context answers presence through `ContextProviderAbstract.is_variable_present`. The caller's `extra_params` are copied, never written to.
+The two operator-specific `assemble_*` functions are there because `run_llm_text` and `run_img_gen` both take a *ready* prompt. A caller that could not build one would be holding an operator it cannot reach, which is what image generation was until `assemble_img_gen_prompt` existed: its only builder was an interpreter-layer blueprint. Both are thin over `pipelex.kernel.prompt_assembly`, the user-prompt assembly PipeLLM, PipeImgGen and PipeJudge share. It owns the part a caller must not re-derive: resolving `ImageReference` and `DocumentReference` out of working memory, numbering the files they name, substituting the `[Image N]` and `[Document N]` tokens for direct, list and dotted references, and handing the files over in the order their tokens number them, since a mismatch mislabels which file the prompt is describing and nothing downstream can detect it. Each file handed over carries the input it came from as its `input_name` (`photos[2]`, the first reference that numbered it), so a failed fetch of its URL names that input and never the URL; an image a filter registered while the template rendered carries none. A template the sandbox refuses while it renders is located on the field it is written in, `prompt` or `system_prompt` for an LLM prompt, `prompt` or `negative_prompt` for an image generation prompt, `prompt` for a judgment's evidence, and for a judgment's question the field it is written in, `question` for a step asking one and `questions.<name>.question` for a step asking several (`locating_template_refusal` in `pipelex/tools/jinja2/jinja2_rendering.py`), so the run's problem names the field to change. `assemble_user_prompt` assembles one template into an `AssembledUserPrompt`, its text with its ordered images and documents; `PromptFiles` is the same numbering shared by several templates of one prompt, a PipeLLM's system and user prompts or a PipeImgGen's positive and negative ones, whose references are all registered before the first renders so their tokens number one sequence. A reference whose root input is declared optional and was not given is skipped before numbering, taking no number and handing over no file, so the template's guard renders it out, while an absent required input is refused; the reference carries `is_optional`, which the factories set through the one analysis they share, `analyze_template_file_references` in `pipelex.pipe_operators.shared`, and the context answers presence through `ContextProviderAbstract.is_variable_present`. The caller's `extra_params` are copied, never written to.
The `resolve_*_setting` functions, and `judgment_setting_of_choice`, walk the deck chain: the step's own choice, then the deck's override where the family has one, then the deck's default. Whose fault a miss is follows the rung that missed. A choice the step names that the deck does not resolve is the method's, `ModelChoiceNotFoundError` with `model.unknown`, whose step asks the method's author for another model; a bare handle the deck serves only as another model type is `model.capability_unsupported`. An override or a default the deck names that it does not resolve is the deployment's, which a caller cannot fix by changing their input: `ModelDeckChoiceUnresolvedError`, naming the deck setting, such as `extract.choice_default`, with `model.unavailable` for a bare handle no backend serves and `pipelex.config.invalid` for a preset, an alias or a waterfall the deck does not define. The deck refuses an override that does not resolve when it loads, and a default when a step first runs on it, or, for a `PipeJudge` naming no model, when its method loads, where the operator lets the error through rather than locating it on the pipe as the method's unknown model.
diff --git a/docs/under-the-hood/template-sandbox.md b/docs/under-the-hood/template-sandbox.md
index a6d304747..f9e79dbeb 100644
--- a/docs/under-the-hood/template-sandbox.md
+++ b/docs/under-the-hood/template-sandbox.md
@@ -42,7 +42,7 @@ A method template renders without a template loader, so `{% include %}`, `{% ext
Many refusals are visible in the template itself, and validation reports them before anything runs: a template that reads an undeclared underscore name with a dot fails with the `template_private_name` validation error, which names the pipe and the template (`prompt`, `system_prompt`, `template`, `expression`, or `construct field '<path>'`).
-What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises `Jinja2TemplateSecurityError`, with the code `security.template_refused`, whose message names the type the refused name was reached on, and the attribute or callable only when the template spells it, as in `{{ record._secret }}`. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
+What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises `Jinja2TemplateSecurityError`, with the code `security.template_refused`, whose message names the type the refused name was reached on, and the attribute or callable only when the template spells it, as in `{{ record._secret }}`, and which is located on the pipe and on the field its template is written in, as the bundle writes it: `template`, or `template.template` for a compose template written as a table of its own, `prompt`, `system_prompt`, `negative_prompt`, a condition's `expression` or `expression_template`, a judgment's `question` or `questions.<name>.question`, a document's `filename`, `template` or `template_file`, or a construct's `construct.<field>`, which each construct field locates itself, since a construct has no `template` field. The sandbox raises `SandboxRefusalError`, which words the refusal with the names it quotes and without them and carries the bare name it refused, and the render keeps the wording with the names, and passes the refused name on as the problem's `name`, only when the parsed template spells every name the refusal quotes: as a variable, an attribute or a literal key, or in a replacement field of the format string a `.format` or `.format_map` call formats, such as the `_x` that `'{0._x}'.format(v)` reads. That scan runs while the refusal is built, so it is bounded: it follows fields nested in format specs only as deep as the formatter reads them, and a format string nested deeper, or one that does not parse, counts nothing, so the refusal always comes out as itself. No other text of the template counts, neither a word another string literal holds, as `mode == 'debug _token'` does, nor the plain text outside its expressions, so a name the run's data chose stays withheld even when the template happens to write the same word; the render budget names the call it refused by the same rule. A template whose own source names what it reached for, such as `{{ topic['_owner'] }}`, gives a problem naming the pipe and the name, *A template of pipe 'say' reached for '_owner', which the template sandbox forbids*, with the step *Remove '_owner' from the templates of pipe 'say'*. A template that looks the name up from the run's data, such as `{{ topic[topic.text] }}`, would carry the run's input in that name, so its message says *A template may not read an unsafe name on a 'StuffArtefact' value*, its problem carries no `name`, and its sentences say what happened without it: *A template of pipe 'say' looked a name up from the run's data, and the template sandbox refused that name*, with the step to change the templates so that the run's data no longer chooses the names they look up. `security.template_refused` requires `name`, which this case withholds by rule until the standard words it, so no raise site is at fault and the problem logs no missing parameter. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
`Jinja2TemplateSecurityError` is a `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. The sandbox's budget refusal is a separate error, `Jinja2TemplateBudgetError`, which is a `ToolError` (see below). `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index 0657da7aa..674157c30 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -26,6 +26,7 @@ from pipelex.errors.problem import (
ProblemDiagnostics,
ProblemView,
ProviderDiagnostics,
+ accepted_params,
cap_problem_text,
make_problem,
merge_locations,
@@ -245,9 +246,19 @@ class ValidationErrorItem(BaseModel):
# (a defined name, a Table, a cell, a shape, a tag). Optional and additive, like ``declared_concepts``.
template_file: str | None = None
template_location: str | None = None
+ # The identifier locator, carried by an ``invalid_pipe_code_syntax`` item: the name that breaks the naming rules, as
+ # the method writes it, a declaration key or the ``main_pipe`` value, which ``field_path`` (``main_pipe``) tells
+ # apart. Optional and additive, like ``declared_concepts``.
+ identifier_name: str | None = None
# The hint locator, carried by a hint lint item: the hint key the finding is about, elided as its message quotes it,
# which its problem item names as the code's ``hint`` parameter. Optional and additive, like ``declared_concepts``.
hint_key: str | None = None
+ # The parameters of its problem item's code the stage that found it knows about this one item, by the registry's
+ # names, beside those its locators give: the facts a raise site gave its refusal (the concept a step declares and
+ # those it expects), and on an item no ``error_type`` classifies, which takes the code of the refusal it rides,
+ # those of this one fault where the refusal's own describe only its first. Optional and additive, like
+ # ``declared_concepts``.
+ params: dict[str, Any] | 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``.
@@ -602,6 +613,17 @@ class PipelexError(Exception):
span_id=trace.format_span_id(span_context.span_id) if span_context is not None else None,
)
+ def operator_diagnostics(self) -> ProblemDiagnostics | None:
+ """The diagnostics the operator's view of this error's problem carries (:meth:`to_problem`), without building it.
+
+ A command refusing something under a code of its own reads the error it caught for these alone, so the
+ parameters the caught error's code requires, which no reader of that refusal is shown, are never asked of it.
+ """
+ recovered = self.recovered_problem()
+ if recovered is not None:
+ return recovered_problem_in_view(problem=recovered, view=ProblemView.OPERATOR).diagnostics
+ return self._diagnostics(facts=self.chain_facts())
+
def to_problem(
self,
*,
@@ -634,6 +656,51 @@ class PipelexError(Exception):
reporter=self, view=view, request_id=request_id, pipeline_run_id=pipeline_run_id, failure_location=failure_location
)
+ def caller_params(self) -> dict[str, Any]:
+ """The parameters this error's problem carries as a caller reads them, read without building the problem.
+
+ They are the parameters :meth:`to_problem` gives in the caller's view, its items' aside: a refusal whose faults
+ its items carry gives none of its own for a code that requires some, which building its problem would log as a
+ fault, while a reader wanting only the parameters, such as a verdict whose items take this refusal's code, has
+ nothing to report.
+ """
+ recovered = self.recovered_problem()
+ if recovered is not None:
+ recovered_params = self.to_problem(view=ProblemView.CALLER).params
+ return recovered_params.as_wire() if recovered_params is not None else {}
+ code = self.resolve_error_code()
+ params, _ = self._reported_params_and_location(reporter=self, failure_location=None)
+ operator_only_params = error_code_spec(code).operator_only_params
+ return {name: value for name, value in accepted_params(code=code, params=params).items() if name not in operator_only_params}
+
+ def _reported_params_and_location(
+ self, *, reporter: "PipelexError", failure_location: ProblemLocation | None
+ ) -> tuple[dict[str, Any], ProblemLocation | None]:
+ """The parameters and the location of this error's problem as ``reporter`` reports it (see :meth:`problem_reported_by`)."""
+ code = self.resolve_error_code()
+ carrier = self.code_carrier()
+ wrappers = reporter.errors_above(carrier=carrier)
+ facts = reporter.chain_facts()
+ spec = error_code_spec(code)
+ params: dict[str, Any] = {}
+ for wrapper in wrappers:
+ # Given in order from the reporter down, so a wrapper nearer the carrier wins over one above it; checked
+ # against the carrier's code when the problem is built, an undeclared one being dropped and logged.
+ params.update(wrapper.given_params)
+ # A fact the carrier does not hold is no parameter, so the location's pipe and the chain's model still fill it below.
+ params.update({name: value for name, value in carrier.problem_params().items() if name in spec.param_names and value is not None})
+ params.update(carrier.given_params)
+ location = reporter.chain_location(carrier=carrier)
+ if failure_location is not None:
+ location = merge_locations(base=location, override=failure_location)
+ if location is not None and location.pipe is not None and "pipe" in spec.param_names:
+ params.setdefault("pipe", location.pipe)
+ if facts.model is not None and "model" in spec.param_names:
+ params.setdefault("model", facts.model)
+ if facts.provider is not None and facts.provider.name is not None and "provider" in spec.param_names:
+ params.setdefault("provider", facts.provider.name)
+ return params, location
+
def problem_reported_by(
self,
*,
@@ -678,26 +745,10 @@ class PipelexError(Exception):
# The wrappers between the reporter and the error whose code the problem reports, the reporter first.
wrappers = reporter.errors_above(carrier=carrier)
facts = reporter.chain_facts()
- spec = error_code_spec(code)
- params: dict[str, Any] = {}
- for wrapper in wrappers:
- # Given in order from the reporter down, so a wrapper nearer the carrier wins over one above it; checked
- # against the carrier's code when the problem is built, an undeclared one being dropped and logged.
- params.update(wrapper.given_params)
- params.update({name: value for name, value in carrier.problem_params().items() if name in spec.param_names})
- params.update(carrier.given_params)
+ params, location = self._reported_params_and_location(reporter=reporter, failure_location=failure_location)
items = list(carrier.chain_items() or [])
for wrapper in reversed(wrappers):
items.extend(wrapper.problem_items() or [])
- location = reporter.chain_location(carrier=carrier)
- if failure_location is not None:
- location = merge_locations(base=location, override=failure_location)
- if location is not None and location.pipe is not None and "pipe" in spec.param_names:
- params.setdefault("pipe", location.pipe)
- if facts.model is not None and "model" in spec.param_names:
- params.setdefault("model", facts.model)
- if facts.provider is not None and facts.provider.name is not None and "provider" in spec.param_names:
- params.setdefault("provider", facts.provider.name)
return make_problem(
code=code,
view=view,
diff --git a/pipelex/cli/installed_methods.py b/pipelex/cli/installed_methods.py
index 1de9b36e7..7e7f289d5 100644
--- a/pipelex/cli/installed_methods.py
+++ b/pipelex/cli/installed_methods.py
@@ -19,6 +19,7 @@ from pydantic import BaseModel, ValidationError
from pipelex.cli.exceptions import DuplicateMethodNameError, MethodNotFoundError
from pipelex.methods.exceptions import MethodInstallError
from pipelex.methods.fetching import MethodProvenance
+from pipelex.methods.package_reason import MethodPackageReason
GLOBAL_METHODS_DIR = Path.home() / ".mthds" / "methods"
PROJECT_METHODS_DIR = Path(".mthds") / "methods"
@@ -354,7 +355,7 @@ def install_method_package(
final_dir = (target_root / name).resolve()
if final_dir == target_root or final_dir.parent != target_root or name.startswith("."):
msg = f"Cannot install method '{name}': the name escapes the methods directory '{target_root}' or is not a valid method directory name."
- raise MethodInstallError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ raise MethodInstallError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID).with_params(reason=MethodPackageReason.PACKAGE_NAME_INVALID)
if final_dir.exists():
return _resolve_occupied_install_target(final_dir=final_dir, name=name, full_address=full_address)
@@ -380,5 +381,5 @@ def install_method_package(
if installed is None:
shutil.rmtree(final_dir, ignore_errors=True)
msg = f"Installed method '{name}' at '{final_dir}' carries no {MANIFEST_FILENAME} — the source package was not a method package."
- raise MethodInstallError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ raise MethodInstallError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID).with_params(reason=MethodPackageReason.MANIFEST_MISSING)
return installed
diff --git a/pipelex/cogt/doc_gen/formatted_markdown.py b/pipelex/cogt/doc_gen/formatted_markdown.py
index e58dddcd5..12ba78261 100644
--- a/pipelex/cogt/doc_gen/formatted_markdown.py
+++ b/pipelex/cogt/doc_gen/formatted_markdown.py
@@ -87,4 +87,6 @@ def format_markdown(*, markdown: str) -> FormattedMarkdown:
f"Formatting a Markdown text of {len(markdown):,} characters would spend more than the {own_budget.total:,} work units "
"a conversion outside a template render may spend: its text, its tables or what they format into is too large."
)
- raise MarkdownFormattingBudgetError(msg) from exc
+ # The bound is the conversion's own budget; the input it formats and the size it would reach are known to the
+ # engine that called it, which reports the refusal as its own fill error.
+ raise MarkdownFormattingBudgetError(msg).with_params(limit=own_budget.total) from exc
diff --git a/pipelex/cogt/exceptions.py b/pipelex/cogt/exceptions.py
index 71ef8c767..55773cdbf 100644
--- a/pipelex/cogt/exceptions.py
+++ b/pipelex/cogt/exceptions.py
@@ -3,7 +3,7 @@ from __future__ import annotations
from enum import StrEnum
from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple
-from mthds.protocol.problem.registry import CoreCode, ModelUnavailableReason
+from mthds.protocol.problem.registry import CoreCode, ModelContextExceededLimit, ModelUnavailableReason
from typing_extensions import override
from pipelex.base_exceptions import PipelexError, ProblemFacts, iter_cause_chain
@@ -283,12 +283,18 @@ class ModelChoiceNotFoundError(CogtError):
Includes available options and migration hints in error message.
The reference is the method's, so the fault is its author's: ``model.unknown`` for a reference the deck does not
- define, and ``model.capability_unsupported`` for a bare handle the deck serves only as another model type, which
- the deck chooses where it raises it. A reference the deck itself names, as a default or an override, is the
- deployment's fault instead: the deck re-raises its miss as a ``ModelDeckChoiceUnresolvedError``.
+ define, with the deck's close matches as its ``suggestions``, and ``model.capability_unsupported`` for a bare handle
+ the deck serves only as another model type, which the deck chooses where it raises it. A bare handle a catalog of
+ this deployment declares as the type the step needs, on a backend that is not enabled, names a model that exists:
+ the deck chooses ``model.unavailable`` for it, with the reason ``not_served``, whose fix is the deployment's. A
+ reference the deck itself names, as a default or an override, is the deployment's fault too: the deck re-raises its
+ miss as a ``ModelDeckChoiceUnresolvedError``.
"""
- error_code = ErrorCodeSet(default=CoreCode.MODEL_UNKNOWN, others=(CoreCode.MODEL_CAPABILITY_UNSUPPORTED,))
+ error_code = ErrorCodeSet(
+ default=CoreCode.MODEL_UNKNOWN,
+ others=(CoreCode.MODEL_CAPABILITY_UNSUPPORTED, CoreCode.MODEL_UNAVAILABLE),
+ )
error_category = InferenceErrorCategory.CONFIGURATION
def __init__(
@@ -329,8 +335,16 @@ class ModelChoiceNotFoundError(CogtError):
@override
def problem_params(self) -> dict[str, Any]:
- suggestions = self.suggestions + self.cross_collection_suggestions
- return {**super().problem_params(), "model": self.model_choice, "model_type": self.model_type, "suggestions": suggestions or None}
+ # Each of the class's codes reads its own: `model.unknown` the close matches, an empty list when the deck has
+ # none, `model.capability_unsupported` the use the step needs the model for, `model.unavailable` its reason.
+ return {
+ **super().problem_params(),
+ "model": self.model_choice,
+ "model_type": self.model_type,
+ "suggestions": self.suggestions + self.cross_collection_suggestions,
+ "capability": f"use as {self.model_type.indefinite_description}",
+ "reason": ModelUnavailableReason.NOT_SERVED,
+ }
class ModelDeckChoiceUnresolvedError(ModelChoiceNotFoundError):
@@ -375,11 +389,6 @@ class ModelDeckChoiceUnresolvedError(ModelChoiceNotFoundError):
case ModelReferenceKind.PRESET | ModelReferenceKind.ALIAS | ModelReferenceKind.WATERFALL:
pass
- @override
- def problem_params(self) -> dict[str, Any]:
- # The reason `model.unavailable` declares: no backend of this deployment serves the handle the deck names.
- return {**super().problem_params(), "reason": ModelUnavailableReason.NOT_SERVED}
-
class ModelDeckValidationError(CogtError):
"""The model deck as configured is invalid: its files do not validate, or a preset names a model it does not serve."""
@@ -703,12 +712,15 @@ class LLMCompletionTruncatedError(LLMCompletionError):
@override
def problem_params(self) -> dict[str, Any]:
+ # At the context window the bound passed is known, and the counts are not: the stop signal carries neither the
+ # prompt's size nor the window's.
return {
**super().problem_params(),
"pipe": self.pipe_code,
"model": self.model_handle,
"max_tokens": self.max_tokens,
"output_tokens": self.output_tokens,
+ "limit": ModelContextExceededLimit.CONTEXT_WINDOW,
}
diff --git a/pipelex/cogt/extract/extract_worker_abstract.py b/pipelex/cogt/extract/extract_worker_abstract.py
index fc99e62f2..434e917f0 100644
--- a/pipelex/cogt/extract/extract_worker_abstract.py
+++ b/pipelex/cogt/extract/extract_worker_abstract.py
@@ -109,7 +109,10 @@ class ExtractWorkerAbstract(InferenceWorkerAbstract):
f"which model '{self.inference_model.name}' cannot extract: it reads {describe_format_keys(format_keys=listed_formats)}. "
"Give a file in one of those formats, or use an extract model that reads this one."
)
- raise ExtractInputFormatError(msg)
+ refusal = ExtractInputFormatError(msg).with_params(format=format_key, model=self.inference_model.name)
+ if extract_input.input_name:
+ refusal = refusal.with_params(input=extract_input.input_name)
+ raise refusal
def _call_summary(self, *, extract_job: ExtractJob) -> InferenceCallSummary:
"""The event the call ends with, its model and its usage read off the worker and the job it reports when it ends."""
diff --git a/pipelex/cogt/inference/error_render.py b/pipelex/cogt/inference/error_render.py
index fd0842559..d76df9581 100644
--- a/pipelex/cogt/inference/error_render.py
+++ b/pipelex/cogt/inference/error_render.py
@@ -9,7 +9,7 @@ worker's error family, with a human-readable message and a structured
import math
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, ModelContextExceededLimit, ModelUnavailableReason
from pipelex.cogt.exceptions import (
CogtError,
@@ -27,6 +27,7 @@ from pipelex.cogt.exceptions import (
)
from pipelex.cogt.inference.error_classification import SDKErrorEnvelope, UserAction, UserActionKind
from pipelex.cogt.inference.error_classify import ClassificationResult, InferenceErrorFamily
+from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
# Generic failure error class per family — used when the error is not a missing model.
@@ -48,6 +49,16 @@ _NOT_FOUND_CLASSES: dict[InferenceErrorFamily, type[ModelNotFoundError]] = {
}
+# The kind of model each family's worker calls, which `model.unavailable` names.
+_FAMILY_MODEL_TYPES: dict[InferenceErrorFamily, ModelType] = {
+ InferenceErrorFamily.LLM: ModelType.LLM,
+ InferenceErrorFamily.IMG_GEN: ModelType.IMG_GEN,
+ InferenceErrorFamily.EXTRACT: ModelType.TEXT_EXTRACTOR,
+ InferenceErrorFamily.SEARCH: ModelType.SEARCH,
+ InferenceErrorFamily.JUDGMENT: ModelType.JUDGMENT,
+}
+
+
def _format_message(metadata: SDKErrorEnvelope, *, model_desc: str) -> str:
"""Compose the human-readable error message from the provider, model, and SDK text."""
status_part = f" (HTTP {metadata.status_code})" if metadata.status_code is not None else ""
@@ -180,14 +191,25 @@ def render_inference_error(
error_category=classification.category,
user_action=user_action,
provider_metadata=metadata,
- )
+ ).with_params(model=model_handle, model_type=_FAMILY_MODEL_TYPES[family], reason=ModelUnavailableReason.UNKNOWN_AT_PROVIDER)
# The not-found classes report ``model.unavailable`` alone, which the classification guarantees. A failure
# class declares every classified code, and its code is chosen here rather than inherited, since the
# provider's exception it is raised from carries none.
failure_class = _FAILURE_CLASSES[family]
- return failure_class(
+ failure = failure_class(
message,
error_category=classification.category,
user_action=user_action,
provider_metadata=metadata,
).with_error_code(classification.error_code)
+ if classification.is_model_not_allowed:
+ # The provider serves the model but does not allow it for this caller.
+ failure.with_params(model=model_handle, model_type=_FAMILY_MODEL_TYPES[family], reason=ModelUnavailableReason.NOT_ALLOWED)
+ match classification.error_code:
+ case CoreCode.MODEL_CONTEXT_EXCEEDED:
+ # The provider's refusal says the inputs are over the model's context window, the bound it names, and
+ # never as numbers the runtime can read, so the prompt's size and the window's are not given.
+ failure.with_params(model=model_handle, limit=ModelContextExceededLimit.CONTEXT_WINDOW)
+ case CoreCode() | PipelexErrorCode():
+ pass
+ return failure
diff --git a/pipelex/cogt/inference/prompt_file_checks.py b/pipelex/cogt/inference/prompt_file_checks.py
index 1fcfc67be..5d65a6206 100644
--- a/pipelex/cogt/inference/prompt_file_checks.py
+++ b/pipelex/cogt/inference/prompt_file_checks.py
@@ -34,7 +34,8 @@ def check_prompt_images_are_images(*, model_name: str, prompt_images: Sequence[P
f"Prompt image {image_index} given to model '{model_name}' is "
f"{describe_file_format(format_key=format_key, mime_type=mime_type)}, not an image."
)
- raise PromptImageFormatError(msg)
+ # A prompt's file is known by its position alone here: no input name reaches the worker.
+ raise PromptImageFormatError(msg).with_params(format=format_key, model=model_name)
def check_prompt_documents_are_read(*, model_name: str, supported_document_types: set[str], prompt_documents: Sequence[PromptDocument]) -> None:
@@ -49,4 +50,5 @@ def check_prompt_documents_are_read(*, model_name: str, supported_document_types
f"{describe_file_format(format_key=format_key, mime_type=mime_type)}, which it does not read: "
f"it reads {describe_format_keys(format_keys=supported_document_types)}."
)
- raise PromptDocumentFormatError(msg)
+ # A prompt's file is known by its position alone here: no input name reaches the worker.
+ raise PromptDocumentFormatError(msg).with_params(format=format_key, model=model_name)
diff --git a/pipelex/cogt/model_backends/backend_library.py b/pipelex/cogt/model_backends/backend_library.py
index 55fbeeaba..0023abef1 100644
--- a/pipelex/cogt/model_backends/backend_library.py
+++ b/pipelex/cogt/model_backends/backend_library.py
@@ -25,6 +25,7 @@ from pipelex.cogt.model_backends.credential_resolution import CredentialResoluti
from pipelex.cogt.model_backends.model_spec_document import (
MODEL_SPEC_DEFAULTS_TABLE,
MODEL_SPEC_HANDLE_FIELD,
+ DeclaredModelSpec,
describe_defaults_not_a_table,
describe_duplicate_declared_model,
describe_handle_in_defaults,
@@ -112,10 +113,14 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
root: InferenceBackendLibraryRoot = Field(default_factory=dict)
_stale_warning: StaleConfigurationWarning | None = PrivateAttr(default=None)
+ # The models each disabled backend's file declares, read for their names and types only: what this deployment's
+ # catalogs know of, beyond what an enabled backend serves.
+ _disabled_backend_declarations: dict[str, list[DeclaredModelSpec]] = PrivateAttr(default_factory=dict)
def reset(self):
self.root = {}
self._stale_warning = None
+ self._disabled_backend_declarations = {}
@classmethod
def make_empty(cls) -> Self:
@@ -225,6 +230,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
inference_backend_blueprint_dict_raw = backend_table.copy()
enabled = inference_backend_blueprint_dict_raw.get("enabled", True)
if not enabled and not include_disabled:
+ self._note_disabled_backend_declarations(backend_name=backend_name, backends_dir_path=backends_dir_path)
continue
if enabled and MODEL_SPECS_SECTION_KEY in backend_table:
# The key once pointed at specs the remote config served. Read as an extra key, it would
@@ -780,6 +786,40 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
self.root[PipelexBackend.INTERNAL] = internal_backend.model_copy(update={"model_specs": merged_model_specs})
return True
+ def _note_disabled_backend_declarations(self, *, backend_name: str, backends_dir_path: str) -> None:
+ """Note the models a disabled backend's file declares, which this deployment knows of but does not serve.
+
+ Only their names and types are read, nothing validated or substituted: a disabled backend's file is never
+ loaded, so a file that is missing, is not UTF-8 text or does not parse declares nothing here, as it refuses
+ nothing at boot. A backend's file has no override files, enabled or not (`_load_local_model_specs`), so the
+ one file is all it declares.
+ """
+ path = backend_toml_path(backends_dir_path=backends_dir_path, backend_name=backend_name)
+ try:
+ document = load_toml_from_path(path=path)
+ except (OSError, UnicodeDecodeError, TomlError):
+ return
+ self._disabled_backend_declarations[backend_name] = list_declared_model_specs(document=document)
+
+ def get_cataloged_types_by_handle(self) -> dict[str, list[ModelType]]:
+ """Every handle a backend file of this deployment declares, enabled or not, with each model type it is declared as.
+
+ What the catalogs this runtime reads know: a handle here that the model deck does not serve as a type it is
+ declared as names a model that exists, which no enabled backend of this deployment serves.
+ """
+ cataloged_types_by_handle = self.get_declared_types_by_handle()
+ for declarations in self._disabled_backend_declarations.values():
+ for declared in declarations:
+ try:
+ model_type = ModelType(declared.model_type)
+ except ValueError:
+ # A type no model type names: the file is not loaded, so nothing refuses it, and it declares nothing.
+ continue
+ declared_types = cataloged_types_by_handle.setdefault(declared.handle, [])
+ if model_type not in declared_types:
+ declared_types.append(model_type)
+ return cataloged_types_by_handle
+
def list_backend_names(self) -> list[str]:
return list(self.root.keys())
diff --git a/pipelex/cogt/models/model_deck.py b/pipelex/cogt/models/model_deck.py
index 6ceb7c3c4..ad97b1348 100644
--- a/pipelex/cogt/models/model_deck.py
+++ b/pipelex/cogt/models/model_deck.py
@@ -54,6 +54,7 @@ from pipelex.system.runtime import ProblemReaction
from pipelex.system.telemetry.otel_constants import OTelLogAttr
from pipelex.tools.log.error_fields import error_fields
from pipelex.tools.log.log_fields import USER_ACTION_FIELD
+from pipelex.tools.misc.string_utils import close_matches
from pipelex.urls import URLs
LLM_PRESET_DISABLED = "disabled"
@@ -198,10 +199,19 @@ class ModelDeckBlueprint(ConfigModel):
judgment: JudgmentDeckBlueprint = Field(default_factory=JudgmentDeckBlueprint)
+# How near a handle must be to a name the deck does not hold to be offered in its place, as difflib's similarity
+# ratio, and how many are offered.
+CLOSE_HANDLE_CUTOFF = 0.5
+CLOSE_HANDLE_MAX_MATCHES = 5
+
+
class ModelDeck(ConfigModel):
model_deck_config: ModelDeckConfig
# The models the deck serves, by model type and handle: a handle names one model per model type.
inference_models: ModelSpecIndex = Field(default_factory=ModelSpecIndex.make_empty)
+ # Every handle a backend file of this deployment declares, enabled or not, with the model types it is declared as:
+ # what the catalogs the runtime reads know, which a model the deck does not serve may still be.
+ cataloged_handles: dict[str, list[ModelType]] = Field(default_factory=dict)
# Track which model_handle fallback warnings have been logged to avoid duplicates
_logged_fallback_warnings: set[str] = PrivateAttr(default_factory=set[str])
@@ -324,6 +334,28 @@ class ModelDeck(ConfigModel):
case ModelReferenceKind.HANDLE:
return self.is_bare_handle_resolvable(name=reference.name, model_type=model_type)
+ def is_cataloged_but_unserved(self, *, name: str, model_type: ModelType) -> bool:
+ """Whether a catalog of this deployment knows a model of this name as this type, which the deck does not serve.
+
+ The model exists, declared by a backend that is not enabled or that the routing profile sends nothing to, so a
+ reference naming it is refused as a model this deployment does not serve (``model.unavailable``), whose fix is
+ the deployment's, rather than as one no catalog knows (``model.unknown``), whose fix is the reference's spelling.
+ """
+ if self.inference_models.get(model_type=model_type, handle=name) is not None:
+ return False
+ return model_type in self.cataloged_handles.get(name, [])
+
+ def close_handles(self, *, name: str, model_type: ModelType) -> list[str]:
+ """The handles the deck serves as this type nearest a name it does not, nearest first, each written as a reference.
+
+ The suggestions a refusal of an unknown model offers when it names a handle: an empty list when none is near.
+ """
+ candidates = self.inference_models.handles_of_type(model_type=model_type)
+ return [
+ write_model_handle(name=match)
+ for match in close_matches(name=name, candidates=candidates, cutoff=CLOSE_HANDLE_CUTOFF, max_matches=CLOSE_HANDLE_MAX_MATCHES)
+ ]
+
def is_served_only_as_other_types(self, *, name: str, model_type: ModelType) -> bool:
"""Whether the deck serves a model of this name, but never as this model type.
@@ -336,9 +368,13 @@ class ModelDeck(ConfigModel):
def unresolved_handle_sentence(self, *, name: str, model_type: ModelType) -> str:
"""The sentence refusing a bare handle that does not resolve for this model type.
- It names the handle and the type the field needs. When the deck serves a model of that name
- only as other types, it says so rather than calling the handle missing, without naming them.
+ It names the handle and the type the field needs. When a catalog of this deployment declares a
+ model of that name and type that no enabled backend serves, it says so; when the deck serves a
+ model of that name only as other types, it says so too, without naming them; otherwise it calls
+ the handle missing.
"""
+ if self.is_cataloged_but_unserved(name=name, model_type=model_type):
+ return f"Model handle '{name}' names {model_type.indefinite_description} no enabled backend of this deployment serves"
if self.is_served_only_as_other_types(name=name, model_type=model_type):
return f"Model handle '{name}' is served by the model deck, but not as {model_type.indefinite_description}"
return f"Model handle '{name}' was not found in the model deck"
@@ -1135,7 +1171,9 @@ class ModelDeck(ConfigModel):
f"Model handle '{waterfall_name}' is a waterfall (i.e. a list of models to try in order) "
"but none of the fallback models were found in the model deck"
)
- raise ModelWaterfallError(message=msg, model_handle=waterfall_name, fallback_list=fallback_list)
+ raise ModelWaterfallError(message=msg, model_handle=waterfall_name, fallback_list=fallback_list).with_params(
+ model=waterfall_name, model_type=model_type, reason=ModelUnavailableReason.NO_FALLBACK_SERVED
+ )
def _resolve_alias(
self,
@@ -1387,6 +1425,13 @@ class ModelDeck(ConfigModel):
# a backend that is not enabled) stays the deployment's fault, `model.unavailable`, and stays
# redacted, with no next step.
# The advice is the local CLI's tip; a problem's reader gets the code's own next step.
+ # A model a catalog of this deployment knows as that type, on a backend that is not enabled, exists:
+ # its refusal is the deployment's, `model.unavailable`, rather than a reference no catalog knows.
+ if self.is_cataloged_but_unserved(name=model_handle, model_type=model_type):
+ unserved_msg = f"{self.unresolved_handle_sentence(name=model_handle, model_type=model_type)}."
+ raise ModelNotFoundError(message=unserved_msg, model_handle=model_handle).with_params(
+ model=model_handle, model_type=model_type, reason=ModelUnavailableReason.NOT_SERVED
+ )
change_model = UserAction(
kind=UserActionKind.CHANGE_MODEL,
detail=f"Change the model '{model_handle}' to {model_type.indefinite_description} the model deck serves.",
@@ -1394,7 +1439,11 @@ class ModelDeck(ConfigModel):
raise (
ModelNotFoundError(message=msg, model_handle=model_handle, user_action=change_model)
.with_error_code(CoreCode.MODEL_UNKNOWN)
- .with_params(model=model_handle, model_type=model_type)
+ .with_params(
+ model=model_handle,
+ model_type=model_type,
+ suggestions=self.close_handles(name=model_handle, model_type=model_type),
+ )
)
raise ModelNotFoundError(message=msg, model_handle=model_handle).with_params(
model=model_handle, model_type=model_type, reason=ModelUnavailableReason.NOT_SERVED
diff --git a/pipelex/cogt/models/model_deck_check.py b/pipelex/cogt/models/model_deck_check.py
index 5a085a4d3..d2ad6b901 100644
--- a/pipelex/cogt/models/model_deck_check.py
+++ b/pipelex/cogt/models/model_deck_check.py
@@ -30,8 +30,10 @@ def _raise_model_choice_not_found(
) -> NoReturn:
"""Compute fuzzy suggestions and raise ModelChoiceNotFoundError.
- A bare handle the deck serves only as other types names a model that exists, so its refusal is the capability
- that model lacks, `model.capability_unsupported`, rather than an unknown model.
+ A bare handle a catalog of this deployment declares as this type, which no enabled backend serves, names a model
+ that exists, so its refusal is the deployment's, `model.unavailable` (reason `not_served`); a bare handle the deck
+ serves only as other types names a model that exists too, so its refusal is the capability that model lacks,
+ `model.capability_unsupported`; any other reference is `model.unknown`, with the deck's close matches.
"""
suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(
model_deck=model_deck, model_type=model_type, name=name, kind=reference_kind
@@ -48,6 +50,8 @@ def _raise_model_choice_not_found(
)
match reference_kind:
case ModelReferenceKind.HANDLE:
+ if model_deck.is_cataloged_but_unserved(name=name, model_type=model_type):
+ raise not_found.with_error_code(CoreCode.MODEL_UNAVAILABLE)
if model_deck.is_served_only_as_other_types(name=name, model_type=model_type):
raise not_found.with_error_code(CoreCode.MODEL_CAPABILITY_UNSUPPORTED)
raise not_found
diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.py
index 03fba13eb..4cbf386b9 100644
--- a/pipelex/cogt/models/model_manager.py
+++ b/pipelex/cogt/models/model_manager.py
@@ -224,6 +224,7 @@ class ModelManager(ModelManagerAbstract):
return ModelDeck(
inference_models=inference_models,
+ cataloged_handles=self.inference_backend_library.get_cataloged_types_by_handle(),
# LLM
llm_default_temperature=model_deck_blueprint.llm.choice_defaults.default_temperature,
llm_aliases=model_deck_blueprint.llm.aliases,
diff --git a/pipelex/cogt/models/model_suggestion.py b/pipelex/cogt/models/model_suggestion.py
index 6554e6298..649ea4a6a 100644
--- a/pipelex/cogt/models/model_suggestion.py
+++ b/pipelex/cogt/models/model_suggestion.py
@@ -4,11 +4,10 @@ Provides functions to find close matches for model names and detect wrong-sigil
Used by the CLI check-model command, the model deck validation layer and the model reference check.
"""
-import difflib
from typing import NamedTuple
from pipelex.cogt.model_backends.model_type import ModelType
-from pipelex.cogt.models.model_deck import ModelDeck
+from pipelex.cogt.models.model_deck import CLOSE_HANDLE_CUTOFF, CLOSE_HANDLE_MAX_MATCHES, ModelDeck
from pipelex.cogt.models.model_reference import (
SIGIL_ALIAS,
SIGIL_PRESET,
@@ -16,6 +15,7 @@ from pipelex.cogt.models.model_reference import (
ModelReferenceKind,
write_model_handle,
)
+from pipelex.tools.misc.string_utils import close_matches
KIND_SIGILS: dict[ModelReferenceKind, str] = {
ModelReferenceKind.PRESET: SIGIL_PRESET,
@@ -90,9 +90,10 @@ class ModelAlternatives(NamedTuple):
# How near a name must be to be offered, as difflib's similarity ratio, and how many are offered: the
# threshold is stricter for another kind than for the reference's own, since a slip of the name alone is
-# likelier than a slip of both the name and the sigil.
-_SAME_KIND_CUTOFF = 0.5
-_SAME_KIND_MAX_MATCHES = 5
+# likelier than a slip of both the name and the sigil. The reference's own kind follows the deck's rule for
+# its handles (`ModelDeck.close_handles`).
+_SAME_KIND_CUTOFF = CLOSE_HANDLE_CUTOFF
+_SAME_KIND_MAX_MATCHES = CLOSE_HANDLE_MAX_MATCHES
_CROSS_KIND_CUTOFF = 0.7
_CROSS_KIND_MAX_MATCHES = 3
@@ -115,7 +116,7 @@ def find_model_alternatives(*, model_deck: ModelDeck, model_type: ModelType, nam
candidates = get_collection_keys(model_deck, model_type=model_type, kind=kind)
same_kind = [
ModelReferenceName(kind=kind, name=match)
- for match in difflib.get_close_matches(name, candidates, n=_SAME_KIND_MAX_MATCHES, cutoff=_SAME_KIND_CUTOFF)
+ for match in close_matches(name=name, candidates=candidates, cutoff=_SAME_KIND_CUTOFF, max_matches=_SAME_KIND_MAX_MATCHES)
]
other_kinds: list[ModelReferenceName] = []
@@ -129,7 +130,7 @@ def find_model_alternatives(*, model_deck: ModelDeck, model_type: ModelType, nam
else:
cross_kind.extend(
ModelReferenceName(kind=other_kind, name=match)
- for match in difflib.get_close_matches(name, other_candidates, n=_CROSS_KIND_MAX_MATCHES, cutoff=_CROSS_KIND_CUTOFF)
+ for match in close_matches(name=name, candidates=other_candidates, cutoff=_CROSS_KIND_CUTOFF, max_matches=_CROSS_KIND_MAX_MATCHES)
)
return ModelAlternatives(same_kind=same_kind, other_kinds=other_kinds, cross_kind=cross_kind)
diff --git a/pipelex/core/exceptions.py b/pipelex/core/exceptions.py
index 5eaa3f872..c53be2271 100644
--- a/pipelex/core/exceptions.py
+++ b/pipelex/core/exceptions.py
@@ -53,6 +53,10 @@ class PipelexBundleBlueprintValidationErrorData(BaseModel):
# so the item keeps the location its pydantic ``loc`` named (``pipe.<code>.<field>``).
field_path: str | None = None
+ # The dot path of the failing field inside the table of the pipe ``pipe_code`` names, set when a blueprint-stage
+ # ``PipeValidationError`` names its field: ``input_item_name`` on a PipeBatch, or ``steps.0.batch_as`` on a step.
+ field_name: 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
@@ -62,6 +66,16 @@ class PipelexBundleBlueprintValidationErrorData(BaseModel):
# ``unresolved_concept`` error so the author sees what the reference could have named.
declared_concepts: list[str] | None = None
+ # The name an ``invalid_pipe_code_syntax`` error is about, as the method writes it: the declaration key, or the
+ # ``main_pipe`` value, which ``field_path`` (``main_pipe``) tells apart.
+ identifier_name: str | None = None
+
+ # The parameters of the item's code its raise site knows about this one item, by the registry's names, for an
+ # error no ``error_type`` classifies, which takes the code of the refusal it rides: they take precedence over the
+ # refusal's own, which describe its first fault. A refusal of several lines of a ``requirements.txt`` names each
+ # line's requirement here.
+ params: dict[str, Any] | 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
@@ -161,6 +175,12 @@ class PipesAndConceptValidationErrorData(BaseModel):
description="The deck's close matches of the same kind, each spelled as a reference the field accepts",
)
+ # === The parameters of the item's code its raise site gave, by the registry's names ===
+ params: dict[str, Any] | None = Field(
+ default=None,
+ description="The parameters of the item's code the raise site knows beside the locators above, those a caller may read",
+ )
+
class DryRunFailureErrorData(BaseModel):
"""Structured error data for one pipe whose dry run failed.
diff --git a/pipelex/core/memory/exceptions.py b/pipelex/core/memory/exceptions.py
index f66bd3e44..da0e23448 100644
--- a/pipelex/core/memory/exceptions.py
+++ b/pipelex/core/memory/exceptions.py
@@ -64,6 +64,8 @@ class InputShapingError(PipelexError):
The message is the operator's diagnostics, so what the caller needs in order to act rides the problem: the input
as the ``input`` parameter and ``location.input``, and the facts each factory knows as the parameters its code's
template declares, such as the counts of ``input.wrong_multiplicity`` or the concepts of ``input.wrong_concept``.
+ The ``field`` of ``input.invalid`` is the dotted path of the field that fails inside the value when the refusal
+ names one, and the input's own name, the root of every such path, when the whole value is at fault.
"""
error_code: ClassVar[ErrorCodeDeclaration] = ABSTRACT_ERROR
@@ -84,7 +86,10 @@ class InputShapingError(PipelexError):
@override
def problem_params(self) -> dict[str, Any]:
- return {"input": self.variable_name, **self.shaping_params}
+ params: dict[str, Any] = {"input": self.variable_name, **self.shaping_params}
+ if params.get("field") is None:
+ params["field"] = self.variable_name
+ return params
@override
def problem_location(self) -> ProblemLocation | None:
diff --git a/pipelex/core/method_trees/tree_python.py b/pipelex/core/method_trees/tree_python.py
index 63d7c11ab..62f401910 100644
--- a/pipelex/core/method_trees/tree_python.py
+++ b/pipelex/core/method_trees/tree_python.py
@@ -42,7 +42,7 @@ from typing import NamedTuple, cast
from mthds.method_tree.models import MethodTree
from mthds.method_tree.tree_path import nfc
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from typing_extensions import Buffer, override
from pipelex import log
@@ -160,7 +160,7 @@ def check_tree_module_names(*, top_level_modules: Mapping[str, str], tree_label:
"With the tree's root first on the import path, it would replace that module for the whole process: rename it, "
"for example by moving it into a package of the method's own."
)
- raise TreeModuleShadowingError(msg)
+ raise TreeModuleShadowingError(msg).with_params(name=module_name, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
if passed_checks is not None:
passed_checks.add(check_key)
@@ -578,5 +578,9 @@ def import_held_tree_module(*, identity: TreePythonIdentity, module_name: str) -
f"The module '{module_name}' resolved outside {identity.describe()}: a module of that name was imported in this "
"process before the tree's Python loaded."
)
- raise TreePythonError(msg).with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ raise (
+ TreePythonError(msg)
+ .with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_params(name=module_name, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
+ )
return module
diff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.py
index ce1b44ee7..a8e4470bf 100644
--- a/pipelex/core/pipes/exceptions.py
+++ b/pipelex/core/pipes/exceptions.py
@@ -97,9 +97,11 @@ class PipeRunError(PipelexError):
),
)
- def __init__(self, message: str, run_mode: PipeRunMode, pipe_code: str):
+ def __init__(self, message: str, run_mode: PipeRunMode, pipe_code: str, field: str | None = None):
self.run_mode = run_mode
self.pipe_code = pipe_code
+ # The field of the pipe the failure is located on, as the bundle writes it, when one field is at fault.
+ self.field = field
super().__init__(message)
@override
@@ -108,7 +110,7 @@ class PipeRunError(PipelexError):
@override
def problem_location(self) -> ProblemLocation | None:
- return make_location(pipe=self.pipe_code)
+ return make_location(pipe=self.pipe_code, field=self.field)
class PipeOperatorModelChoiceError(PipelexError):
@@ -310,6 +312,10 @@ def pipe_validation_error_code(*, error_type: PipeValidationErrorType | None) ->
return CoreCode.METHOD_SCHEMA_VIOLATION
+# The name a refusal gives a pipe's own output where its code names an input or an output: the field that declares it.
+PIPE_OUTPUT_NAME = "output"
+
+
class PipeValidationError(PipelexError, ValueError):
"""A pipe that breaks a rule of the language or of its pipe type, found when the bundle is validated.
@@ -407,6 +413,11 @@ class PipeValidationError(PipelexError, ValueError):
super().__init__(message)
self.with_error_code(pipe_validation_error_code(error_type=error_type))
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ # The facts every refusal of a pipe holds; its raise site gives the others its code requires with `with_params`.
+ return {"pipe": self.pipe_code, "variables": self.variable_names, "model": self.model_reference}
+
def desc(self) -> str:
msg = f"{self.error_type} • domain_code='{self.domain_code}'"
if self.pipe_code:
diff --git a/pipelex/core/pipes/variable_multiplicity.py b/pipelex/core/pipes/variable_multiplicity.py
index 2206af156..7af08167f 100644
--- a/pipelex/core/pipes/variable_multiplicity.py
+++ b/pipelex/core/pipes/variable_multiplicity.py
@@ -3,6 +3,7 @@ from __future__ import annotations
import re
from mthds.protocol.pipe_io_contracts import PresenceMarker
+from mthds.protocol.problem.registry import MethodOutputMultiplicityMismatchExpected
from pydantic import BaseModel, Field
from pipelex.core.pipes.exceptions import PipeVariableMultiplicityError
@@ -19,6 +20,7 @@ __all__ = [
"is_multiple_multiplicity",
"is_multiplicity_compatible",
"make_variable_multiplicity",
+ "multiplicity_kind",
"multiplicity_from_bracket_content",
"normalize_variable_multiplicity",
"parse_concept_with_multiplicity",
@@ -174,6 +176,18 @@ def fixed_item_count(*, multiplicity: VariableMultiplicity | None) -> int | None
return multiplicity if multiplicity > 1 else None
+def multiplicity_kind(*, multiplicity: VariableMultiplicity | None) -> MethodOutputMultiplicityMismatchExpected:
+ """The kind of a multiplicity as a problem names it: one item, a list, or a list of a fixed length.
+
+ A fixed count of one (`[1]`) is one item, as everywhere else in the chain.
+ """
+ if fixed_item_count(multiplicity=multiplicity) is not None:
+ return MethodOutputMultiplicityMismatchExpected.FIXED
+ if is_multiple_multiplicity(multiplicity=multiplicity):
+ return MethodOutputMultiplicityMismatchExpected.LIST
+ return MethodOutputMultiplicityMismatchExpected.SINGLE
+
+
class MultiplicityParseResult(BaseModel):
concept_ref_or_code: str
multiplicity: int | bool | None
diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.py
index 3008f0fc5..5535a81bb 100644
--- a/pipelex/core/stuffs/stuff_factory.py
+++ b/pipelex/core/stuffs/stuff_factory.py
@@ -21,6 +21,7 @@ from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_content_factory import StuffContentFactory
from pipelex.core.stuffs.text_content import TextContent
from pipelex.errors.error_codes import error_code_spec
+from pipelex.errors.unsupported_reasons import REMOTE_TABLE_UNSUPPORTED_REASON
from pipelex.runtime_hub import get_class_registry
from pipelex.tools.storage.storage_provider_abstract import PIPELEX_STORAGE_SCHEME
from pipelex.tools.tabular.csv_codec import is_tabular_path, list_content_from_csv
@@ -36,6 +37,15 @@ from pipelex.tools.uri.uri_resolver import resolve_uri
_NAMED_REMOTE_SCHEMES: frozenset[str] = frozenset({"http", "https", "s3", "gs", PIPELEX_STORAGE_SCHEME.removesuffix("://")})
+# The kind of file a table input is read as, the `file_type` of `input.file_unreadable`.
+_TABLE_FILE_TYPE = "csv"
+
+
+def _input_request_field(*, name: str | None) -> str:
+ """The request's field, as a dotted path, that gives a table input: `inputs.<name>`, or `inputs` for an unnamed one."""
+ return f"inputs.{name}" if name is not None else "inputs"
+
+
class StuffBlueprint(BaseModel):
stuff_name: str
concept_ref: str
@@ -257,7 +267,12 @@ class StuffFactory:
f"'{concept.concept_ref}' has a url that could not be parsed. "
"Download the file locally and reference it by path."
)
- raise CsvError(msg) from exc
+ raise (
+ CsvError(msg)
+ .with_input(input_name=name)
+ .with_error_code(CoreCode.INPUT_FILE_UNREADABLE)
+ .with_params(file_type=_TABLE_FILE_TYPE, reason="the URL does not parse")
+ ) from exc
# Detect the tabular suffix on the URL's PATH component only. A raw URL fed to ``Path`` keeps
# any ``?query``/``#fragment`` inside ``.suffix`` (e.g. an S3 presigned ``...csv?X-Amz-...``),
# which would hide the ``.csv`` and let a remote ref slip past the local-only guard below.
@@ -278,26 +293,39 @@ class StuffFactory:
f"'{concept.concept_ref}' points at a remote or non-local url{in_scheme}. "
"Download the file locally and reference it by path."
)
- raise CsvError(msg)
+ raise (
+ CsvError(msg)
+ .with_input(input_name=name)
+ .with_error_code(CoreCode.REQUEST_UNSUPPORTED)
+ .with_params(field=_input_request_field(name=name), reason=REMOTE_TABLE_UNSUPPORTED_REASON)
+ )
try:
row_model = concept_provider.get_structure_class(concept=concept)
except ConceptValueError as exc:
- # Keep the codec's typed-error boundary intact: an unregistered structure class is a
- # caller-fixable input problem, not a raw ValueError that escapes into core/runner.
+ # Keep the codec's typed-error boundary intact: an unregistered structure class is no fault of the caller's
+ # table but of the method's concept, which cannot be built, and never a raw ValueError escaping into the runner.
msg = f"CSV input for stuff '{name}': concept '{concept.concept_ref}' has no registered structure class to read CSV rows into."
- raise CsvError(msg) from exc
+ raise (
+ CsvError(msg)
+ .with_input(input_name=name)
+ .with_error_code(CoreCode.METHOD_CONCEPT_INVALID)
+ .with_params(concept=concept.concept_ref, finding="it has no structure class to read rows into")
+ ) from exc
authorize_uri_read(
uri=url,
read_scope=read_scope,
position=f"the table given for input '{name}'" if name is not None else "a table given as an input",
+ input_name=name,
)
try:
return list_content_from_csv(Path(resolved.path), row_model=row_model, input_name=name)
except CsvError as exc:
- # The codec names the file by the input it was given as, and the code's sentences name it as well.
- if name is not None and "input" in error_code_spec(exc.resolve_error_code()).param_names:
- exc.with_params(input=name)
+ # The codec names the file by the input it was given as, and the problem names and locates it as well: the input,
+ # and, for a code naming the field at fault, the input itself when the codec located the fault nowhere inside it.
+ exc.with_input(input_name=name)
+ if name is not None and "field" in error_code_spec(exc.resolve_error_code()).param_names and exc.given_params.get("field") is None:
+ exc.with_params(field=name)
raise
@classmethod
diff --git a/pipelex/errors/error_codes.py b/pipelex/errors/error_codes.py
index da78307ca..a848c175a 100644
--- a/pipelex/errors/error_codes.py
+++ b/pipelex/errors/error_codes.py
@@ -47,6 +47,10 @@ class ErrorCodeSpec(BaseModel):
type_uri: The code's documentation page: its registry's base URL, a slash, then the code.
params_model: The generated model of the code's parameters.
param_names: Every parameter the code declares.
+ required_params: The parameters a caller reads on every occurrence of the code: every one the registry marks
+ neither optional nor operator-only, the rule a conformance check holds a caller's problem to. A problem or
+ an item that lacks one is a fault of its raise site, which
+ :func:`pipelex.errors.problem.missing_required_params` names.
operator_only_params: The parameters only whoever runs the runtime may read: they render into the
operator's step and ride the operator's diagnostics, never a problem's ``params``.
"""
@@ -66,8 +70,14 @@ class ErrorCodeSpec(BaseModel):
type_uri: str
params_model: type[BaseModel]
param_names: frozenset[str]
+ required_params: frozenset[str]
operator_only_params: frozenset[str]
+ @property
+ def caller_param_names(self) -> frozenset[str]:
+ """The parameters a caller may read: every one the code declares but the operator-only ones."""
+ return self.param_names - self.operator_only_params
+
@property
def invites_retry(self) -> bool:
"""Whether the verdict invites a repeat of the operation: only ``yes``, never ``no`` nor ``outcome_unknown``."""
@@ -96,6 +106,7 @@ def _build_specs() -> dict[str, ErrorCodeSpec]:
type_uri=f"{CORE_BASE_URL}/{core_code}",
params_model=core_spec.params_model,
param_names=frozenset(param.name for param in core_spec.params),
+ required_params=frozenset(param.name for param in core_spec.params if not param.optional and not param.operator_only),
operator_only_params=frozenset(param.name for param in core_spec.params if param.operator_only),
)
for pipelex_code in PipelexErrorCode:
@@ -115,6 +126,9 @@ def _build_specs() -> dict[str, ErrorCodeSpec]:
type_uri=f"{PIPELEX_ERROR_BASE_URL}/{pipelex_code}",
params_model=params_model,
param_names=frozenset(params_model.model_fields),
+ required_params=frozenset(
+ name for name, field in params_model.model_fields.items() if field.is_required() and name not in params_model.operator_only_params
+ ),
operator_only_params=params_model.operator_only_params,
)
return specs
diff --git a/pipelex/errors/failure_problem.py b/pipelex/errors/failure_problem.py
index 7b5cd5275..e5d81e671 100644
--- a/pipelex/errors/failure_problem.py
+++ b/pipelex/errors/failure_problem.py
@@ -63,7 +63,7 @@ def failure_diagnostics(*, cause: BaseException | None) -> ProblemDiagnostics |
if cause is None:
return None
if isinstance(cause, PipelexError):
- return cause.to_problem(view=ProblemView.OPERATOR).diagnostics
+ return cause.operator_diagnostics()
return foreign_failure_diagnostics(error=cause)
diff --git a/pipelex/errors/problem.py b/pipelex/errors/problem.py
index a55548db7..00123ab28 100644
--- a/pipelex/errors/problem.py
+++ b/pipelex/errors/problem.py
@@ -23,9 +23,18 @@ template that cannot be rendered, because a parameter it names was not given, fa
can be given the parameter.
**The parameters.** A problem's ``params`` hold the parameters the code declares and the raise site gave, validated
-against the code's generated model: an undeclared parameter, or one of the wrong type, is dropped and logged. A
-parameter the registry declares operator-only never rides ``params`` in any view; it renders into the operator's step
-and rides ``diagnostics.params``.
+against the code's generated model: an undeclared parameter, or one of the wrong type, is dropped and logged. The
+member is present whenever the code declares a parameter a caller may read, an empty object on an occurrence that has
+none of them, as the protocol puts it on every problem whose code declares parameters. A parameter a caller may read
+that the registry does not mark optional is present on every occurrence, so a problem or an item built without one is a
+fault of its raise site, logged with the parameters it lacks (:func:`missing_required_params`), unless the runner
+withholds it by rule, as a template refusal withholds a name the run's data chose. A parameter the registry declares
+operator-only never rides ``params`` in any view; it renders into the operator's step and rides ``diagnostics.params``.
+
+**One fault, no list.** ``errors`` lists the faults of a problem with several. A problem built with a single item
+restating its own code has one fault, so the item is folded into it: its parameters and its location fill those the
+problem lacks, and the list is left out (:func:`make_problem`). An item carrying suggestions or a suggested fix fills
+them too but stays the list's one item, since only an item has members for those.
**The bound.** Every text a raise site, a provider or a caller wrote is capped at :data:`MAX_PROBLEM_TEXT_LENGTH`
characters, keeping its head, which names the fault: an exception's message, a provider's message and every text
@@ -44,7 +53,7 @@ import logging
import math
from enum import Enum, StrEnum
from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, NamedTuple, cast
from mthds.protocol.problem.client_problems import render_template
from mthds.protocol.problem.models import NextStep, Problem, ProblemItem, ProblemLocation, ProblemParams
@@ -351,6 +360,45 @@ _GENERIC_STEP_SENTENCES: dict[StepKind, str] = {
}
+class _CodeSentences(NamedTuple):
+ """The templates of a code's sentences: its ``detail``, its actor's step and any other reader's step."""
+
+ detail: str
+ actor_step_detail: str
+ other_step_detail: str
+
+
+# The sentences of a code whose required parameter a runner withholds by rule, keyed by the code and the parameters it
+# withholds, until the standard words that occurrence itself. `security.template_refused` requires `name`, but a name the
+# template looked up from the run's data is the run's input, which no problem carries (`pipelex.tools.jinja2`), so its
+# refusal carries no `name`: its sentences then say what happened without the name, rather than the code's title and the
+# generic step. No raise site is at fault for a parameter withheld by rule, so its absence is not logged
+# (`missing_required_params`); any other parameter the code requires still is.
+_WITHHELD_PARAM_SENTENCES: dict[tuple[str, frozenset[str]], _CodeSentences] = {
+ ("security.template_refused", frozenset({"name"})): _CodeSentences(
+ detail="A template of pipe '{pipe}' looked a name up from the run's data, and the template sandbox refused that name.",
+ actor_step_detail=(
+ "Change the templates of pipe '{pipe}' so that the run's data no longer chooses the names they look up, then run the method again."
+ ),
+ other_step_detail=(
+ "Ask the method's owner to change the templates of pipe '{pipe}' so that the run's data no longer chooses the names they look up."
+ ),
+ ),
+}
+
+
+def _code_sentences(*, spec: ErrorCodeSpec, params: Mapping[str, Any]) -> _CodeSentences:
+ """The templates of a code's sentences for the parameters given: the code's own, or the wording of a withheld parameter.
+
+ The wording of :data:`_WITHHELD_PARAM_SENTENCES` replaces the code's own only when every parameter it withholds is
+ absent, so every rendering of one problem, in any view and after any projection, picks the same sentences.
+ """
+ for (code, withheld), sentences in _WITHHELD_PARAM_SENTENCES.items():
+ if code == spec.code and not any(name in params for name in withheld):
+ return sentences
+ return _CodeSentences(detail=spec.detail, actor_step_detail=spec.actor_step_detail, other_step_detail=spec.other_step_detail)
+
+
# The logger of the faults of a raise site this module finds while it builds a problem. This module sits under the
# import chain of `pipelex.log` itself, whose configuration loads the error classes that build problems, so it cannot
# import the log, and emits its records on this stdlib logger instead, with the same attached fields, through the
@@ -463,7 +511,7 @@ def accepted_params(*, code: ErrorCode, params: Mapping[str, Any]) -> dict[str,
if value is None:
continue
if name not in spec.param_names:
- _warn(message="An error gives a parameter its code does not declare", fields={"error.code": code, "param": name})
+ _warn(message=UNDECLARED_PARAM_MESSAGE, fields={"error.code": code, "param": name})
continue
param_value = _param_value(value=value)
if param_value is _NOT_A_PARAM_VALUE:
@@ -514,6 +562,68 @@ def _drop_refused_params(*, accepted: dict[str, Any], params_model: type[BaseMod
accepted.clear()
+UNDECLARED_PARAM_MESSAGE = "An error gives a parameter its code does not declare"
+"""The message of the warning logged when an error gives a parameter its code does not declare, which is dropped."""
+
+MISSING_REQUIRED_PARAMS_MESSAGE = "A problem lacks a parameter its code requires"
+"""The message of the warning logged when a problem or an item is built without a parameter its code requires.
+
+It names a fault of the raise site, as the warnings about a parameter dropped or a sentence not rendered do, and the
+test suites fail a test during which it is logged, so that no raise site they reach answers less than its code promises.
+"""
+
+
+def missing_required_params(*, code: ErrorCode, params: Mapping[str, Any]) -> list[str]:
+ """The parameters the code requires on every occurrence that ``params`` does not give, by name.
+
+ A parameter a caller may read that the registry does not mark optional is a fact every caller relies on, and the
+ protocol puts it on every occurrence: a problem or an item that lacks one tells its caller less than its code
+ promises, and its sentences fall back on the code's title and the step's generic sentence. An operator-only
+ parameter is not counted, as no caller's problem carries it, and neither is a parameter withheld by rule, such as
+ the `name` of a template refusal whose name the run's data chose: :data:`_WITHHELD_PARAM_SENTENCES` words that
+ occurrence without it, and no raise site is at fault for its absence.
+
+ Args:
+ code: The code of the problem or the item.
+ params: The parameters it was given, by name.
+
+ Returns:
+ The names of the required parameters ``params`` lacks, sorted; empty when it gives them all.
+ """
+ missing = error_code_spec(code).required_params - params.keys()
+ for withheld_code, withheld in _WITHHELD_PARAM_SENTENCES:
+ if withheld_code == code and withheld <= missing:
+ missing -= withheld
+ return sorted(missing)
+
+
+def _report_missing_required_params(*, code: ErrorCode, params: Mapping[str, Any], part: str) -> None:
+ """Log a raise site that built a problem or an item without a parameter its code requires."""
+ missing = missing_required_params(code=code, params=params)
+ if missing:
+ _warn(message=MISSING_REQUIRED_PARAMS_MESSAGE, fields={"error.code": code, "params": missing, "problem_part": part})
+
+
+def _params_member(*, spec: ErrorCodeSpec, caller_params: Mapping[str, Any]) -> ProblemParams | None:
+ """The ``params`` member of a problem or an item: present whenever its code declares a parameter a caller may read."""
+ if not caller_params and not spec.caller_param_names:
+ return None
+ return ProblemParams.model_validate(dict(caller_params))
+
+
+def _lone_item_restating(*, code: ErrorCode, errors: list[ProblemItem] | None) -> ProblemItem | None:
+ """The one item of ``errors`` when it is the only one and restates ``code``: a single fault, which no list carries."""
+ if errors is None or len(errors) != 1:
+ return None
+ lone_item = errors[0]
+ return lone_item if lone_item.code == code else None
+
+
+def _item_carries_remedies(*, item: ProblemItem) -> bool:
+ """Whether an item carries suggestions or a suggested fix, which a problem has no member for: only the item keeps them."""
+ return bool(item.suggestions) or item.suggested_fix is not None
+
+
def _caller_step_is_actor_step(*, domain: ProblemDomain) -> bool:
"""Whether the caller reads the actor's step: for every domain but ``operator``, whose actor is whoever runs the runtime."""
match domain:
@@ -527,14 +637,15 @@ def _next_step(*, spec: ErrorCodeSpec, view: ProblemView, params: Mapping[str, A
"""The step of a view, rendered with the parameters the view may read, a generic sentence of its kind when it cannot be."""
kind: StepKind
template: str
+ sentences = _code_sentences(spec=spec, params=params)
match view:
case ProblemView.OPERATOR:
- kind, template = spec.actor_step, spec.actor_step_detail
+ kind, template = spec.actor_step, sentences.actor_step_detail
case ProblemView.CALLER:
if _caller_step_is_actor_step(domain=spec.domain):
- kind, template = spec.actor_step, spec.actor_step_detail
+ kind, template = spec.actor_step, sentences.actor_step_detail
else:
- kind, template = spec.other_step, spec.other_step_detail
+ kind, template = spec.other_step, sentences.other_step_detail
detail = _render_sentence(template=template, params=params, code=spec.code, part=f"step.{kind}")
return NextStep(kind=kind, detail=detail or _GENERIC_STEP_SENTENCES[kind])
@@ -571,7 +682,10 @@ def make_problem(
location: Where the error happened.
errors: One item per fault, for a refusal with several; a parameter an item's code declares operator-only is
taken out of it in every view, and the caller's view of an item whose code neither registry of this process
- holds carries no parameter (:func:`item_in_view`).
+ holds carries no parameter (:func:`item_in_view`). A single item restating ``code`` is the problem's one
+ fault, so it is folded into the problem: its parameters and its location fill those the problem lacks, and
+ the problem carries no ``errors``, unless the item carries suggestions or a suggested fix, which only an
+ item has members for: it then stays the list's one item.
retry_after: The delay before a retry, kept only when the code's verdict is ``yes`` and the delay is a finite,
non-negative number of seconds: a provider can send any value, ``inf`` included, and the wire takes none of those.
pipeline_run_id: The run the error belongs to.
@@ -582,10 +696,19 @@ def make_problem(
The problem, without a ``status``, which the HTTP response that carries it adds.
"""
spec = error_code_spec(code)
+ lone_fault = _lone_item_restating(code=code, errors=errors)
+ if lone_fault is not None:
+ params = {**(lone_fault.params.as_wire() if lone_fault.params is not None else {}), **(params or {})}
+ if lone_fault.location is not None:
+ location = lone_fault.location if location is None else merge_locations(base=lone_fault.location, override=location)
+ if not _item_carries_remedies(item=lone_fault):
+ errors = None
given = accepted_params(code=code, params=params or {})
+ _report_missing_required_params(code=code, params=given, part="problem")
caller_params = {name: value for name, value in given.items() if name not in spec.operator_only_params}
operator_params = {name: value for name, value in given.items() if name in spec.operator_only_params}
- detail = _render_sentence(template=spec.detail, params=caller_params, code=code, part="detail") or spec.title
+ detail = _render_sentence(template=_code_sentences(spec=spec, params=caller_params).detail, params=caller_params, code=code, part="detail")
+ detail = detail or spec.title
step_params = given if view.shows_diagnostics else caller_params
view_diagnostics: ProblemDiagnostics | None = None
if view.shows_diagnostics and diagnostics is not None:
@@ -601,7 +724,7 @@ def make_problem(
retry=spec.retry,
retry_after=retry_after if invites_retry and _is_usable_delay(seconds=retry_after) else None,
next_step=_next_step(spec=spec, view=view, params=step_params),
- params=ProblemParams.model_validate(caller_params) if caller_params else None,
+ params=_params_member(spec=spec, caller_params=caller_params),
location=location,
errors=[item_in_view(item=item, view=view) for item in errors] if errors else None,
pipeline_run_id=pipeline_run_id,
@@ -636,13 +759,15 @@ def make_problem_item(
"""
spec = error_code_spec(code)
given = accepted_params(code=code, params=params or {})
+ _report_missing_required_params(code=code, params=given, part="item")
caller_params = {name: value for name, value in given.items() if name not in spec.operator_only_params}
- detail = _render_sentence(template=spec.detail, params=caller_params, code=code, part="detail") or spec.title
+ detail = _render_sentence(template=_code_sentences(spec=spec, params=caller_params).detail, params=caller_params, code=code, part="detail")
+ detail = detail or spec.title
return ProblemItem.model_validate(
_members(
code=spec.code,
detail=detail,
- params=ProblemParams.model_validate(caller_params) if caller_params else None,
+ params=_params_member(spec=spec, caller_params=caller_params),
location=location,
suggestions=suggestions or None,
suggested_fix=dict(suggested_fix) if suggested_fix is not None else None,
@@ -691,10 +816,12 @@ def item_in_view(*, item: ProblemItem, view: ProblemView) -> ProblemItem:
return item
caller_params = {name: value for name, value in params.items() if name not in spec.operator_only_params}
members = item.as_wire()
- members["detail"] = _render_sentence(template=spec.detail, params=caller_params, code=code, part="detail") or spec.title
+ detail_template = _code_sentences(spec=spec, params=caller_params).detail
+ members["detail"] = _render_sentence(template=detail_template, params=caller_params, code=code, part="detail") or spec.title
members.pop("params")
- if caller_params:
- members["params"] = caller_params
+ params_member = _params_member(spec=spec, caller_params=caller_params)
+ if params_member is not None:
+ members["params"] = params_member
return ProblemItem.model_validate(members)
diff --git a/pipelex/errors/registry/pipelex-error-registry.json b/pipelex/errors/registry/pipelex-error-registry.json
index 674819c91..ad82a2939 100644
--- a/pipelex/errors/registry/pipelex-error-registry.json
+++ b/pipelex/errors/registry/pipelex-error-registry.json
@@ -19,6 +19,10 @@
"family": "pipelex.run",
"description": "Pipelex's extensions to runs."
},
+ {
+ "family": "pipelex.request",
+ "description": "Refusals of a request's shape that name a fact no core code carries."
+ },
{
"family": "pipelex.storage",
"description": "Pipelex's storage addresses and uploads."
@@ -613,6 +617,37 @@
"meaning": "The caller chose the run's id, which Pipelex allows as an extension of the protocol, whose run id is always the runner's, and a run already holds that id.",
"what_to_do": "Start the run with a new id, or with none so that the runner assigns it. To see the run that holds the id, read it by that id."
},
+ {
+ "code": "pipelex.request.dependency_key_mismatch",
+ "title": "A dependency is keyed by another address than its manifest declares",
+ "domain": "input",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 422,
+ "detail": "The dependency keyed '{key}' declares the address '{address}', which must be its key.",
+ "steps": {
+ "actor": {
+ "kind": "change_input",
+ "detail": "Key the dependency by '{address}', the address its manifest declares, then send the request again."
+ },
+ "other": {
+ "kind": "change_input",
+ "detail": "Pass this to the caller, who must key the dependency '{key}' by '{address}'."
+ }
+ },
+ "params": {
+ "key": {
+ "type": "identifier",
+ "description": "The key the request gives the dependency in `dependencies`."
+ },
+ "address": {
+ "type": "identifier",
+ "description": "The full address the dependency's manifest declares, its repository address followed by its package name, which its key must be."
+ }
+ },
+ "meaning": "A request ships each package its method calls by address in `dependencies`, keyed by the package's full address: the address its `METHODS.toml` declares, followed by a slash and the package's name. This dependency is keyed by another address, such as its repository address alone, so the method's calls cannot reach it.",
+ "what_to_do": "Key the dependency by `params.address`, the full address its manifest declares, as the method's calls name it."
+ },
{
"code": "pipelex.storage.uri_invalid",
"title": "The storage address is malformed",
@@ -666,9 +701,10 @@
"local",
"s3",
"gcs",
- "memory"
+ "memory",
+ "plugin"
],
- "description": "The kind of storage that no longer holds the file."
+ "description": "The kind of storage that no longer holds the file: one Pipelex ships, or `plugin` for a storage plugin's own."
}
},
"meaning": "A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead.",
@@ -699,9 +735,10 @@
"local",
"s3",
"gcs",
- "memory"
+ "memory",
+ "plugin"
],
- "description": "The kind of storage that holds the damaged file."
+ "description": "The kind of storage that holds the damaged file: one Pipelex ships, or `plugin` for a storage plugin's own."
}
},
"meaning": "Storage still holds an object under the file's key, but its bytes are not the ones the runtime stored: they do not hash to the key the file is stored under, or they are not the size storage holds them at. A retry reads the same damaged object, and no upload writes over it, so it stays until whoever runs the runtime removes it.",
@@ -732,9 +769,10 @@
"local",
"s3",
"gcs",
- "memory"
+ "memory",
+ "plugin"
],
- "description": "The kind of storage that failed."
+ "description": "The kind of storage that failed: one Pipelex ships, or `plugin` for a storage plugin's own."
}
},
"meaning": "The storage backend failed a read or a write, which may succeed later.",
diff --git a/pipelex/errors/registry/pipelex-error-registry.yaml b/pipelex/errors/registry/pipelex-error-registry.yaml
index 616405443..e3c1e24d2 100644
--- a/pipelex/errors/registry/pipelex-error-registry.yaml
+++ b/pipelex/errors/registry/pipelex-error-registry.yaml
@@ -28,6 +28,7 @@ families:
- {family: pipelex.org, description: "Organizations, their members, their API keys and their promo codes."}
- {family: pipelex.catalog, description: "Saved methods in an organization's catalog."}
- {family: pipelex.run, description: "Pipelex's extensions to runs."}
+ - {family: pipelex.request, description: "Refusals of a request's shape that name a fact no core code carries."}
- {family: pipelex.storage, description: "Pipelex's storage addresses and uploads."}
- {family: pipelex.security, description: "Pipelex's own refusals made for safety, each recorded as a security event."}
- {family: pipelex.config, description: "The runtime's own configuration."}
@@ -334,6 +335,24 @@ codes:
meaning: "The caller chose the run's id, which Pipelex allows as an extension of the protocol, whose run id is always the runner's, and a run already holds that id."
what_to_do: "Start the run with a new id, or with none so that the runner assigns it. To see the run that holds the id, read it by that id."
+ # --- pipelex.request. -------------------------------------------------------------------
+
+ - code: pipelex.request.dependency_key_mismatch
+ title: "A dependency is keyed by another address than its manifest declares"
+ domain: input
+ retry: "no"
+ raised_as: problem
+ status: 422
+ detail: "The dependency keyed '{key}' declares the address '{address}', which must be its key."
+ steps:
+ actor: {kind: change_input, detail: "Key the dependency by '{address}', the address its manifest declares, then send the request again."}
+ other: {kind: change_input, detail: "Pass this to the caller, who must key the dependency '{key}' by '{address}'."}
+ params:
+ key: {type: identifier, description: "The key the request gives the dependency in `dependencies`."}
+ address: {type: identifier, description: "The full address the dependency's manifest declares, its repository address followed by its package name, which its key must be."}
+ meaning: "A request ships each package its method calls by address in `dependencies`, keyed by the package's full address: the address its `METHODS.toml` declares, followed by a slash and the package's name. This dependency is keyed by another address, such as its repository address alone, so the method's calls cannot reach it."
+ what_to_do: "Key the dependency by `params.address`, the full address its manifest declares, as the method's calls name it."
+
# --- pipelex.storage. -------------------------------------------------------------------
- code: pipelex.storage.uri_invalid
@@ -363,7 +382,7 @@ codes:
actor: {kind: report, detail: "Report this to whoever runs the runtime."}
other: {kind: report, detail: "Report this to whoever runs the runtime."}
params:
- scheme: {type: enum, values: [local, s3, gcs, memory], description: "The kind of storage that no longer holds the file."}
+ scheme: {type: enum, values: [local, s3, gcs, memory, plugin], description: "The kind of storage that no longer holds the file: one Pipelex ships, or `plugin` for a storage plugin's own."}
meaning: "A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead."
what_to_do: "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id` when it has one."
@@ -378,7 +397,7 @@ codes:
actor: {kind: report, detail: "Report this to whoever runs the runtime."}
other: {kind: report, detail: "Report this to whoever runs the runtime."}
params:
- scheme: {type: enum, values: [local, s3, gcs, memory], description: "The kind of storage that holds the damaged file."}
+ scheme: {type: enum, values: [local, s3, gcs, memory, plugin], description: "The kind of storage that holds the damaged file: one Pipelex ships, or `plugin` for a storage plugin's own."}
meaning: "Storage still holds an object under the file's key, but its bytes are not the ones the runtime stored: they do not hash to the key the file is stored under, or they are not the size storage holds them at. A retry reads the same damaged object, and no upload writes over it, so it stays until whoever runs the runtime removes it."
what_to_do: "Report the problem to whoever runs the runtime, with the `request_id`. Once they have removed the damaged object, upload the file again."
@@ -393,7 +412,7 @@ codes:
actor: {kind: retry, detail: "Send the request again after a while."}
other: {kind: wait, detail: "Wait, then send the request again."}
params:
- scheme: {type: enum, values: [local, s3, gcs, memory], description: "The kind of storage that failed."}
+ scheme: {type: enum, values: [local, s3, gcs, memory, plugin], description: "The kind of storage that failed: one Pipelex ships, or `plugin` for a storage plugin's own."}
meaning: "The storage backend failed a read or a write, which may succeed later."
what_to_do: "Send the request again after `retry_after` seconds when the problem gives it. If storage keeps failing, report it to whoever runs the runtime."
diff --git a/pipelex/errors/registry/pipelex_codes.py b/pipelex/errors/registry/pipelex_codes.py
index 43fdb5ae3..542a51540 100644
--- a/pipelex/errors/registry/pipelex_codes.py
+++ b/pipelex/errors/registry/pipelex_codes.py
@@ -35,6 +35,7 @@ class PipelexErrorCode(StrEnum):
CATALOG_SELECTOR_INVALID = "pipelex.catalog.selector_invalid"
CATALOG_LINK_CONFLICT = "pipelex.catalog.link_conflict"
RUN_ALREADY_EXISTS = "pipelex.run.already_exists"
+ REQUEST_DEPENDENCY_KEY_MISMATCH = "pipelex.request.dependency_key_mismatch"
STORAGE_URI_INVALID = "pipelex.storage.uri_invalid"
STORAGE_NOT_FOUND = "pipelex.storage.not_found"
STORAGE_DAMAGED = "pipelex.storage.damaged"
@@ -353,6 +354,23 @@ class RunAlreadyExistsParams(PipelexErrorParams):
pipeline_run_id: str
+class RequestDependencyKeyMismatchParams(PipelexErrorParams):
+ """The parameters of `pipelex.request.dependency_key_mismatch`.
+
+ A dependency is keyed by another address than its manifest declares.
+
+ Attributes:
+ key: The key the request gives the dependency in `dependencies`.
+ address: The full address the dependency's manifest declares, its repository address followed by its
+ package name, which its key must be.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.REQUEST_DEPENDENCY_KEY_MISMATCH
+
+ key: str
+ address: str
+
+
class StorageUriInvalidParams(PipelexErrorParams):
"""The parameters of `pipelex.storage.uri_invalid`.
@@ -368,12 +386,13 @@ class StorageNotFoundParams(PipelexErrorParams):
A stored file is gone.
Attributes:
- scheme: The kind of storage that no longer holds the file.
+ scheme: The kind of storage that no longer holds the file: one Pipelex ships, or `plugin` for a
+ storage plugin's own.
"""
code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_NOT_FOUND
- scheme: Literal["local", "s3", "gcs", "memory"]
+ scheme: Literal["local", "s3", "gcs", "memory", "plugin"]
class StorageDamagedParams(PipelexErrorParams):
@@ -382,12 +401,13 @@ class StorageDamagedParams(PipelexErrorParams):
A stored file is damaged.
Attributes:
- scheme: The kind of storage that holds the damaged file.
+ scheme: The kind of storage that holds the damaged file: one Pipelex ships, or `plugin` for a storage
+ plugin's own.
"""
code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_DAMAGED
- scheme: Literal["local", "s3", "gcs", "memory"]
+ scheme: Literal["local", "s3", "gcs", "memory", "plugin"]
class StorageUnavailableParams(PipelexErrorParams):
@@ -396,12 +416,12 @@ class StorageUnavailableParams(PipelexErrorParams):
Storage is unavailable.
Attributes:
- scheme: The kind of storage that failed.
+ scheme: The kind of storage that failed: one Pipelex ships, or `plugin` for a storage plugin's own.
"""
code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_UNAVAILABLE
- scheme: Literal["local", "s3", "gcs", "memory"]
+ scheme: Literal["local", "s3", "gcs", "memory", "plugin"]
class StorageNotConfiguredParams(PipelexErrorParams):
@@ -988,6 +1008,7 @@ PIPELEX_ERROR_PARAMS: dict[PipelexErrorCode, type[PipelexErrorParams]] = {
PipelexErrorCode.CATALOG_SELECTOR_INVALID: CatalogSelectorInvalidParams,
PipelexErrorCode.CATALOG_LINK_CONFLICT: CatalogLinkConflictParams,
PipelexErrorCode.RUN_ALREADY_EXISTS: RunAlreadyExistsParams,
+ PipelexErrorCode.REQUEST_DEPENDENCY_KEY_MISMATCH: RequestDependencyKeyMismatchParams,
PipelexErrorCode.STORAGE_URI_INVALID: StorageUriInvalidParams,
PipelexErrorCode.STORAGE_NOT_FOUND: StorageNotFoundParams,
PipelexErrorCode.STORAGE_DAMAGED: StorageDamagedParams,
@@ -1270,6 +1291,17 @@ PIPELEX_ERROR_ENTRIES: dict[PipelexErrorCode, PipelexErrorEntry] = {
other_step="change_input",
other_step_detail="Pass this to the caller, who chose the run id '{pipeline_run_id}', which is already taken.",
),
+ PipelexErrorCode.REQUEST_DEPENDENCY_KEY_MISMATCH: PipelexErrorEntry(
+ title="A dependency is keyed by another address than its manifest declares",
+ domain="input",
+ retry="no",
+ status=422,
+ detail="The dependency keyed '{key}' declares the address '{address}', which must be its key.",
+ actor_step="change_input",
+ actor_step_detail="Key the dependency by '{address}', the address its manifest declares, then send the request again.",
+ other_step="change_input",
+ other_step_detail="Pass this to the caller, who must key the dependency '{key}' by '{address}'.",
+ ),
PipelexErrorCode.STORAGE_URI_INVALID: PipelexErrorEntry(
title="The storage address is malformed",
domain="input",
diff --git a/pipelex/errors/unsupported_reasons.py b/pipelex/errors/unsupported_reasons.py
index 10f454578..ca7bd5df3 100644
--- a/pipelex/errors/unsupported_reasons.py
+++ b/pipelex/errors/unsupported_reasons.py
@@ -8,3 +8,7 @@ interpreter.
#: Contents-only resolution, the core of `POST /v1/pipe-io`, met a method calling another one by its address, which it
#: cannot fetch. A hosted run tells this refusal apart by it, since the run route fetches such a dependency.
ADDRESS_DEPENDENCY_UNSUPPORTED_REASON = "address_based_dependency"
+
+#: A table input, such as a CSV file, given by a URL that is not a local file path: this runtime reads a table from a
+#: local file alone, so the form the input uses is one it does not accept, whatever the URL names.
+REMOTE_TABLE_UNSUPPORTED_REASON = "remote_table_url"
diff --git a/pipelex/interpreter_hub.py b/pipelex/interpreter_hub.py
index e1a4b9418..8572e31ea 100644
--- a/pipelex/interpreter_hub.py
+++ b/pipelex/interpreter_hub.py
@@ -359,8 +359,14 @@ def get_own_pipes() -> list[PipeAbstract]:
return get_interpreter_hub().get_required_pipe_library().get_own_pipes()
-def get_required_pipe(pipe_code: str) -> PipeAbstract:
- return get_interpreter_hub().get_required_pipe_library().get_required_pipe(pipe_code=pipe_code)
+def get_selectable_own_pipe_refs() -> list[str]:
+ """The refs of the current library's own pipes a refusal may offer its caller (see `PipeLibraryAbstract.selectable_own_pipe_refs`)."""
+ return get_interpreter_hub().get_required_pipe_library().selectable_own_pipe_refs()
+
+
+def get_required_pipe(pipe_code: str, *, referring_pipe_code: str | None = None) -> PipeAbstract:
+ """The pipe a reference names, refused naming the reference and, when one writes it, the referring pipe."""
+ return get_interpreter_hub().get_required_pipe_library().get_required_pipe(pipe_code=pipe_code, referring_pipe_code=referring_pipe_code)
def get_optional_pipe(pipe_code: str) -> PipeAbstract | None:
diff --git a/pipelex/kernel/img_gen_prompt.py b/pipelex/kernel/img_gen_prompt.py
index c653190d4..d26439e19 100644
--- a/pipelex/kernel/img_gen_prompt.py
+++ b/pipelex/kernel/img_gen_prompt.py
@@ -24,6 +24,7 @@ from pipelex.cogt.img_gen.img_gen_prompt import ImgGenPrompt
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
from pipelex.kernel.prompt_assembly import PromptFiles
from pipelex.kernel.prompt_references import ImageReference
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract
from pipelex.tools.templating.templating_style import TemplatingStyle
@@ -56,21 +57,23 @@ async def assemble_img_gen_prompt(
positive_text: str = ""
if prompt_blueprint:
- positive_text = await prompt_files.render(
- template_blueprint=prompt_blueprint,
- context_provider=context_provider,
- extra_params=template_params,
- templating_style=templating_style,
- )
+ with locating_template_refusal(template_field="prompt"):
+ positive_text = await prompt_files.render(
+ template_blueprint=prompt_blueprint,
+ context_provider=context_provider,
+ extra_params=template_params,
+ templating_style=templating_style,
+ )
negative_text: str | None = None
if negative_prompt_blueprint:
- negative_text = await prompt_files.render(
- template_blueprint=negative_prompt_blueprint,
- context_provider=context_provider,
- extra_params=template_params,
- templating_style=templating_style,
- )
+ with locating_template_refusal(template_field="negative_prompt"):
+ negative_text = await prompt_files.render(
+ template_blueprint=negative_prompt_blueprint,
+ context_provider=context_provider,
+ extra_params=template_params,
+ templating_style=templating_style,
+ )
return ImgGenPrompt(
positive_text=positive_text,
diff --git a/pipelex/kernel/judgment_ops.py b/pipelex/kernel/judgment_ops.py
index 6bf523ecd..4bc8e3a4a 100644
--- a/pipelex/kernel/judgment_ops.py
+++ b/pipelex/kernel/judgment_ops.py
@@ -16,6 +16,7 @@ A step asks one question, `run_judgment`, whose verdict native is the result, or
judging model, every question answered independently over the same evidence.
"""
+from collections.abc import Mapping
from functools import partial
from typing import NamedTuple
@@ -55,6 +56,7 @@ from pipelex.kernel.memory_ops import store_result
from pipelex.kernel.prompt_assembly import UserPromptContent, assemble_user_prompt
from pipelex.runtime_hub import get_content_generator, get_model_deck
from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.templating.templating_style import TemplatingStyle
@@ -176,6 +178,7 @@ async def run_judgment(
memory=memory,
prompt_content=prompt_content,
questions={JUDGMENT_QUESTION_KEY: question},
+ question_fields={JUDGMENT_QUESTION_KEY: "question"},
judgment_setting=judgment_setting,
job_metadata=job_metadata,
cogt_run_params=cogt_run_params,
@@ -242,6 +245,7 @@ async def run_multi_judgment(
memory=memory,
prompt_content=prompt_content,
questions={question_name: asked_question.question for question_name, asked_question in questions.items()},
+ question_fields={question_name: f"questions.{question_name}.question" for question_name in questions},
judgment_setting=judgment_setting,
job_metadata=job_metadata,
cogt_run_params=cogt_run_params,
@@ -318,24 +322,31 @@ async def _ask_judgment(
memory: WorkingMemory,
prompt_content: UserPromptContent,
questions: dict[str, JudgmentQuestion],
+ question_fields: Mapping[str, str],
judgment_setting: JudgmentSetting,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
templating_style: TemplatingStyle,
) -> _AskedJudgment:
- """One request to the judging model: the evidence assembled, every question rendered as a `BASIC` template, all sent in one job."""
+ """One request to the judging model: the evidence assembled, every question rendered as a `BASIC` template, all sent in one job.
+
+ ``question_fields`` names, by the key of each question, the field of the step its template is written in, such as
+ ``question`` or ``questions.urgent.question``, which a refusal of the template sandbox is located on.
+ """
with job_metadata.log_context():
- assembled_prompt = await assemble_user_prompt(prompt_content=prompt_content, context_provider=memory, templating_style=templating_style)
+ with locating_template_refusal(template_field="prompt"):
+ assembled_prompt = await assemble_user_prompt(prompt_content=prompt_content, context_provider=memory, templating_style=templating_style)
judgment_prompt = JudgmentPrompt(text=assembled_prompt.text, images=assembled_prompt.images, documents=assembled_prompt.documents)
context = memory.generate_context()
asked_questions: dict[str, JudgmentQuestion] = {}
for question_key, question in questions.items():
- rendered_question = await render_template(
- template=question.instructions,
- category=TemplateCategory.BASIC,
- context=context,
- templating_style=templating_style,
- )
+ with locating_template_refusal(template_field=question_fields[question_key]):
+ rendered_question = await render_template(
+ template=question.instructions,
+ category=TemplateCategory.BASIC,
+ context=context,
+ templating_style=templating_style,
+ )
asked_questions[question_key] = question.model_copy(update={"instructions": rendered_question})
judgment_assignment = JudgmentAssignment(
job_metadata=job_metadata,
diff --git a/pipelex/kernel/llm_prompt_content.py b/pipelex/kernel/llm_prompt_content.py
index f996cead6..bca49e144 100644
--- a/pipelex/kernel/llm_prompt_content.py
+++ b/pipelex/kernel/llm_prompt_content.py
@@ -21,6 +21,7 @@ from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.templating.template_blueprint import TemplateBlueprint
from pipelex.kernel.prompt_assembly import PromptFiles
from pipelex.kernel.prompt_references import DocumentReference, ImageReference
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.context_provider_abstract import ContextProviderAbstract
from pipelex.tools.templating.templating_style import TemplatingStyle
@@ -77,21 +78,23 @@ async def assemble_llm_prompt(
system_text: str | None = None
if prompt_content.system_template:
- system_text = await prompt_files.render(
- template_blueprint=prompt_content.system_template,
- context_provider=context_provider,
- extra_params=template_params,
- templating_style=templating_style,
- )
+ with locating_template_refusal(template_field="system_prompt"):
+ system_text = await prompt_files.render(
+ template_blueprint=prompt_content.system_template,
+ context_provider=context_provider,
+ extra_params=template_params,
+ templating_style=templating_style,
+ )
user_text: str | None
if prompt_content.user_template:
- user_text = await prompt_files.render(
- template_blueprint=prompt_content.user_template,
- context_provider=context_provider,
- extra_params=template_params,
- templating_style=templating_style,
- )
+ with locating_template_refusal(template_field="prompt"):
+ user_text = await prompt_files.render(
+ template_blueprint=prompt_content.user_template,
+ context_provider=context_provider,
+ extra_params=template_params,
+ templating_style=templating_style,
+ )
if output_structure_prompt:
user_text += output_structure_prompt
else:
diff --git a/pipelex/libraries/collision_messages.py b/pipelex/libraries/collision_messages.py
index 69a437102..f9d849dc9 100644
--- a/pipelex/libraries/collision_messages.py
+++ b/pipelex/libraries/collision_messages.py
@@ -1,6 +1,20 @@
+from enum import StrEnum
+
+from mthds.protocol.problem.registry import MethodNameConflictConflict
+
+from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData
+
+
+class DeclarationKind(StrEnum):
+ """The kind of declaration a merged library found declared twice."""
+
+ CONCEPT = "concept"
+ PIPE = "pipe"
+
+
def duplicate_ref_msg(
*,
- ref_kind: str,
+ ref_kind: DeclarationKind,
ref: str,
existing_source: str | None,
incoming_source: str | None,
@@ -12,7 +26,7 @@ def duplicate_ref_msg(
the two sources, so callers do not pass a separate flag.
Args:
- ref_kind: Singular noun for the kind of reference ("concept" or "pipe").
+ ref_kind: The kind of the declaration, whose value is its singular noun.
ref: The fully qualified ref that is declared twice (e.g. "scoring.compute_score").
existing_source: Source file of the already-seen declaration, or None if unknown.
incoming_source: Source file of the colliding declaration, or None if unknown.
@@ -28,3 +42,67 @@ def duplicate_ref_msg(
f"'{existing_source or 'unknown'}' and '{incoming_source or 'unknown'}'. "
f"Please remove one of the declarations or rename one of the {ref_kind}s."
)
+
+
+def duplicate_ref_items(
+ *,
+ ref_kind: DeclarationKind,
+ ref: str,
+ existing_source: str | None,
+ incoming_source: str | None,
+) -> list[PipelexBundleBlueprintValidationErrorData]:
+ """The faults of a declaration made twice, one per bundle that makes it, for a verdict to locate each in its bundle.
+
+ Each item names the declaration by its qualified ref and the conflict, the parameters of ``method.name_conflict``,
+ and is located on its bundle and its declaration, the table that declares it by its bundle-root path
+ (``concept.Score``, ``pipe.compute_score``), so the verdict names both bundles: the one that declared it first and
+ the one whose declaration was refused. A ref declared twice in one bundle is one item; two declarations whose
+ bundles are unknown are two, since nothing shows them to be one bundle's.
+
+ Args:
+ ref_kind: The kind of the declaration.
+ ref: The qualified ref declared twice, such as ``scoring.Score``.
+ existing_source: The bundle of the declaration met first, when known.
+ incoming_source: The bundle of the declaration refused, when known.
+
+ Returns:
+ The items, the refused declaration's first.
+ """
+ noun = ref_kind.capitalize()
+ domain_code, _, code = ref.rpartition(".")
+ params = {"name": ref, "conflict": MethodNameConflictConflict.DUPLICATE_DECLARATION}
+ is_one_bundle = existing_source is not None and existing_source == incoming_source
+ # Each declaration with the bundle of the other, the refused declaration's first.
+ located_declarations = [(incoming_source, existing_source), (existing_source, incoming_source)]
+ if is_one_bundle:
+ located_declarations = located_declarations[:1]
+ items: list[PipelexBundleBlueprintValidationErrorData] = []
+ for source, other_source in located_declarations:
+ if is_one_bundle:
+ message = f"{noun} '{ref}' is declared twice in this bundle."
+ else:
+ message = f"{noun} '{ref}' is declared here and in '{other_source or 'unknown'}'."
+ match ref_kind:
+ case DeclarationKind.CONCEPT:
+ items.append(
+ PipelexBundleBlueprintValidationErrorData(
+ source=source,
+ domain_code=domain_code or None,
+ concept_code=code,
+ field_path=f"{ref_kind}.{code}",
+ message=message,
+ params=params,
+ )
+ )
+ case DeclarationKind.PIPE:
+ items.append(
+ PipelexBundleBlueprintValidationErrorData(
+ source=source,
+ domain_code=domain_code or None,
+ pipe_code=code,
+ field_path=f"{ref_kind}.{code}",
+ message=message,
+ params=params,
+ )
+ )
+ return items
diff --git a/pipelex/libraries/concept/concept_library.py b/pipelex/libraries/concept/concept_library.py
index 28dfbdeec..dc93f1998 100644
--- a/pipelex/libraries/concept/concept_library.py
+++ b/pipelex/libraries/concept/concept_library.py
@@ -1,7 +1,7 @@
from typing import Any, Callable, Self, cast
from kajson.exceptions import ClassRegistryInheritanceError, ClassRegistryNotFoundError
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from pydantic import Field, RootModel, model_validator
from typing_extensions import override
@@ -107,7 +107,11 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):
def add_new_concept(self, concept: Concept):
if concept.concept_ref in self.root:
msg = f"Concept '{concept.concept_ref}' already exists in the library"
- raise ConceptLibraryError(msg).with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ raise (
+ ConceptLibraryError(msg)
+ .with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_params(name=concept.concept_ref, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
+ )
self.root[concept.concept_ref] = concept
self._mark_changed()
diff --git a/pipelex/libraries/concept_reference_validation.py b/pipelex/libraries/concept_reference_validation.py
index 04dbd4c4a..8374a6b8a 100644
--- a/pipelex/libraries/concept_reference_validation.py
+++ b/pipelex/libraries/concept_reference_validation.py
@@ -149,6 +149,9 @@ def validate_concept_references_in_blueprints(
concept_code=owning_concept_code or concept_ref_or_code,
declared_concepts=declared_concepts,
message=item_message,
+ # The concept the reference names, which no library declares: the item's `concept`,
+ # where its concept_code locates the concept that holds the reference.
+ params={"concept": concept_ref_or_code},
)
)
diff --git a/pipelex/libraries/exceptions.py b/pipelex/libraries/exceptions.py
index 94f1979c0..3dadfad4f 100644
--- a/pipelex/libraries/exceptions.py
+++ b/pipelex/libraries/exceptions.py
@@ -1,11 +1,15 @@
-from typing import ClassVar
+from typing import Any, ClassVar
+from mthds.method_tree.exceptions import MethodTreeRefusedError, TreeLimitError, TreeSourceError
+from mthds.method_tree.vocabulary import TreeLimitKind
from mthds.protocol.problem.registry import CoreCode
+from typing_extensions import override
from pipelex.base_exceptions import PipelexError
from pipelex.core.exceptions import PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorData
from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, ErrorCodeSet
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
+from pipelex.methods.package_reason import MethodPackageReason
class LibraryError(PipelexError):
@@ -21,6 +25,24 @@ class LibraryError(PipelexError):
others=(CoreCode.REQUEST_INVALID, CoreCode.METHOD_CONCEPT_UNRESOLVED, PipelexErrorCode.CONFIG_INVALID),
)
+ def __init__(
+ self,
+ message: str,
+ blueprint_validation_errors: list[PipelexBundleBlueprintValidationErrorData] | None = None,
+ pipe_concept_validation_errors: list[PipesAndConceptValidationErrorData] | None = None,
+ ):
+ """Initialize a library error, with the structured items a validation verdict built from it lists.
+
+ Args:
+ message: Error message
+ blueprint_validation_errors: Blueprint validation errors (from PipelexBundleBlueprint validation), or the
+ faults of a refusal that locates each in a bundle, such as both declarations of a name declared twice
+ pipe_concept_validation_errors: Pipe/Concept validation errors (from Pipe/Concept validation)
+ """
+ self.blueprint_validation_errors = blueprint_validation_errors or []
+ self.pipe_concept_validation_errors = pipe_concept_validation_errors or []
+ super().__init__(message)
+
class CrateNormalizationError(LibraryError):
"""Raised when a library crate cannot be normalized (e.g. a non-domain-qualified key, or a pipe ref matching no crate pipe, or several).
@@ -63,23 +85,6 @@ class LibraryLoadingError(LibraryError):
),
)
- def __init__(
- self,
- message: str,
- blueprint_validation_errors: list[PipelexBundleBlueprintValidationErrorData] | None = None,
- pipe_concept_validation_errors: list[PipesAndConceptValidationErrorData] | None = None,
- ):
- """Initialize LibraryLoadingError.
-
- Args:
- message: Error message
- blueprint_validation_errors: Blueprint validation errors (from PipelexBundleBlueprint validation)
- pipe_concept_validation_errors: Pipe/Concept validation errors (from Pipe/Concept validation)
- """
- self.blueprint_validation_errors = blueprint_validation_errors or []
- self.pipe_concept_validation_errors = pipe_concept_validation_errors or []
- super().__init__(message)
-
class MethodTreeLoadError(LibraryLoadingError):
"""Raised when a method tree a load reads from this host's disk cannot be listed.
@@ -89,10 +94,35 @@ class MethodTreeLoadError(LibraryLoadingError):
out), it passed a limit this machine lists trees under, or a directory or a file of it could not be read. The
tree is the caller's own method, so the message, which names the tree's root and the files by their tree paths,
is theirs to read, and the same load is refused again until the tree changes.
+
+ Its ``reason`` is read from the listing's refusal it was raised from: the standard's refusal code, the limit the
+ tree passed with that limit, or ``tree_unreadable``. A raise site with no such cause gives its own.
"""
error_code = CoreCode.METHOD_PACKAGE_INVALID
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ cause = self.__cause__
+ if isinstance(cause, MethodTreeRefusedError):
+ return {"reason": cause.refusal.code}
+ if isinstance(cause, TreeLimitError):
+ return {"reason": _tree_limit_reason(kind=cause.kind), "limit": cause.limit}
+ if isinstance(cause, TreeSourceError):
+ return {"reason": MethodPackageReason.TREE_UNREADABLE}
+ return {}
+
+
+def _tree_limit_reason(*, kind: TreeLimitKind) -> MethodPackageReason:
+ """The reason of the limit of a method tree a listing stopped at."""
+ match kind:
+ case TreeLimitKind.FILE_COUNT:
+ return MethodPackageReason.TOO_MANY_FILES
+ case TreeLimitKind.TOTAL_BYTES:
+ return MethodPackageReason.TREE_TOO_LARGE
+ case TreeLimitKind.FILE_BYTES:
+ return MethodPackageReason.FILE_TOO_LARGE
+
class EmptyMethodTreeError(MethodTreeLoadError):
"""Raised when a folder handed over as a method holds no bundle.
diff --git a/pipelex/libraries/library.py b/pipelex/libraries/library.py
index f05d335e1..efacac3ba 100644
--- a/pipelex/libraries/library.py
+++ b/pipelex/libraries/library.py
@@ -1,6 +1,6 @@
from collections import defaultdict
from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from kajson.class_registry import ClassRegistry
from mthds.protocol.problem.registry import CoreCode
@@ -17,6 +17,7 @@ from pipelex.libraries.domain.domain_library import DomainLibrary
from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError
from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundError
from pipelex.libraries.pipe.pipe_library import PipeLibrary
+from pipelex.libraries.pipe.pipe_suggestions import close_pipe_refs
from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
from pipelex.validation_error_types import PipeValidationErrorType
@@ -90,13 +91,23 @@ def _describe_unexported_pipe_dependency(*, referring_pipe_key: str, private_ref
)
-def _pipe_dependency_refusal(*, pipe: PipeController, missing_ref: str, error_type: PipeValidationErrorType, message: str) -> LibraryLoadingError:
+def _pipe_dependency_refusal(
+ *, pipe: PipeController, missing_ref: str, error_type: PipeValidationErrorType, message: str, params: dict[str, Any]
+) -> LibraryLoadingError:
"""The refusal of a controller's sub-pipe reference, carrying a structured item.
The item makes the refusal a categorized `pipe_validation` item: `pipe_code` is the referring controller and
`missing_pipe_code` the reference that does not resolve, or is not visible, so a machine consumer reads both
without parsing the message. LibraryLoadingError rides the existing `except LibraryError` forwarding in
translate_to_validate_bundle_error.
+
+ Args:
+ pipe: The referring controller.
+ missing_ref: The reference that does not resolve, or is not visible.
+ error_type: The item's type.
+ message: The refusal's message.
+ params: The parameters of the item's code the locators do not give: the pipes a reference that resolves to
+ nothing may have meant, or the package withholding a pipe and that pipe.
"""
dependency_error_data = PipesAndConceptValidationErrorData(
error_type=error_type,
@@ -105,6 +116,7 @@ def _pipe_dependency_refusal(*, pipe: PipeController, missing_ref: str, error_ty
missing_pipe_code=missing_ref,
message=message,
field_path=f"pipe.{pipe.code}",
+ params=params,
)
return LibraryLoadingError(message=message, pipe_concept_validation_errors=[dependency_error_data])
@@ -243,8 +255,13 @@ class Library(BaseModel):
candidates=bare_code_candidates,
cause=pipe_error,
)
+ candidate_refs = [pipe_ref for pipe_refs in bare_code_candidates.values() for pipe_ref in pipe_refs]
raise _pipe_dependency_refusal(
- pipe=pipe, missing_ref=sub_pipe_code, error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY, message=msg
+ pipe=pipe,
+ missing_ref=sub_pipe_code,
+ error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY,
+ message=msg,
+ params={"candidates": close_pipe_refs(name=sub_pipe_code, pipe_refs=candidate_refs)},
) from pipe_error
for pipe in self.pipe_library.root.values():
@@ -278,15 +295,26 @@ class Library(BaseModel):
f"Pipe '{pipe_key}' references '{sub_pipe_code}', which the package loaded as '{ref_alias}' declares "
f"but could not build: {unbuilt_reason}"
)
+ # The package declares the pipe: no other pipe is the one it meant.
raise _pipe_dependency_refusal(
- pipe=pipe, missing_ref=sub_pipe_code, error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY, message=msg
+ pipe=pipe,
+ missing_ref=sub_pipe_code,
+ error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY,
+ message=msg,
+ params={"candidates": []},
)
try:
sub_pipe = self.pipe_library.get_optional_pipe(pipe_code=sub_pipe_code)
except PipeLibraryError as pipe_error:
msg = _describe_unresolved_pipe_dependency(referring_pipe_ref=pipe.pipe_ref, missing_ref=sub_pipe_code, candidates={}, cause=pipe_error)
raise _pipe_dependency_refusal(
- pipe=pipe, missing_ref=sub_pipe_code, error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY, message=msg
+ pipe=pipe,
+ missing_ref=sub_pipe_code,
+ error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY,
+ message=msg,
+ params={
+ "candidates": self._dependency_pipe_candidates(alias=ref_alias, missing_ref=sub_pipe_code, is_package_own=dep_alias == ref_alias)
+ },
) from pipe_error
if sub_pipe is None:
if self.pipe_library.is_withheld_dependency_pipe(pipe_code=sub_pipe_code):
@@ -295,13 +323,20 @@ class Library(BaseModel):
missing_ref=sub_pipe_code,
error_type=PipeValidationErrorType.UNEXPORTED_PIPE_DEPENDENCY,
message=_describe_unexported_pipe_dependency(referring_pipe_key=pipe_key, private_ref=sub_pipe_code, package_alias=ref_alias),
+ params={"pipe": sub_pipe_code, "package": ref_alias},
)
msg = (
f"Pipe '{pipe_key}' references '{sub_pipe_code}', which does not exist. "
f"The package loaded as '{ref_alias}' has no pipe '{remainder}'."
)
raise _pipe_dependency_refusal(
- pipe=pipe, missing_ref=sub_pipe_code, error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY, message=msg
+ pipe=pipe,
+ missing_ref=sub_pipe_code,
+ error_type=PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY,
+ message=msg,
+ params={
+ "candidates": self._dependency_pipe_candidates(alias=ref_alias, missing_ref=sub_pipe_code, is_package_own=dep_alias == ref_alias)
+ },
)
# A package's private pipe is visible to that package's own pipes, and to nothing else.
if ref_alias != dep_alias and self.pipe_library.is_private_dependency_pipe(pipe_key=f"{ref_alias}->{sub_pipe.pipe_ref}"):
@@ -310,8 +345,18 @@ class Library(BaseModel):
missing_ref=sub_pipe_code,
error_type=PipeValidationErrorType.UNEXPORTED_PIPE_DEPENDENCY,
message=_describe_unexported_pipe_dependency(referring_pipe_key=pipe_key, private_ref=sub_pipe_code, package_alias=ref_alias),
+ params={"pipe": sub_pipe_code, "package": ref_alias},
)
+ def _dependency_pipe_candidates(self, *, alias: str, missing_ref: str, is_package_own: bool) -> list[str]:
+ """The pipes of the package loaded as ``alias`` nearest the reference that names none of them, each as a reference into it.
+
+ Only the pipes the referring pipe may name are offered: those the package exports, and its private ones too when
+ the reference is written in the package itself, which alone may name them.
+ """
+ dependency_refs = self.pipe_library.dependency_pipe_keys(alias=alias, with_private=is_package_own)
+ return close_pipe_refs(name=missing_ref, pipe_refs=dependency_refs)
+
def _index_pipe_refs_by_bare_code(self) -> dict[str, list[str]]:
"""Group every pipe ref in this library by its bare code, for failure-path diagnostics only.
@@ -319,9 +364,8 @@ class Library(BaseModel):
unrelated package happens to be installed is worse than suggesting nothing.
"""
by_code: dict[str, list[str]] = defaultdict(list)
- for pipe_ref in self.pipe_library.root:
- if QualifiedRef.has_cross_package_prefix(pipe_ref):
- continue
+ # The own pipes a caller may be offered: beside a host's library directories, the caller's alone.
+ for pipe_ref in self.pipe_library.selectable_own_pipe_refs():
by_code[QualifiedRef.parse(pipe_ref).local_code].append(pipe_ref)
return by_code
diff --git a/pipelex/libraries/library_crate_factory.py b/pipelex/libraries/library_crate_factory.py
index 3c8ab18df..c50d725ae 100644
--- a/pipelex/libraries/library_crate_factory.py
+++ b/pipelex/libraries/library_crate_factory.py
@@ -1,10 +1,10 @@
from typing import TYPE_CHECKING, NamedTuple
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.domains.domain_blueprint import DomainBlueprint
-from pipelex.libraries.collision_messages import duplicate_ref_msg
+from pipelex.libraries.collision_messages import DeclarationKind, duplicate_ref_items, duplicate_ref_msg
from pipelex.libraries.concept.exceptions import ConceptLibraryError
from pipelex.libraries.contract_match import contracts_match
from pipelex.libraries.domain.domain_metadata_merge import merge_domain_metadata_field
@@ -114,14 +114,24 @@ class LibraryCrateFactory:
for concept_code, value in blueprint.concept.items():
concept_ref = ConceptFactory.make_concept_ref_with_domain(domain_code=domain_code, concept_code=concept_code)
if concept_ref in concepts:
- raise ConceptLibraryError(
- duplicate_ref_msg(
- ref_kind="concept",
- ref=concept_ref,
- existing_source=source_map.get(concept_ref),
- incoming_source=source,
+ raise (
+ ConceptLibraryError(
+ duplicate_ref_msg(
+ ref_kind=DeclarationKind.CONCEPT,
+ ref=concept_ref,
+ existing_source=source_map.get(concept_ref),
+ incoming_source=source,
+ ),
+ blueprint_validation_errors=duplicate_ref_items(
+ ref_kind=DeclarationKind.CONCEPT,
+ ref=concept_ref,
+ existing_source=source_map.get(concept_ref),
+ incoming_source=source,
+ ),
)
- ).with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_params(name=concept_ref, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
+ )
concepts[concept_ref] = value
if source:
source_map[concept_ref] = source
@@ -214,12 +224,18 @@ class LibraryCrateFactory:
if not existing_is_signature and not incoming_is_signature:
raise PipeLibraryError(
duplicate_ref_msg(
- ref_kind="pipe",
+ ref_kind=DeclarationKind.PIPE,
ref=pipe_ref,
existing_source=existing.source,
incoming_source=incoming.source,
- )
- )
+ ),
+ blueprint_validation_errors=duplicate_ref_items(
+ ref_kind=DeclarationKind.PIPE,
+ ref=pipe_ref,
+ existing_source=existing.source,
+ incoming_source=incoming.source,
+ ),
+ ).with_params(name=pipe_ref, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
# At least one is a signature: the declarations' contracts must match (normalized identity).
if not contracts_match(existing=existing.blueprint, incoming=incoming.blueprint, domain_code=domain_code):
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index babefa220..b574e8e5c 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -1,4 +1,5 @@
import uuid
+from collections import deque
from collections.abc import Generator, Mapping
from contextlib import ExitStack, contextmanager
from graphlib import CycleError, TopologicalSorter
@@ -13,7 +14,8 @@ from mthds.package.dependency_resolver import ResolvedDependency, determine_expo
from mthds.package.discovery import find_package_manifest
from mthds.package.exceptions import DependencyResolveError, ManifestError
from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION, MethodsManifest
-from mthds.protocol.problem.registry import CoreCode
+from mthds.package.visibility import VisibilityError
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from pydantic import BaseModel, PydanticUserError, ValidationError
from typing_extensions import override
@@ -39,7 +41,7 @@ from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.structured_content import StructuredContent
from pipelex.core.validation import report_validation_error
from pipelex.interpreter_hub import get_current_library, get_current_library_id_or_none, scoped_current_library
-from pipelex.libraries.collision_messages import duplicate_ref_msg
+from pipelex.libraries.collision_messages import DeclarationKind, duplicate_ref_items, duplicate_ref_msg
from pipelex.libraries.concept.exceptions import ConceptLibraryError
from pipelex.libraries.concept_reference_validation import validate_concept_references_in_blueprints
from pipelex.libraries.crate_qualification import qualify_crate
@@ -67,7 +69,7 @@ from pipelex.libraries.method_trees import (
tree_python_sources,
)
from pipelex.libraries.pipe.exceptions import PipeLibraryError
-from pipelex.libraries.visibility_utils import check_visibility_for_blueprints, make_visibility_checker
+from pipelex.libraries.visibility_utils import make_visibility_checker
from pipelex.libraries.written_trees import WRITTEN_METHOD_TREES
from pipelex.methods.address_dependencies import AddressDependencySources, unshipped_address_dependency_message
from pipelex.methods.exceptions import MethodDependencyFetchError, MethodDependencyNotShippedError, MethodFetchDisabledError
@@ -1157,14 +1159,26 @@ class LibraryManager(LibraryManagerAbstract):
# Detect duplicate concept declarations across different bundles in the same library
if concept_ref in concept_source_in_this_load:
existing_source = concept_source_in_this_load[concept_ref]
- raise ConceptLibraryError(
- duplicate_ref_msg(
- ref_kind="concept",
- ref=concept_ref,
- existing_source=str(existing_source) if existing_source else None,
- incoming_source=str(new_source) if new_source else None,
+ existing_source_str = str(existing_source) if existing_source else None
+ incoming_source_str = str(new_source) if new_source else None
+ raise (
+ ConceptLibraryError(
+ duplicate_ref_msg(
+ ref_kind=DeclarationKind.CONCEPT,
+ ref=concept_ref,
+ existing_source=existing_source_str,
+ incoming_source=incoming_source_str,
+ ),
+ blueprint_validation_errors=duplicate_ref_items(
+ ref_kind=DeclarationKind.CONCEPT,
+ ref=concept_ref,
+ existing_source=existing_source_str,
+ incoming_source=incoming_source_str,
+ ),
)
- ).with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_params(name=concept_ref, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
+ )
concept_source_in_this_load[concept_ref] = new_source
ref_to_entry[concept_ref] = (
blueprint.domain,
@@ -1480,10 +1494,7 @@ class LibraryManager(LibraryManagerAbstract):
checker = make_visibility_checker(manifest=None, blueprints=blueprints)
reserved_errors = checker.validate_reserved_domains()
if reserved_errors:
- error_messages = [err.message for err in reserved_errors]
- joined_errors = "\n - ".join(error_messages)
- msg = f"Reserved domain violations found:\n - {joined_errors}"
- raise LibraryLoadingError(msg).with_error_code(CoreCode.METHOD_NAME_CONFLICT) from exc
+ raise _reserved_domain_refusal(reserved_errors=reserved_errors, blueprints=blueprints) from exc
return None
if manifest is None:
@@ -1491,18 +1502,17 @@ class LibraryManager(LibraryManagerAbstract):
checker = make_visibility_checker(manifest=None, blueprints=blueprints)
reserved_errors = checker.validate_reserved_domains()
if reserved_errors:
- error_messages = [err.message for err in reserved_errors]
- joined_errors = "\n - ".join(error_messages)
- msg = f"Reserved domain violations found:\n - {joined_errors}"
- raise LibraryLoadingError(msg).with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ raise _reserved_domain_refusal(reserved_errors=reserved_errors, blueprints=blueprints)
return None
- visibility_errors = check_visibility_for_blueprints(manifest=manifest, blueprints=blueprints)
- if visibility_errors:
- error_messages = [err.message for err in visibility_errors]
- joined_errors = "\n - ".join(error_messages)
- msg = f"Package visibility violations found:\n - {joined_errors}"
- raise LibraryLoadingError(msg).with_error_code(CoreCode.METHOD_PIPE_NOT_EXPORTED)
+ # A reserved domain is refused as in a standalone bundle, before the exports are read: the two are different faults.
+ checker = make_visibility_checker(manifest=manifest, blueprints=blueprints)
+ reserved_errors = checker.validate_reserved_domains()
+ if reserved_errors:
+ raise _reserved_domain_refusal(reserved_errors=reserved_errors, blueprints=blueprints)
+ export_errors = checker.validate_all_pipe_references() + checker.validate_cross_package_references()
+ if export_errors:
+ raise _unexported_pipe_refusal(export_errors=export_errors, blueprints=blueprints, package_address=manifest.address)
return manifest
@@ -2223,3 +2233,69 @@ def _building_bundle_of(
if live_tree is None:
return tree_bundle_ref
return TreeBundle(tree=live_tree, tree_path=tree_bundle_ref.tree_path)
+
+
+def _unexported_pipe_refusal(
+ *, export_errors: list[VisibilityError], blueprints: list[PipelexBundleBlueprint], package_address: str
+) -> LibraryLoadingError:
+ """The refusal of pipe references a domain of the package does not export, one item per reference.
+
+ Each item names the pipe and the package declaring it, the parameters of ``method.pipe_not_exported``, and is
+ located on the bundle, the pipe and the field that write the reference: the checker names a reference by its
+ domain and by its field path, its ``context``, which the bundles' references are indexed by.
+ """
+ # Where each reference is written, by the domain of its bundle and its field path; a field path holds one reference.
+ referring_sites: dict[tuple[str, str], tuple[str | None, str]] = {}
+ for blueprint in blueprints:
+ for reference in blueprint.collect_located_pipe_references():
+ referring_sites.setdefault((blueprint.domain, reference.field_path), (blueprint.source, reference.referring_pipe_code))
+ items: list[PipelexBundleBlueprintValidationErrorData] = []
+ for export_error in export_errors:
+ source, referring_pipe_code = referring_sites.get((export_error.source_domain, export_error.context), (None, None))
+ items.append(
+ PipelexBundleBlueprintValidationErrorData(
+ source=source,
+ domain_code=export_error.source_domain,
+ pipe_code=referring_pipe_code,
+ field_path=export_error.context,
+ message=export_error.message,
+ params={"pipe": export_error.pipe_ref, "package": package_address},
+ )
+ )
+ joined_errors = "\n - ".join(export_error.message for export_error in export_errors)
+ msg = f"Package visibility violations found:\n - {joined_errors}"
+ return (
+ LibraryLoadingError(msg, blueprint_validation_errors=items)
+ .with_error_code(CoreCode.METHOD_PIPE_NOT_EXPORTED)
+ .with_params(pipe=export_errors[0].pipe_ref, package=package_address)
+ )
+
+
+def _reserved_domain_refusal(*, reserved_errors: list[VisibilityError], blueprints: list[PipelexBundleBlueprint]) -> LibraryLoadingError:
+ """The refusal of bundles declaring a reserved domain, one item per bundle, each naming the domain and located on its bundle.
+
+ The checker reports one error per bundle, in the order of the bundles, naming only its domain: each error is paired
+ with the next bundle of that domain not yet paired, so that two bundles declaring one reserved domain are each
+ located on their own file.
+ """
+ sources_by_domain: dict[str, deque[str | None]] = {}
+ for blueprint in blueprints:
+ sources_by_domain.setdefault(blueprint.domain, deque()).append(blueprint.source)
+ items: list[PipelexBundleBlueprintValidationErrorData] = []
+ for reserved_error in reserved_errors:
+ domain_sources = sources_by_domain.get(reserved_error.source_domain)
+ items.append(
+ PipelexBundleBlueprintValidationErrorData(
+ source=domain_sources.popleft() if domain_sources else None,
+ domain_code=reserved_error.source_domain,
+ message=reserved_error.message,
+ params={"name": reserved_error.source_domain, "conflict": MethodNameConflictConflict.RESERVED_DOMAIN},
+ )
+ )
+ joined_errors = "\n - ".join(reserved_error.message for reserved_error in reserved_errors)
+ msg = f"Reserved domain violations found:\n - {joined_errors}"
+ return (
+ LibraryLoadingError(msg, blueprint_validation_errors=items)
+ .with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_params(name=reserved_errors[0].source_domain, conflict=MethodNameConflictConflict.RESERVED_DOMAIN)
+ )
diff --git a/pipelex/libraries/method_requirements.py b/pipelex/libraries/method_requirements.py
index cb4d6426b..aedae8420 100644
--- a/pipelex/libraries/method_requirements.py
+++ b/pipelex/libraries/method_requirements.py
@@ -32,6 +32,7 @@ from pathlib import Path
from typing import NamedTuple
from mthds.method_tree.models import MethodTree, TreeLimits
+from mthds.protocol.problem.registry import MethodDependencyMissingKind, MethodDependencyMissingReason
from packaging.markers import Marker, UndefinedComparison, UndefinedEnvironmentName
from packaging.requirements import InvalidRequirement, Requirement
from packaging.utils import canonicalize_name
@@ -47,8 +48,12 @@ from pipelex.core.method_trees.requirements_file import (
from pipelex.libraries.exceptions import MethodRequirementsFileError, MethodRequirementsNotMetError
from pipelex.libraries.method_trees import list_library_dir_trees, listing_identity, reporting_host_library_tree_faults
from pipelex.libraries.package_environments import PythonPackageEnvironment, resolve_pipe_func_package_environment
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.plugins.pipe_func_package_offer_registry import PipeFuncPackageRefusal
+# The parameters of `method.package_invalid` for a `requirements.txt` the standard refuses or that cannot be read.
+_REQUIREMENTS_INVALID_PARAMS: dict[str, str] = {"reason": MethodPackageReason.REQUIREMENTS_INVALID, "path": REQUIREMENTS_FILE_NAME}
+
PYTHON_SUFFIX = ".py"
# The variables a PEP 508 marker can read. `extra` is not the environment's to state: a line of a requirements file
@@ -74,11 +79,21 @@ _QUOTED_MARKER_VALUE = re.compile(r"\"[^\"]*\"|'[^']*'")
_MARKER_WORD = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+class UnmetDistribution(NamedTuple):
+ """Why a requirement is not met, and the distribution that fails it: the one required, or one an extra of it needs."""
+
+ reason: str
+ distribution_name: str
+ missing_reason: MethodDependencyMissingReason
+
+
class UnmetRequirement(NamedTuple):
- """A requirement the environment does not meet, with why."""
+ """A requirement the environment does not meet, with why, and the distribution that fails it."""
requirement_line: RequirementLine
reason: str
+ distribution_name: str
+ missing_reason: MethodDependencyMissingReason
def marker_variables_of(*, marker: Marker) -> set[str]:
@@ -104,17 +119,31 @@ def _unmet_reason(
requirement: Requirement,
environment: PythonPackageEnvironment,
followed_extras: set[tuple[str, str]],
-) -> str | None:
- """Why the environment does not meet a requirement whose marker it already judged true, or None when it does."""
+) -> UnmetDistribution | None:
+ """Why the environment does not meet a requirement whose marker it already judged true, or None when it does.
+
+ The distribution that fails it is the one required, missing or held at a version the requirement does not accept,
+ or one that an extra of it needs, followed down the extras.
+ """
installed_version = environment.version_of(distribution_name=requirement.name)
if installed_version is None:
- return f"{requirement.name} is missing"
+ return UnmetDistribution(
+ reason=f"{requirement.name} is missing", distribution_name=requirement.name, missing_reason=MethodDependencyMissingReason.NOT_FOUND
+ )
try:
version = Version(installed_version)
except InvalidVersion:
- return f"{requirement.name} {installed_version} is there, a version no specifier can be compared with"
+ return UnmetDistribution(
+ reason=f"{requirement.name} {installed_version} is there, a version no specifier can be compared with",
+ distribution_name=requirement.name,
+ missing_reason=MethodDependencyMissingReason.NO_MATCHING_VERSION,
+ )
if not requirement.specifier.contains(version, prereleases=True):
- return f"{requirement.name} {installed_version} is there"
+ return UnmetDistribution(
+ reason=f"{requirement.name} {installed_version} is there",
+ distribution_name=requirement.name,
+ missing_reason=MethodDependencyMissingReason.NO_MATCHING_VERSION,
+ )
for extra in sorted(requirement.extras):
extra_reason = _unmet_extra_reason(distribution_name=requirement.name, extra=extra, environment=environment, followed_extras=followed_extras)
if extra_reason is not None:
@@ -128,11 +157,13 @@ def _unmet_extra_reason(
extra: str,
environment: PythonPackageEnvironment,
followed_extras: set[tuple[str, str]],
-) -> str | None:
+) -> UnmetDistribution | None:
"""Why the environment does not meet what an extra of a distribution it holds needs, or None when it does.
An extra needs each requirement of the distribution's metadata whose marker holds with the extra and not without
- it. Each extra is followed once, so extras that name one another end.
+ it. Each extra is followed once, so extras that name one another end. The distribution that fails is the one the
+ extra needs; when the environment does not state what the extra needs, it is the distribution holding the extra,
+ which is there in a form that cannot be shown to serve the requirement.
"""
key = (canonicalize_name(distribution_name), canonicalize_name(extra))
if key in followed_extras:
@@ -140,9 +171,13 @@ def _unmet_extra_reason(
followed_extras.add(key)
dependencies = environment.dependencies_of(distribution_name=distribution_name)
if dependencies is None:
- return (
- f"{environment.description} does not state what the extra '{extra}' of {distribution_name} needs; "
- "list the packages it needs in requirements.txt instead"
+ return UnmetDistribution(
+ reason=(
+ f"{environment.description} does not state what the extra '{extra}' of {distribution_name} needs; "
+ "list the packages it needs in requirements.txt instead"
+ ),
+ distribution_name=distribution_name,
+ missing_reason=MethodDependencyMissingReason.NO_MATCHING_VERSION,
)
for dependency_text in dependencies:
try:
@@ -159,9 +194,11 @@ def _unmet_extra_reason(
continue
if not needed_by_extra or needed_anyway:
continue
- dependency_reason = _unmet_reason(requirement=dependency, environment=environment, followed_extras=followed_extras)
- if dependency_reason is not None:
- return f"the extra '{extra}' of {distribution_name} needs '{dependency_text}', and {dependency_reason}"
+ dependency_unmet = _unmet_reason(requirement=dependency, environment=environment, followed_extras=followed_extras)
+ if dependency_unmet is not None:
+ return dependency_unmet._replace(
+ reason=f"the extra '{extra}' of {distribution_name} needs '{dependency_text}', and {dependency_unmet.reason}"
+ )
return None
@@ -169,9 +206,16 @@ def unmet_requirements(*, requirements: Iterable[RequirementLine], environment:
"""The requirements the environment does not meet, in the order given, each with why."""
unmet: list[UnmetRequirement] = []
for requirement_line in requirements:
- reason = _requirement_line_unmet_reason(requirement_line=requirement_line, environment=environment)
- if reason is not None:
- unmet.append(UnmetRequirement(requirement_line=requirement_line, reason=reason))
+ unmet_distribution = _requirement_line_unmet_reason(requirement_line=requirement_line, environment=environment)
+ if unmet_distribution is not None:
+ unmet.append(
+ UnmetRequirement(
+ requirement_line=requirement_line,
+ reason=unmet_distribution.reason,
+ distribution_name=unmet_distribution.distribution_name,
+ missing_reason=unmet_distribution.missing_reason,
+ )
+ )
return unmet
@@ -202,18 +246,34 @@ def _is_marker_false(*, marker: Marker, marker_environment: Mapping[str, str]) -
return False
-def _requirement_line_unmet_reason(*, requirement_line: RequirementLine, environment: PythonPackageEnvironment) -> str | None:
- marker = requirement_line.requirement.marker
+def _requirement_line_unmet_reason(*, requirement_line: RequirementLine, environment: PythonPackageEnvironment) -> UnmetDistribution | None:
+ requirement = requirement_line.requirement
+ marker = requirement.marker
if marker is not None:
unstated = sorted(marker_variables_of(marker=marker) - set(environment.marker_environment) - {"extra"})
if unstated:
- return f"its marker reads {', '.join(unstated)}, which {environment.description} does not state"
+ return _unjudged_requirement(
+ reason=f"its marker reads {', '.join(unstated)}, which {environment.description} does not state",
+ requirement=requirement,
+ environment=environment,
+ )
try:
if not _evaluate_marker(marker=marker, marker_environment=environment.marker_environment, extra=""):
return None
except (UndefinedComparison, UndefinedEnvironmentName, InvalidVersion) as exc:
- return f"its marker cannot be evaluated: {exc}"
- return _unmet_reason(requirement=requirement_line.requirement, environment=environment, followed_extras=set())
+ return _unjudged_requirement(reason=f"its marker cannot be evaluated: {exc}", requirement=requirement, environment=environment)
+ return _unmet_reason(requirement=requirement, environment=environment, followed_extras=set())
+
+
+def _unjudged_requirement(*, reason: str, requirement: Requirement, environment: PythonPackageEnvironment) -> UnmetDistribution:
+ """A requirement whose marker the environment cannot judge, failed by the distribution it requires.
+
+ The distribution is missing (`not_found`), or held in a form the requirement cannot be shown to accept
+ (`no_matching_version`).
+ """
+ is_installed = environment.version_of(distribution_name=requirement.name) is not None
+ missing_reason = MethodDependencyMissingReason.NO_MATCHING_VERSION if is_installed else MethodDependencyMissingReason.NOT_FOUND
+ return UnmetDistribution(reason=reason, distribution_name=requirement.name, missing_reason=missing_reason)
def holds_requirements_to_check(*, tree: MethodTree) -> bool:
@@ -252,10 +312,27 @@ def _read_requirements_text(*, judged: JudgedMethod) -> str:
return location.read_bytes().decode("utf-8")
except UnicodeDecodeError as exc:
msg = f"{judged.method_name} declares its packages in a {REQUIREMENTS_FILE_NAME} that is not UTF-8 text, so they cannot be read."
- raise MethodRequirementsFileError(msg, items=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg)]) from exc
+ raise MethodRequirementsFileError(msg, items=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg)]).with_params(
+ **_REQUIREMENTS_INVALID_PARAMS
+ ) from exc
except OSError as exc:
msg = f"{judged.method_name} declares its packages in a {REQUIREMENTS_FILE_NAME} that cannot be read: {exc.strerror or type(exc).__name__}."
- raise MethodRequirementsFileError(msg, items=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg)]) from exc
+ raise MethodRequirementsFileError(msg, items=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg)]).with_params(
+ **_REQUIREMENTS_INVALID_PARAMS
+ ) from exc
+
+
+def _unmet_requirement_params(*, unmet_requirement: UnmetRequirement) -> dict[str, str]:
+ """The parameters of `method.dependency_missing` for a requirement the environment does not meet.
+
+ They name the distribution that fails it: the one required, or one an extra of it needs, which is missing
+ (`not_found`) or held at a version the requirement does not accept (`no_matching_version`).
+ """
+ return {
+ "kind": MethodDependencyMissingKind.REQUIREMENT,
+ "name": unmet_requirement.distribution_name,
+ "reason": unmet_requirement.missing_reason,
+ }
def _raise_refused_lines(*, judged: JudgedMethod, refused_lines: list[RefusedRequirementsLine]) -> None:
@@ -280,7 +357,7 @@ def _raise_refused_lines(*, judged: JudgedMethod, refused_lines: list[RefusedReq
f"{judged.method_name} declares its packages in a {REQUIREMENTS_FILE_NAME} holding lines the MTHDS standard "
f"refuses, where each line is blank, a comment, or exactly one PEP 508 requirement: {'; '.join(line_texts)}."
)
- raise MethodRequirementsFileError(msg, items=items)
+ raise MethodRequirementsFileError(msg, items=items).with_params(**_REQUIREMENTS_INVALID_PARAMS)
def _raise_unmet(*, judged: JudgedMethod, unmet: list[UnmetRequirement], environment: PythonPackageEnvironment) -> None:
@@ -300,6 +377,7 @@ def _raise_unmet(*, judged: JudgedMethod, unmet: list[UnmetRequirement], environ
source=judged.requirements_source,
line=requirement_line.line_number,
message=f"The requirement '{requirement_line.text}' is not met by {environment.description}: {unmet_requirement.reason}.",
+ params=_unmet_requirement_params(unmet_requirement=unmet_requirement),
)
)
advice = environment.advice(requirement_texts=[unmet_requirement.requirement_line.text for unmet_requirement in unmet])
@@ -307,15 +385,24 @@ def _raise_unmet(*, judged: JudgedMethod, unmet: list[UnmetRequirement], environ
f"{judged.method_name} needs Python packages that {environment.description} "
f"does not have, as its {REQUIREMENTS_FILE_NAME} declares: {'; '.join(line_texts)}. {advice}"
)
- raise MethodRequirementsNotMetError(msg, items=items)
+ raise MethodRequirementsNotMetError(msg, items=items).with_params(**_unmet_requirement_params(unmet_requirement=unmet[0]))
-def _refused_by_deployment_error(*, judged: JudgedMethod, refusal: PipeFuncPackageRefusal) -> MethodRequirementsNotMetError:
+def _refused_by_deployment_error(
+ *, judged: JudgedMethod, refusal: PipeFuncPackageRefusal, requirements: Sequence[RequirementLine]
+) -> MethodRequirementsNotMetError:
"""The refusal of a method whose requirements the deployment cannot hold in any environment, carrying its reason.
The deployment's reason is about the requirements together, such as a conflict its resolver found among them, so the
- one item it rides on names the file and no line.
+ one item it rides on names the file and no line. `method.dependency_missing` names one distribution, as a refusal
+ of several unmet requirements names the first of them: the first requirement the file declares, with the `reason`
+ `no_matching_version`, since no set of versions the deployment can build satisfies the requirements.
"""
+ params = {
+ "kind": MethodDependencyMissingKind.REQUIREMENT,
+ "name": requirements[0].requirement.name,
+ "reason": MethodDependencyMissingReason.NO_MATCHING_VERSION,
+ }
msg = (
f"{judged.method_name} needs Python packages that {refusal.environment} cannot offer, "
f"as its {REQUIREMENTS_FILE_NAME} declares: {refusal.reason}"
@@ -323,8 +410,9 @@ def _refused_by_deployment_error(*, judged: JudgedMethod, refusal: PipeFuncPacka
item = PipelexBundleBlueprintValidationErrorData(
source=judged.requirements_source,
message=f"The requirements are refused by {refusal.environment}: {refusal.reason}",
+ params=params,
)
- return MethodRequirementsNotMetError(msg, items=[item])
+ return MethodRequirementsNotMetError(msg, items=[item]).with_params(**params)
def _ensure_judged_methods_met(*, judged_methods: Iterable[JudgedMethod], names_host_paths: bool) -> None:
@@ -356,7 +444,7 @@ def _ensure_judged_methods_met(*, judged_methods: Iterable[JudgedMethod], names_
continue
environment = resolve_pipe_func_package_environment(requirements=parsed.requirements, names_host_paths=names_host_paths)
if isinstance(environment, PipeFuncPackageRefusal):
- raise _refused_by_deployment_error(judged=judged, refusal=environment)
+ raise _refused_by_deployment_error(judged=judged, refusal=environment, requirements=parsed.requirements)
unmet = unmet_requirements(requirements=parsed.requirements, environment=environment)
if unmet:
_raise_unmet(judged=judged, unmet=unmet, environment=environment)
diff --git a/pipelex/libraries/method_trees.py b/pipelex/libraries/method_trees.py
index 34080bc15..5572b1262 100644
--- a/pipelex/libraries/method_trees.py
+++ b/pipelex/libraries/method_trees.py
@@ -246,7 +246,7 @@ def tree_bundle_of_lone_file(*, bundle_file: Path, limits: TreeLimits | None = N
tree = list_local_method_tree(handed_over=bundle_file, limits=limits)
if tree.entry is None:
msg = f"Listing the method tree of the bundle file '{bundle_file}' named no entry for it."
- raise MethodTreeLoadError(msg)
+ raise MethodTreeLoadError(msg).with_params(reason=TreeRefusalCode.LONE_FILE_EXCLUDED)
return TreeBundle(tree=tree, tree_path=tree.entry)
diff --git a/pipelex/libraries/pipe/exceptions.py b/pipelex/libraries/pipe/exceptions.py
index da9576e8a..d172a3dda 100644
--- a/pipelex/libraries/pipe/exceptions.py
+++ b/pipelex/libraries/pipe/exceptions.py
@@ -39,7 +39,9 @@ class EntryPipeNotFoundError(PipeNotFoundError):
the method itself declares that names no pipe of the method chooses ``method.pipe_unresolved``.
The message names only the caller's own `pipe_code`, and each raise site owes that invariant: a
- message here may name what the caller typed and nothing from the loaded library.
+ message here may name what the caller typed and nothing from the loaded library. The code's `suggestions` offer
+ only pipes the caller may select: the entry package's own for a bare or domain-qualified code, and for an
+ `alias->…` code the pipes that package exports, never its private ones (`PipeLibrary.get_required_entry_pipe`).
"""
error_code = ErrorCodeSet(
diff --git a/pipelex/libraries/pipe/pipe_library.py b/pipelex/libraries/pipe/pipe_library.py
index 1626fcba7..eaf11637c 100644
--- a/pipelex/libraries/pipe/pipe_library.py
+++ b/pipelex/libraries/pipe/pipe_library.py
@@ -1,7 +1,8 @@
+from collections.abc import Iterable
from itertools import groupby
from typing import Self
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from pydantic import PrivateAttr, RootModel
from typing_extensions import override
@@ -10,6 +11,7 @@ from pipelex.core.qualified_ref import QualifiedRef
from pipelex.libraries.library_state import next_library_state_token
from pipelex.libraries.pipe.exceptions import EntryPipeAmbiguousError, EntryPipeNotFoundError, PipeLibraryError, PipeNotFoundError
from pipelex.libraries.pipe.pipe_library_abstract import PipeLibraryAbstract
+from pipelex.libraries.pipe.pipe_suggestions import close_pipe_refs
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.tools.misc.rich_extra import RICH_TABLE_MISSING_MESSAGE, require_rich
@@ -26,6 +28,10 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
# The aliased keys of dependency pipes the package meant to load but that failed to build, with the reason, so a
# reference to one is refused naming that failure rather than as a pipe the package does not have.
_unbuilt_dependency_reasons: dict[str, str] = PrivateAttr(default_factory=dict)
+ # The refs of the pipes a caller's own bundles declare, when they are loaded beside a host's library directories:
+ # a refusal the caller reads offers only these among the library's own pipes, since the host's are its own to name.
+ # None when every own pipe is the caller's.
+ _caller_pipe_refs: frozenset[str] | None = PrivateAttr(default=None)
# Replaced on every change to what the library holds, so a value derived from the pipes it resolves knows it is stale.
_state_token: int = PrivateAttr(default_factory=next_library_state_token)
@@ -47,6 +53,7 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
self._private_dependency_keys = set()
self._withheld_dependency_keys = set()
self._unbuilt_dependency_reasons = {}
+ self._caller_pipe_refs = None
self._mark_changed()
@override
@@ -69,7 +76,7 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
"Check your library configuration: PIPELEXPATH environment variable, "
"library_dirs passed to Pipelex.make(), or the --library-dir / -L CLI option."
)
- raise PipeLibraryError(msg)
+ raise PipeLibraryError(msg).with_params(name=pipe.pipe_ref, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
self.root[pipe.pipe_ref] = pipe
self._mark_changed()
@@ -161,7 +168,7 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
raise
except PipeLibraryError as exc:
# The candidates the lookup found, which the refusal's code names to the caller and a selection reads back.
- raise EntryPipeAmbiguousError(str(exc)).with_params(pipe=pipe_code, candidates=exc.given_params.get("candidates")) from exc
+ raise EntryPipeAmbiguousError(str(exc)).with_params(pipe=pipe_code, candidates=exc.given_params.get("candidates", [])) from exc
if pipe is not None:
return pipe
@@ -187,9 +194,49 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
f"Pipe '{pipe_code}' could not be resolved. Check for typos and make sure its bundle is loaded. "
"A bare code only matches this library's own domains — a pipe from a dependency package must be named 'alias->pipe_code'."
)
- raise EntryPipeNotFoundError(msg).with_params(pipe=pipe_code)
+ # The pipes nearest the code a caller supplied that it may select, so the refusal offers what it most likely meant.
+ suggestions = close_pipe_refs(name=pipe_code, pipe_refs=self._scope_pipe_refs(pipe_code=pipe_code))
+ raise EntryPipeNotFoundError(msg).with_params(pipe=pipe_code, suggestions=suggestions)
return the_pipe
+ def _scope_pipe_refs(self, *, pipe_code: str) -> list[str]:
+ """The pipes a refusal of a code that names none may offer in its place, each in the form the code names a pipe.
+
+ A code naming a dependency (`alias->…`), whether an entry selection or a reference in a pipe's body, is offered
+ only the pipes that package exports, as `alias->domain.code`: its private pipes are no one else's to name. Any
+ other code is offered the entry package's own pipes, as `domain.code`, which a bare code or a domain-qualified
+ ref names; a dependency's pipe is never offered to it, since a bare code never names one.
+ """
+ if QualifiedRef.has_cross_package_prefix(pipe_code):
+ alias, _ = QualifiedRef.split_cross_package_ref(pipe_code)
+ return self.dependency_pipe_keys(alias=alias, with_private=False)
+ return self.selectable_own_pipe_refs()
+
+ def set_caller_pipe_refs(self, *, pipe_refs: Iterable[str]) -> None:
+ """Record the pipes the caller's own bundles declare, loaded beside a host's library directories.
+
+ From then on a refusal the caller reads offers only these among the library's own pipes, as a verdict names
+ none of the host's files: the host's pipes are its own, and their refs are not the caller's to read.
+ """
+ self._caller_pipe_refs = frozenset(pipe_refs)
+
+ @override
+ def selectable_own_pipe_refs(self) -> list[str]:
+ own_pipe_refs = [pipe.pipe_ref for pipe in self.get_own_pipes()]
+ if self._caller_pipe_refs is None:
+ return own_pipe_refs
+ return [pipe_ref for pipe_ref in own_pipe_refs if pipe_ref in self._caller_pipe_refs]
+
+ def dependency_pipe_keys(self, *, alias: str, with_private: bool) -> list[str]:
+ """The aliased keys, `alias->domain.code`, of the pipes the package loaded as `alias` holds in this library.
+
+ Args:
+ alias: The dependency alias.
+ with_private: Whether the package's private pipes are included, which only the package's own pipes may name.
+ """
+ prefix = f"{alias}->"
+ return [key for key in self.root if key.startswith(prefix) and (with_private or key not in self._private_dependency_keys)]
+
def add_dependency_pipe(self, *, alias: str, pipe: PipeAbstract, is_exported: bool) -> None:
"""Add a pipe from a dependency package with an aliased key.
@@ -258,11 +305,16 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
return sorted(key for key in keys if key.startswith(f"{alias}->") and key.endswith(f".{remainder}"))
@override
- def get_required_pipe(self, pipe_code: str) -> PipeAbstract:
+ def get_required_pipe(self, pipe_code: str, *, referring_pipe_code: str | None = None) -> PipeAbstract:
the_pipe = self.get_optional_pipe(pipe_code=pipe_code)
if not the_pipe:
msg = f"Pipe '{pipe_code}' not found. Check for typos and make sure it is declared in MTHDS file in an imported package."
- raise PipeNotFoundError(msg)
+ # The candidates are the refs of the scope the ref is read in: the package it names, or this library's own pipes.
+ candidates = close_pipe_refs(name=pipe_code, pipe_refs=self._scope_pipe_refs(pipe_code=pipe_code))
+ refusal = PipeNotFoundError(msg).with_params(missing=pipe_code, candidates=candidates)
+ if referring_pipe_code is not None:
+ refusal = refusal.with_params(pipe=referring_pipe_code)
+ raise refusal
return the_pipe
@override
diff --git a/pipelex/libraries/pipe/pipe_library_abstract.py b/pipelex/libraries/pipe/pipe_library_abstract.py
index a1c7f767e..407463cc7 100644
--- a/pipelex/libraries/pipe/pipe_library_abstract.py
+++ b/pipelex/libraries/pipe/pipe_library_abstract.py
@@ -29,8 +29,14 @@ class PipeLibraryAbstract(ABC):
"""
@abstractmethod
- def get_required_pipe(self, pipe_code: str) -> PipeAbstract:
- """Resolve an in-body pipe reference, raising when it is not known."""
+ def get_required_pipe(self, pipe_code: str, *, referring_pipe_code: str | None = None) -> PipeAbstract:
+ """Resolve an in-body pipe reference, raising when it is not known.
+
+ Args:
+ pipe_code: The reference, as the referring pipe's body writes it.
+ referring_pipe_code: The pipe whose body writes the reference, which the refusal names as its `pipe`; none
+ for a reference no pipe writes, such as a bundle's `main_pipe`.
+ """
@property
@abstractmethod
@@ -76,6 +82,13 @@ class PipeLibraryAbstract(ABC):
def get_own_pipes(self) -> list[PipeAbstract]:
"""The library's own pipes, without the aliased entries its dependency packages contributed."""
+ @abstractmethod
+ def selectable_own_pipe_refs(self) -> list[str]:
+ """The refs of the own pipes a refusal may offer its caller in place of one that names nothing.
+
+ Every own pipe, unless the caller's bundles were loaded beside a host's library directories: then only theirs.
+ """
+
@abstractmethod
def get_pipes_dict(self) -> dict[str, PipeAbstract]:
pass
diff --git a/pipelex/libraries/pipe/pipe_suggestions.py b/pipelex/libraries/pipe/pipe_suggestions.py
new file mode 100644
index 000000000..73f43fc61
--- /dev/null
+++ b/pipelex/libraries/pipe/pipe_suggestions.py
@@ -0,0 +1,58 @@
+"""The pipes a refusal of a pipe selection or reference offers in place of the one that names nothing.
+
+A refusal that names a pipe the method does not declare, or that names no pipe where the method gives none to
+start from, carries the pipes the caller most likely meant (``request.pipe_not_found``'s ``suggestions``,
+``method.pipe_unresolved``'s and ``request.pipe_unspecified``'s ``candidates``). Each is written as the qualified
+``domain.pipe_code`` a selection accepts, whatever form the name that missed was written in.
+"""
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from pipelex.core.qualified_ref import QualifiedRef
+from pipelex.tools.misc.string_utils import close_matches
+
+if TYPE_CHECKING:
+ from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
+
+# The declaration a `method.pipe_unresolved` refusal names as its `pipe` when the reference that names nothing is a
+# `main_pipe`, of a bundle or of a package manifest: no pipe declares that reference, so the refusal names the
+# declaration that holds it.
+MAIN_PIPE_DECLARATION = "main_pipe"
+
+# How near a pipe code must be to the code that missed to be offered, as difflib's similarity ratio, and how many are offered.
+_CLOSE_PIPE_CUTOFF = 0.6
+_CLOSE_PIPE_MAX_MATCHES = 5
+
+
+def declared_pipe_refs(*, blueprints: Iterable["PipelexBundleBlueprint"]) -> list[str]:
+ """The qualified refs of every pipe the bundles declare, sorted: the pipes a request sending them may select."""
+ return sorted({f"{blueprint.domain}.{pipe_code}" for blueprint in blueprints for pipe_code in blueprint.pipe or {}})
+
+
+def close_pipe_refs(*, name: str, pipe_refs: Iterable[str]) -> list[str]:
+ """The pipe refs whose code is nearest the code ``name`` writes, nearest first; an empty list when none is near.
+
+ ``name`` is matched by its code, the part after its domain and after a dependency alias, so a selection that
+ names the right pipe in the wrong domain is offered the pipe it meant. A code declared in several domains offers
+ each of its refs.
+
+ Args:
+ name: The pipe code or ref that names no pipe, as it was written.
+ pipe_refs: The qualified refs of the pipes that may be offered.
+
+ Returns:
+ The refs offered, nearest first.
+ """
+ refs_by_code: dict[str, list[str]] = {}
+ for pipe_ref in sorted(set(pipe_refs)):
+ refs_by_code.setdefault(_pipe_code_of(ref=pipe_ref), []).append(pipe_ref)
+ matches = close_matches(name=_pipe_code_of(ref=name), candidates=refs_by_code, cutoff=_CLOSE_PIPE_CUTOFF, max_matches=_CLOSE_PIPE_MAX_MATCHES)
+ return [pipe_ref for code in matches for pipe_ref in refs_by_code[code]]
+
+
+def _pipe_code_of(*, ref: str) -> str:
+ """The pipe code a ref writes, without its dependency alias or its domain."""
+ if QualifiedRef.has_cross_package_prefix(ref):
+ ref = QualifiedRef.split_cross_package_ref(ref).remainder
+ return ref.rsplit(".", 1)[-1]
diff --git a/pipelex/libraries/visibility_utils.py b/pipelex/libraries/visibility_utils.py
index fbe1cc3d0..365aa4dfd 100644
--- a/pipelex/libraries/visibility_utils.py
+++ b/pipelex/libraries/visibility_utils.py
@@ -6,7 +6,7 @@ the mthds PackageVisibilityChecker.
from mthds.package.bundle_metadata import BundleMetadata
from mthds.package.manifest.schema import MethodsManifest
-from mthds.package.visibility import PackageVisibilityChecker, VisibilityError
+from mthds.package.visibility import PackageVisibilityChecker
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
@@ -48,26 +48,3 @@ def make_visibility_checker(
"""
metadatas = [_blueprint_to_metadata(blueprint) for blueprint in blueprints]
return PackageVisibilityChecker(manifest=manifest, bundle_metadatas=metadatas)
-
-
-def check_visibility_for_blueprints(
- *,
- manifest: MethodsManifest | None,
- blueprints: list[PipelexBundleBlueprint],
-) -> list[VisibilityError]:
- """Convenience function: check visibility for pipelex blueprints.
-
- Validates both intra-package cross-domain visibility and cross-package references.
-
- Args:
- manifest: The package manifest (None means all-public).
- blueprints: The pipelex bundle blueprints to check.
-
- Returns:
- List of visibility errors.
- """
- checker = make_visibility_checker(manifest=manifest, blueprints=blueprints)
- errors = checker.validate_reserved_domains()
- errors.extend(checker.validate_all_pipe_references())
- errors.extend(checker.validate_cross_package_references())
- return errors
diff --git a/pipelex/methods/exceptions.py b/pipelex/methods/exceptions.py
index b813d15f9..77f9c553f 100644
--- a/pipelex/methods/exceptions.py
+++ b/pipelex/methods/exceptions.py
@@ -6,6 +6,7 @@ from typing_extensions import override
from pipelex.base_exceptions import PipelexError
from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, ErrorCodeSet
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
+from pipelex.methods.package_reason import MethodPackageReason
class MethodRefError(PipelexError):
@@ -77,6 +78,10 @@ class MethodPackageSymlinkError(MethodRefError):
error_code = CoreCode.METHOD_PACKAGE_INVALID
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"reason": MethodPackageReason.SYMLINK}
+
class MethodStructuresRefusedError(MethodRefError):
"""The method declares Python structure classes, which hosted execution refuses to import into its own process.
diff --git a/pipelex/methods/fetching.py b/pipelex/methods/fetching.py
index ab4acff1d..0b7e0d5a5 100644
--- a/pipelex/methods/fetching.py
+++ b/pipelex/methods/fetching.py
@@ -20,6 +20,7 @@ from pipelex.methods.exceptions import MethodFetchError, MethodPackageSymlinkErr
from pipelex.methods.fetch_limits import MAX_FETCHED_PACKAGE_FILES, MAX_FETCHED_PACKAGE_TOTAL_BYTES
from pipelex.methods.method_ref import MethodRef
from pipelex.methods.package_locator import locate_package_in_clone
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.methods.structures_check import ensure_no_structured_content_python
GIT_REV_PARSE_TIMEOUT_SECONDS = 30
@@ -178,17 +179,17 @@ def ensure_package_within_bounds(*, package_dir: Path, package_address: str) ->
if file_path.is_symlink():
relative = "/".join(relative_parts)
msg = f"Method package '{package_address}' contains a symlink ('{relative}') — fetched packages must not contain symlinks."
- raise MethodPackageSymlinkError(msg)
+ raise MethodPackageSymlinkError(msg).with_params(path=relative)
if not file_path.is_file():
continue
file_count += 1
total_bytes += file_path.stat().st_size
if file_count > MAX_FETCHED_PACKAGE_FILES:
msg = f"Method package '{package_address}' exceeds the fetched-package ceiling of {MAX_FETCHED_PACKAGE_FILES} files."
- raise MethodPackageTooLargeError(msg)
+ raise MethodPackageTooLargeError(msg).with_params(reason=MethodPackageReason.TOO_MANY_FILES, limit=MAX_FETCHED_PACKAGE_FILES)
if total_bytes > MAX_FETCHED_PACKAGE_TOTAL_BYTES:
msg = f"Method package '{package_address}' exceeds the fetched-package ceiling of {MAX_FETCHED_PACKAGE_TOTAL_BYTES} bytes in total."
- raise MethodPackageTooLargeError(msg)
+ raise MethodPackageTooLargeError(msg).with_params(reason=MethodPackageReason.TREE_TOO_LARGE, limit=MAX_FETCHED_PACKAGE_TOTAL_BYTES)
def fetch_method_package(
diff --git a/pipelex/methods/package_locator.py b/pipelex/methods/package_locator.py
index edb678587..0a8715e5b 100644
--- a/pipelex/methods/package_locator.py
+++ b/pipelex/methods/package_locator.py
@@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict, Field
from pipelex.methods.exceptions import MethodPackageAmbiguityError, MethodPackageNotFoundError, MethodPackageTooLargeError
from pipelex.methods.fetch_limits import MAX_MANIFEST_FILE_BYTES, MAX_SCANNED_MANIFESTS
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
_SKIPPED_DIR_NAMES = {".git"}
@@ -134,7 +135,7 @@ def scan_packages_in_clone(*, clone_root: Path) -> PackageScan:
manifest_count += 1
if manifest_count > MAX_SCANNED_MANIFESTS:
msg = f"The fetched repository contains more than {MAX_SCANNED_MANIFESTS} {MANIFEST_FILENAME} manifests; refusing to scan further."
- raise MethodPackageTooLargeError(msg)
+ raise MethodPackageTooLargeError(msg).with_params(reason=MethodPackageReason.TOO_MANY_MANIFESTS, limit=MAX_SCANNED_MANIFESTS)
relative_path = manifest_path.relative_to(clone_root).as_posix()
manifest_read = _read_manifest_text(manifest_path=manifest_path)
if manifest_read.text is None:
diff --git a/pipelex/methods/package_reason.py b/pipelex/methods/package_reason.py
new file mode 100644
index 000000000..a3c373c6a
--- /dev/null
+++ b/pipelex/methods/package_reason.py
@@ -0,0 +1,44 @@
+"""The reasons a method's package breaks a package rule, the `reason` of `method.package_invalid`."""
+
+from enum import StrEnum, unique
+
+
+@unique
+class MethodPackageReason(StrEnum):
+ """The `reason` of a `method.package_invalid` the runtime and its runner raise themselves, one member per rule and one per limit.
+
+ Beside them, a refusal of the standard's tree rule gives the standard's own refusal code (`TreeRefusalCode`) as its
+ reason. A limit's refusal also gives its `limit`, and each limit has its own reason, so a caller reads which one the
+ method passed: a tree's, a request's or a `bundle_b64` archive's.
+ """
+
+ # The limits of one method tree.
+ TOO_MANY_FILES = "too_many_files"
+ FILE_TOO_LARGE = "file_too_large"
+ TREE_TOO_LARGE = "tree_too_large"
+ # The limits of a request's trees together.
+ TOO_MANY_DEPENDENCIES = "too_many_dependencies"
+ METHOD_TOO_LARGE = "method_too_large"
+ # The limits of a `bundle_b64` archive, on its members and on its decompressed size.
+ BUNDLE_TOO_MANY_FILES = "bundle_too_many_files"
+ BUNDLE_TOO_LARGE = "bundle_too_large"
+ # The method's own tree holds no `.mthds` bundle.
+ NO_BUNDLE = "no_bundle"
+ # The manifest of a shipped package or of a dependency tree.
+ MANIFEST_MISSING = "manifest_missing"
+ MANIFEST_INVALID = "manifest_invalid"
+ PACKAGE_NAME_INVALID = "package_name_invalid"
+ # Two dependencies a reference could not tell apart.
+ DEPENDENCY_ADDRESS_COLLISION = "dependency_address_collision"
+ # A fetched package holds a file whose name is not UTF-8 text.
+ FILE_NAME_NOT_UTF8 = "file_name_not_utf8"
+ # A fetched package holds a symbolic link, which would let a file reach outside it past the content scans.
+ SYMLINK = "symlink"
+ # A fetched repository holds more manifests than the runtime scans for the package an address names.
+ TOO_MANY_MANIFESTS = "too_many_manifests"
+ # The method's `requirements.txt` holds a line the standard refuses, or cannot be read as UTF-8 text.
+ REQUIREMENTS_INVALID = "requirements_invalid"
+ # A version, or a version constraint, the package declares does not parse.
+ VERSION_INVALID = "version_invalid"
+ # The method's tree cannot be listed: a path it names is missing, one of its files cannot be read, or its manifest does not parse.
+ TREE_UNREADABLE = "tree_unreadable"
diff --git a/pipelex/mthds_parsing/exceptions.py b/pipelex/mthds_parsing/exceptions.py
index 981c2e8bd..76b6f0136 100644
--- a/pipelex/mthds_parsing/exceptions.py
+++ b/pipelex/mthds_parsing/exceptions.py
@@ -24,22 +24,20 @@ class NativeConceptRedeclarationError(PipelexError, ValueError):
class InvalidPipeCodeSyntaxError(PipelexError, ValueError):
- """A same-domain over-qualified pipe code the fix planner can strip back to its bare form.
-
- Raised (in place of a bare ``ValueError``) only at the two snake_case-enforcing raise sites —
- a ``[pipe."<domain>.<code>"]`` declaration key and a ``main_pipe = "<domain>.<code>"`` value —
- and only when the code is safely strippable: the prefix equals the bundle's own ``domain``, the
- bare tail is itself a valid snake_case code, and (for a declaration) no bare code already
- occupies that key. Subclasses ``ValueError`` so a ``mode="before"`` field validator can raise
- it and pydantic keeps it in ``ctx["error"]`` for the categorizer to unwrap structurally —
- carrying the ``stripped_code`` (and, for a declaration, the ``offending_code`` to rename from)
- that the ``strip-namespace`` planner needs. Genuinely malformed codes and cross-package dotted
- refs stay bare ``ValueError``s → uncategorized-as-fixable, so they are never stripped.
+ """A pipe code that breaks the naming rules, as a ``[pipe."<code>"]`` declaration key or as the ``main_pipe`` value.
+
+ Raised at the two snake_case-enforcing raise sites, carrying the ``offending_code`` as the method writes it, which
+ the item names. Subclasses ``ValueError`` so a ``mode="before"`` field validator can raise it and pydantic keeps it
+ in ``ctx["error"]`` for the categorizer to unwrap structurally. When the code is a same-domain over-qualified one
+ the fix planner can strip back to its bare form (the prefix equals the bundle's own ``domain``, the bare tail is
+ itself a valid snake_case code, and, for a declaration, no bare code already occupies that key), it also carries
+ the ``stripped_code`` the ``strip-namespace`` planner needs; a genuinely malformed code or a cross-package dotted
+ ref carries none, so it is never stripped.
"""
error_code = CoreCode.METHOD_IDENTIFIER_INVALID
- def __init__(self, message: str, offending_code: str, stripped_code: str):
+ def __init__(self, message: str, offending_code: str, stripped_code: str | None = None):
self.offending_code = offending_code
self.stripped_code = stripped_code
super().__init__(message)
diff --git a/pipelex/mthds_parsing/handle_pipe_errors.py b/pipelex/mthds_parsing/handle_pipe_errors.py
index e8374f1f1..57dc6b121 100644
--- a/pipelex/mthds_parsing/handle_pipe_errors.py
+++ b/pipelex/mthds_parsing/handle_pipe_errors.py
@@ -223,6 +223,8 @@ def categorize_pipe_validation_with_libraries_error(
expected_inputs=pipe_error.expected_inputs,
declared_inputs=pipe_error.declared_inputs,
model_reference=pipe_error.model_reference,
+ # The facts of the error's code its raise site gave, which a caller may read.
+ params=pipe_error.caller_params() or None,
)
diff --git a/pipelex/mthds_parsing/parser.py b/pipelex/mthds_parsing/parser.py
index f8d080e34..1adfa87fa 100644
--- a/pipelex/mthds_parsing/parser.py
+++ b/pipelex/mthds_parsing/parser.py
@@ -33,10 +33,14 @@ def undecodable_mthds_error(*, error: UnicodeDecodeError, source: str | None) ->
"""
line, column = _decode_error_position(error)
msg = f"The MTHDS file is not UTF-8 text: the byte at line {line}, column {column} does not decode."
- return MthdsParserError(
- msg,
- validation_errors=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg, line=line, column=column)],
- ).with_error_code(CoreCode.METHOD_SYNTAX)
+ return (
+ MthdsParserError(
+ msg,
+ validation_errors=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg, line=line, column=column)],
+ )
+ .with_error_code(CoreCode.METHOD_SYNTAX)
+ .with_params(finding=msg)
+ )
def decode_mthds_text(*, content: bytes, source: str | None) -> str:
@@ -110,18 +114,22 @@ class MthdsParser(BaseModel):
toml_message = toml_message.replace(str(bundle_path), mthds_source)
msg = f"TOML syntax error at line {exc.lineno}, column {exc.colno}: {toml_message}"
source = str(bundle_path) if bundle_path is not None and mthds_source is None else mthds_source
- raise MthdsParserError(
- msg,
- validation_errors=[
- PipelexBundleBlueprintValidationErrorData(
- source=source,
- message=msg,
- # tomli counts both from 1, as the item's locators do.
- line=exc.lineno,
- column=exc.colno,
- )
- ],
- ).with_error_code(CoreCode.METHOD_SYNTAX) from exc
+ raise (
+ MthdsParserError(
+ msg,
+ validation_errors=[
+ PipelexBundleBlueprintValidationErrorData(
+ source=source,
+ message=msg,
+ # tomli counts both from 1, as the item's locators do.
+ line=exc.lineno,
+ column=exc.colno,
+ )
+ ],
+ )
+ .with_error_code(CoreCode.METHOD_SYNTAX)
+ .with_params(finding=msg)
+ ) from exc
except UnicodeDecodeError as exc:
# tomli reads a file as bytes and decodes them as UTF-8, so a file of a tree that is not text fails here.
source = mthds_source if mthds_source is not None else str(bundle_path)
diff --git a/pipelex/mthds_parsing/pipelex_bundle_blueprint.py b/pipelex/mthds_parsing/pipelex_bundle_blueprint.py
index 1e2c2a2f8..b5a854487 100644
--- a/pipelex/mthds_parsing/pipelex_bundle_blueprint.py
+++ b/pipelex/mthds_parsing/pipelex_bundle_blueprint.py
@@ -198,11 +198,9 @@ class PipelexBundleBlueprint(BaseModel):
if not is_pipe_code_valid(main_pipe):
msg = f"Invalid main pipe syntax '{main_pipe}'. Must be in snake_case."
stripped = _strippable_same_domain_pipe_code(main_pipe, domain=cast("str | None", info.data.get("domain")))
- if stripped is not None:
- # Typed (still a ValueError, so pydantic wraps it into ``ctx["error"]``) so the
- # blueprint categorizer recovers the strip target structurally for the fix planner.
- raise InvalidPipeCodeSyntaxError(msg, offending_code=main_pipe, stripped_code=stripped)
- raise ValueError(msg)
+ # Typed (still a ValueError, so pydantic wraps it into ``ctx["error"]``) so the blueprint categorizer
+ # recovers the name, and the strip target when there is one, structurally.
+ raise InvalidPipeCodeSyntaxError(msg, offending_code=main_pipe, stripped_code=stripped)
return main_pipe
@field_validator("pipe", mode="before")
@@ -230,11 +228,9 @@ class PipelexBundleBlueprint(BaseModel):
if isinstance(pipe_code, str) and not is_pipe_code_valid(pipe_code=pipe_code):
msg = f"Pipe code '{pipe_code}' is not a valid pipe code. Must be in snake_case."
stripped = _strippable_same_domain_pipe_code(pipe_code, domain=domain, existing_pipe_codes=existing_pipe_codes)
- if stripped is not None:
- # Typed (still a ValueError) so the categorizer recovers the rename target
- # (offending dotted key + stripped bare key) structurally for the fix planner.
- raise InvalidPipeCodeSyntaxError(msg, offending_code=pipe_code, stripped_code=stripped)
- raise ValueError(msg)
+ # Typed (still a ValueError) so the categorizer recovers the offending key, and the rename
+ # target when there is one, structurally.
+ raise InvalidPipeCodeSyntaxError(msg, offending_code=pipe_code, stripped_code=stripped)
normalized[pipe_code] = normalize_typeless_signature_section(pipe_code=pipe_code, pipe_section=pipe_section)
return normalized
diff --git a/pipelex/mthds_parsing/validation_error_categorizer.py b/pipelex/mthds_parsing/validation_error_categorizer.py
index 52662b034..8a25410a6 100644
--- a/pipelex/mthds_parsing/validation_error_categorizer.py
+++ b/pipelex/mthds_parsing/validation_error_categorizer.py
@@ -19,6 +19,7 @@ from pipelex.mthds_parsing.helpers import ValidationErrorScope, get_error_scope
from pipelex.pipe_controllers.binding.binding_concept_resolvers import BlueprintConceptWalkResolver, qualify_concept_ref
from pipelex.pipe_controllers.binding.binding_derivation import BindingRoot, derive_binding
from pipelex.pipe_controllers.binding.exceptions import BindingPathUnresolvedError
+from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import SEQUENCE_STEP_TAGS
from pipelex.pipe_machinery.pipe_blueprint import PIPE_SIGNATURE_TYPE_TAG, PipeType
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
from pipelex.validation_error_types import PipeValidationErrorType
@@ -214,45 +215,6 @@ def _categorize_typeless_pipe_error(
)
-def _categorize_syntax_validation_error(
- message: str,
- *,
- domain: str | None,
- source: str | None,
-) -> PipelexBundleBlueprintValidationErrorData | None:
- """Categorize syntax validation errors (invalid pipe code, invalid main_pipe).
-
- Args:
- message: The error message from the validation
- domain: Domain code
- source: Source file path
-
- Returns:
- Categorized error data, or None if not a syntax validation error
- """
- message_lower = message.lower()
-
- # Detect invalid main_pipe syntax
- if "invalid main pipe syntax" in message_lower:
- return PipelexBundleBlueprintValidationErrorData(
- error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,
- domain_code=domain,
- source=source,
- message=message,
- )
-
- # Detect invalid pipe code syntax
- if "is not a valid pipe code" in message_lower:
- return PipelexBundleBlueprintValidationErrorData(
- error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,
- domain_code=domain,
- source=source,
- message=message,
- )
-
- return None
-
-
def _is_pydantic_internal_loc_element(element: str) -> bool:
"""Check if a loc element is a pydantic internal type discriminator rather than a user-facing field name.
@@ -317,14 +279,17 @@ def _bundle_field_path(*, loc: tuple[int | str, ...], ends_with_authored_key: bo
"""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 (``pipe.summarize.PipeLLM.promtp``), and a sequence step through a union tagged by its shape
+ (``pipe.run_all.PipeSequence.steps.0.pipe_step.batch_as``); those tags 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]
+ if len(parts) >= 5 and parts[2] == "steps" and parts[3].isdigit() and parts[4] in SEQUENCE_STEP_TAGS:
+ del parts[4]
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:
@@ -332,6 +297,21 @@ def _bundle_field_path(*, loc: tuple[int | str, ...], ends_with_authored_key: bo
return ".".join(clean_parts) or None
+def _pipe_field_name(*, loc: tuple[int | str, ...], field_name: str | None) -> str | None:
+ """The path, inside its pipe's table, of the field a blueprint-stage error raised inside that pipe names.
+
+ The error knows the field of the table it validated (``batch_as``) but not where that table sits in its pipe, which
+ the pydantic ``loc`` gives (``pipe.run_all.PipeSequence.steps.0``): the field is joined to what follows the pipe's
+ code, giving ``steps.0.batch_as``, or the field alone when the pipe's own table raised it.
+ """
+ if field_name is None:
+ return None
+ bundle_path = _bundle_field_path(loc=loc, ends_with_authored_key=False) or ""
+ parts = bundle_path.split(".")
+ inner_parts = parts[2:] if len(parts) >= 2 and parts[0] == PIPELEX_BUNDLE_BLUEPRINT_PIPE_FIELD else []
+ return ".".join([*inner_parts, field_name])
+
+
def _make_uncategorized_blueprint_error(
*,
error: ErrorDetails,
@@ -429,6 +409,7 @@ def categorize_blueprint_validation_error(
pipe_code=wrapped_pipe_error.pipe_code or pipe_code,
message=wrapped_pipe_error.explanation or str(wrapped_pipe_error),
variable_names=wrapped_pipe_error.variable_names,
+ field_name=_pipe_field_name(loc=loc, field_name=wrapped_pipe_error.field_name),
redundant_input_name=wrapped_pipe_error.redundant_input_name,
dropped_input_marker=wrapped_pipe_error.dropped_input_marker,
root_input_marker=wrapped_pipe_error.root_input_marker,
@@ -445,18 +426,20 @@ def categorize_blueprint_validation_error(
domain_code=domain,
source=source,
concept_code=wrapped_native_redeclaration.concept_code,
+ # The table that redeclares it, by its bundle-root path, where a caller edits the bundle.
+ field_path=f"concept.{wrapped_native_redeclaration.concept_code}",
# The exception's own clean message, not the pydantic ``msg`` (which carries a
# "Value error, " prefix) — same choice as the wrapped-pipe-error path above.
message=str(wrapped_native_redeclaration),
)
- # A strippable same-domain over-qualified pipe code: ``validate_pipe_keys`` /
- # ``validate_main_pipe_syntax`` raised a typed ``ValueError`` carrying the stripped bare code
- # (which the message text and pydantic ``loc`` — ``("pipe",)`` / ``("main_pipe",)`` — cannot).
- # ``pipe_code`` discriminates the two raise sites for the planner: the offending dotted code for
- # a declaration-key rename, ``None`` for a ``main_pipe`` value strip (loc's first element names
- # the field). The bare ``ValueError`` path (malformed codes, cross-package refs) still falls
- # through to the message-matching ``_categorize_syntax_validation_error`` → unfixable.
+ # A pipe code that breaks the naming rules: ``validate_pipe_keys`` / ``validate_main_pipe_syntax``
+ # raised a typed ``ValueError`` carrying the offending name, and the stripped bare code when the
+ # name is a strippable same-domain over-qualified one (which the message text and pydantic ``loc``
+ # — ``("pipe",)`` / ``("main_pipe",)`` — cannot carry). ``pipe_code`` discriminates the two raise
+ # sites for the planner: the offending code for a declaration-key rename, ``None`` for a
+ # ``main_pipe`` value strip (loc's first element names the field, which ``field_path`` keeps). A
+ # malformed code or a cross-package ref carries no stripped code → unfixable.
#
# The ``main_pipe`` raise site cannot see the declarations (the ``pipe`` field validates after
# it), so the safety gate lives here, on the raw bundle dict: a strip that would retarget
@@ -466,10 +449,14 @@ def categorize_blueprint_validation_error(
if wrapped_invalid_pipe_code is not None:
is_main_pipe = bool(loc) and loc[0] == PIPELEX_BUNDLE_BLUEPRINT_MAIN_PIPE_FIELD
stripped_pipe_code: str | None = wrapped_invalid_pipe_code.stripped_code
- if is_main_pipe and not _main_pipe_strip_is_safe(
- offending_code=wrapped_invalid_pipe_code.offending_code,
- stripped_code=wrapped_invalid_pipe_code.stripped_code,
- blueprint_dict=blueprint_dict,
+ if (
+ is_main_pipe
+ and stripped_pipe_code is not None
+ and not _main_pipe_strip_is_safe(
+ offending_code=wrapped_invalid_pipe_code.offending_code,
+ stripped_code=stripped_pipe_code,
+ blueprint_dict=blueprint_dict,
+ )
):
stripped_pipe_code = None
return PipelexBundleBlueprintValidationErrorData(
@@ -477,6 +464,8 @@ def categorize_blueprint_validation_error(
domain_code=domain,
source=source,
pipe_code=None if is_main_pipe else wrapped_invalid_pipe_code.offending_code,
+ field_path=PIPELEX_BUNDLE_BLUEPRINT_MAIN_PIPE_FIELD if is_main_pipe else None,
+ identifier_name=wrapped_invalid_pipe_code.offending_code,
stripped_pipe_code=stripped_pipe_code,
message=str(wrapped_invalid_pipe_code),
)
@@ -520,15 +509,6 @@ def categorize_blueprint_validation_error(
if missing_type_error:
return missing_type_error
- # Try to categorize syntax validation errors (invalid pipe code, main_pipe)
- syntax_error = _categorize_syntax_validation_error(
- message=message,
- domain=domain,
- source=source,
- )
- if syntax_error:
- return syntax_error
-
# No categorizer knows it: keep it as an item of its own, never dropped because another item exists.
log.verbose(f"A bundle blueprint validation error 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/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.py
index 0c51e0174..4ce8603b0 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch.py
@@ -61,7 +61,7 @@ class PipeBatch(PipeController):
def required_variables(self) -> set[str]:
required_variables: set[str] = set()
# 1. Check that the inputs of the branch_pipe are in the inputs of the pipe
- branch_pipe = get_required_pipe(pipe_code=self.branch_pipe_code)
+ branch_pipe = get_required_pipe(pipe_code=self.branch_pipe_code, referring_pipe_code=self.code)
required_variables.update(branch_pipe.inputs.variables)
# 2. Check that the input_list_stuff_name is in the inputs of the pipe
if self.batch_params.input_item_stuff_name not in required_variables:
@@ -86,7 +86,7 @@ class PipeBatch(PipeController):
@override
def validate_inputs_with_library(self):
# Check that the item name is in the inputs of the branch_pipe
- branch_pipe = get_required_pipe(pipe_code=self.branch_pipe_code)
+ branch_pipe = get_required_pipe(pipe_code=self.branch_pipe_code, referring_pipe_code=self.code)
if self.batch_params.input_item_stuff_name not in branch_pipe.inputs.variables:
msg = f"Input item name '{self.batch_params.input_item_stuff_name}' not found in inputs of branch pipe '{self.branch_pipe_code}'"
raise PipeValidationError(message=msg, domain_code=self.domain_code, pipe_code=self.code).with_error_code(CoreCode.METHOD_WIRING_INVALID)
@@ -147,7 +147,7 @@ class PipeBatch(PipeController):
input_content = cast("ListContent[StuffContent]", input_stuff.content)
# TODO: Make commented code work when inputing images named "a.b.c"
- sub_pipe = get_required_pipe(pipe_code=self.branch_pipe_code)
+ sub_pipe = get_required_pipe(pipe_code=self.branch_pipe_code, referring_pipe_code=self.code)
batch_output_stuff_code = StuffFactory.make_stuff_code()
item_count = len(input_content.items)
diff --git a/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py b/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py
index f5e6c9dd4..4c8c85efe 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch_blueprint.py
@@ -49,6 +49,8 @@ class PipeBatchBlueprint(PipeBlueprint):
raise PipeValidationError(
message=msg,
error_type=PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION,
+ variable_names=[self.input_item_name],
+ field_name="input_item_name",
)
# General guard: item name must not collide with any other input key either
# (e.g. a batch pipe with inputs {"items": "Item[]", "context": "Text"} must not use "context" as item name)
@@ -62,6 +64,8 @@ class PipeBatchBlueprint(PipeBlueprint):
raise PipeValidationError(
message=msg,
error_type=PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION,
+ variable_names=[self.input_item_name],
+ field_name="input_item_name",
)
@override
diff --git a/pipelex/pipe_controllers/binding/exceptions.py b/pipelex/pipe_controllers/binding/exceptions.py
index be2b77d17..2e67cfb81 100644
--- a/pipelex/pipe_controllers/binding/exceptions.py
+++ b/pipelex/pipe_controllers/binding/exceptions.py
@@ -1,4 +1,7 @@
+from typing import Any
+
from mthds.protocol.problem.registry import CoreCode
+from typing_extensions import override
from pipelex.base_exceptions import PipelexError
from pipelex.errors.error_code_declaration import ErrorCodeSet
@@ -23,6 +26,10 @@ class BindingPathUnresolvedError(PipelexError):
self.available_fields = available_fields
super().__init__(message)
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"path": self.path, "segment": self.failed_segment, "available_fields": self.available_fields}
+
class BindingStepRunError(PipelexError):
"""A binding step that could not bind its value at run time, although its path was derived before the run.
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index 181ba11b8..508d821de 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -1,6 +1,6 @@
from typing import TYPE_CHECKING, Any, Literal
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodOptionalUnhandledSite
from pydantic import BaseModel, ConfigDict
from typing_extensions import override
@@ -8,7 +8,7 @@ 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
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemory
-from pipelex.core.pipes.exceptions import PipeRunError, PipeValidationError
+from pipelex.core.pipes.exceptions import PIPE_OUTPUT_NAME, PipeRunError, PipeValidationError
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
@@ -25,7 +25,7 @@ from pipelex.pipe_controllers.absence_taint import (
optional_input_taints,
scan_taint_triggers,
)
-from pipelex.pipe_controllers.condition.pipe_condition_blueprint import describe_expression_parse_failure
+from pipelex.pipe_controllers.condition.pipe_condition_blueprint import ConditionExpressionField, describe_expression_parse_failure
from pipelex.pipe_controllers.condition.special_outcome import SpecialOutcome
from pipelex.pipe_controllers.pipe_controller import PipeController
from pipelex.pipe_machinery.memory_writes import AlternativeWrites, MemoryWrite, SlotTaint, merge_alternative_writes, write_after_lift
@@ -36,6 +36,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_
from pipelex.system.invocation_path import DEFAULT_OUTCOME_SEGMENT, outcome_segment
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError, Jinja2TemplateInvalidError
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
@@ -76,6 +77,8 @@ class DryRunOutcomeSlot(BaseModel):
class PipeCondition(PipeController):
type: Literal["PipeCondition"] = "PipeCondition"
expression: str
+ # The field the bundle wrote the expression in, which a refusal of the expression is located on and names.
+ expression_field: ConditionExpressionField
outcome_map: ConditionOutcomeMap
default_outcome: str | SpecialOutcome
add_alias_from_expression_to: str | None = None
@@ -100,7 +103,7 @@ class PipeCondition(PipeController):
# Variables from the outcomes map and default_outcome
for pipe_code in self.pipe_dependencies():
- required_variables.update(get_required_pipe(pipe_code=pipe_code).required_variables())
+ required_variables.update(get_required_pipe(pipe_code=pipe_code, referring_pipe_code=self.code).required_variables())
# Exclude internal variables starting with `_`
return {var for var in required_variables if not var.startswith("_")}
@@ -242,7 +245,7 @@ class PipeCondition(PipeController):
# Add the inputs needed by all possible target pipes
for pipe_code in self.pipe_dependencies():
- pipe = get_required_pipe(pipe_code=pipe_code)
+ pipe = get_required_pipe(pipe_code=pipe_code, referring_pipe_code=self.code)
# Use the centralized recursion detection
pipe_needed_inputs = pipe.needed_inputs(visited_pipes=visited_pipes_with_current)
@@ -263,7 +266,7 @@ class PipeCondition(PipeController):
inputs=self.inputs,
template_source=self.expression,
template_category=TemplateCategory.EXPRESSION,
- template_label="expression",
+ template_label=self.expression_field,
)
@override
@@ -292,7 +295,7 @@ class PipeCondition(PipeController):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
- )
+ ).with_params(input=PIPE_OUTPUT_NAME, site=MethodOptionalUnhandledSite.CONDITION_OUTPUT)
@override
def validate_output_with_library(self):
@@ -315,7 +318,7 @@ class PipeCondition(PipeController):
# silently escape through the condition boundary.
if not self.output.presence.is_optional:
for pipe_code in sorted(mapped_pipe_codes):
- mapped_pipe = get_required_pipe(pipe_code=pipe_code)
+ mapped_pipe = get_required_pipe(pipe_code=pipe_code, referring_pipe_code=self.code)
if mapped_pipe.output.presence.is_optional:
msg = (
f"PipeCondition '{self.code}' maps outcome pipe '{pipe_code}' whose output "
@@ -329,7 +332,7 @@ class PipeCondition(PipeController):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
- )
+ ).with_params(input=pipe_code, site=MethodOptionalUnhandledSite.CONDITION)
# An outcome that the condition's own `?` inputs may lift resolves the condition's result absent, unless the
# result is a list, which the lift leaves empty (D4). The expression is not read, so an outcome it chooses only
# when the input is present is refused too, and forcing the input on that outcome (`!`) is the guarded remedy.
@@ -356,12 +359,12 @@ class PipeCondition(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
variable_names=[trigger_name],
- )
+ ).with_params(input=trigger_name, site=MethodOptionalUnhandledSite.CONDITION)
# Collect all unique output concept refs from mapped pipes
mapped_output_refs: set[str] = set()
for pipe_code in mapped_pipe_codes:
- pipe = get_required_pipe(pipe_code=pipe_code)
+ pipe = get_required_pipe(pipe_code=pipe_code, referring_pipe_code=self.code)
mapped_output_refs.add(pipe.output.concept.concept_ref)
all_outputs_same = len(mapped_output_refs) == 1
@@ -382,6 +385,10 @@ class PipeCondition(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
required_concept_codes=[expected_output_ref],
+ ).with_params(
+ declared=self.output.concept.concept_ref,
+ expected=[expected_output_ref, NativeConceptCode.ANYTHING.concept_ref],
+ pipe_type=self.type,
)
# Mapped pipes have different outputs - PipeCondition MUST use Dynamic
elif self.output.concept.concept_ref != NativeConceptCode.ANYTHING.concept_ref:
@@ -398,7 +405,7 @@ class PipeCondition(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
required_concept_codes=[NativeConceptCode.ANYTHING.concept_ref],
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=[NativeConceptCode.ANYTHING.concept_ref], pipe_type=self.type)
@override
async def _validate_before_run(
@@ -429,24 +436,26 @@ class PipeCondition(PipeController):
Raises:
PipeRunError: `method.template_invalid` when the expression cannot render as written, such as a filter or
a test inside a branch that the expression environment does not define, which only rendering that
- branch finds. The message names the pipe, its expression and what Jinja2 refused, never the
- expression's text.
+ branch finds. The message names the pipe, the field the bundle wrote the expression in and what Jinja2
+ refused, never the expression's text, and the refusal is located on that field, as a refusal of the
+ template sandbox is.
"""
try:
- return await render_template(
- template=self.expression,
- category=TemplateCategory.EXPRESSION,
- context=working_memory.generate_context(),
- )
+ with locating_template_refusal(template_field=self.expression_field):
+ return await render_template(
+ template=self.expression,
+ category=TemplateCategory.EXPRESSION,
+ context=working_memory.generate_context(),
+ )
except Jinja2TemplateInvalidError as exc:
if not exc.template_owner.is_method:
# One of Pipelex's own templates, reached from the expression's render: ours, kept as it is.
raise
- msg = f"PipeCondition '{self.code}': its expression cannot render: {exc.fault}"
+ msg = f"PipeCondition '{self.code}': its {self.expression_field} cannot render: {exc.fault}"
raise (
- PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
+ PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code, field=self.expression_field)
.with_error_code(CoreCode.METHOD_TEMPLATE_INVALID)
- .with_params(template="expression", finding=exc.fault)
+ .with_params(template=self.expression_field, finding=exc.fault)
) from exc
async def _evaluate_expression(
@@ -519,7 +528,7 @@ class PipeCondition(PipeController):
.with_params(outcome=outcome)
)
- chosen_pipe = get_required_pipe(pipe_code=outcome)
+ chosen_pipe = get_required_pipe(pipe_code=outcome, referring_pipe_code=self.code)
# Get required variables and validate they exist in working memory
# Extract root names from full paths for looking up stuffs in working memory
@@ -594,12 +603,12 @@ class PipeCondition(PipeController):
"""
pipes_by_visit_key: dict[str, PipeAbstract] = {}
for pipe_code in sorted(self.pipe_dependencies()):
- outcome_pipe = get_required_pipe(pipe_code=pipe_code)
+ outcome_pipe = get_required_pipe(pipe_code=pipe_code, referring_pipe_code=self.code)
pipes_by_visit_key.setdefault(outcome_pipe.visit_key, outcome_pipe)
group_pipes = list(pipes_by_visit_key.values())
if not self.default_outcome or self.default_outcome in SpecialOutcome.value_list():
return group_pipes
- default_pipe = get_required_pipe(pipe_code=self.default_outcome)
+ default_pipe = get_required_pipe(pipe_code=self.default_outcome, referring_pipe_code=self.code)
return [outcome_pipe for outcome_pipe in group_pipes if outcome_pipe is not default_pipe] + [default_pipe]
def _record_resolution(self, *, job_metadata: JobMetadata, evaluated_expression: str, outcome: str) -> None:
diff --git a/pipelex/pipe_controllers/condition/pipe_condition_blueprint.py b/pipelex/pipe_controllers/condition/pipe_condition_blueprint.py
index 33afb596e..8fa5a649a 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition_blueprint.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition_blueprint.py
@@ -12,6 +12,9 @@ from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_require
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.typing.validation_utils import has_exactly_one_among_attributes_from_list
+#: The field a bundle writes a condition's expression in: a template as written, or an expression.
+ConditionExpressionField = Literal["expression_template", "expression"]
+
OutcomeMap = dict[str, str]
@@ -58,6 +61,14 @@ class PipeConditionBlueprint(PipeBlueprint):
return "{{ " + self.expression + " }}"
return None
+ @property
+ def runtime_expression_field(self) -> ConditionExpressionField:
+ """The field the bundle writes the condition in, which a refusal of its expression is located on.
+
+ ``expression_template`` when it gives one, else ``expression``, the field ``runtime_expression`` reads first.
+ """
+ return "expression_template" if self.expression_template else "expression"
+
@field_validator("outcomes", mode="after")
@classmethod
def validate_outcome_map(cls, outcomes: OutcomeMap) -> OutcomeMap:
@@ -92,7 +103,7 @@ class PipeConditionBlueprint(PipeBlueprint):
runtime_expression = self.runtime_expression
if runtime_expression is None:
return
- field_name = "expression_template" if self.expression_template else "expression"
+ field_name = self.runtime_expression_field
wanted = "a Jinja2 template" if self.expression_template else "a Jinja2 expression"
try:
detect_jinja2_required_variables(template_category=TemplateCategory.EXPRESSION, template_source=runtime_expression)
diff --git a/pipelex/pipe_controllers/condition/pipe_condition_factory.py b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
index 018628200..304074e37 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition_factory.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
@@ -37,6 +37,7 @@ class PipeConditionFactory(PipeFactoryProtocol[PipeConditionBlueprint, PipeCondi
inputs=inputs,
output=output,
expression=expression,
+ expression_field=blueprint.runtime_expression_field,
outcome_map=blueprint.outcomes,
default_outcome=blueprint.default_outcome,
add_alias_from_expression_to=blueprint.add_alias_from_expression_to,
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.py
index 690d6b423..6abcfd37a 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py
@@ -2,7 +2,12 @@ import asyncio
import builtins
from typing import TYPE_CHECKING, Any, Literal, get_origin
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import (
+ CoreCode,
+ MethodNameConflictConflict,
+ MethodOptionalUnhandledSite,
+ MethodOutputMultiplicityMismatchExpected,
+)
from pydantic import ValidationError, field_validator
from typing_extensions import override
@@ -18,6 +23,7 @@ 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.pipes.variable_multiplicity import multiplicity_kind
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.composite_content import CompositeContent
from pipelex.core.stuffs.exceptions import StuffFactoryError
@@ -44,6 +50,7 @@ from pipelex.pipe_machinery.pipe_abstract import CompanionSlot
from pipelex.pipe_run.pipe_run_params import PipeRunParams, output_multiplicity_to_apply
from pipelex.system.invocation_path import branch_segment
from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.validation_error_types import PipeValidationErrorType
if TYPE_CHECKING:
@@ -119,7 +126,7 @@ class PipeParallel(PipeController):
needed_inputs = InputStuffSpecsFactory.make_empty()
for sub_pipe in self.parallel_sub_pipes:
- pipe = get_required_pipe(pipe_code=sub_pipe.pipe_code)
+ pipe = get_required_pipe(pipe_code=sub_pipe.pipe_code, referring_pipe_code=self.code)
# Use the centralized recursion detection
pipe_needed_inputs = pipe.needed_inputs(visited_pipes=visited_pipes_with_current)
if sub_pipe.batch_params:
@@ -169,7 +176,7 @@ class PipeParallel(PipeController):
error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,
domain_code=self.domain_code,
pipe_code=self.code,
- )
+ ).with_params(declared=multiplicity_kind(multiplicity=self.output.multiplicity), expected=MethodOutputMultiplicityMismatchExpected.SINGLE)
output_concept = self.output.concept
if Concept.is_native_concept(concept=output_concept):
native_code = NativeConceptCode(output_concept.code)
@@ -185,7 +192,7 @@ class PipeParallel(PipeController):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=output_concept.concept_ref,
- )
+ ).with_params(declared=output_concept.concept_ref, expected=[NativeConceptCode.COMPOSITE.concept_ref], pipe_type=self.type)
@override
def validate_output_with_library(self):
@@ -211,7 +218,7 @@ class PipeParallel(PipeController):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
- ) from exc
+ ).with_params(declared=self.output.concept.concept_ref, expected=[NativeConceptCode.COMPOSITE.concept_ref], pipe_type=self.type) from exc
if issubclass(structure_class, CompositeContent):
return
@@ -233,7 +240,7 @@ class PipeParallel(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
variable_names=sorted(missing_required_fields),
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=[NativeConceptCode.COMPOSITE.concept_ref], pipe_type=self.type)
extraneous_result_names = result_names - declared_fields
if extraneous_result_names:
@@ -250,7 +257,7 @@ class PipeParallel(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
variable_names=sorted(extraneous_result_names),
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=[NativeConceptCode.COMPOSITE.concept_ref], pipe_type=self.type)
self._validate_branch_output_types(structure_class=structure_class)
@@ -280,7 +287,7 @@ class PipeParallel(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
variable_names=[result_name],
- )
+ ).with_params(input=result_name, site=MethodOptionalUnhandledSite.PARALLEL_BRANCH)
def analyze_branch_taint(self, *, visited_pipes: set[str] | None = None) -> ParallelTaintAnalysis:
"""Static taint over the branches (D6): which branch results are maybe-absent.
@@ -396,7 +403,7 @@ class PipeParallel(PipeController):
field_annotation = structure_class.model_fields[sub_pipe.output_name].annotation
if not isinstance(field_annotation, type) or not issubclass(field_annotation, StuffContent):
continue
- branch_pipe = get_required_pipe(pipe_code=sub_pipe.pipe_code)
+ branch_pipe = get_required_pipe(pipe_code=sub_pipe.pipe_code, referring_pipe_code=self.code)
if output_multiplicity_to_apply(
base_multiplicity=branch_pipe.output.multiplicity,
override_multiplicity=sub_pipe.output_multiplicity,
@@ -422,6 +429,8 @@ class PipeParallel(PipeController):
pipe_code=self.code,
provided_concept_code=branch_pipe.output.concept.concept_ref,
variable_names=[sub_pipe.output_name],
+ ).with_params(
+ declared=branch_pipe.output.concept.concept_ref, expected=_concepts_held_as(content_class=field_annotation), pipe_type=self.type
) from exc
if not issubclass(branch_structure_class, field_annotation):
msg = (
@@ -438,6 +447,8 @@ class PipeParallel(PipeController):
pipe_code=self.code,
provided_concept_code=branch_pipe.output.concept.concept_ref,
variable_names=[sub_pipe.output_name],
+ ).with_params(
+ declared=branch_pipe.output.concept.concept_ref, expected=_concepts_held_as(content_class=field_annotation), pipe_type=self.type
)
@override
@@ -500,16 +511,12 @@ class PipeParallel(PipeController):
output_stuff_contents: dict[str, StuffContent] = {}
for output_index, pipe_output in enumerate(pipe_outputs):
- sub_pipe_output_name = self.parallel_sub_pipes[output_index].output_name
- if not sub_pipe_output_name:
- sub_pipe_code = self.parallel_sub_pipes[output_index].pipe_code
- msg = f"PipeParallel '{self.code}': sub-pipe '{sub_pipe_code}' output name not specified"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
- if sub_pipe_output_name in seen_output_names:
- # TODO: check that at the blueprint / factory level
- sub_pipe_code = self.parallel_sub_pipes[output_index].pipe_code
- msg = f"PipeParallel '{self.code}': sub-pipe '{sub_pipe_code}' duplicate output name '{sub_pipe_output_name}'"
- raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ sub_pipe_output_name = branch_output_name(
+ pipe_code=self.code,
+ sub_pipe=self.parallel_sub_pipes[output_index],
+ seen_output_names=seen_output_names,
+ run_mode=pipe_run_params.run_mode,
+ )
seen_output_names.add(sub_pipe_output_name)
branch_resolved = pipe_output.working_memory.resolve_main_stuff()
if isinstance(branch_resolved, AbsenceRecord):
@@ -667,7 +674,7 @@ class PipeParallel(PipeController):
# Validate that all sub-pipes exist before dispatching the dry branches
for sub_pipe in self.parallel_sub_pipes:
try:
- get_required_pipe(pipe_code=sub_pipe.pipe_code)
+ get_required_pipe(pipe_code=sub_pipe.pipe_code, referring_pipe_code=self.code)
except PipeNotFoundError as exc:
msg = f"Dry run failed for pipe '{self.code}' (PipeParallel): sub-pipe '{sub_pipe.pipe_code}' not found"
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc
@@ -872,6 +879,33 @@ class PipeParallel(PipeController):
pass
+def branch_output_name(*, pipe_code: str, sub_pipe: SubPipe, seen_output_names: set[str], run_mode: PipeRunMode) -> str:
+ """The name a branch's output is combined under, refused when the branch names none or one an earlier branch took.
+
+ Args:
+ pipe_code: The parallel's code.
+ sub_pipe: The branch.
+ seen_output_names: The names the earlier branches' outputs took.
+ run_mode: The run's mode, which the refusal carries.
+
+ Raises:
+ PipeRunError: The branch names no output, or, under `method.name_conflict`, one an earlier branch took.
+ """
+ output_name = sub_pipe.output_name
+ if not output_name:
+ msg = f"PipeParallel '{pipe_code}': sub-pipe '{sub_pipe.pipe_code}' output name not specified"
+ raise PipeRunError(message=msg, run_mode=run_mode, pipe_code=pipe_code)
+ if output_name in seen_output_names:
+ # TODO: check that at the blueprint / factory level
+ msg = f"PipeParallel '{pipe_code}': sub-pipe '{sub_pipe.pipe_code}' duplicate output name '{output_name}'"
+ raise (
+ PipeRunError(message=msg, run_mode=run_mode, pipe_code=pipe_code)
+ .with_error_code(CoreCode.METHOD_NAME_CONFLICT)
+ .with_params(name=output_name, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
+ )
+ return output_name
+
+
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__
@@ -886,3 +920,8 @@ def _refused_field_names(*, exc: StuffFactoryError) -> set[str] | None:
return None
refused_fields.add(str(location[0]))
return refused_fields
+
+
+def _concepts_held_as(*, content_class: type[StuffContent]) -> list[str]:
+ """The refs of the concepts whose content is ``content_class``, those a field of that class holds as they are."""
+ return sorted(concept.concept_ref for concept in get_concept_library().list_concepts() if concept.structure_class_name == content_class.__name__)
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.py
index cd47a4b58..f9906312d 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py
@@ -1,6 +1,7 @@
import sys
from typing import TYPE_CHECKING, Literal
+from mthds.protocol.problem.registry import MethodOptionalUnhandledSite
from pydantic import PrivateAttr, field_validator
from typing_extensions import override
@@ -12,7 +13,13 @@ 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.pipes.stuff_spec.stuff_spec import StuffSpec
-from pipelex.core.pipes.variable_multiplicity import PresenceMarker, VariableMultiplicity, is_multiple_multiplicity, is_multiplicity_compatible
+from pipelex.core.pipes.variable_multiplicity import (
+ PresenceMarker,
+ VariableMultiplicity,
+ is_multiple_multiplicity,
+ is_multiplicity_compatible,
+ multiplicity_kind,
+)
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff import Stuff
@@ -239,7 +246,7 @@ class PipeSequence(PipeController):
if sub_pipe is None:
continue
else:
- sub_pipe = get_required_pipe(pipe_code=sequential_sub_pipe.pipe_code)
+ sub_pipe = get_required_pipe(pipe_code=sequential_sub_pipe.pipe_code, referring_pipe_code=self.code)
# Use the centralized recursion detection
sub_pipe_needed_inputs = sub_pipe.needed_inputs(visited_pipes=visited_pipes_with_current)
@@ -472,6 +479,10 @@ class PipeSequence(PipeController):
pipe_code=self.code,
provided_concept_code=bound_spec.concept.concept_ref,
required_concept_codes=[step_pipe.output.concept.concept_ref],
+ ).with_params(
+ pipe=step_pipe.code,
+ declared=multiplicity_kind(multiplicity=bound_spec.multiplicity),
+ expected=multiplicity_kind(multiplicity=requested_multiplicity),
)
def _render_spec(self, *, stuff_spec: StuffSpec) -> str:
@@ -538,6 +549,11 @@ class PipeSequence(PipeController):
variable_names=[variable_name],
provided_concept_code=unreadable_specs[0].concept.concept_ref,
required_concept_codes=[needed_spec.concept.concept_ref],
+ ).with_params(
+ pipe=step_pipe_code,
+ input=variable_name,
+ declared=needed_ref,
+ expected=sorted({self._render_spec(stuff_spec=unreadable_spec) for unreadable_spec in unreadable_specs}),
)
if self._is_readable_as(provided_spec=provided_spec, needed_spec=needed_spec, is_stored_by_pipe_step=slot.is_stored_by_pipe_step):
return None
@@ -562,7 +578,7 @@ class PipeSequence(PipeController):
variable_names=[variable_name],
provided_concept_code=provided_spec.concept.concept_ref,
required_concept_codes=[needed_spec.concept.concept_ref],
- )
+ ).with_params(pipe=step_pipe_code, input=variable_name, declared=needed_ref, expected=[provided_ref])
@classmethod
def _is_readable_as(cls, *, provided_spec: StuffSpec, needed_spec: StuffSpec, is_stored_by_pipe_step: bool) -> bool:
@@ -648,6 +664,10 @@ class PipeSequence(PipeController):
pipe_code=self.code,
variable_names=[list_label],
provided_concept_code=stored_spec.concept.concept_ref,
+ ).with_params(
+ input=list_label,
+ declared=stored_ref,
+ expected=[self._render_spec(stuff_spec=StuffSpec(concept=stored_spec.concept, multiplicity=True))],
)
if item_need is None or item_need.concept.code in {NativeConceptCode.DYNAMIC, NativeConceptCode.ANYTHING}:
continue
@@ -671,7 +691,7 @@ class PipeSequence(PipeController):
variable_names=[item_name],
provided_concept_code=stored_spec.concept.concept_ref,
required_concept_codes=[item_need.concept.concept_ref],
- )
+ ).with_params(pipe=step_pipe_code, input=item_name, declared=needed_ref, expected=[item_ref])
return None
@override
@@ -711,7 +731,7 @@ class PipeSequence(PipeController):
# Skip output validation if the last step is an unresolved cross-package ref
if QualifiedRef.has_cross_package_prefix(last_step_pipe_code) and get_optional_pipe(pipe_code=last_step_pipe_code) is None:
return
- last_step_pipe = get_required_pipe(pipe_code=last_step_pipe_code)
+ last_step_pipe = get_required_pipe(pipe_code=last_step_pipe_code, referring_pipe_code=self.code)
last_step_concept = last_step_pipe.output.concept
last_step_label = f" '{last_step_pipe.code}'"
# What the step stores under its result, resolved exactly the way the run path and the typed flow resolve it
@@ -757,7 +777,7 @@ class PipeSequence(PipeController):
provided_concept_code=last_step_concept.concept_ref,
required_concept_codes=[self.output.concept.concept_ref],
expected_output_ref=expected_output_ref,
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=[last_step_concept.concept_ref], pipe_type=self.type)
# Check multiplicity compatibility
if not is_multiplicity_compatible(
@@ -778,6 +798,9 @@ class PipeSequence(PipeController):
provided_concept_code=last_step_concept.concept_ref,
required_concept_codes=[self.output.concept.concept_ref],
expected_output_ref=expected_output_ref,
+ ).with_params(
+ declared=multiplicity_kind(multiplicity=self.output.multiplicity),
+ expected=multiplicity_kind(multiplicity=effective_last_step_output_multiplicity),
)
self._refuse_escaping_absence(taint_analysis=taint_analysis)
@@ -801,7 +824,7 @@ class PipeSequence(PipeController):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
variable_names=[taint_analysis.output_taint.origin_slot_name],
- )
+ ).with_params(input=taint_analysis.output_taint.origin_slot_name, site=MethodOptionalUnhandledSite.SEQUENCE_STEP)
def analyze_taint(self) -> SequenceTaintAnalysis:
"""Static absence-taint walk over the steps (D6), computing per-slot presence.
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence_blueprint.py b/pipelex/pipe_controllers/sequence/pipe_sequence_blueprint.py
index 04061de42..a0c7ec4c3 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence_blueprint.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence_blueprint.py
@@ -15,6 +15,10 @@ from pipelex.pipe_machinery.pipe_blueprint import PipeBlueprint
_PIPE_STEP_TAG = "pipe_step"
_BINDING_STEP_TAG = "binding_step"
+# The tags of a sequence step's shapes, which pydantic puts in the location of an error inside a step
+# (`pipe.run_all.PipeSequence.steps.0.pipe_step.batch_as`) though the author never writes them.
+SEQUENCE_STEP_TAGS = frozenset({_PIPE_STEP_TAG, _BINDING_STEP_TAG})
+
def _sequence_step_kind(step: Any) -> str: # kw-only: ignore
"""Which shape a sequence step takes: a binding step when it carries `from`, a pipe step otherwise."""
diff --git a/pipelex/pipe_controllers/sequence/sequence_typed_flow.py b/pipelex/pipe_controllers/sequence/sequence_typed_flow.py
index 11efb1252..d099f869a 100644
--- a/pipelex/pipe_controllers/sequence/sequence_typed_flow.py
+++ b/pipelex/pipe_controllers/sequence/sequence_typed_flow.py
@@ -218,7 +218,7 @@ def binding_path_unresolved_error(
domain_code=domain_code,
pipe_code=sequence_code,
variable_names=[binding_step.from_path],
- )
+ ).with_params(path=exc.path, segment=exc.failed_segment, available_fields=exc.available_fields)
def derive_binding_spec(*, binding_step: BindingStep, root_spec: StuffSpec, sequence_code: str, domain_code: str) -> DerivedBinding:
diff --git a/pipelex/pipe_controllers/sub_pipe.py b/pipelex/pipe_controllers/sub_pipe.py
index 7aad696a5..0cb53a428 100644
--- a/pipelex/pipe_controllers/sub_pipe.py
+++ b/pipelex/pipe_controllers/sub_pipe.py
@@ -84,7 +84,7 @@ class SubPipe(BaseModel):
if self.output_multiplicity is not None:
sub_pipe_run_params.output_multiplicity = self.output_multiplicity
- sub_pipe = get_required_pipe(pipe_code=self.pipe_code)
+ sub_pipe = get_required_pipe(pipe_code=self.pipe_code, referring_pipe_code=calling_pipe_code)
# Case 1: Batch processing
if batch_params := self.batch_params:
diff --git a/pipelex/pipe_controllers/sub_pipe_blueprint.py b/pipelex/pipe_controllers/sub_pipe_blueprint.py
index c39a8a2aa..7a867a3e5 100644
--- a/pipelex/pipe_controllers/sub_pipe_blueprint.py
+++ b/pipelex/pipe_controllers/sub_pipe_blueprint.py
@@ -64,6 +64,8 @@ class SubPipeBlueprint(BaseModel):
raise PipeValidationError(
message=msg,
error_type=PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION,
+ variable_names=[self.batch_as],
+ field_name="batch_as",
)
return self
diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.py
index df16b118c..129a95baf 100644
--- a/pipelex/pipe_machinery/pipe_abstract.py
+++ b/pipelex/pipe_machinery/pipe_abstract.py
@@ -482,7 +482,7 @@ class PipeAbstract(ABC, BaseModel):
variable_names=[var_name],
expected_inputs=self._expected_inputs_for_fix(the_needed_inputs),
declared_inputs=self._declared_inputs_for_fix(),
- )
+ ).with_params(input=var_name, declared=declared_ref, expected=[required_ref])
# Check that all declared inputs are actually needed
for input_name in self.inputs.variables:
diff --git a/pipelex/pipe_machinery/rendering/output_renderer.py b/pipelex/pipe_machinery/rendering/output_renderer.py
index 61dd72d94..f900b65aa 100644
--- a/pipelex/pipe_machinery/rendering/output_renderer.py
+++ b/pipelex/pipe_machinery/rendering/output_renderer.py
@@ -54,7 +54,7 @@ def _collect_possible_outputs(
concept_provider = get_concept_library()
# pipe_dependencies() is a set — sort so the user-facing output_option_N numbering is deterministic
for mapped_pipe_code in sorted(mapped_pipe_codes):
- mapped_pipe = get_required_pipe(pipe_code=mapped_pipe_code)
+ mapped_pipe = get_required_pipe(pipe_code=mapped_pipe_code, referring_pipe_code=the_pipe.code)
try:
output_dict = mapped_pipe.output.render_stuff_spec(concept_provider=concept_provider, output_format=output_format)
content = output_dict.get("content", output_dict)
@@ -105,7 +105,7 @@ def _collect_possible_outputs(
if not last_pipe_code:
return []
- last_pipe = get_required_pipe(pipe_code=last_pipe_code)
+ last_pipe = get_required_pipe(pipe_code=last_pipe_code, referring_pipe_code=the_pipe.code)
# If last pipe also has Anything output, recurse
if last_pipe.output.concept.code == NativeConceptCode.ANYTHING:
diff --git a/pipelex/pipe_machinery/template_guard_lint.py b/pipelex/pipe_machinery/template_guard_lint.py
index accfdfbf9..cdea49ad5 100644
--- a/pipelex/pipe_machinery/template_guard_lint.py
+++ b/pipelex/pipe_machinery/template_guard_lint.py
@@ -10,6 +10,8 @@ PipeJudge questions, PipeCondition expressions):
located error.
"""
+from mthds.protocol.problem.registry import MethodOptionalUnhandledSite
+
from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigils
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.core.pipes.inputs.input_stuff_specs import InputStuffSpecs
@@ -115,7 +117,7 @@ def lint_optional_input_guards(
pipe_code=pipe_code,
variable_names=[finding.variable_name],
explanation=f"Unguarded reference '{finding.path}' to optional input '{finding.variable_name}' in the {template_label}.",
- )
+ ).with_params(input=finding.variable_name, site=MethodOptionalUnhandledSite.TEMPLATE)
def lint_template_private_names(
@@ -165,5 +167,6 @@ def lint_template_private_names(
error_type=PipeValidationErrorType.TEMPLATE_PRIVATE_NAME,
domain_code=domain_code,
pipe_code=pipe_code,
+ variable_names=list(refused_names),
explanation=f"The {template_label} reads the private name '{refused_name}'.",
)
diff --git a/pipelex/pipe_operators/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index 3cc0747d3..09ba0bb2b 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -27,6 +27,7 @@ from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.runtime_hub import get_class_registry
from pipelex.system.job_metadata import JobMetadata
from pipelex.tools.jinja2.exceptions import Jinja2DetectVariablesError
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.jinja2.jinja2_required_variables import detect_jinja2_required_variables
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
@@ -43,6 +44,10 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
# Template mode fields (used when template is provided)
template: str | None = None
+ # The key of the pipe's table holding the template's source, which a refusal its render meets is located on:
+ # `template.template` when the template is a table of its own. None in construct mode, whose fields each locate their
+ # own refusals (`construct.<path>`), and on a pipe built without its blueprint, whose template is the plain string.
+ template_field: str | None = None
templating_style: TemplatingStyle | None = None
category: TemplateCategory = Field(default=TemplateCategory.BASIC, strict=False)
extra_context: dict[str, Any] | None = None
@@ -164,6 +169,10 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
required_concept_codes=[NativeConceptCode.TEXT.concept_ref, NativeConceptCode.HTML.concept_ref],
+ ).with_params(
+ declared=self.output.concept.concept_ref,
+ expected=[NativeConceptCode.TEXT.concept_ref, NativeConceptCode.HTML.concept_ref],
+ pipe_type=self.type,
)
@override
@@ -210,17 +219,18 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
name=self.output.concept.structure_class_name,
base_class=StuffContent,
)
- compose_result = await run_compose_template(
- memory=working_memory,
- template=self.template,
- category=self.category,
- concept=self.output.concept,
- output_class=structure_class,
- templating_style=resolve_templating_style(authored=self.templating_style),
- runtime_params=pipe_run_params.params,
- extra_context=self.extra_context,
- result_name=output_name,
- )
+ with locating_template_refusal(template_field=self.template_field or "template"):
+ compose_result = await run_compose_template(
+ memory=working_memory,
+ template=self.template,
+ category=self.category,
+ concept=self.output.concept,
+ output_class=structure_class,
+ templating_style=resolve_templating_style(authored=self.templating_style),
+ runtime_params=pipe_run_params.params,
+ extra_context=self.extra_context,
+ result_name=output_name,
+ )
working_memory = compose_result.memory
# Capture execution data for the graph tracer
diff --git a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
index 4b915d6a2..f0f8c9de7 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_blueprint.py
@@ -69,6 +69,19 @@ class PipeComposeBlueprint(PipeBlueprint):
return self.template.template
return self.template
+ @property
+ def template_field(self) -> str | None:
+ """The key of the pipe's table that holds the template's source.
+
+ It is `template`, or `template.template` when the template is a table of its own; None in construct mode, whose
+ fields each hold their own (`construct.<path>`).
+ """
+ if self.template is None:
+ return None
+ if isinstance(self.template, TemplateBlueprint):
+ return "template.template"
+ return "template"
+
@property
def template_category(self) -> TemplateCategory:
"""Get the template category (only relevant in template mode)."""
diff --git a/pipelex/pipe_operators/compose/pipe_compose_factory.py b/pipelex/pipe_operators/compose/pipe_compose_factory.py
index c5c829de4..113e1ed46 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_factory.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_factory.py
@@ -92,6 +92,7 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
inputs=inputs,
output=output,
template=template_source,
+ template_field=blueprint.template_field,
templating_style=blueprint.templating_style,
category=blueprint.template_category,
extra_context=blueprint.extra_context,
diff --git a/pipelex/pipe_operators/compose/structured_content_composer.py b/pipelex/pipe_operators/compose/structured_content_composer.py
index 1a9ea95ce..09c6e945b 100644
--- a/pipelex/pipe_operators/compose/structured_content_composer.py
+++ b/pipelex/pipe_operators/compose/structured_content_composer.py
@@ -22,6 +22,8 @@ from pipelex.pipe_operators.compose.exceptions import (
StructuredContentComposerValidationError,
StructuredContentComposerValueError,
)
+from pipelex.tools.jinja2.exceptions import Jinja2TemplateSecurityError
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.misc.string_utils import find_private_path_segment
from pipelex.tools.templating.templating_style import TemplatingStyle
@@ -174,12 +176,20 @@ class StructuredContentComposer:
return self._resolve_from_var(field_blueprint=field_blueprint, field_name=field_name)
case ConstructFieldMethod.TEMPLATE:
- rendered_text = await self._resolve_template(field_blueprint=field_blueprint)
+ with locating_template_refusal(template_field=f"construct.{field_name}"):
+ rendered_text = await self._resolve_template(field_blueprint=field_blueprint)
self.field_resolutions[field_name]["rendered"] = rendered_text
return rendered_text
case ConstructFieldMethod.NESTED:
- return await self._resolve_nested(field_blueprint=field_blueprint, field_name=field_name)
+ try:
+ return await self._resolve_nested(field_blueprint=field_blueprint, field_name=field_name)
+ except Jinja2TemplateSecurityError as exc:
+ # The nested composer located the refusal on its own field: the path from this construct's root
+ # runs through this field.
+ if exc.template_field is not None and exc.template_field.startswith("construct."):
+ exc.with_template_field(template_field=f"construct.{field_name}.{exc.template_field.removeprefix('construct.')}")
+ raise
def _resolve_from_var(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> Any:
"""Resolve a FROM_VAR field by getting value from working memory.
diff --git a/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py b/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py
index 6547add83..46c76281a 100644
--- a/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py
+++ b/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py
@@ -15,7 +15,7 @@ from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigil
from pipelex.cogt.templating.template_rendering import render_template
from pipelex.pipe_operators.doc_gen.exceptions import PipeDocGenRunError, PipeDocGenUndefinedValueError
from pipelex.tools.jinja2.exceptions import Jinja2TemplateInvalidError, Jinja2TemplateRenderError
-from pipelex.tools.jinja2.jinja2_rendering import template_line_of, undefined_variable_name
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal, template_line_of, undefined_variable_name
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.templating.templating_style import TemplatingStyle
@@ -27,22 +27,28 @@ async def render_doc_gen_template(
category: TemplateCategory,
context: dict[str, Any],
label: str,
+ template_field: str,
templating_style: TemplatingStyle | None = None,
) -> str:
"""A template of the step `pipe_code` rendered with `context`, every value it reads required to exist.
+ `template_field` is the field of the step the template is written in, `filename`, `template` or `template_file`,
+ which a refusal of the template sandbox is located on.
+
Raises:
PipeDocGenUndefinedValueError: The template reads a value that does not exist.
PipeDocGenRunError: The template could not be rendered for another reason.
+ Jinja2TemplateSecurityError: The template sandbox refused what the template reached for.
"""
try:
- return await render_template(
- template=template,
- category=category,
- context=context,
- templating_style=templating_style,
- is_undefined_strict=True,
- )
+ with locating_template_refusal(template_field=template_field):
+ return await render_template(
+ template=template,
+ category=category,
+ context=context,
+ templating_style=templating_style,
+ is_undefined_strict=True,
+ )
except Jinja2TemplateInvalidError as exc:
if not exc.template_owner.is_method:
# One of Pipelex's own templates, reached from the method's render: ours, kept as it is.
diff --git a/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py b/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py
index bacdee192..cf13555cc 100644
--- a/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py
+++ b/pipelex/pipe_operators/doc_gen/pipe_doc_gen.py
@@ -235,10 +235,23 @@ class PipeDocGen(PipeOperator[PipeDocGenOutput]):
return humanize(self.code)
async def _render(
- self, *, template: str, category: TemplateCategory, context: dict[str, Any], label: str, templating_style: TemplatingStyle | None = None
+ self,
+ *,
+ template: str,
+ category: TemplateCategory,
+ context: dict[str, Any],
+ label: str,
+ template_field: str,
+ templating_style: TemplatingStyle | None = None,
) -> str:
return await render_doc_gen_template(
- pipe_code=self.code, template=template, category=category, context=context, label=label, templating_style=templating_style
+ pipe_code=self.code,
+ template=template,
+ category=category,
+ context=context,
+ label=label,
+ template_field=template_field,
+ templating_style=templating_style,
)
async def compose(self, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams) -> DocumentComposition:
@@ -258,6 +271,7 @@ class PipeDocGen(PipeOperator[PipeDocGenOutput]):
category=TemplateCategory.BASIC,
context=context,
label="filename",
+ template_field="filename",
templating_style=resolve_templating_style(authored=None),
)
# Stored under a name every `pipelex-storage://` reader serves, the hosted platform's included.
@@ -281,6 +295,7 @@ class PipeDocGen(PipeOperator[PipeDocGenOutput]):
category=TemplateCategory.HTML,
context=context,
label="template",
+ template_field="template",
templating_style=resolve_templating_style(authored=None),
)
return DocumentComposition(
diff --git a/pipelex/pipe_operators/doc_gen/template_file_stage.py b/pipelex/pipe_operators/doc_gen/template_file_stage.py
index f914581b7..1e2725de9 100644
--- a/pipelex/pipe_operators/doc_gen/template_file_stage.py
+++ b/pipelex/pipe_operators/doc_gen/template_file_stage.py
@@ -170,6 +170,7 @@ class DocGenTemplateFileStage(TemplateFileStageProtocol):
category=TemplateCategory.HTML,
context=context,
label=f"template file '{template_file.name}'",
+ template_field="template_file",
templating_style=resolve_templating_style(authored=None),
)
diff --git a/pipelex/pipe_operators/extract/pipe_extract.py b/pipelex/pipe_operators/extract/pipe_extract.py
index 527c484ba..7defb0263 100644
--- a/pipelex/pipe_operators/extract/pipe_extract.py
+++ b/pipelex/pipe_operators/extract/pipe_extract.py
@@ -99,7 +99,7 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
required_concept_codes=[NativeConceptCode.PAGE.concept_ref],
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=[NativeConceptCode.PAGE.concept_ref], pipe_type=self.type)
@override
async def _live_run_operator_pipe(
diff --git a/pipelex/pipe_operators/func/direct_pipe_func_executor.py b/pipelex/pipe_operators/func/direct_pipe_func_executor.py
index e311b8b69..22fee5f2c 100644
--- a/pipelex/pipe_operators/func/direct_pipe_func_executor.py
+++ b/pipelex/pipe_operators/func/direct_pipe_func_executor.py
@@ -220,7 +220,11 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):
)
except TimeoutError as exc:
msg = f"PipeFunc '{request.function_name}' exceeded its {request.timeout_seconds}s timeout"
- raise PipeFuncExecutionError(msg).with_error_code(CoreCode.PIPE_FUNCTION_TIMED_OUT) from exc
+ raise (
+ PipeFuncExecutionError(msg)
+ .with_error_code(CoreCode.PIPE_FUNCTION_TIMED_OUT)
+ .with_params(function=request.function_name, timeout=request.timeout_seconds)
+ ) from exc
# Wrap the output in a memory so it round-trips with its concept (and thus its class identity).
pipe = get_library_manager().get_library(library_id=TRANSPORTED_LIBRARY_ID).pipe_library.get_required_pipe(pipe_code=request.pipe_code)
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index 6e7b52bdc..4e40ba539 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -151,7 +151,7 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
required_concept_codes=[NativeConceptCode.IMAGE.concept_ref],
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=[NativeConceptCode.IMAGE.concept_ref], pipe_type=self.type)
@override
async def _live_run_operator_pipe(
diff --git a/pipelex/pipe_operators/judge/pipe_judge.py b/pipelex/pipe_operators/judge/pipe_judge.py
index 6a768ed8f..87da953bd 100644
--- a/pipelex/pipe_operators/judge/pipe_judge.py
+++ b/pipelex/pipe_operators/judge/pipe_judge.py
@@ -189,13 +189,20 @@ class PipeJudge(PipeOperator[PipeJudgeOutput]):
f"PipeJudge '{self.code}' reads {quoted_paths} in its {question_label}, which is an image or a document, and only the "
"prompt presents files to the judging model: read it in `prompt`, and ask about it in the question."
)
+ # The code names the step's input, the root of the path the question reads, and the concept it declares.
+ # No `expected` is given: no concept of an input lets a question present a file, which the code cannot yet say.
+ input_name = get_root_from_dotted_path(question_file_paths[0])
+ input_params: dict[str, str] = {"input": input_name}
+ declared_spec = self.inputs.root.get(input_name)
+ if declared_spec is not None:
+ input_params["declared"] = declared_spec.concept.concept_ref
raise PipeValidationError(
message=msg,
error_type=PipeValidationErrorType.INPUT_STUFF_SPEC_MISMATCH,
domain_code=self.domain_code,
pipe_code=self.code,
variable_names=question_file_paths,
- )
+ ).with_params(**input_params)
# Template lints: no private names, and every reference to a declared-optional input guarded (D7).
labelled_templates = [(self.prompt_content.template, "prompt")]
@@ -370,6 +377,7 @@ class PipeJudge(PipeOperator[PipeJudgeOutput]):
raise self._inadequate_output_error(message=msg, required_concept_codes=[verdict_native.concept_ref])
def _inadequate_output_error(self, *, message: str, required_concept_codes: list[str] | None = None) -> PipeValidationError:
+ # A refusal of the output's structure, rather than of its concept, has no concepts to offer as the ones that fit.
return PipeValidationError(
message=message,
error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,
@@ -377,7 +385,7 @@ class PipeJudge(PipeOperator[PipeJudgeOutput]):
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
required_concept_codes=required_concept_codes,
- )
+ ).with_params(declared=self.output.concept.concept_ref, expected=required_concept_codes, pipe_type=self.type)
@override
async def _live_run_operator_pipe(
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index 47b524eb4..4017b91a5 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -157,7 +157,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
- )
+ ).with_params(declared=self.output.concept.concept_ref, pipe_type=self.type)
self._refuse_a_setting_its_model_refuses(is_dynamic_output=is_dynamic_output)
diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.py
index c20336d37..606276f51 100644
--- a/pipelex/pipe_operators/search/pipe_search.py
+++ b/pipelex/pipe_operators/search/pipe_search.py
@@ -15,6 +15,7 @@ from pipelex.pipe_machinery.template_guard_lint import lint_authored_template
from pipelex.pipe_operators.pipe_operator import PipeOperator
from pipelex.pipe_run.pipe_run_params import PipeRunParams
from pipelex.system.job_metadata import JobMetadata
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal
from pipelex.tools.misc.string_utils import get_root_from_dotted_path
if TYPE_CHECKING:
@@ -99,24 +100,25 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
if self.is_structured_output:
output_structure_class = get_concept_library().get_structure_class(concept=self.output.concept)
- search_result = await run_search(
- memory=working_memory,
- template=self.prompt_blueprint.template,
- category=self.prompt_blueprint.category,
- search_setting=search_setting,
- concept=self.output.concept,
- job_metadata=job_metadata,
- cogt_run_params=pipe_run_params.cogt_run_params,
- # No authored style on this operator: a query template takes the runtime default, the
- # same one an LLM pipe that declares nothing gets.
- templating_style=resolve_templating_style(authored=None),
- output_structure_class=output_structure_class,
- include_domains=self.include_domains,
- exclude_domains=self.exclude_domains,
- from_date=self.from_date,
- to_date=self.to_date,
- result_name=output_name,
- )
+ with locating_template_refusal(template_field="prompt"):
+ search_result = await run_search(
+ memory=working_memory,
+ template=self.prompt_blueprint.template,
+ category=self.prompt_blueprint.category,
+ search_setting=search_setting,
+ concept=self.output.concept,
+ job_metadata=job_metadata,
+ cogt_run_params=pipe_run_params.cogt_run_params,
+ # No authored style on this operator: a query template takes the runtime default, the
+ # same one an LLM pipe that declares nothing gets.
+ templating_style=resolve_templating_style(authored=None),
+ output_structure_class=output_structure_class,
+ include_domains=self.include_domains,
+ exclude_domains=self.exclude_domains,
+ from_date=self.from_date,
+ to_date=self.to_date,
+ result_name=output_name,
+ )
working_memory = search_result.memory
# Capture execution data for the graph tracer
diff --git a/pipelex/pipe_operators/shared/llm_setting_check.py b/pipelex/pipe_operators/shared/llm_setting_check.py
index 2d347ae5d..c950ee306 100644
--- a/pipelex/pipe_operators/shared/llm_setting_check.py
+++ b/pipelex/pipe_operators/shared/llm_setting_check.py
@@ -71,4 +71,4 @@ def refuse_llm_setting_its_model_refuses(
pipe_code=pipe_code,
field_name=field_name,
model_reference=model_reference,
- ) from refusal
+ ).with_params(model=model_reference or llm_setting.model, capability=refusal.caller_params().get("capability")) from refusal
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index 4829e1b40..7b004c166 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -74,7 +74,7 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=the_single_input.concept.concept_ref,
- )
+ ).with_params(input=next(iter(self.inputs.root)), declared=the_single_input.concept.concept_ref, expected=[text_concept.concept_ref])
@override
def validate_output_static(self):
@@ -95,7 +95,7 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
domain_code=self.domain_code,
pipe_code=self.code,
provided_concept_code=self.output.concept.concept_ref,
- )
+ ).with_params(declared=self.output.concept.concept_ref, pipe_type=self.type)
# A reference the deck does not define is refused when the pipe is built, so it is not looked up again here
try:
diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.py
index b5e3f104e..ab2034318 100644
--- a/pipelex/pipe_run/delivery_executor.py
+++ b/pipelex/pipe_run/delivery_executor.py
@@ -39,6 +39,7 @@ if TYPE_CHECKING:
from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment, DeliveryStatus, StorageTarget, WebhookTarget
+ from pipelex.tools.storage.storage_provider_abstract import StorageKind
class ResultFile(NamedTuple):
@@ -454,8 +455,10 @@ class DeliveryExecutor:
appears in the key; it stays a parameter because the failure below
names it.
"""
+ storage_kind: StorageKind | None = None
try:
storage_provider = get_storage_provider()
+ storage_kind = storage_provider.storage_kind
prefix: str = storage.key_prefix or ""
base_key: str = f"{storage_scope}/{prefix}results"
@@ -474,7 +477,12 @@ class DeliveryExecutor:
except Exception as exc:
# Delivery boundary: any failure across result-file generation or storage is converted to StorageDeliveryError. Re-raises, never swallows.
msg = f"Storage delivery failed for pipeline_run_id={pipeline_run_id}"
- raise StorageDeliveryError(msg) from exc
+ # The storage's kind is what `pipelex.storage.unavailable`, the fallback of an uncoded cause, names; a coded
+ # cause that names its own keeps it.
+ delivery_error = StorageDeliveryError(msg)
+ if storage_kind is not None:
+ delivery_error = delivery_error.with_params(scheme=storage_kind)
+ raise delivery_error from exc
# ---- Webhooks ----
diff --git a/pipelex/pipeline/dry_run_pipeline.py b/pipelex/pipeline/dry_run_pipeline.py
index bb9aa8877..e9db2ce1a 100644
--- a/pipelex/pipeline/dry_run_pipeline.py
+++ b/pipelex/pipeline/dry_run_pipeline.py
@@ -16,6 +16,7 @@ from mthds.protocol.problem.registry import CoreCode
from pipelex.base_exceptions import PipelexUnexpectedError
from pipelex.config import get_config
from pipelex.graph.graphspec import GraphSpec
+from pipelex.libraries.pipe.pipe_suggestions import declared_pipe_refs
from pipelex.mthds_parsing.exceptions import MthdsParserError
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipe_run.exceptions import DryRunGraphNotProducedError
@@ -74,7 +75,9 @@ async def dry_run_pipeline(
if not pipe_ref:
msg = "Bundle does not declare a main_pipe, cannot generate graph"
- raise MthdsParserError(msg).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED)
+ # With no entry pipe to start from, the request may select any pipe the bundles declare.
+ candidates = declared_pipe_refs(blueprints=blueprints)
+ raise MthdsParserError(msg).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED).with_params(candidates=candidates)
execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(
generate_graph=True,
diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.py
index 04ef048ff..44bcc0590 100644
--- a/pipelex/pipeline/exceptions.py
+++ b/pipelex/pipeline/exceptions.py
@@ -3,10 +3,10 @@ from collections.abc import Collection
from typing import Any, ClassVar, NamedTuple, Self, TypeVar, cast
from mthds.protocol.problem.models import ProblemItem, ProblemLocation
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from typing_extensions import override
-from pipelex.base_exceptions import PipelexError, ValidationErrorItem
+from pipelex.base_exceptions import PipelexError, ValidationErrorItem, iter_pipelex_cause_chain
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.core.exceptions import (
DryRunFailureErrorData,
@@ -16,7 +16,7 @@ from pipelex.core.exceptions import (
)
from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, ErrorCodeSet, InheritsCause
from pipelex.errors.error_codes import ErrorCode, code_is_method_domain
-from pipelex.errors.problem import PipelexProblem, ProblemView
+from pipelex.errors.problem import PipelexProblem, ProblemView, make_location
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.pipe_run.exceptions import find_failure_location
from pipelex.pipe_run.located_failure import failure_location_of, locate_failure_message, located_problem, located_root_fault
@@ -217,18 +217,30 @@ class _FileWithholding(NamedTuple):
names, reads the placeholder too.
"""
withheld: list[_SourcedErrorData] = []
- for error in errors:
+ for error in self._without_withheld_restatements(errors=errors):
update: dict[str, Any] = {
"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"] = ""
- if isinstance(error, DryRunFailureErrorData) and error.params:
+ if error.params:
update["params"] = self.withheld_params(params=error.params)
withheld.append(error.model_copy(update=update))
return withheld
+ def _without_withheld_restatements(self, *, errors: list[_SourcedErrorData]) -> list[_SourcedErrorData]:
+ """The errors without those located in a withheld file that restate a name conflict another error locates elsewhere.
+
+ A name declared twice is one error per file declaring it (``duplicate_ref_items``). When one of those files is
+ withheld, its error would be located nowhere and name the other declaration, which the error located in the
+ caller's own file already names: the caller reads that one alone.
+ """
+ located_conflicts = {
+ conflict_name for error in errors if error.source not in self.names and (conflict_name := _duplicate_declaration_name(error=error))
+ }
+ return [error for error in errors if error.source not in self.names or _duplicate_declaration_name(error=error) not in located_conflicts]
+
def withheld_params(self, *, params: dict[str, Any]) -> dict[str, Any]:
"""Parameters reading the placeholder where a text of them named a withheld file."""
return {name: self._withheld_value(value=value) for name, value in params.items()}
@@ -248,6 +260,18 @@ class _FileWithholding(NamedTuple):
return value
+def _duplicate_declaration_name(*, error: _SourcedErrorData) -> str | None:
+ """The name an error reports declared twice, when it is a ``method.name_conflict`` of a duplicate declaration."""
+ if not error.params:
+ return None
+ match error.params.get("conflict"):
+ case MethodNameConflictConflict.DUPLICATE_DECLARATION:
+ name = error.params.get("name")
+ return name if isinstance(name, str) else None
+ case _:
+ return None
+
+
def withhold_names_in_text(*, text: str, names: Collection[str], placeholder: str) -> str:
"""``text`` reading ``placeholder`` where it named one of ``names`` standing on its own, never inside a longer name.
@@ -346,8 +370,9 @@ class ValidateBundleError(PipelexError):
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
+ never inside a longer name. An item of a withheld file restating a name conflict an item located elsewhere
+ reports is left out, as it would be located nowhere. 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. So is what the raise site chose
after building it: the code it chose (:meth:`with_error_code`), and the parameters and items it gave
(:meth:`with_params`, :meth:`with_items`), withheld as the messages are. The new verdict keeps the withholding,
@@ -435,19 +460,22 @@ class ValidateBundleError(PipelexError):
"""Each of :meth:`validation_error_items` with its code: a dry run's the failure's, any other its type's.
An item no stage classified takes the code of the refusal this verdict was built from when that refusal is
- the method's, and ``method.schema_violation`` otherwise, or when that code is ``method.invalid``: the verdict's
- own umbrella, whose sentence says nothing of the item.
+ the method's, and ``method.schema_violation`` otherwise. A refusal under ``method.invalid``, the verdict's own
+ umbrella, whose sentence says nothing of the item, is read through to the error it was raised from: a library
+ that could not load a bundle forwards the parser's refusal of its syntax that way.
"""
residual_code: ErrorCode = CoreCode.METHOD_SCHEMA_VIOLATION
# The parameters the refusal's code renders from, as a caller reads them, which an item taking its code keeps.
residual_params: dict[str, Any] | None = None
cause = self.__cause__
- if isinstance(cause, PipelexError):
- cause_code = cause.resolve_error_code()
- if code_is_method_domain(code=cause_code) and cause_code not in _VERDICT_UMBRELLA_CODES:
- residual_code = cause_code
- cause_params = cause.to_problem(view=ProblemView.CALLER).params
- residual_params = cause_params.as_wire() if cause_params is not None else None
+ for refusal in iter_pipelex_cause_chain(cause) if cause is not None else ():
+ refusal_code = refusal.resolve_error_code()
+ if refusal_code in _VERDICT_UMBRELLA_CODES:
+ continue
+ if code_is_method_domain(code=refusal_code):
+ residual_code = refusal_code
+ residual_params = refusal.caller_params() or None
+ break
dry_run_failures = iter(self.dry_run_failures)
coded_items: list[tuple[ValidationErrorItem, ValidationItemCode]] = []
for item in self.validation_error_items():
@@ -466,6 +494,16 @@ class ValidateBundleError(PipelexError):
return coded_items
+class TreePythonSyntaxError(PipelexError):
+ """A Python file of a method's tree that is not UTF-8 text or does not parse, found when the tree is validated.
+
+ It is the cause of the invalid verdict the validation raises, one item per such file, so each item takes its code,
+ ``method.syntax``, with its own ``finding``; the error's own parameters describe the first file.
+ """
+
+ error_code = CoreCode.METHOD_SYNTAX
+
+
class HostLibraryLoadRefusalError(PipelexError):
"""A method of this host's own library directories refused to load: the deployment's fault, never the caller's input.
@@ -495,6 +533,11 @@ class PipeIOContractError(PipelexError):
error_code = CoreCode.METHOD_CONCEPT_INVALID
+# The finding of `method.concept_invalid` for a concept whose structure has no JSON Schema: what the caller can act on,
+# where the operator's message names the schema generator's own error.
+SCHEMA_UNRENDERABLE_FINDING = "its structure cannot be described as a JSON Schema"
+
+
class PipelineInputContentError(PipelexError):
"""A pipeline input's content reference (url) is unusable.
@@ -528,6 +571,33 @@ class PipelineInputContentError(PipelexError):
),
)
+ def __init__(self, message: str, *, input_name: str | None = None, field: str | None = None):
+ """The refusal of a file input, named by the run input it belongs to and the path down to it.
+
+ Args:
+ message: The operator's diagnostics.
+ input_name: The run input the file belongs to, the root of its path: `documents`. It is the problem's
+ `input` and `location.input`.
+ field: The dotted path from that input down to what is refused, the input included: `documents[1]`, or
+ `documents[1].url` for its url. It is `location.field`, and the `field` of a code that declares one.
+ """
+ super().__init__(message)
+ self.input_name = input_name
+ self.field = field
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ params: dict[str, Any] = {}
+ if self.input_name is not None:
+ params["input"] = self.input_name
+ if self.field is not None:
+ params["field"] = self.field
+ return params
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(input_name=self.input_name, field=self.field)
+
class PipelineInputUrlInvalidError(PipelineInputContentError):
"""An Image/Document input carries an http(s) url that does not parse as one.
diff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.py
index 440c89dc6..492a163bd 100644
--- a/pipelex/pipeline/execution_seams.py
+++ b/pipelex/pipeline/execution_seams.py
@@ -42,6 +42,7 @@ from pipelex.interpreter_hub import (
)
from pipelex.kernel.memory_ops import shape_inputs
from pipelex.libraries.bundle_resources import check_submitted_files
+from pipelex.libraries.pipe.pipe_suggestions import declared_pipe_refs
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
from pipelex.pipe_run.pipe_job import PipeJob
@@ -190,6 +191,11 @@ def acquire_library(
if submitted_files:
check_submitted_files(blueprints=all_blueprints, submitted_files=submitted_files)
library_manager.add_submitted_files(library_id=library_id, submitted_files=submitted_files)
+ if not library_dirs_are_callers:
+ # A refusal the caller reads offers the pipes of the bundles it sent, never the host's.
+ library_manager.get_library(library_id=library_id).pipe_library.set_caller_pipe_refs(
+ pipe_refs=declared_pipe_refs(blueprints=all_blueprints)
+ )
# Filter out blueprints whose URIs are already loaded (e.g. via PIPELEXPATH), and record the file on this
# host each of the others was read from, so its steps read beside it as when its directory loads.
diff --git a/pipelex/pipeline/file_input_consumers.py b/pipelex/pipeline/file_input_consumers.py
index 6141689fa..6cad72d8f 100644
--- a/pipelex/pipeline/file_input_consumers.py
+++ b/pipelex/pipeline/file_input_consumers.py
@@ -222,8 +222,9 @@ def check_file_inputs_against_consumers(*, entry_pipe: PipeAbstract, file_inputs
return
consumers_by_slot = collect_file_input_consumers(entry_pipe)
violations: list[str] = []
- # The code's parameters name one violation, the first, which the message lists among the others.
- first_violation_params: dict[str, str | None] | None = None
+ # The code's parameters name one violation, the first, which the message lists among the others: its file is named
+ # by the root input, as `input`, and the path down to it, as the location's `field`.
+ first_violation: tuple[IdentifiedFileInput, dict[str, str | None]] | None = None
for file_input in known_file_inputs:
format_key = file_input.format_key
if format_key is None:
@@ -241,11 +242,14 @@ def check_file_inputs_against_consumers(*, entry_pipe: PipeAbstract, file_inputs
f"pipe '{consumer.pipe_code}' {consumer.verb_phrase} model '{consumer.model}', "
f"which reads {describe_format_keys(format_keys=consumer.listed_formats)}."
)
- if first_violation_params is None:
- first_violation_params = {"input": file_input.display_path, "format": format_key, "model": consumer.model}
- if violations:
+ if first_violation is None:
+ first_violation = (file_input, {"format": format_key, "model": consumer.model})
+ if first_violation is not None:
msg = " ".join([*violations, "Give a file in a format its model reads, or use a model that reads this format."])
- raise PipelineInputFormatUnsupportedError(msg).with_params(**(first_violation_params or {}))
+ violating_input, violation_params = first_violation
+ raise PipelineInputFormatUnsupportedError(msg, input_name=str(violating_input.path[0]), field=violating_input.display_path).with_params(
+ **violation_params
+ )
def _is_http_url(*, uri_kind: UriKind) -> bool:
diff --git a/pipelex/pipeline/input_normalizer.py b/pipelex/pipeline/input_normalizer.py
index 22c9fe7b6..41367f0b0 100644
--- a/pipelex/pipeline/input_normalizer.py
+++ b/pipelex/pipeline/input_normalizer.py
@@ -116,6 +116,41 @@ class _PreparationContext(NamedTuple):
semaphore: asyncio.Semaphore
+# The field of a file input that holds its reference, named by an `input.invalid` refusal of a blank or malformed one.
+_URL_FIELD = "url"
+
+
+def _refused_file_input(*, path: FileInputPath, field_suffix: str | None = None) -> dict[str, str]:
+ """How a refusal of a file input names it, by `InputShapingError`'s convention, as the error's keyword arguments.
+
+ `input_name` is the root input, the first segment of the path, and `field` the dotted path inside it down to what
+ is refused, the root included: `documents[1]` for a file a list holds, `case.attachments[0]` for one a structure
+ holds, and with `field_suffix` the member at fault, such as `photo.url` for an image input's url.
+ """
+ field = format_file_input_path(path)
+ if field_suffix is not None:
+ field = f"{field}.{field_suffix}"
+ return {"input_name": str(path[0]), "field": field}
+
+
+class FileInputUnreadableReason(StrEnum):
+ """Why a file input could not be read, the `reason` of `input.file_unreadable`."""
+
+ # A data URL whose payload does not decode as base64.
+ INVALID_BASE64 = "invalid_base64"
+ # A local path the runner cannot open: it does not exist, is a directory, or is not readable.
+ PATH_UNREADABLE = "path_unreadable"
+
+
+def _file_type_of(*, content: NormalizableContent) -> str:
+ """The kind of file an input was read as, the `file_type` of `input.file_unreadable`: an image or a document."""
+ match content:
+ case ImageContent():
+ return "image"
+ case DocumentContent():
+ return "document"
+
+
def format_file_input_path(path: FileInputPath) -> str:
"""Render a file input's path the way a caller writes it: `transcripts[2]`, `case.attachments[0]`."""
rendered = ""
@@ -360,30 +395,34 @@ async def _prepare_url_content(
UriReadRefusedError: If the url is a local path, or a storage reference outside the
read scope, on a run with a read scope.
"""
- input_name = format_file_input_path(path)
+ display_path = format_file_input_path(path)
if not content.url.strip():
msg = f"{type(content).__name__} input has a blank url — provide https://, data:, pipelex-storage://, or a local file path."
- raise PipelineInputUrlMissingError(msg)
+ raise PipelineInputUrlMissingError(msg, **_refused_file_input(path=path, field_suffix=_URL_FIELD))
# Before anything reads or links the url. A signed link is a read by whoever holds it, so a
# foreign storage reference is refused here rather than read or signed; a local path is refused
# rather than read, uploaded, or kept for the prompt preparation to read later.
- authorize_uri_read(uri=content.url, read_scope=context.read_scope, position=f"the file given for input '{input_name}'")
+ authorize_uri_read(
+ uri=content.url, read_scope=context.read_scope, position=f"the file given for input '{display_path}'", **_refused_file_input(path=path)
+ )
resolved_uri = resolve_uri(content.url)
async with context.semaphore:
match resolved_uri:
case ResolvedHttpUrl():
- return _prepare_http_url(content=content, resolved_uri=resolved_uri, context=context)
+ return _prepare_http_url(content=content, resolved_uri=resolved_uri, path=path, context=context)
case ResolvedPipelexStorage():
- return await _prepare_storage_reference(content=content, resolved_uri=resolved_uri, input_name=input_name, context=context)
+ return await _prepare_storage_reference(content=content, resolved_uri=resolved_uri, path=path, context=context)
case ResolvedBase64DataUrl():
- return await _prepare_data_url(content=content, resolved_uri=resolved_uri, input_name=input_name, context=context)
+ return await _prepare_data_url(content=content, resolved_uri=resolved_uri, path=path, context=context)
case ResolvedLocalPath():
- return await _prepare_local_path(content=content, resolved_uri=resolved_uri, input_name=input_name, context=context)
+ return await _prepare_local_path(content=content, resolved_uri=resolved_uri, path=path, context=context)
-def _prepare_http_url(*, content: NormalizableContent, resolved_uri: ResolvedHttpUrl, context: _PreparationContext) -> NormalizableContent:
+def _prepare_http_url(
+ *, content: NormalizableContent, resolved_uri: ResolvedHttpUrl, path: FileInputPath, context: _PreparationContext
+) -> NormalizableContent:
# Never fetched: setup makes no outbound request to a host the caller chose. The operator that
# consumes the input fetches it and reports a real failure. Its format is only what the caller
# declared: the checks compare a declared type, and leave a URL that declares none to the provider.
@@ -394,7 +433,7 @@ def _prepare_http_url(*, content: NormalizableContent, resolved_uri: ResolvedHtt
validate_http_url_syntax(url=resolved_uri.url)
except ValueError as exc:
msg = f"{type(content).__name__} input: {exc}"
- raise PipelineInputUrlInvalidError(msg) from exc
+ raise PipelineInputUrlInvalidError(msg, **_refused_file_input(path=path, field_suffix=_URL_FIELD)) from exc
if content.public_url is not None:
return content
return content.model_copy(update={"public_url": content.url})
@@ -404,16 +443,17 @@ async def _prepare_storage_reference(
*,
content: NormalizableContent,
resolved_uri: ResolvedPipelexStorage,
- input_name: str,
+ path: FileInputPath,
context: _PreparationContext,
) -> NormalizableContent:
+ display_path = format_file_input_path(path)
try:
head = await context.storage.load_head(uri=resolved_uri.storage_uri, nb_bytes=FILE_HEAD_NB_BYTES)
except StorageFileNotFoundError as exc:
- msg = f"{type(content).__name__} input '{input_name}': the storage reference '{content.url}' names no stored file"
- raise PipelineInputContentError(msg).with_error_code(CoreCode.INPUT_REFERENCE_NOT_FOUND) from exc
+ msg = f"{type(content).__name__} input '{display_path}': the storage reference '{content.url}' names no stored file"
+ raise PipelineInputContentError(msg, **_refused_file_input(path=path)).with_error_code(CoreCode.INPUT_REFERENCE_NOT_FOUND) from exc
except StorageInvalidUriError as exc:
- msg = f"{type(content).__name__} input '{input_name}': the storage reference '{content.url}' cannot be read ({exc})"
+ msg = f"{type(content).__name__} input '{display_path}': the storage reference '{content.url}' cannot be read ({exc})"
raise PipelineInputContentError(msg) from exc
updates: dict[str, Any] = {}
mime_type = _identify_file_input(
@@ -421,7 +461,7 @@ async def _prepare_storage_reference(
head=head,
declared_mime_type=content.mime_type,
file_name=content.filename or PurePosixPath(resolved_uri.storage_uri).name,
- input_name=input_name,
+ path=path,
)
if mime_type != content.mime_type:
updates["mime_type"] = mime_type
@@ -446,7 +486,7 @@ async def _prepare_data_url(
*,
content: NormalizableContent,
resolved_uri: ResolvedBase64DataUrl,
- input_name: str,
+ path: FileInputPath,
context: _PreparationContext,
) -> NormalizableContent:
# Lenient on purpose, as it always was: characters outside the alphabet, such as the line breaks
@@ -454,14 +494,18 @@ async def _prepare_data_url(
try:
raw_bytes = base64.b64decode(resolved_uri.base64_data)
except binascii.Error as exc:
- msg = f"{type(content).__name__} input '{input_name}': the data URL does not hold valid base64 ({exc})"
- raise PipelineInputContentError(msg).with_error_code(CoreCode.INPUT_FILE_UNREADABLE) from exc
+ msg = f"{type(content).__name__} input '{format_file_input_path(path)}': the data URL does not hold valid base64 ({exc})"
+ raise (
+ PipelineInputContentError(msg, **_refused_file_input(path=path))
+ .with_error_code(CoreCode.INPUT_FILE_UNREADABLE)
+ .with_params(file_type=_file_type_of(content=content), reason=FileInputUnreadableReason.INVALID_BASE64)
+ ) from exc
mime_type = _identify_file_input(
content=content,
head=raw_bytes[:FILE_HEAD_NB_BYTES],
declared_mime_type=resolved_uri.mime_type or content.mime_type,
file_name=content.filename,
- input_name=input_name,
+ path=path,
)
if not context.is_relocation_enabled:
@@ -493,7 +537,7 @@ async def _prepare_local_path(
*,
content: NormalizableContent,
resolved_uri: ResolvedLocalPath,
- input_name: str,
+ path: FileInputPath,
context: _PreparationContext,
) -> NormalizableContent:
local_path = Path(resolved_uri.path)
@@ -505,7 +549,7 @@ async def _prepare_local_path(
except (OSError, ValueError):
return content
mime_type = _identify_file_input(
- content=content, head=head, declared_mime_type=content.mime_type, file_name=content.filename or local_path.name, input_name=input_name
+ content=content, head=head, declared_mime_type=content.mime_type, file_name=content.filename or local_path.name, path=path
)
if mime_type == content.mime_type:
return content
@@ -520,13 +564,17 @@ async def _prepare_local_path(
raw_bytes = await load_binary_async(local_path)
except (OSError, ValueError) as exc:
msg = f"Input file cannot be read: '{resolved_uri.path}' ({type(exc).__name__})"
- raise PipelineInputContentError(msg).with_error_code(CoreCode.INPUT_FILE_UNREADABLE) from exc
+ raise (
+ PipelineInputContentError(msg, **_refused_file_input(path=path))
+ .with_error_code(CoreCode.INPUT_FILE_UNREADABLE)
+ .with_params(file_type=_file_type_of(content=content), reason=FileInputUnreadableReason.PATH_UNREADABLE)
+ ) from exc
mime_type = _identify_file_input(
content=content,
head=raw_bytes[:FILE_HEAD_NB_BYTES],
declared_mime_type=content.mime_type,
file_name=content.filename or local_path.name,
- input_name=input_name,
+ path=path,
)
extension = _storage_key_extension(raw_bytes=raw_bytes, mime_type=mime_type, fallback_suffix=local_path.suffix.removeprefix(".") or None)
key = f"{context.storage_scope}/assets/{shortuuid.uuid()}.{extension}"
@@ -543,7 +591,7 @@ async def _prepare_local_path(
def _identify_file_input(
- *, content: NormalizableContent, head: bytes | None, declared_mime_type: str | None, file_name: str | None, input_name: str
+ *, content: NormalizableContent, head: bytes | None, declared_mime_type: str | None, file_name: str | None, path: FileInputPath
) -> str | None:
"""The MIME type that describes a file input, refusing an Image input whose bytes are not an image.
@@ -567,12 +615,10 @@ def _identify_file_input(
format_key = format_key_from_mime_type(mime_type=mime_type_to_describe)
if format_key is None or format_key == IMAGE_FORMAT_KEY:
return mime_type
- msg = (
- f"Input '{input_name}' expects an image, but the file is {describe_file_format(format_key=format_key, mime_type=mime_type_to_describe)}. "
- "Give an image file such as PNG, JPEG or WebP."
- )
+ file_format = describe_file_format(format_key=format_key, mime_type=mime_type_to_describe)
+ msg = f"Input '{format_file_input_path(path)}' expects an image, but the file is {file_format}. Give an image file such as PNG, JPEG or WebP."
# No model reads the input yet, so the code's sentence, which names one, falls back to its title.
- raise PipelineInputNotAnImageError(msg).with_params(input=input_name, format=format_key)
+ raise PipelineInputNotAnImageError(msg, **_refused_file_input(path=path)).with_params(format=format_key)
async def _load_local_head(local_path: Path) -> bytes:
diff --git a/pipelex/pipeline/inputs_template.py b/pipelex/pipeline/inputs_template.py
index 5d91ea452..5ba4dff7b 100644
--- a/pipelex/pipeline/inputs_template.py
+++ b/pipelex/pipeline/inputs_template.py
@@ -58,7 +58,7 @@ async def build_inputs_for_pipe(
main_pipe_ref = select_primary_blueprint(blueprints).main_pipe_ref
if not main_pipe_ref:
msg = "Bundle does not declare a main_pipe. Specify a pipe code."
- raise MethodEntryError(msg)
+ raise MethodEntryError(msg).with_params(candidates=[])
pipe_code = main_pipe_ref
elif bundle_path:
# allow_signatures=True: see the mthds_contents branch — rendering inputs tolerates placeholders.
@@ -68,7 +68,7 @@ async def build_inputs_for_pipe(
main_pipe_code = bundle_blueprint.main_pipe
if not main_pipe_code:
msg = f"Bundle '{bundle_path}' does not declare a main_pipe. Specify a pipe code."
- raise MethodEntryError(msg)
+ raise MethodEntryError(msg).with_params(candidates=[])
pipe_code = PipeFactory.make_pipe_ref_with_domain(domain_code=bundle_blueprint.domain, pipe_code=main_pipe_code)
else:
# No bundle - initialize the library manually
@@ -81,7 +81,7 @@ async def build_inputs_for_pipe(
if not pipe_code:
msg = "No pipe code specified"
- raise MethodEntryError(msg)
+ raise MethodEntryError(msg).with_params(candidates=[])
the_pipe = get_required_entry_pipe(pipe_code=pipe_code)
# The envelope names the pipe that was resolved, always domain-qualified, never the selector
diff --git a/pipelex/pipeline/method_entry.py b/pipelex/pipeline/method_entry.py
index 63c1b10c5..3505c9c6e 100644
--- a/pipelex/pipeline/method_entry.py
+++ b/pipelex/pipeline/method_entry.py
@@ -28,6 +28,8 @@ from mthds.protocol.problem.registry import CoreCode
from pipelex.base_exceptions import PipelexUnexpectedError
from pipelex.core.qualified_ref import QualifiedRef, QualifiedRefError
+from pipelex.libraries.pipe.pipe_suggestions import MAIN_PIPE_DECLARATION, close_pipe_refs
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.mthds_parsing.parser import MthdsParser
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.pipe_machinery.validation import is_pipe_code_valid
@@ -71,6 +73,11 @@ def _listed(*, names: list[str]) -> str:
return ", ".join(f"'{name}'" for name in names)
+def _declared_pipe_refs(*, candidates: list[EntryCandidate]) -> list[str]:
+ """The qualified refs of every pipe the method's bundles declare, sorted: the pipes a run may name to start at."""
+ return sorted({f"{candidate.domain}.{pipe_code}" for candidate in candidates for pipe_code in candidate.pipe_codes})
+
+
def _entry_of(*, candidate: EntryCandidate, pipe_code: str) -> MethodEntry:
return MethodEntry(
tree_path=candidate.tree_path,
@@ -161,10 +168,18 @@ def read_method_manifest(*, tree: MethodTree) -> MethodsManifest | None:
manifest = read_package_manifest_at(tree.directory)
except ManifestError as exc:
msg = f"The {MANIFEST_NAME} of the method {method_label} cannot be read: {exc}"
- raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID) from exc
+ raise (
+ MethodEntryError(msg)
+ .with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ .with_params(reason=MethodPackageReason.MANIFEST_INVALID, path=MANIFEST_NAME)
+ ) from exc
if manifest is None:
msg = f"The method {method_label} lists a {MANIFEST_NAME} at its root that could not be read back."
- raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ raise (
+ MethodEntryError(msg)
+ .with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ .with_params(reason=MethodPackageReason.MANIFEST_INVALID, path=MANIFEST_NAME)
+ )
return manifest
@@ -193,7 +208,7 @@ def select_entry(*, candidates: list[EntryCandidate], manifest: MethodsManifest
f"The method {method_label} has no {MANIFEST_NAME}, and none of its bundles declares a main_pipe "
f"({_listed(names=bundle_paths)}), so it has no pipe to start at. Declare a main_pipe in one bundle, or name the pipe to run."
)
- raise MethodEntryError(msg)
+ raise MethodEntryError(msg).with_params(candidates=_declared_pipe_refs(candidates=candidates))
if len(declaring) > 1:
declarations = ", ".join(f"'{candidate.tree_path}' declares '{candidate.main_pipe}'" for candidate in declaring)
msg = (
@@ -226,7 +241,7 @@ def _manifest_entry(*, candidates: list[EntryCandidate], manifest: MethodsManife
f"The {MANIFEST_NAME} of the method {method_label} declares no main_pipe, so the method has no pipe to start at. "
f"Declare main_pipe under [package], or name the pipe to run. Its bundles: {_listed(names=bundle_paths)}."
)
- raise MethodEntryError(msg)
+ raise MethodEntryError(msg).with_params(candidates=_declared_pipe_refs(candidates=candidates))
# The manifest refuses a main_pipe no domain exports, so the domains exporting it say which bundles may define it.
exporting_domains = {domain for domain, domain_exports in manifest.exports.items() if main_pipe in domain_exports.pipes}
defining = [candidate for candidate in candidates if candidate.domain in exporting_domains and main_pipe in candidate.pipe_codes]
@@ -235,7 +250,15 @@ def _manifest_entry(*, candidates: list[EntryCandidate], manifest: MethodsManife
f"The {MANIFEST_NAME} of the method {method_label} declares the main_pipe '{main_pipe}', exported by "
f"{_listed(names=sorted(exporting_domains))}, which none of its bundles defines in that domain: {_listed(names=bundle_paths)}."
)
- raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_PIPE_UNRESOLVED).with_params(missing=main_pipe)
+ raise (
+ MethodEntryError(msg)
+ .with_error_code(CoreCode.METHOD_PIPE_UNRESOLVED)
+ .with_params(
+ pipe=MAIN_PIPE_DECLARATION,
+ missing=main_pipe,
+ candidates=close_pipe_refs(name=main_pipe, pipe_refs=_declared_pipe_refs(candidates=candidates)),
+ )
+ )
if len(defining) > 1:
definitions = ", ".join(f"'{candidate.tree_path}' in domain '{candidate.domain}'" for candidate in defining)
msg = (
@@ -290,7 +313,8 @@ def select_named_pipe(*, candidates: list[EntryCandidate], pipe_ref: str, method
]
if not defining:
msg = f"No bundle of the method {method_label} defines the pipe '{pipe_ref}'. Its bundles: {_listed(names=bundle_paths)}."
- raise MethodEntryError(msg).with_error_code(CoreCode.REQUEST_PIPE_NOT_FOUND).with_params(pipe=pipe_ref)
+ suggestions = close_pipe_refs(name=pipe_ref, pipe_refs=_declared_pipe_refs(candidates=candidates))
+ raise MethodEntryError(msg).with_error_code(CoreCode.REQUEST_PIPE_NOT_FOUND).with_params(pipe=pipe_ref, suggestions=suggestions)
if len(defining) > 1:
definitions = ", ".join(f"'{candidate.tree_path}' in domain '{candidate.domain}'" for candidate in defining)
msg = f"Several bundles of the method {method_label} define the pipe '{pipe_ref}': {definitions}. Name the pipe as domain.pipe_code."
diff --git a/pipelex/pipeline/pipe_io_contracts.py b/pipelex/pipeline/pipe_io_contracts.py
index 0c0546c98..071b72ddb 100644
--- a/pipelex/pipeline/pipe_io_contracts.py
+++ b/pipelex/pipeline/pipe_io_contracts.py
@@ -40,7 +40,7 @@ from pipelex.core.pipes.variable_multiplicity import VariableMultiplicity, fixed
from pipelex.core.stuffs.list_content import ListContent
from pipelex.interpreter_hub import get_concept_library
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
-from pipelex.pipeline.exceptions import PipeIOContractError
+from pipelex.pipeline.exceptions import SCHEMA_UNRENDERABLE_FINDING, PipeIOContractError
__all__ = [
"IOMultiplicity",
@@ -129,7 +129,7 @@ def _render_output_schema(*, pipe: PipeAbstract, concept_provider: ConceptProvid
return schema
except (ConceptValueError, KeyError, PydanticUserError, PydanticUndefinedAnnotation) as exc:
msg = f"Failed to render the JSON Schema for the output of pipe '{pipe.pipe_ref}' (concept '{pipe.output.concept.concept_ref}'): {exc}"
- raise PipeIOContractError(message=msg) from exc
+ raise PipeIOContractError(message=msg).with_params(concept=pipe.output.concept.concept_ref, finding=SCHEMA_UNRENDERABLE_FINDING) from exc
def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> PipeIOContracts:
@@ -185,7 +185,9 @@ def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> PipeIOContracts:
f"Failed to render the JSON Schema for input '{var_name}' of pipe "
f"'{pipe.pipe_ref}' (concept '{stuff_spec.concept.concept_ref}'): {exc}"
)
- raise PipeIOContractError(message=msg) from exc
+ raise PipeIOContractError(message=msg).with_params(
+ concept=stuff_spec.concept.concept_ref, finding=SCHEMA_UNRENDERABLE_FINDING
+ ) from exc
schema_memo[memo_key] = json_schema
input_multiplicity, input_item_count = make_io_multiplicity(multiplicity=stuff_spec.multiplicity)
pipe_inputs[var_name] = PipeInputContract(
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index 7f2dcbf22..e86260d37 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -17,6 +17,7 @@ from pipelex.interpreter_hub import (
get_pipeline_manager,
get_required_entry_pipe,
get_required_pipe,
+ get_selectable_own_pipe_refs,
set_current_library,
)
from pipelex.pipe_run.pipe_job import PipeJob
@@ -224,7 +225,8 @@ async def pipeline_run_setup(
# production. The constant survives for telemetry only.
if not mthds_contents and not pipe_code:
msg = "Either pipe_code or mthds_contents must be provided to the pipeline API."
- raise PipeExecutionError(message=msg).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED)
+ # The request carries no method, so it has no pipe to select.
+ raise PipeExecutionError(message=msg).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED).with_params(candidates=[])
# Validate the extras HERE, before this function causes anything observable.
#
@@ -355,7 +357,9 @@ async def pipeline_run_setup(
pipe = get_required_pipe(pipe_code=qualified_main_pipe)
else:
msg = "No pipe_code provided and no main_pipe found in any of the MTHDS contents."
- raise PipeExecutionError(message=msg).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED)
+ # With no entry pipe to start from, the request may select any pipe of the method it sent.
+ candidates = sorted(get_selectable_own_pipe_refs())
+ raise PipeExecutionError(message=msg).with_error_code(CoreCode.REQUEST_PIPE_UNSPECIFIED).with_params(candidates=candidates)
elif pipe_code:
pipe = get_required_entry_pipe(pipe_code=pipe_code)
else:
diff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.py
index 907e9d34e..b81f318b7 100644
--- a/pipelex/pipeline/validate_bundle.py
+++ b/pipelex/pipeline/validate_bundle.py
@@ -29,11 +29,12 @@ from pipelex.libraries.bundle_resources import check_submitted_files
from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
from pipelex.libraries.method_trees import list_local_method_tree
from pipelex.libraries.pipe.exceptions import EntryPipeNotFoundError
+from pipelex.libraries.pipe.pipe_suggestions import close_pipe_refs, declared_pipe_refs
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.pipeline.bundle_validator import BundleValidator, DryRunOutput, DryRunStatus
-from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.exceptions import TreePythonSyntaxError, ValidateBundleError
from pipelex.pipeline.validate_bundle_translation import (
reporting_host_library_faults,
translate_to_validate_bundle_error,
@@ -121,7 +122,9 @@ def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], *, dry_run_pipe_codes: l
missing_str = ", ".join(f"'{code}'" for code in sorted(missing))
msg = f"Pipe(s) {missing_str} not found in the bundle. Check for typos and make sure they are declared in the bundle."
# The bundle-scoped wording stays the raise site's own, more precise here than the class's library-lookup message.
- raise EntryPipeNotFoundError(msg).with_params(pipe=", ".join(sorted(missing)))
+ loaded_refs = [pipe.pipe_ref for pipe in loaded_pipes]
+ suggestions = list(dict.fromkeys(ref for code in sorted(missing) for ref in close_pipe_refs(name=code, pipe_refs=loaded_refs)))
+ raise EntryPipeNotFoundError(msg).with_params(pipe=", ".join(sorted(missing)), suggestions=suggestions)
return selected
@@ -280,6 +283,9 @@ async def validate_bundle(
if submitted_files:
check_submitted_files(blueprints=loaded_blueprints, submitted_files=submitted_files)
library_manager.add_submitted_files(library_id=library_id, submitted_files=submitted_files)
+ if not library_dirs_are_callers:
+ # A refusal the caller reads offers the pipes of the bundles it sent, never the host's.
+ library.pipe_library.set_caller_pipe_refs(pipe_refs=declared_pipe_refs(blueprints=loaded_blueprints))
loaded_pipes = library_manager.load_from_blueprints(library_id=library_id, blueprints=loaded_blueprints)
dry_run_results = await BundleValidator().validate_pipes(
pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes=dry_run_pipe_codes),
@@ -363,28 +369,43 @@ def _ensure_tree_python_parses(*, tree: MethodTree) -> None:
try:
source = tree.file_location(tree_path).read_bytes().decode("utf-8")
except UnicodeDecodeError:
- items.append(PipelexBundleBlueprintValidationErrorData(source=tree_path, message=f"The Python file '{tree_path}' is not UTF-8 text."))
+ items.append(
+ _tree_python_item(tree_path=tree_path, finding="not UTF-8 text", message=f"The Python file '{tree_path}' is not UTF-8 text.")
+ )
continue
try:
ast.parse(source, filename=tree_path)
except SyntaxError as exc:
- items.append(
- PipelexBundleBlueprintValidationErrorData(
- source=tree_path,
- message=f"The Python file '{tree_path}' does not parse: {exc.msg} (line {exc.lineno}).",
- line=exc.lineno,
- column=exc.offset,
- )
- )
+ items.append(_tree_python_item(tree_path=tree_path, finding=f"{exc.msg} (line {exc.lineno})", line=exc.lineno, column=exc.offset))
except ValueError as exc:
# Python 3.11 refuses a source holding a NUL byte with a ValueError where later versions raise a SyntaxError.
- items.append(PipelexBundleBlueprintValidationErrorData(source=tree_path, message=f"The Python file '{tree_path}' does not parse: {exc}."))
+ items.append(_tree_python_item(tree_path=tree_path, finding=str(exc)))
except (RecursionError, MemoryError):
# Nesting deep enough to exhaust the parser, which Python's own import refuses the same way.
- message = f"The Python file '{tree_path}' does not parse: it nests too deeply."
- items.append(PipelexBundleBlueprintValidationErrorData(source=tree_path, message=message))
+ items.append(_tree_python_item(tree_path=tree_path, finding="it nests too deeply"))
if items:
- raise ValidateBundleError(message=" ".join(item.message for item in items), pipelex_bundle_blueprint_validation_errors=items)
+ message = " ".join(item.message for item in items)
+ # Each item takes the code of the verdict's cause, `method.syntax`, with its own finding.
+ first_finding = (items[0].params or {}).get("finding")
+ raise ValidateBundleError(message=message, pipelex_bundle_blueprint_validation_errors=items) from TreePythonSyntaxError(message).with_params(
+ finding=first_finding
+ )
+
+
+def _tree_python_item(
+ *, tree_path: str, finding: str, message: str | None = None, line: int | None = None, column: int | None = None
+) -> PipelexBundleBlueprintValidationErrorData:
+ """The item of a Python file of a method's tree that does not parse, located on the file and, when known, its line.
+
+ Its ``finding`` is what the parser found, the ``method.syntax`` parameter; its message says so, naming the file.
+ """
+ return PipelexBundleBlueprintValidationErrorData(
+ source=tree_path,
+ message=message or f"The Python file '{tree_path}' does not parse: {finding}.",
+ line=line,
+ column=column,
+ params={"finding": finding},
+ )
def _is_member_blueprint(*, blueprint: PipelexBundleBlueprint, tree: MethodTree) -> bool:
diff --git a/pipelex/pipeline/validate_bundle_translation.py b/pipelex/pipeline/validate_bundle_translation.py
index 6804ba3a7..f3dafc124 100644
--- a/pipelex/pipeline/validate_bundle_translation.py
+++ b/pipelex/pipeline/validate_bundle_translation.py
@@ -36,7 +36,7 @@ from pipelex.errors.error_codes import ErrorCode, code_is_method_domain
from pipelex.errors.problem import ProblemView
from pipelex.errors.security_event import security_target_kind
from pipelex.interpreter_hub import get_library_manager
-from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError, MethodTreeLoadError
+from pipelex.libraries.exceptions import LibraryError, MethodTreeLoadError
from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
from pipelex.libraries.method_trees import bundle_files_under, reporting_host_library_tree_faults
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
@@ -157,19 +157,15 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
# 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;
+ # raw traceback. A LibraryError carries the blueprint- and pipe/concept-validation errors it was raised with;
# forward them so the CLI renders the same structured detail it does for the other arms.
# A library error that is not the method's, such as an invariant of the library manager
# (`runtime.unexpected`) or library directories configured wrongly (`pipelex.config.invalid`), is no
# verdict about the bundle, and propagates as it is, as does a security refusal.
if not _code_makes_a_verdict(code=library_error.resolve_error_code()):
raise
- 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
+ blueprint_validation_errors = library_error.blueprint_validation_errors or None
+ pipe_concept_validation_errors = library_error.pipe_concept_validation_errors or None
if not blueprint_validation_errors and not pipe_concept_validation_errors:
# A tree the package rules refuse, such as one holding a symbolic link, gives its one item the file at fault.
refused_path = _refused_tree_path(refusal=library_error)
@@ -223,7 +219,11 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
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.
+ # the reference as written, the model type and the deck's suggestions. A model a catalog of this
+ # deployment knows, which no enabled backend serves (`model.unavailable`), is no fault of the
+ # method: it leaves as it is, located on the pipe and the field, whose fix is the deployment's.
+ if not _code_makes_a_verdict(code=model_choice_error.resolve_error_code()):
+ raise
raise ValidateBundleError(
message=model_choice_error.message,
pipe_validation_errors=[categorize_pipe_operator_model_choice_error(model_choice_error=model_choice_error)],
@@ -349,7 +349,8 @@ def withholding_host_library_files(
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
+ domain, and a message reads ``HOST_LIBRARY_FILE_PLACEHOLDER`` where it named one, while the item of a host file that
+ restates a name conflict an item of the caller's own file reports is left out. 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. The template files the host's ``PipeDocGen`` steps
diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.py
index 37ce96972..9df4427ff 100644
--- a/pipelex/pipeline/validation_errors.py
+++ b/pipelex/pipeline/validation_errors.py
@@ -28,6 +28,7 @@ from mthds.protocol.problem.registry import (
MethodDependencyMissingReason,
MethodHintInvalidReason,
MethodIdentifierInvalidIdentifierKind,
+ MethodNameConflictConflict,
)
from pydantic import BaseModel, ConfigDict
@@ -44,6 +45,7 @@ from pipelex.errors.error_codes import ErrorCode, error_code_spec
from pipelex.errors.problem import make_location, make_problem_item
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error, plan_fix_for_pipe_validation_error
+from pipelex.tools.misc.string_utils import close_matches
from pipelex.validation_error_types import (
HintLintErrorType,
PipeFactoryErrorType,
@@ -110,8 +112,11 @@ def build_validation_error_items(
domain_code=blueprint_error.domain_code,
source=blueprint_error.source,
field_path=blueprint_error.field_path,
+ field_name=blueprint_error.field_name,
variable_names=blueprint_error.variable_names or None,
declared_concepts=blueprint_error.declared_concepts or None,
+ identifier_name=blueprint_error.identifier_name,
+ params=blueprint_error.params,
line=blueprint_error.line,
column=blueprint_error.column,
message=blueprint_error.message,
@@ -149,6 +154,7 @@ def build_validation_error_items(
model_reference=pipe_error.model_reference,
model_type=pipe_error.model_type,
suggestions=pipe_error.suggestions or None,
+ params=pipe_error.params,
message=pipe_error.message,
suggested_fix=plan_fix_for_pipe_validation_error(pipe_error),
)
@@ -265,11 +271,12 @@ def warning_problem_items(*, warnings: list[ValidationErrorItem]) -> list[Proble
# The identifier an item of these types is about, and where the item holds it: an input name among its variable names, a pipe
-# code as its pipe. A main_pipe the item does not name, or a pipe code only its message quotes, gives no identifier facts.
+# code as its identifier name, else as its pipe. A pipe code item whose field path is `main_pipe` is about the main pipe.
_IDENTIFIER_KINDS: dict[PipeValidationErrorType, MethodIdentifierInvalidIdentifierKind] = {
PipeValidationErrorType.INVALID_INPUT_NAME: MethodIdentifierInvalidIdentifierKind.INPUT_NAME,
PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX: MethodIdentifierInvalidIdentifierKind.PIPE_CODE,
}
+_MAIN_PIPE_FIELD_PATH = "main_pipe"
def _identifier_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
@@ -279,11 +286,13 @@ def _identifier_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
identifier_kind = _IDENTIFIER_KINDS.get(item.error_type)
if identifier_kind is None:
return {}
+ if identifier_kind == MethodIdentifierInvalidIdentifierKind.PIPE_CODE and item.field_path == _MAIN_PIPE_FIELD_PATH:
+ identifier_kind = MethodIdentifierInvalidIdentifierKind.MAIN_PIPE
match identifier_kind:
case MethodIdentifierInvalidIdentifierKind.INPUT_NAME:
- name = item.variable_names[0] if item.variable_names else None
+ name = item.identifier_name or (item.variable_names[0] if item.variable_names else None)
case MethodIdentifierInvalidIdentifierKind.PIPE_CODE | MethodIdentifierInvalidIdentifierKind.MAIN_PIPE:
- name = item.pipe_code
+ name = item.identifier_name or item.pipe_code
if name is None:
return {}
return {"identifier_kind": identifier_kind, "name": name}
@@ -306,19 +315,70 @@ def _dependency_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
_PACKAGE_DEPENDENCY_TYPES: frozenset[PipeValidationErrorType] = frozenset({PipeValidationErrorType.UNRESOLVED_PACKAGE_DEPENDENCY})
+# How near a declared concept must be to an unresolved one to be offered in its place, as difflib's similarity ratio,
+# and how many are offered.
+_CLOSE_CONCEPT_CUTOFF = 0.6
+_CLOSE_CONCEPT_MAX_MATCHES = 5
+
+
+def _concept_suggestions(*, item: ValidationErrorItem) -> list[str] | None:
+ """The concepts the bundle declares nearest the one an unresolved-concept item names, nearest first; ``None`` for another item."""
+ is_unresolved_concept = item.error_type in {PipeValidationErrorType.UNRESOLVED_CONCEPT, PipeFactoryErrorType.UNKNOWN_CONCEPT}
+ # A concept-owned reference locates the concept that holds it and names the one it misses in its own parameters.
+ concept = (item.params or {}).get("concept") or item.missing_concept_code or item.concept_code
+ if not is_unresolved_concept or concept is None:
+ return None
+ local_code = concept.rsplit(".", 1)[-1]
+ return close_matches(
+ name=local_code, candidates=item.declared_concepts or [], cutoff=_CLOSE_CONCEPT_CUTOFF, max_matches=_CLOSE_CONCEPT_MAX_MATCHES
+ )
+
+
+# What the name of a `method.name_conflict` item collides with, by the type of the item; a name declared twice across a
+# method's bundles is an item no type classifies, which takes the refusal's own parameters.
+_NAME_CONFLICTS: dict[PipeValidationErrorType, MethodNameConflictConflict] = {
+ PipeValidationErrorType.NATIVE_CONCEPT_REDECLARATION: MethodNameConflictConflict.NATIVE_CONCEPT,
+ PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION: MethodNameConflictConflict.BATCH_ITEM,
+}
+
+
+# The name conflicts no declaration makes: a batch item named as its list or as another input of its pipe is a name that
+# pipe uses twice, located on the pipe and on the field it collides on, as any other item about a pipe is.
+_PIPE_NAME_CONFLICTS: frozenset[PipeValidationErrorType] = frozenset({PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION})
+
+
+def _name_conflict_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
+ """The name and the conflict of a name-conflict item: the concept a bundle redeclares, or the batch item's name."""
+ conflict = _NAME_CONFLICTS.get(item.error_type) if isinstance(item.error_type, PipeValidationErrorType) else None
+ if conflict is None:
+ return {}
+ name: str | None
+ match conflict:
+ case MethodNameConflictConflict.NATIVE_CONCEPT:
+ name = item.concept_code
+ case MethodNameConflictConflict.BATCH_ITEM:
+ name = item.variable_names[0] if item.variable_names else None
+ case MethodNameConflictConflict.DUPLICATE_DECLARATION | MethodNameConflictConflict.RESERVED_DOMAIN:
+ name = None
+ return {"name": name, "conflict": conflict}
+
+
def _item_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
"""The facts a validation item holds, by the names the registry gives the parameters that carry them."""
facts: dict[str, Any] = {
**_identifier_facts(item=item),
**_dependency_facts(item=item),
**_hint_facts(item=item),
+ **_name_conflict_facts(item=item),
"template": item.template_file,
"pipe": item.pipe_code,
"concept": item.missing_concept_code or item.concept_code,
"variables": item.variable_names,
+ # The one input an item names, for a code about a single input.
+ "input": item.variable_names[0] if item.variable_names and len(item.variable_names) == 1 else None,
"model": item.model_reference,
"model_type": item.model_type,
- "suggestions": item.suggestions,
+ "suggestions": item.suggestions if item.suggestions is not None else _concept_suggestions(item=item),
"field_path": item.field_path or _declaration_path(item=item),
"missing": item.missing_pipe_code,
"finding": item.message,
@@ -341,30 +401,42 @@ def problem_item_of(*, item: ValidationErrorItem, code: ErrorCode, params: dict[
Args:
item: The validation item.
code: Its code: :func:`validation_item_code`'s, or the dry-run failure's own.
- params: Parameters known beside the item, such as those a dry-run failure was rendered from, which take
- precedence over the item's own.
+ params: Parameters known beside the item, such as those a dry-run failure was rendered from or those of the
+ refusal an unclassified item takes its code from, which take precedence over the facts its locators give;
+ the parameters the item itself holds (``item.params``) take precedence over both.
Returns:
The problem item, its sentence rendered from the code's template.
"""
spec = error_code_spec(code)
- facts = {**_item_facts(item=item), **(params or {})}
+ facts = {**_item_facts(item=item), **(params or {}), **(item.params or {})}
item_params = {name: value for name, value in facts.items() if name in spec.param_names}
+ if "suggestions" in spec.required_params:
+ # A stage that offers close matches leaves the list out when it found none, which the code reads as an empty one.
+ item_params.setdefault("suggestions", [])
return make_problem_item(
code=code,
params=item_params,
- location=_item_location(item=item),
+ location=_item_location(item=item, code=code),
suggestions=item.suggestions,
suggested_fix=_problem_fix(item=item),
)
-def _item_location(*, item: ValidationErrorItem) -> ProblemLocation | None:
- """Where in the method a validation item is: the declaration a hint lint is on, else the pipe, field and file it names."""
+def _item_location(*, item: ValidationErrorItem, code: ErrorCode) -> ProblemLocation | None:
+ """Where in the method a validation item is: the declaration a hint lint is on, the declaration a name conflict
+ collides on, else the pipe, field and file it names.
+ """
if isinstance(item.error_type, HintLintErrorType):
return _hint_location(item=item)
line = item.line if item.line is not None and item.line >= 1 else None
column = item.column if item.column is not None and item.column >= 1 else None
+ if code == CoreCode.METHOD_NAME_CONFLICT and item.error_type not in _PIPE_NAME_CONFLICTS:
+ # A declaration's name conflict, a duplicate declaration or a native concept's redeclaration, is located on the
+ # declaration that collides, by its path from the bundle's root, such as `concept.Rating` or `pipe.compute_score`,
+ # which a caller edits. A `field` beside no `pipe` reads from the bundle's root, so the location names no `pipe` a
+ # reader would join that path to.
+ return make_location(field=item.field_path or _declaration_path(item=item), file=item.source, line=line, column=column)
return make_location(pipe=item.pipe_code, field=item.field_name or item.field_path or None, file=item.source, line=line, column=column)
diff --git a/pipelex/providers/google/google_img_gen_worker.py b/pipelex/providers/google/google_img_gen_worker.py
index 9dafd1f58..d9622f1f5 100644
--- a/pipelex/providers/google/google_img_gen_worker.py
+++ b/pipelex/providers/google/google_img_gen_worker.py
@@ -282,12 +282,16 @@ class GoogleImgGenWorker(ImgGenWorkerAbstract):
cause = _IMAGE_REFUSAL_CAUSES.get(refusal_reason.upper())
next_step = "Revise the image prompt or its input images."
msg = f"{what_happened}: {cause}. {next_step}" if cause else f"{what_happened}. {next_step}"
- raise ImgGenGenerationError(
- msg,
- error_category=InferenceErrorCategory.CONTENT,
- user_action=UserAction(kind=UserActionKind.CHANGE_INPUT, detail=next_step),
- provider_metadata=None,
- ).with_error_code(CoreCode.MODEL_CONTENT_REFUSED)
+ raise (
+ ImgGenGenerationError(
+ msg,
+ error_category=InferenceErrorCategory.CONTENT,
+ user_action=UserAction(kind=UserActionKind.CHANGE_INPUT, detail=next_step),
+ provider_metadata=None,
+ )
+ .with_error_code(CoreCode.MODEL_CONTENT_REFUSED)
+ .with_params(model=model_handle)
+ )
@override
async def _gen_image_list(
diff --git a/pipelex/test_extras/required_params_sweep.py b/pipelex/test_extras/required_params_sweep.py
new file mode 100644
index 000000000..579056335
--- /dev/null
+++ b/pipelex/test_extras/required_params_sweep.py
@@ -0,0 +1,43 @@
+"""The sweep that fails a test during which a problem or an item was built lacking a parameter its code requires.
+
+Whatever a test makes the runtime or the runner answer, a refusal, an item of a verdict or a run's failure, is built by
+`make_problem` or `make_problem_item`, which log each required parameter a raise site did not give
+(`pipelex.errors.problem.missing_required_params`). The library's unit tests and the API server's run every test under
+this sweep, from an autouse fixture of their `conftest.py` that spies before the test and asserts after it, so a raise
+site any test reaches cannot answer less than its code promises. A test that builds such a problem on purpose, to check
+something its parameters do not decide, or that reaches a raise site which cannot know a fact, says so with the marker
+`REQUIRED_PARAMS_OPT_OUT_MARKER` and its reason.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pytest_mock import MockerFixture, MockType
+
+from pipelex.errors import problem as problem_module
+from pipelex.errors.problem import MISSING_REQUIRED_PARAMS_MESSAGE
+
+# The marker a test carries, with a `reason`, when it builds a problem lacking a required parameter on purpose.
+REQUIRED_PARAMS_OPT_OUT_MARKER = "builds_problems_without_required_params"
+
+
+def spy_on_problem_warnings(*, mocker: MockerFixture) -> MockType:
+ """Spy, for the test's duration, on the warnings the problem builders log, before the test runs.
+
+ Args:
+ mocker: The test's mocker, which removes the spy when the test ends.
+ """
+ return mocker.spy(problem_module, "_warn")
+
+
+def assert_problems_carried_required_params(*, warn_spy: MockType, keywords: Mapping[str, Any]) -> None:
+ """Fail the test when a problem or an item built during it lacked a required parameter, unless the test opts out.
+
+ Args:
+ warn_spy: The spy `spy_on_problem_warnings` set before the test ran.
+ keywords: The test's keywords, where a marker on the test, its class or its module appears by name.
+ """
+ if REQUIRED_PARAMS_OPT_OUT_MARKER in keywords:
+ return
+ lacking = [call.kwargs["fields"] for call in warn_spy.call_args_list if call.kwargs.get("message") == MISSING_REQUIRED_PARAMS_MESSAGE]
+ assert not lacking, f"A problem or an item was built without a parameter its code requires: {lacking}"
diff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.py
index 8a7ed0653..733574901 100644
--- a/pipelex/tools/jinja2/exceptions.py
+++ b/pipelex/tools/jinja2/exceptions.py
@@ -1,8 +1,13 @@
+from typing import Any
+
from jinja2.exceptions import SecurityError as JinjaSecurityError
+from mthds.protocol.problem.models import ProblemLocation
from mthds.protocol.problem.registry import CoreCode
+from typing_extensions import Self, override
from pipelex.base_exceptions import SecurityError
from pipelex.errors.error_code_declaration import ErrorCodeSet
+from pipelex.errors.problem import make_location
from pipelex.system.exceptions import ToolError
from pipelex.tools.jinja2.template_owner import TemplateOwner
@@ -61,6 +66,13 @@ class Jinja2TemplateSecurityError(SecurityError):
Pipelex's own templates. On a method's template it is `security.template_refused`, the default; on
Pipelex's own, our template tripping our sandbox is our bug, `runtime.unexpected`.
+ The refused attribute or callable is a name the template's own source spells, as in ``{{ topic['_owner'] }}``, or a
+ value of the run's data, as in ``{{ topic[topic.text] }}``. The render gives it as ``refused_name`` only in the first
+ case, and the problem's ``name`` with it; in the second the problem carries no ``name``, the run's input never
+ reaching the caller, and its sentences say that the template looked the name up from the run's data
+ (`pipelex.errors.problem`). The pipe whose template it was locates it on the template's field, ``template_field``
+ (`locating_template_refusal`).
+
A `SecurityError`, not a `ToolError`, in the family of `UriReadRefusedError`, `SsrfBlockedError` and
`UnsafeSchemaError`, so that a host catching that family never absorbs it into a domain answer and never retries
it. A type of its own, apart from `Jinja2TemplateRenderError`, so that a refusal reads apart from a template that
@@ -69,6 +81,32 @@ class Jinja2TemplateSecurityError(SecurityError):
error_code = ErrorCodeSet(default=CoreCode.SECURITY_TEMPLATE_REFUSED, others=(CoreCode.RUNTIME_UNEXPECTED,))
+ def __init__(self, message: str, *, refused_name: str | None = None):
+ super().__init__(message)
+ # The attribute or the callable the template reached for, by its bare name, when the template's source spells it.
+ self.refused_name = refused_name
+ # The field of the pipe whose template was refused, such as `template` or `prompt`, which that pipe gives.
+ self.template_field: str | None = None
+
+ def with_template_field(self, *, template_field: str) -> Self:
+ """Name, where the pipe that rendered the template catches the refusal, the field its template is written in.
+
+ Returns:
+ This error, so that the catch site can re-raise it.
+ """
+ self.template_field = template_field
+ return self
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ if self.refused_name is None:
+ return {}
+ return {"name": self.refused_name}
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(field=self.template_field)
+
class Jinja2TemplateBudgetError(ToolError):
"""A render tried to spend more than its budget (`jinja2_render_budget.py`).
@@ -121,10 +159,13 @@ class SandboxRefusalError(JinjaSecurityError):
method or function it called. A template reaching ``obj[key]``, ``obj | attr(key)`` or ``namespace({key: value})``
takes that name from the run's data, so the refusal also carries the names its message quotes, ``named``, and its
wording without them, ``anonymous_message``: the render reporting it keeps the message only when the template's own
- source spells every name it quotes (`pipelex.tools.jinja2.jinja2_rendering`).
+ source spells every name it quotes (`pipelex.tools.jinja2.jinja2_rendering`). ``refused_name`` is the bare name of
+ the attribute or the callable it refused, which the render passes on as the ``name`` of `security.template_refused`
+ under the same rule, and withholds otherwise.
"""
- def __init__(self, message: str, *, named: tuple[str, ...], anonymous_message: str):
+ def __init__(self, message: str, *, named: tuple[str, ...], anonymous_message: str, refused_name: str):
super().__init__(message)
self.named = named
self.anonymous_message = anonymous_message
+ self.refused_name = refused_name
diff --git a/pipelex/tools/jinja2/jinja2_rendering.py b/pipelex/tools/jinja2/jinja2_rendering.py
index 06fa3f21d..95e28d253 100644
--- a/pipelex/tools/jinja2/jinja2_rendering.py
+++ b/pipelex/tools/jinja2/jinja2_rendering.py
@@ -1,5 +1,7 @@
import re
-from collections.abc import Awaitable, Callable
+import string
+from collections.abc import Awaitable, Callable, Generator
+from contextlib import contextmanager
from typing import Any, NamedTuple, Protocol, TypeVar
from jinja2 import nodes
@@ -13,7 +15,7 @@ from jinja2.exceptions import (
TemplateSyntaxError,
UndefinedError,
)
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from pipelex.base_exceptions import PipelexError, PipelexUnexpectedError
from pipelex.system.exceptions import ToolError
@@ -57,9 +59,13 @@ def _add_to_templating_context(
templating_context: dict[str, Any], *, jinja2_context_key: Jinja2ContextKey, value: Any, template_owner: TemplateOwner
) -> None:
if jinja2_context_key in templating_context:
- # On a method's template, a method variable named like the reserved key: `method.name_conflict`, the default.
+ # On a method's template, a method variable named like the reserved key: `method.name_conflict`, the default,
+ # which names the key; on Pipelex's own, `runtime.unexpected`, which declares no parameter.
msg = f"Jinja2 context key '{jinja2_context_key}' already in templating_context"
- raise _coded_by_owner(error=Jinja2StuffError(msg), template_owner=template_owner)
+ refusal = Jinja2StuffError(msg)
+ if template_owner == TemplateOwner.METHOD:
+ refusal = refusal.with_params(name=jinja2_context_key, conflict=MethodNameConflictConflict.DUPLICATE_DECLARATION)
+ raise _coded_by_owner(error=refusal, template_owner=template_owner)
templating_context[jinja2_context_key] = value
@@ -154,15 +160,76 @@ class SpelledNames(NamedTuple):
``references`` are the names it reads, stores or reaches as a variable or an attribute: a variable (``invoice``), an
attribute (``.total``), a key written as a literal (``['total']``, ``attr('total')``, ``{'total': ...}``), a
- keyword's name (``namespace(total=...)``), a namespace's attribute it sets and a macro's name. ``filters_and_tests``
+ keyword's name (``namespace(total=...)``), a namespace's attribute it sets, a macro's name, and a name a replacement
+ field of a format string reads, where the literal is the string a ``.format`` or ``.format_map`` call formats
+ (``'{0.total}'.format(invoice)``), which the sandboxed formatter reads as an attribute or a key. ``filters_and_tests``
are the filters and tests it applies. A name the template reaches through a value, ``notes[patient_id]``, is none of
- them: that name is a value of the run's data.
+ them: that name is a value of the run's data. Nor is a word any other string literal holds, ``mode == 'debug'``, which
+ no access reads.
"""
references: frozenset[str]
filters_and_tests: frozenset[str]
+# The methods of a string that format it, reading its replacement fields as attributes and keys of their arguments.
+_FORMAT_METHODS = frozenset({"format", "format_map"})
+
+# A part of a replacement field's name after its first: an attribute (`.total`) or a key (`[total]`), as `str.format` reads it.
+_FORMAT_FIELD_PART_PATTERN = re.compile(r"\.(?P<attribute>[^.\[]*)|\[(?P<key>[^\]]*)\]")
+
+
+# How deep the scan follows replacement fields nested in format specs: `string.Formatter`, which the sandbox's formatter
+# extends, reads a field of the string (depth 0), of its spec (1) and of that spec's spec (2), then refuses to go deeper.
+_FORMAT_SPEC_MAX_DEPTH = 2
+
+
+def _format_string_names(*, format_string: str) -> set[str]:
+ """The names the replacement fields of a `str.format` string read: argument names, attributes and keys, nested fields included.
+
+ The scan runs while a refusal is being built, outside the render's own error handling, so it walks the nested specs
+ without recursion and never past `_FORMAT_SPEC_MAX_DEPTH`. A string nested deeper, or one that does not parse as a
+ format string, counts nothing at all, so a name only it writes is withheld rather than named: the refusal comes out
+ as itself, whatever the literal holds.
+ """
+ names: set[str] = set()
+ pending: list[tuple[str, int]] = [(format_string, 0)]
+ while pending:
+ text, depth = pending.pop()
+ if depth > _FORMAT_SPEC_MAX_DEPTH:
+ return set()
+ try:
+ parsed_fields = list(string.Formatter().parse(text))
+ except ValueError:
+ return set()
+ for _, field_name, format_spec, _ in parsed_fields:
+ if field_name is None:
+ continue
+ argument_name = re.split(r"[.\[]", field_name, maxsplit=1)[0]
+ if argument_name and not argument_name.isdigit():
+ names.add(argument_name)
+ for part in _FORMAT_FIELD_PART_PATTERN.finditer(field_name[len(argument_name) :]):
+ name = part.group("attribute") if part.group("attribute") is not None else part.group("key")
+ if name and not name.isdigit():
+ names.add(name)
+ if format_spec:
+ pending.append((format_spec, depth + 1))
+ return names
+
+
+def _formatted_literal(*, call: nodes.Call) -> str | None:
+ """The string literal a call formats, ``'{0.x}'.format(v)`` or ``'{0.x}' | attr('format')`` called, else ``None``."""
+ match call.node:
+ case nodes.Getattr(node=nodes.Const(value=str() as format_string), attr=str() as method) if method in _FORMAT_METHODS:
+ return format_string
+ case nodes.Filter(name="attr", node=nodes.Const(value=str() as format_string), args=[nodes.Const(value=str() as method)]) if (
+ method in _FORMAT_METHODS
+ ):
+ return format_string
+ case _:
+ return None
+
+
def template_spelled_names(*, template_source: str) -> SpelledNames:
"""The names ``template_source`` spells (see ``SpelledNames``), none when it does not parse.
@@ -176,9 +243,24 @@ def template_spelled_names(*, template_source: str) -> SpelledNames:
return SpelledNames(references=frozenset(), filters_and_tests=frozenset())
references: set[str] = set()
filters_and_tests: set[str] = set()
- spelling_nodes = (nodes.Name, nodes.Getattr, nodes.NSRef, nodes.Keyword, nodes.Getitem, nodes.Pair, nodes.Macro, nodes.Filter, nodes.Test)
+ spelling_nodes = (
+ nodes.Name,
+ nodes.Getattr,
+ nodes.NSRef,
+ nodes.Keyword,
+ nodes.Getitem,
+ nodes.Pair,
+ nodes.Macro,
+ nodes.Filter,
+ nodes.Test,
+ nodes.Call,
+ )
for node in parsed_template.find_all(spelling_nodes):
match node:
+ case nodes.Call():
+ format_string = _formatted_literal(call=node)
+ if format_string is not None:
+ references |= _format_string_names(format_string=format_string)
case nodes.Name(name=str() as name) | nodes.Macro(name=str() as name):
references.add(name)
case nodes.Getattr(attr=str() as attribute) | nodes.NSRef(attr=str() as attribute):
@@ -228,28 +310,42 @@ def _describe_render_error(*, description: str, render_error: BaseException) ->
def _spells_every_name(*, named: tuple[str, ...], template_source: str) -> bool:
- """Whether the parsed template spells every name a refusal quotes (see ``template_spelled_names``)."""
+ """Whether the parsed template spells every name a refusal quotes, the sandbox's and the budget's alike.
+
+ A name spelled as a variable, an attribute or a literal key is the template's own (see ``template_spelled_names``), and
+ so is one a replacement field reads in the format string a ``.format`` or ``.format_map`` call formats, such as the
+ ``_x`` of ``{{ '{0._x}'.format(v) }}``: the template's own literal holds it, so naming it leaks nothing of the run's
+ data. No other text of the template counts, a word another string literal holds (``mode == 'debug _x'``) or the plain
+ text outside its expressions, so a key the data chose that the template happens to write elsewhere is still withheld.
+ """
if not named:
return True
spelled_references = template_spelled_names(template_source=template_source).references
return all(name in spelled_references for name in named)
-def _make_security_error_msg(*, security_error: SecurityError, template_source: str) -> str:
- """The sandbox's refusal, worded with the names it quotes where the template spells them all, without them otherwise.
+def _make_security_refusal(*, security_error: SecurityError, template_source: str) -> Jinja2TemplateSecurityError:
+ """The sandbox's refusal, worded with the names it quotes and naming what it refused only where the template writes them all.
A refusal names what the template reached for, which a template reading ``obj[key]``, ``obj | attr(key)`` or
storing ``namespace({key: value})`` takes from the run's data: the sandbox words each refusal twice
- (``SandboxRefusalError``), and the wording with the names is kept only when the parsed template spells every one.
- A refusal worded by Jinja2 itself, not by the sandbox, is written as a fixed description.
+ (``SandboxRefusalError``), and the wording with the names, and the refused name passed on as the problem's ``name``,
+ are kept only when the parsed template spells every name the refusal quotes (``_spells_every_name``), a format
+ string it formats included, such as the ``_x`` of ``{{ '{0._x}'.format(v) }}``. Otherwise the refusal carries
+ neither, so the run's input reaches no message and no problem. A refusal worded by Jinja2 itself, not by the sandbox, is written as a
+ fixed description and names nothing.
"""
+ refused_name: str | None = None
if isinstance(security_error, SandboxRefusalError):
- is_spelled = _spells_every_name(named=security_error.named, template_source=template_source)
- refusal = (security_error.message or "") if is_spelled else security_error.anonymous_message
+ if _spells_every_name(named=security_error.named, template_source=template_source):
+ refusal = security_error.message or ""
+ refused_name = security_error.refused_name
+ else:
+ refusal = security_error.anonymous_message
else:
description = "the template reached for an attribute, a method or a call the sandbox does not allow"
refusal = _describe_render_error(description=description, render_error=security_error)
- return f"Jinja2 render — refused by the template sandbox: {refusal}"
+ return Jinja2TemplateSecurityError(f"Jinja2 render — refused by the template sandbox: {refusal}", refused_name=refused_name)
# A template nesting macro calls or recursive loops deep enough reaches Python's recursion limit before
@@ -261,8 +357,8 @@ def _make_budget_error_msg(*, budget_error: RenderBudgetExceededError, template_
"""The budget's refusal, which names the operation and its size, never the template source or a value.
A refused call names the callable it called, which a template reading it by ``obj[key]`` or ``obj | attr(key)`` names
- by a value of the run's data: as for the sandbox's refusals, the wording with the names is kept only when the parsed
- template spells every one (``RenderBudgetExceededError``).
+ by a value of the run's data: by the sandbox's own rule (``_spells_every_name``), the wording with the names is kept
+ only when the parsed template spells every one (``RenderBudgetExceededError``).
"""
is_spelled = _spells_every_name(named=budget_error.named, template_source=template_source)
refusal = (budget_error.message or "") if is_spelled else budget_error.anonymous_message
@@ -380,8 +476,9 @@ def _make_render_failure(
(``'dict object' has no attribute '<the key>'``) or a type error's operands.
"""
if isinstance(render_error, SecurityError):
- security_msg = _make_security_error_msg(security_error=render_error, template_source=template_source)
- return _coded_by_owner(error=Jinja2TemplateSecurityError(security_msg), template_owner=template_owner)
+ return _coded_by_owner(
+ error=_make_security_refusal(security_error=render_error, template_source=template_source), template_owner=template_owner
+ )
if isinstance(render_error, (RenderBudgetExceededError, RecursionError)):
budget_msg = (
_make_budget_error_msg(budget_error=render_error, template_source=template_source)
@@ -425,6 +522,26 @@ def _make_render_failure(
raise PipelexUnexpectedError(msg) from render_error
+@contextmanager
+def locating_template_refusal(*, template_field: str) -> Generator[None]:
+ """Locate a refusal of the template sandbox the block raises on ``template_field``, the field the template is written in.
+
+ The render knows the template's source, never which field of which pipe wrote it, so the code that renders a pipe's
+ template wraps the render, naming the field as the method writes it: ``template``, ``prompt``, ``system_prompt``,
+ ``expression`` or ``construct.<field>``. A refusal that already names a field keeps it, the innermost site knowing
+ best.
+
+ Raises:
+ Jinja2TemplateSecurityError: What the block raised, located on the field.
+ """
+ try:
+ yield
+ except Jinja2TemplateSecurityError as exc:
+ if exc.template_field is None:
+ exc.with_template_field(template_field=template_field)
+ raise
+
+
def _render_template_sync(
*, template: _Jinja2Template, template_source: str, templating_context: dict[str, Any], template_owner: TemplateOwner
) -> str:
diff --git a/pipelex/tools/jinja2/jinja2_sandbox.py b/pipelex/tools/jinja2/jinja2_sandbox.py
index 6165c7e2c..cfad9f151 100644
--- a/pipelex/tools/jinja2/jinja2_sandbox.py
+++ b/pipelex/tools/jinja2/jinja2_sandbox.py
@@ -23,10 +23,11 @@ forge content, such as an image pointing at another organisation's storage key.
pydantic methods, `Stuff` and content methods, classes, free functions and class methods, every
method that changes a list, a dict or a set in place, and the few that produce bytes.
- **Refusing.** A refusal raises `jinja2.exceptions.SecurityError` at the point of access, as the
- `SandboxRefusalError` that words it with the names it quotes and without them, which the render
- functions turn into `Jinja2TemplateSecurityError`, a Pipelex `SecurityError` like the runtime's
- other policy refusals, quoting a name only where the template spells it. Jinja's stock sandbox
- returns an undefined value that prints as nothing, which would send a prompt with a hole in it.
+ `SandboxRefusalError` that words it with the names it quotes and without them and carries the bare
+ name it refused, which the render functions turn into `Jinja2TemplateSecurityError`, a Pipelex
+ `SecurityError` like the runtime's other policy refusals, quoting and passing a name on only where
+ the template spells it. Jinja's stock sandbox returns an undefined value that prints as nothing,
+ which would send a prompt with a hole in it.
- **Spending.** What a template may reach says nothing about what it may spend, so every render also
spends from one budget (`jinja2_render_budget.py`), charged by the hooks of this class, by wrappers
around every filter and test, and by a rewrite of the parsed template for what no hook reaches
@@ -111,7 +112,12 @@ def _refuse_callable_in_namespace(*, name: str, value: object) -> None:
callable_description = _describe_callable(obj=value)
msg = f"A template may not store {callable_description.text} in a namespace, as '{name}': a namespace holds data only."
anonymous_msg = f"A template may not store {callable_description.anonymous_text} in a namespace: a namespace holds data only."
- raise SandboxRefusalError(msg, named=(name, *callable_description.named), anonymous_message=anonymous_msg)
+ raise SandboxRefusalError(
+ msg,
+ named=(name, *callable_description.named),
+ anonymous_message=anonymous_msg,
+ refused_name=_callable_name(obj=value),
+ )
class DataNamespace(Namespace):
@@ -210,6 +216,18 @@ def _is_declared_template_method(*, obj: object) -> bool:
return inspect.getattr_static(type(bound_to), obj.__name__, _MISSING) is obj.__func__
+def _callable_name(*, obj: object) -> str:
+ """The bare name of a refused callable, as a template reaches for it: a method's, a function's, a macro's or a class's name.
+
+ A callable value of another kind, which has no name of its own, is named by its class, a name of code.
+ """
+ if isinstance(obj, (types.BuiltinMethodType, types.MethodType, types.FunctionType, type)):
+ return obj.__name__
+ if isinstance(obj, Macro):
+ return obj.name
+ return type(obj).__name__
+
+
class _CallableDescription(NamedTuple):
"""A refused callable described with its name, ``text``, and without it, ``anonymous_text``.
@@ -349,7 +367,7 @@ class PipelexTemplateEnvironment(ImmutableSandboxedEnvironment):
type_name = type(obj).__name__
msg = f"A template may not read '{attribute}' on a '{type_name}' value."
anonymous_msg = f"A template may not read an unsafe name on a '{type_name}' value."
- raise SandboxRefusalError(msg, named=(attribute,), anonymous_message=anonymous_msg)
+ raise SandboxRefusalError(msg, named=(attribute,), anonymous_message=anonymous_msg, refused_name=attribute)
@override
def wrap_str_format(self, value: Any) -> Callable[..., str] | None:
@@ -368,7 +386,7 @@ class PipelexTemplateEnvironment(ImmutableSandboxedEnvironment):
anonymous_msg = (
f"A template may not call {callable_description.anonymous_text}: templates read data and call methods of plain values only."
)
- raise SandboxRefusalError(msg, named=callable_description.named, anonymous_message=anonymous_msg)
+ raise SandboxRefusalError(msg, named=callable_description.named, anonymous_message=anonymous_msg, refused_name=_callable_name(obj=obj))
# A callable the sandbox lets a template call is a method of code, a plain value's or one a type declares, or the
# template's own macro, so the budget's message names it, but only where the template spells its name: one read
# by `obj[key]` or `obj | attr(key)` is named by a value of the run's data.
diff --git a/pipelex/tools/misc/exceptions.py b/pipelex/tools/misc/exceptions.py
index 2dc9e7f60..0e2f918e2 100644
--- a/pipelex/tools/misc/exceptions.py
+++ b/pipelex/tools/misc/exceptions.py
@@ -8,6 +8,7 @@ from typing_extensions import override
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, ErrorCodeSet
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
+from pipelex.methods.package_reason import MethodPackageReason
from pipelex.system.exceptions import ToolError
@@ -91,10 +92,12 @@ class RemoteFileFetchError(ToolError):
``input.url_unreachable``; a file a provider's answer pointed at is
``provider.response_invalid``, which the provider's raise site chooses.
- The URL's host, and the input it belongs to, are facts the error holds, not parameters its raise
- site gives: a catch site can choose another code for it, and the problem takes each fact only for
- a code that declares it, so ``provider.response_invalid``, which declares neither, is given no
- parameter it would refuse. The fetch does not know the input; a catch site that does, such as an
+ The URL's host, what went wrong, and the input it belongs to are facts the error holds, not parameters
+ its raise site gives: a catch site can choose another code for it, and the problem takes each fact only
+ for a code that declares it, so ``input.url_unreachable`` takes the host, ``input.file_unreadable`` the
+ reason, and ``provider.response_invalid``, which declares none of them, is given no parameter it would
+ refuse. The reason says what the server or the network answered, an HTTP status or the class of the
+ request's failure, never the URL. The fetch does not know the input; a catch site that does, such as an
extract worker, names it with :meth:`with_input`.
"""
@@ -107,10 +110,12 @@ class RemoteFileFetchError(ToolError):
detail="Check that the URL serves the file to a plain HTTP client, or upload the file and reference it instead.",
)
- def __init__(self, message: str, *, host: str | None = None):
+ def __init__(self, message: str, *, host: str | None = None, reason: str | None = None):
super().__init__(message)
# The host of the URL that could not be fetched, `None` when the URL names none the parser can read.
self.host = host
+ # What the server or the network answered, such as `the server answered HTTP 404`, never naming the URL.
+ self.reason = reason
# The input the URL belongs to, as a caller writes it, which the catch site that knows it gives.
self.input_name: str | None = None
@@ -125,7 +130,7 @@ class RemoteFileFetchError(ToolError):
@override
def problem_params(self) -> dict[str, Any]:
- return {"host": self.host, "input": self.input_name}
+ return {"host": self.host, "reason": self.reason, "input": self.input_name}
class SemVerError(ToolError):
@@ -133,6 +138,10 @@ class SemVerError(ToolError):
error_code = CoreCode.METHOD_PACKAGE_INVALID
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"reason": MethodPackageReason.VERSION_INVALID}
+
class UrlSyntaxError(ToolError, ValueError):
"""Raised when a URL is not a well-formed http(s) URL, checked without touching the network.
diff --git a/pipelex/tools/misc/file_fetch_utils.py b/pipelex/tools/misc/file_fetch_utils.py
index 79a9b78e8..a6509ceb5 100644
--- a/pipelex/tools/misc/file_fetch_utils.py
+++ b/pipelex/tools/misc/file_fetch_utils.py
@@ -83,11 +83,12 @@ async def fetch_file_and_content_type_from_url_httpx(
response.raise_for_status()
except httpx.HTTPStatusError as exc:
status_code = exc.response.status_code
- msg = f"Could not fetch a remote file: the server answered HTTP {status_code}"
+ reason = f"the server answered HTTP {status_code}"
+ msg = f"Could not fetch a remote file: {reason}"
if status_code in _TRANSIENT_HTTP_STATUSES or status_code >= _HTTP_SERVER_ERROR_FLOOR:
# The server is there but cannot answer now: a retry may get the file.
raise RemoteFileFetchError(msg, host=host).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from exc
- raise RemoteFileFetchError(msg, host=host) from exc
+ raise RemoteFileFetchError(msg, host=host, reason=reason) from exc
except httpx.TimeoutException as exc:
msg = "Could not fetch a remote file: the request timed out"
raise RemoteFileFetchError(msg, host=host).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from exc
@@ -95,13 +96,15 @@ async def fetch_file_and_content_type_from_url_httpx(
msg = "Could not fetch a remote file: the host could not be reached"
raise RemoteFileFetchError(msg, host=host).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from exc
except httpx.RequestError as exc:
- msg = f"Could not fetch a remote file: the request failed ({type(exc).__name__})"
- raise RemoteFileFetchError(msg, host=host) from exc
+ reason = f"the request failed ({type(exc).__name__})"
+ msg = f"Could not fetch a remote file: {reason}"
+ raise RemoteFileFetchError(msg, host=host, reason=reason) from exc
except httpx.InvalidURL as exc:
# Raised while the request is built, before anything is sent, and not a `RequestError`: its text quotes the
# part of the URL the parser refused, so it is named by what failed alone.
- msg = "Could not fetch a remote file: the URL does not parse"
- raise RemoteFileFetchError(msg) from exc
+ reason = "the URL does not parse"
+ msg = f"Could not fetch a remote file: {reason}"
+ raise RemoteFileFetchError(msg, reason=reason) from exc
declared_content_type: str | None = response.headers.get("content-type")
if declared_content_type is None:
diff --git a/pipelex/tools/misc/string_utils.py b/pipelex/tools/misc/string_utils.py
index 74666ef7d..4dcefe862 100644
--- a/pipelex/tools/misc/string_utils.py
+++ b/pipelex/tools/misc/string_utils.py
@@ -1,5 +1,7 @@
+import difflib
import re
import unicodedata
+from collections.abc import Iterable
from typing import Any
@@ -489,3 +491,18 @@ def matches_wildcard_pattern(text: str, *, pattern: str) -> bool:
else:
# Exact match
return text == pattern
+
+
+def close_matches(*, name: str, candidates: Iterable[str], cutoff: float, max_matches: int) -> list[str]:
+ """The candidates nearest a name, nearest first, as a refusal offers what its caller most likely meant.
+
+ Args:
+ name: The name that matched nothing.
+ candidates: The names that may be offered.
+ cutoff: How near a candidate must be to be offered, as difflib's similarity ratio, between 0 and 1.
+ max_matches: How many candidates are offered at most.
+
+ Returns:
+ The candidates offered, nearest first; an empty list when none is near.
+ """
+ return difflib.get_close_matches(name, list(candidates), n=max_matches, cutoff=cutoff)
diff --git a/pipelex/tools/storage/exceptions.py b/pipelex/tools/storage/exceptions.py
index 17ed6e2e1..5b3d5b1e0 100644
--- a/pipelex/tools/storage/exceptions.py
+++ b/pipelex/tools/storage/exceptions.py
@@ -1,6 +1,7 @@
-from typing import ClassVar
+from typing import Any, ClassVar
from mthds.protocol.problem.registry import CoreCode
+from typing_extensions import override
from pipelex.base_exceptions import PipelexConfigError
from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, ErrorCodeSet
@@ -98,6 +99,11 @@ class StorageS3Error(StorageError):
),
)
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ # The kind of storage `pipelex.storage.unavailable` names; a configuration code declares no such parameter.
+ return {"scheme": "s3"}
+
class StorageGcpError(StorageError):
"""Raised when a GCP storage operation fails.
@@ -110,6 +116,11 @@ class StorageGcpError(StorageError):
default=PipelexErrorCode.STORAGE_UNAVAILABLE, others=(PipelexErrorCode.CONFIG_CREDENTIAL_REFUSED,)
)
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ # The kind of storage `pipelex.storage.unavailable` names; a configuration code declares no such parameter.
+ return {"scheme": "gcs"}
+
class StorageGcpCredentialsError(StorageGcpError):
"""Raised when GCP credentials file is not found or invalid."""
diff --git a/pipelex/tools/storage/gcp_storage_provider.py b/pipelex/tools/storage/gcp_storage_provider.py
index 19964a1d3..917e62e45 100644
--- a/pipelex/tools/storage/gcp_storage_provider.py
+++ b/pipelex/tools/storage/gcp_storage_provider.py
@@ -2,7 +2,7 @@ import asyncio
import importlib.util
from datetime import timedelta
from pathlib import Path
-from typing import Any
+from typing import Any, ClassVar
from urllib.parse import quote
from typing_extensions import override
@@ -14,7 +14,7 @@ from pipelex.tools.storage.exceptions import (
StorageGcpCredentialsError,
StorageGcpError,
)
-from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredData
+from pipelex.tools.storage.storage_provider_abstract import StorageKind, StorageProviderAbstract, StoredData
# GCS signed URL signing process version (v4 is recommended, v2 is deprecated)
GCS_SIGNED_URL_VERSION = "v4"
@@ -27,6 +27,8 @@ class GcpStorageProvider(StorageProviderAbstract):
Uses asyncio.to_thread to wrap sync GCS operations.
"""
+ storage_kind: ClassVar[StorageKind] = "gcs"
+
def __init__(
self,
bucket_name: str,
@@ -114,7 +116,7 @@ class GcpStorageProvider(StorageProviderAbstract):
return StoredData(data=data, mime_type=content_type)
except NotFound as exc: # pyright: ignore[reportUnknownVariableType]
msg = f"Object not found in GCS: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
except (Forbidden, Unauthorized) as exc: # pyright: ignore[reportUnknownVariableType]
msg = f"Failed to load object from GCS: '{key}': {exc}"
raise StorageGcpError(msg).with_error_code(PipelexErrorCode.CONFIG_CREDENTIAL_REFUSED) from exc
@@ -169,7 +171,7 @@ class GcpStorageProvider(StorageProviderAbstract):
return data[:nb_bytes]
except NotFound as exc: # pyright: ignore[reportUnknownVariableType]
msg = f"Object not found in GCS: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
except RequestRangeNotSatisfiable: # pyright: ignore[reportUnknownVariableType]
# GCS refuses any range over an empty object: its head is empty.
return b""
@@ -223,7 +225,7 @@ class GcpStorageProvider(StorageProviderAbstract):
raise StorageGcpError(msg) from exc
if blob is None:
msg = f"Object not found in GCS: '{key}'"
- raise StorageFileNotFoundError(msg)
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind)
size: int = blob.size
return size
diff --git a/pipelex/tools/storage/in_memory_storage_provider.py b/pipelex/tools/storage/in_memory_storage_provider.py
index 593b04ebf..91e03bdcd 100644
--- a/pipelex/tools/storage/in_memory_storage_provider.py
+++ b/pipelex/tools/storage/in_memory_storage_provider.py
@@ -1,10 +1,12 @@
+from typing import ClassVar
+
from pydantic import RootModel
from typing_extensions import override
from pipelex.tools.misc.exceptions import FileTypeError
from pipelex.tools.misc.filetype_utils import detect_file_type_from_bytes
from pipelex.tools.storage.exceptions import StorageFileNotFoundError
-from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredData
+from pipelex.tools.storage.storage_provider_abstract import StorageKind, StorageProviderAbstract, StoredData
InMemoryStorageRoot = dict[str, bytes]
@@ -12,6 +14,8 @@ InMemoryStorageRoot = dict[str, bytes]
class InMemoryStorageProvider(RootModel[InMemoryStorageRoot], StorageProviderAbstract):
"""In-memory storage provider using a dict mapping URIs to bytes."""
+ storage_kind: ClassVar[StorageKind] = "memory"
+
root: InMemoryStorageRoot = {}
@override
@@ -29,7 +33,7 @@ class InMemoryStorageProvider(RootModel[InMemoryStorageRoot], StorageProviderAbs
"""
if key not in self.root:
msg = f"File not found: '{key}'"
- raise StorageFileNotFoundError(msg)
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind)
data = self.root[key]
@@ -52,7 +56,7 @@ class InMemoryStorageProvider(RootModel[InMemoryStorageRoot], StorageProviderAbs
"""
if key not in self.root:
msg = f"File not found: '{key}'"
- raise StorageFileNotFoundError(msg)
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind)
return len(self.root[key])
@override
diff --git a/pipelex/tools/storage/local_storage_provider.py b/pipelex/tools/storage/local_storage_provider.py
index 646682fad..b382382b8 100644
--- a/pipelex/tools/storage/local_storage_provider.py
+++ b/pipelex/tools/storage/local_storage_provider.py
@@ -1,6 +1,7 @@
import contextlib
import os
from pathlib import Path
+from typing import ClassVar
from uuid import uuid4
import aiofiles
@@ -9,7 +10,7 @@ from typing_extensions import override
from pipelex.tools.misc.exceptions import FileTypeError
from pipelex.tools.misc.filetype_utils import detect_file_type_from_path
from pipelex.tools.storage.exceptions import StorageFileNotFoundError, StorageInvalidUriError, StorageLocalError
-from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredData
+from pipelex.tools.storage.storage_provider_abstract import StorageKind, StorageProviderAbstract, StoredData
class LocalStorageProvider(StorageProviderAbstract):
@@ -18,6 +19,8 @@ class LocalStorageProvider(StorageProviderAbstract):
Files are stored relative to a root path, with keys being relative path strings.
"""
+ storage_kind: ClassVar[StorageKind] = "local"
+
def __init__(self, root_path: Path) -> None:
"""Initialize the local storage provider.
@@ -79,7 +82,7 @@ class LocalStorageProvider(StorageProviderAbstract):
if not file_path.exists():
msg = f"File not found: '{key}'"
- raise StorageFileNotFoundError(msg)
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind)
try:
async with aiofiles.open(file_path, "rb") as file_handle: # pyright: ignore[reportUnknownMemberType]
@@ -87,7 +90,7 @@ class LocalStorageProvider(StorageProviderAbstract):
except FileNotFoundError as exc:
# TOCTOU: the file passed exists() above but was removed before the open.
msg = f"File not found: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
except OSError as exc:
msg = f"Failed to read file '{key}': {exc}"
raise StorageLocalError(msg) from exc
@@ -116,7 +119,7 @@ class LocalStorageProvider(StorageProviderAbstract):
stat_result = file_path.stat()
except FileNotFoundError as exc:
msg = f"File not found: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
except OSError as exc:
msg = f"Failed to read the size of file '{key}': {exc}"
raise StorageLocalError(msg) from exc
diff --git a/pipelex/tools/storage/s3_storage_provider.py b/pipelex/tools/storage/s3_storage_provider.py
index f6e9e4429..d404c8e41 100644
--- a/pipelex/tools/storage/s3_storage_provider.py
+++ b/pipelex/tools/storage/s3_storage_provider.py
@@ -1,7 +1,7 @@
import base64
import importlib.util
from asyncio import sleep
-from typing import Any
+from typing import Any, ClassVar
from urllib.parse import quote
from typing_extensions import override
@@ -13,7 +13,7 @@ from pipelex.tools.storage.exceptions import (
StorageFileNotFoundError,
StorageS3Error,
)
-from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredData
+from pipelex.tools.storage.storage_provider_abstract import StorageKind, StorageProviderAbstract, StoredData
# The S3 error codes by which S3 refuses the credentials themselves, rather than failing to serve: an operator fixes these.
_S3_CREDENTIAL_REFUSAL_CODES = frozenset({"AccessDenied", "InvalidAccessKeyId", "SignatureDoesNotMatch", "ExpiredToken", "InvalidToken"})
@@ -53,6 +53,8 @@ class S3StorageProvider(StorageProviderAbstract):
Uses aiobotocore for async S3 operations.
"""
+ storage_kind: ClassVar[StorageKind] = "s3"
+
def __init__(
self,
bucket_name: str,
@@ -156,7 +158,7 @@ class S3StorageProvider(StorageProviderAbstract):
return StoredData(data=data, mime_type=content_type)
except client.exceptions.NoSuchKey as exc:
msg = f"Object not found in S3: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
except client.exceptions.NoSuchBucket as exc:
msg = f"Bucket not found in S3: '{self._bucket_name}'"
raise StorageS3Error(msg).with_error_code(PipelexErrorCode.CONFIG_INVALID) from exc
@@ -164,7 +166,7 @@ class S3StorageProvider(StorageProviderAbstract):
error_code = (exc.response.get("Error") or {}).get("Code", "Unknown")
if error_code == "NoSuchKey":
msg = f"Object not found in S3: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
msg = f"S3 ClientError ({error_code}) for key '{key}'"
raise StorageS3Error(msg).with_error_code(_code_for_s3_client_error(s3_error_code=error_code)) from exc
except NoCredentialsError as exc:
@@ -207,7 +209,7 @@ class S3StorageProvider(StorageProviderAbstract):
return data[:nb_bytes]
except client.exceptions.NoSuchKey as exc:
msg = f"Object not found in S3: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
except client.exceptions.NoSuchBucket as exc:
msg = f"Bucket not found in S3: '{self._bucket_name}'"
raise StorageS3Error(msg).with_error_code(PipelexErrorCode.CONFIG_INVALID) from exc
@@ -218,7 +220,7 @@ class S3StorageProvider(StorageProviderAbstract):
return b""
if error_code == "NoSuchKey":
msg = f"Object not found in S3: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
msg = f"S3 ClientError ({error_code}) for key '{key}'"
raise StorageS3Error(msg).with_error_code(_code_for_s3_client_error(s3_error_code=error_code)) from exc
except NoCredentialsError as exc:
@@ -259,7 +261,7 @@ class S3StorageProvider(StorageProviderAbstract):
# A HEAD answer has no body, so a missing object comes back as the bare status code.
if error_code in {"404", "NoSuchKey", "NotFound"}:
msg = f"Object not found in S3: '{key}'"
- raise StorageFileNotFoundError(msg) from exc
+ raise StorageFileNotFoundError(msg).with_params(scheme=self.storage_kind) from exc
msg = f"S3 ClientError ({error_code}) for key '{key}'"
raise StorageS3Error(msg).with_error_code(_code_for_s3_client_error(s3_error_code=error_code)) from exc
except NoCredentialsError as exc:
diff --git a/pipelex/tools/storage/storage_provider_abstract.py b/pipelex/tools/storage/storage_provider_abstract.py
index add5b9b98..d31d352dd 100644
--- a/pipelex/tools/storage/storage_provider_abstract.py
+++ b/pipelex/tools/storage/storage_provider_abstract.py
@@ -1,6 +1,6 @@
import hashlib
from abc import ABC, abstractmethod
-from typing import NamedTuple
+from typing import ClassVar, Literal, NamedTuple
from mthds.protocol.problem.registry import CoreCode
@@ -8,6 +8,10 @@ from pipelex.tools.storage.exceptions import StorageChecksumMismatchError, Stora
PIPELEX_STORAGE_SCHEME = "pipelex-storage://"
+# The kind of storage a provider is, as the `scheme` parameter of the `pipelex.storage.*` codes names it: one Pipelex
+# ships, or `plugin` for a storage plugin's own.
+StorageKind = Literal["local", "s3", "gcs", "memory", "plugin"]
+
class StoredData(NamedTuple):
"""Data returned from storage with optional MIME type metadata."""
@@ -26,8 +30,13 @@ class StorageProviderAbstract(ABC):
- _load_with_metadata(key): Load data with MIME type by key (without scheme)
- _store(data, key, content_type): Store data and return URI
- public_url(uri): Return human-readable link for URI
+
+ A provider Pipelex ships names its kind in ``storage_kind``, the ``scheme`` its refusals carry; a plugin's provider
+ keeps the default, ``plugin``.
"""
+ storage_kind: ClassVar[StorageKind] = "plugin"
+
def _strip_scheme(self, uri: str) -> str:
"""Extract key from URI, raising error if invalid.
diff --git a/pipelex/tools/tabular/exceptions.py b/pipelex/tools/tabular/exceptions.py
index 3f975520d..9889397f0 100644
--- a/pipelex/tools/tabular/exceptions.py
+++ b/pipelex/tools/tabular/exceptions.py
@@ -1,8 +1,10 @@
-from typing import ClassVar
+from typing import Any, ClassVar, Self
from mthds.protocol.problem.registry import CoreCode
+from typing_extensions import override
from pipelex.errors.error_code_declaration import ErrorCodeDeclaration, ErrorCodeSet
+from pipelex.errors.problem import ProblemLocation, make_location
from pipelex.system.exceptions import ToolError
@@ -13,13 +15,48 @@ class CsvError(ToolError):
that does not match the row concept, a cell that cannot be coerced), so the default is
``input.invalid``. Writing a table the CLI's ``--save-csv`` asked for is
``request.invalid``, and a delimiter or a row the codec was handed by its own caller is
- ``runtime.unexpected``.
+ ``runtime.unexpected``. A table input refused before the codec reads it says what happened instead: a URL that
+ does not parse is ``input.file_unreadable``, a URL that is not a local path, which this runtime does not read a
+ table from, ``request.unsupported``, and a concept with no structure class to read rows into
+ ``method.concept_invalid``.
+
+ The codec reads a file and does not know the run input it was given as: the site that does names it with
+ :meth:`with_input`, which gives the problem its ``location.input`` and, for a code declaring it, its ``input``.
"""
error_code: ClassVar[ErrorCodeDeclaration] = ErrorCodeSet(
- default=CoreCode.INPUT_INVALID, others=(CoreCode.REQUEST_INVALID, CoreCode.RUNTIME_UNEXPECTED)
+ default=CoreCode.INPUT_INVALID,
+ others=(
+ CoreCode.REQUEST_INVALID,
+ CoreCode.RUNTIME_UNEXPECTED,
+ CoreCode.INPUT_FILE_UNREADABLE,
+ CoreCode.REQUEST_UNSUPPORTED,
+ CoreCode.METHOD_CONCEPT_INVALID,
+ ),
)
+ def __init__(self, message: str):
+ super().__init__(message)
+ # The run input the table was given as, which the site that knows it gives.
+ self.input_name: str | None = None
+
+ def with_input(self, *, input_name: str | None) -> Self:
+ """Name the run input the table was given as, where the site raising or catching the error knows it.
+
+ Returns:
+ This error, so that the site can raise it.
+ """
+ self.input_name = input_name
+ return self
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"input": self.input_name}
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(input_name=self.input_name)
+
class CsvReadError(CsvError):
"""Raised when a CSV file cannot be opened, decoded, or parsed.
diff --git a/pipelex/tools/uri/exceptions.py b/pipelex/tools/uri/exceptions.py
index e0590bb99..437cf5504 100644
--- a/pipelex/tools/uri/exceptions.py
+++ b/pipelex/tools/uri/exceptions.py
@@ -1,11 +1,13 @@
from enum import StrEnum
from typing import Any
+from mthds.protocol.problem.models import ProblemLocation
from mthds.protocol.problem.registry import CoreCode
from typing_extensions import override
from pipelex.base_exceptions import SecurityError
from pipelex.errors.error_code_declaration import ErrorCodeSet
+from pipelex.errors.problem import make_location
from pipelex.errors.security_target import SecurityTargetClass
@@ -53,9 +55,14 @@ class UriReadRefusedError(SecurityError):
error_code = ErrorCodeSet(default=CoreCode.SECURITY_INPUT_URL_REFUSED, others=(CoreCode.SECURITY_METHOD_URL_REFUSED,))
- def __init__(self, message: str, *, reason: UriReadRefusalReason):
+ def __init__(self, message: str, *, reason: UriReadRefusalReason, input_name: str | None = None, field: str | None = None):
super().__init__(message)
self.reason = reason
+ # The run input whose file the URL is, when the caller gave it: the `input` of `security.input_url_refused`, the
+ # root of the file's path. The path down to the file, the input included, such as `documents[1]`, is the
+ # location's `field`.
+ self.input_name = input_name
+ self.field = field
# The reason is the class of destination refused, so the security event names it without the raise site saying so.
self.with_security_target_class(reason.target_class)
@@ -64,4 +71,11 @@ class UriReadRefusedError(SecurityError):
# The problem's `target_class` is a value the registry lists, which the code's sentence reads as a word ("points
# at a private target"): `scheme` for a local path, and `private` for another tenant's key, which the registry
# lists no value for. The security event names the finer class the refusal states, `foreign_storage_key`.
- return {"reason": self.reason.desc, "target_class": self.reason.target_class.listed_target_class}
+ params: dict[str, Any] = {"reason": self.reason.desc, "target_class": self.reason.target_class.listed_target_class}
+ if self.input_name is not None:
+ params["input"] = self.input_name
+ return params
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(input_name=self.input_name, field=self.field)
diff --git a/pipelex/tools/uri/uri_read_scope.py b/pipelex/tools/uri/uri_read_scope.py
index 2756fa204..1d1db1fdd 100644
--- a/pipelex/tools/uri/uri_read_scope.py
+++ b/pipelex/tools/uri/uri_read_scope.py
@@ -38,13 +38,17 @@ class UriReference(NamedTuple):
position: str
-def authorize_uri_read(*, uri: str, read_scope: str | None, position: str) -> None:
+def authorize_uri_read(*, uri: str, read_scope: str | None, position: str, input_name: str | None = None, field: str | None = None) -> None:
"""Refuse the read of `uri` if the run's read scope does not allow it.
Args:
uri: The URL about to be read.
read_scope: The run's read scope, ``None`` for an unscoped run, which reads everything.
position: Where the URL sits, named in the refusal instead of the URL itself.
+ input_name: The run input whose file the URL is, when it is one, which the refusal names as its ``input``: the
+ root of the file's path, never the path itself.
+ field: The path from that input down to the file, the input included, such as ``documents[1]``, which the
+ refusal's location names as its ``field``.
Raises:
UriReadRefusedError: the URL is a storage key outside the read scope, or a local path.
@@ -63,7 +67,7 @@ def authorize_uri_read(*, uri: str, read_scope: str | None, position: str) -> No
case ResolvedLocalPath():
reason = UriReadRefusalReason.LOCAL_PATH
msg = f"Refused to read {position}: {reason.desc}. Pass the file as an input of the run, or upload it first."
- raise UriReadRefusedError(msg, reason=reason)
+ raise UriReadRefusedError(msg, reason=reason, input_name=input_name, field=field)
def authorize_uri_reads(*, uri_references: list[UriReference], read_scope: str | None) -> None:
diff --git a/pyproject.toml b/pyproject.toml
index ff4b9409e..06d32a909 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -327,6 +327,7 @@ markers = [
"codex_disabled: tests that should not run in Codex",
"dry_runnable: tests that can be run in dry-run mode",
"pipelex_api: tests that require access to the Pipelex API",
+ "builds_problems_without_required_params(reason): the test builds a problem lacking a parameter its code requires on purpose, which the sweep of tests/unit/conftest.py otherwise fails",
]
[tool.coverage.run]
diff --git a/subject_grants.toml b/subject_grants.toml
index 72a872630..6c8094a50 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -3932,10 +3932,6 @@ rationale = "Single-operand transformation of the code; the rest is context."
param = "loc"
rationale = "Verb-object: categorizes the error at the loc; context stays keyword."
-["pipelex/mthds_parsing/validation_error_categorizer.py::_categorize_syntax_validation_error"]
-param = "message"
-rationale = "Verb-object: categorizes the error message; context stays keyword."
-
["pipelex/mthds_parsing/validation_error_categorizer.py::_categorize_typeless_pipe_error"]
param = "message"
rationale = "Verb-object: categorizes the message; the rest is context."
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 735b6e066..6187c3a8a 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -56,7 +56,7 @@ CrateNormalizationError | one of runtime.unexpected, method.cycle
CredentialsError | abstract
CsvCoercionError | input.invalid
CsvColumnError | input.invalid
-CsvError | one of input.invalid, request.invalid, runtime.unexpected
+CsvError | one of input.invalid, request.invalid, runtime.unexpected, input.file_unreadable, request.unsupported, method.concept_invalid
CsvFlatnessError | input.invalid
CsvReadError | input.file_unreadable
DateContentError | pipe.function_raised
@@ -228,7 +228,7 @@ MistralModelListingError | provider.response_invalid
MistralPluginError | abstract
MistralWorkerConfigurationError | pipelex.config.invalid
MockUsageOnLiveRunError | request.invalid
-ModelChoiceNotFoundError | one of model.unknown, model.capability_unsupported
+ModelChoiceNotFoundError | one of model.unknown, model.capability_unsupported, model.unavailable
ModelDeckChoiceUnresolvedError | one of pipelex.config.invalid, model.unavailable
ModelDeckNotFoundError | pipelex.config.invalid
ModelDeckPresetValidationError | pipelex.config.invalid
@@ -376,6 +376,7 @@ TracebackMessageError | abstract
TreeModuleShadowingError | method.name_conflict
TreePythonError | one of runtime.unexpected, request.unsupported, method.name_conflict
TreePythonHeldError | runtime.unavailable
+TreePythonSyntaxError | method.syntax
TypesafeError | pipelex.config.credential_missing
TypesafeJudgmentResponseError | provider.response_invalid
TypesafeQuestionUnsupportedError | one of model.capability_unsupported, runtime.unexpected
diff --git a/tests/data/errors/foreign_raises.txt b/tests/data/errors/foreign_raises.txt
index 67bbb37ae..4c18850ac 100644
--- a/tests/data/errors/foreign_raises.txt
+++ b/tests/data/errors/foreign_raises.txt
@@ -8,7 +8,8 @@
# - validator: a builtin raised in a helper only pydantic validators call, which pydantic wraps;
# - private: a private class caught in the module that defines it, which no reader sees;
# - carrier: a class a library or protocol expects by type (the import system's ImportError, httpx's transport
-# errors, the standard's method tree refusal its callers translate) that the scan cannot recognise by its name alone;
+# errors, the standard's method tree refusal its callers translate, the Jinja2 SecurityError the template sandbox
+# stops a render with) that the scan cannot recognise by its name alone;
# - tooling: developer or release code outside the exempt directories, which only the development CLI calls;
# - caught: a builtin raised in a module that must import nothing of Pipelex, which its every caller catches by type.
#
diff --git a/tests/integration/pipelex/libraries/test_dependency_private_pipes.py b/tests/integration/pipelex/libraries/test_dependency_private_pipes.py
index 922af576a..de526ca57 100644
--- a/tests/integration/pipelex/libraries/test_dependency_private_pipes.py
+++ b/tests/integration/pipelex/libraries/test_dependency_private_pipes.py
@@ -74,6 +74,31 @@ class TestDependencyPrivatePipes:
(PipeValidationErrorType.UNEXPORTED_PIPE_DEPENDENCY, "go", private_ref)
]
+ def test_a_consumer_s_unresolved_reference_is_offered_no_private_pipe(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """The private `helper` is nearest the typo, but the consumer cannot name it: the refusal offers only exported pipes."""
+ isolate_installed_methods(mocker=mocker, root=tmp_path)
+ install_probe(root=tmp_path, manifest=ProbePackageTestData.MANIFEST_EXPORTING_ONLY_THE_ENTRY)
+ typo_ref = f"{PROBE_ALIAS}->probe_dep.helpr"
+ consumer_files = write_consumer(
+ root=tmp_path,
+ bundles={
+ "consumer.mthds": ProbePackageTestData.CONSUMER_BUNDLE,
+ "typo.mthds": ProbePackageTestData.consumer_calling(pipe_ref=typo_ref).replace("probe_consumer", "probe_typo"),
+ },
+ )
+ library_manager = get_library_manager()
+ library_id, _ = library_manager.open_library()
+ try:
+ with pytest.raises(LibraryLoadingError) as exc_info:
+ library_manager.load_libraries(library_id=library_id, library_file_paths=consumer_files)
+ finally:
+ library_manager.teardown(library_id=library_id)
+
+ items = exc_info.value.pipe_concept_validation_errors or []
+ assert [(item.error_type, item.missing_pipe_code, item.params) for item in items] == [
+ (PipeValidationErrorType.UNRESOLVED_PIPE_DEPENDENCY, typo_ref, {"candidates": []})
+ ]
+
@pytest.mark.parametrize("orphan_ref", [f"{PROBE_ALIAS}->probe_dep.orphan", f"{PROBE_ALIAS}->orphan"])
def test_a_reference_to_a_withheld_private_pipe_is_refused_as_unexported(self, tmp_path: Path, mocker: MockerFixture, orphan_ref: str) -> None:
"""`orphan` is never built, but the package declares it: a reference to it is unexported, not missing."""
diff --git a/tests/integration/pipelex/pipeline/test_data.py b/tests/integration/pipelex/pipeline/test_data.py
index e2bd068ef..5a74d58df 100644
--- a/tests/integration/pipelex/pipeline/test_data.py
+++ b/tests/integration/pipelex/pipeline/test_data.py
@@ -638,7 +638,7 @@ type = "PipeCondition"
description = "Choose the lane a parcel goes down"
inputs = { parcel = "Parcel", lane = "Text" }
output = "Parcel"
-expression_template = "{% if lane.text == 'express' %}{{ lane.text | frob_the_lane }}{% else %}quietly_routed{% endif %}"
+<expression-line>
outcomes = { express = "send_express" }
default_outcome = "send_standard"
@@ -657,6 +657,13 @@ output = "Parcel"
template = "Standard: $parcel"
"""
+ # Replaced by the condition's field, written as a template or as an expression, each with the branch in it.
+ EXPRESSION_LINE_SLOT: ClassVar[str] = "<expression-line>"
+ EXPRESSION_TEMPLATE_LINE: ClassVar[str] = (
+ "expression_template = \"{% if lane.text == 'express' %}{{ lane.text | frob_the_lane }}{% else %}quietly_routed{% endif %}\""
+ )
+ EXPRESSION_LINE: ClassVar[str] = "expression = \"lane.text | frob_the_lane if lane.text == 'express' else 'quietly_routed'\""
+
# Replaced by the prompt field each case puts the branch in, `prompt` or `system_prompt`.
PROMPT_FIELD_SLOT: ClassVar[str] = "<prompt-field>"
# A step whose prompt is only parsed at load, so its unknown filter in a branch passes the load and fails the render.
@@ -700,76 +707,6 @@ prompt = "Read the label from $note"
"""
-class RunContentMarkerTestData:
- """Steps that each fail on the run's own data, which carries a marker no log line and no view may hold."""
-
- # A value no secret pattern matches, so no redaction hides it: only the raise sites' own rule can keep it out.
- MARKER: ClassVar[str] = "zebra-quartz-ledger-5521"
-
- # One step per family of raise site: the input shaper, the content factory, a method's function, the composer and a
- # structure refusing the model's answer, the stand-in model answering the marker for every field.
- MTHDS: ClassVar[str] = """
-domain = "run_content_marker"
-description = "Steps that each fail on the run's own data"
-
-[concept.Tally]
-description = "A count"
-
-[concept.Tally.structure]
-count = { type = "integer", description = "How many there are", required = true }
-
-[concept.Ticket]
-description = "A ticket and its priority"
-
-[concept.Ticket.structure]
-priority = { choices = ["low", "high"], description = "How urgent it is", required = true }
-
-[pipe.echo_amount]
-type = "PipeCompose"
-description = "Read a number input"
-inputs = { amount = "Number" }
-output = "Text"
-template = "{{ amount }}"
-
-[pipe.echo_tally]
-type = "PipeCompose"
-description = "Read a structured input"
-inputs = { tally = "Tally" }
-output = "Text"
-template = "{{ tally.count }}"
-
-[pipe.echo_date]
-type = "PipeCompose"
-description = "Read a date input"
-inputs = { when = "Date" }
-output = "Text"
-template = "{{ when }}"
-
-[pipe.file_note]
-type = "PipeFunc"
-description = "A function whose own refusal quotes its input"
-inputs = { note = "Text" }
-output = "Text"
-function_name = "tests.integration.pipelex.pipeline.test_run_content_stays_out_of_sinks.run_content_quote_the_note"
-
-[pipe.make_ticket]
-type = "PipeCompose"
-description = "Copy a text into a field holding one of its choices"
-inputs = { level = "Text" }
-output = "Ticket"
-
-[pipe.make_ticket.construct]
-priority = { from = "level" }
-
-[pipe.count_notes]
-type = "PipeLLM"
-description = "Ask a model for a count"
-inputs = { note = "Text" }
-output = "Tally"
-prompt = "Count the items in $note"
-"""
-
-
class SecurityRefusalTestData:
"""Runs a security rule refuses, mid-run, before the run and at a template's render, and what none of their events may quote."""
@@ -844,8 +781,18 @@ $photo
# A template reading a private name off a value, which passes the load and which the sandbox refuses at render.
PRIVATE_READ_TEMPLATE: ClassVar[str] = "Talk about {{ topic['_owner'] }}"
+ # The same name, written by the template inside a string literal that the sandboxed `format` reads it through.
+ FORMAT_LITERAL_TEMPLATE: ClassVar[str] = "Talk about {{ '{0._owner}'.format(topic) }}"
# A template that fails at render for a reason no security rule has, a method the value lacks.
MISSING_METHOD_TEMPLATE: ClassVar[str] = "Talk about {{ topic.model_dump_json() }}"
+ # A template looking a name up from the run's data, and a topic naming a private attribute: the sandbox refuses a name
+ # that is the run's input, which no problem may carry.
+ DATA_NAMED_TEMPLATE: ClassVar[str] = "Talk about {{ topic[topic.text] }}"
+ DATA_NAMED_TOPIC: ClassVar[str] = "_quokka_marmalade_4471"
+ # The same lookup, in a template whose condition compares the topic to a string literal holding the name the data
+ # chose as a word: a literal no access reads names nothing the template reached for.
+ DATA_NAMED_BESIDE_LITERAL_TEMPLATE: ClassVar[str] = "Talk about {% if topic.text == 'debug _token' %}debug{% endif %}{{ topic[topic.text] }}"
+ DATA_NAMED_BESIDE_LITERAL_TOPIC: ClassVar[str] = "_token"
TOPIC: ClassVar[str] = "the quarterly payroll"
COMPOSE_MTHDS_SLOT: ClassVar[str] = "TEMPLATE_SLOT"
COMPOSE_MTHDS: ClassVar[str] = """
@@ -862,6 +809,76 @@ template = "TEMPLATE_SLOT"
"""
+class RunContentMarkerTestData:
+ """Steps that each fail on the run's own data, which carries a marker no log line and no view may hold."""
+
+ # A value no secret pattern matches, so no redaction hides it: only the raise sites' own rule can keep it out.
+ MARKER: ClassVar[str] = "zebra-quartz-ledger-5521"
+
+ # One step per family of raise site: the input shaper, the content factory, a method's function, the composer and a
+ # structure refusing the model's answer, the stand-in model answering the marker for every field.
+ MTHDS: ClassVar[str] = """
+domain = "run_content_marker"
+description = "Steps that each fail on the run's own data"
+
+[concept.Tally]
+description = "A count"
+
+[concept.Tally.structure]
+count = { type = "integer", description = "How many there are", required = true }
+
+[concept.Ticket]
+description = "A ticket and its priority"
+
+[concept.Ticket.structure]
+priority = { choices = ["low", "high"], description = "How urgent it is", required = true }
+
+[pipe.echo_amount]
+type = "PipeCompose"
+description = "Read a number input"
+inputs = { amount = "Number" }
+output = "Text"
+template = "{{ amount }}"
+
+[pipe.echo_tally]
+type = "PipeCompose"
+description = "Read a structured input"
+inputs = { tally = "Tally" }
+output = "Text"
+template = "{{ tally.count }}"
+
+[pipe.echo_date]
+type = "PipeCompose"
+description = "Read a date input"
+inputs = { when = "Date" }
+output = "Text"
+template = "{{ when }}"
+
+[pipe.file_note]
+type = "PipeFunc"
+description = "A function whose own refusal quotes its input"
+inputs = { note = "Text" }
+output = "Text"
+function_name = "tests.integration.pipelex.pipeline.test_run_content_stays_out_of_sinks.run_content_quote_the_note"
+
+[pipe.make_ticket]
+type = "PipeCompose"
+description = "Copy a text into a field holding one of its choices"
+inputs = { level = "Text" }
+output = "Ticket"
+
+[pipe.make_ticket.construct]
+priority = { from = "level" }
+
+[pipe.count_notes]
+type = "PipeLLM"
+description = "Ask a model for a count"
+inputs = { note = "Text" }
+output = "Tally"
+prompt = "Count the items in $note"
+"""
+
+
class ResolveBundleTestData:
"""Bundles the host-facing resolve cores are pinned with."""
diff --git a/tests/integration/pipelex/pipeline/test_name_conflict_location.py b/tests/integration/pipelex/pipeline/test_name_conflict_location.py
new file mode 100644
index 000000000..ee8020b07
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_name_conflict_location.py
@@ -0,0 +1,203 @@
+"""A name declared twice, or colliding with a native concept, is located on the declaration that collides.
+
+Each `method.name_conflict` item names the table that declares the colliding name by its bundle-root path, such as
+`concept.Rating`, and the bundle file it is declared in whenever the caller named that file, in a validation verdict
+and in a run's refusal alike.
+"""
+
+from operator import itemgetter
+from typing import Any, ClassVar
+
+import pytest
+from mthds.protocol.problem.registry import CoreCode
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.errors.problem import ProblemView
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_bundle import validate_bundle
+
+
+class _NameConflictData:
+ NATIVE_REDECLARATION: ClassVar[str] = """
+domain = "name_conflict_native"
+main_pipe = "echo"
+
+[concept.Rating]
+description = "A rating, declared again"
+
+[pipe.echo]
+type = "PipeCompose"
+description = "Echo"
+inputs = { text = "Text" }
+output = "Text"
+template = "{{ text }}"
+"""
+ FIRST: ClassVar[str] = """
+domain = "name_conflict_dup"
+main_pipe = "echo"
+
+[concept]
+Doc = "A document, as the first bundle declares it"
+
+[pipe.echo]
+type = "PipeCompose"
+description = "Echo"
+inputs = { text = "Text" }
+output = "Text"
+template = "{{ text }}"
+"""
+ SECOND: ClassVar[str] = """
+domain = "name_conflict_dup"
+
+[concept]
+Doc = "A document, as the second bundle declares it"
+"""
+ # A second bundle declaring the first one's pipe again.
+ SECOND_PIPE: ClassVar[str] = """
+domain = "name_conflict_dup"
+
+[pipe.echo]
+type = "PipeCompose"
+description = "Echo, as the second bundle declares it"
+inputs = { text = "Text" }
+output = "Text"
+template = "{{ text }}"
+"""
+
+ # A PipeBatch naming its item as its list, which is no declaration but a name the pipe uses twice.
+ BATCH_ITEM_AS_LIST: ClassVar[str] = """
+domain = "name_conflict_batch"
+main_pipe = "batch_echo"
+
+[pipe.batch_echo]
+type = "PipeBatch"
+description = "Echo each item"
+inputs = { items = "Text[]" }
+output = "Text[]"
+branch_pipe_code = "echo"
+input_list_name = "items"
+input_item_name = "items"
+
+[pipe.echo]
+type = "PipeCompose"
+description = "Echo"
+inputs = { items = "Text" }
+output = "Text"
+template = "{{ items }}"
+"""
+ # A sequence step batching over a list under the list's own name.
+ STEP_BATCH_AS_LIST: ClassVar[str] = """
+domain = "name_conflict_step"
+main_pipe = "run_all"
+
+[pipe.run_all]
+type = "PipeSequence"
+description = "Echo each item"
+inputs = { items = "Text[]" }
+output = "Text[]"
+steps = [
+ { pipe = "echo", result = "echoes", batch_over = "items", batch_as = "items" },
+]
+
+[pipe.echo]
+type = "PipeCompose"
+description = "Echo"
+inputs = { items = "Text" }
+output = "Text"
+template = "{{ items }}"
+"""
+
+
+def _name_conflict_locations(error: PipelexError) -> list[dict[str, Any]]:
+ """The locations of the caller's `method.name_conflict` items, or of the problem itself when it is the one fault."""
+ problem = error.to_problem(view=ProblemView.CALLER)
+ if problem.code == CoreCode.METHOD_NAME_CONFLICT:
+ assert problem.location is not None
+ return [problem.location.as_wire()]
+ assert problem.errors is not None, problem
+ locations: list[dict[str, Any]] = []
+ for item in problem.errors:
+ if item.code == CoreCode.METHOD_NAME_CONFLICT:
+ assert item.location is not None, item
+ locations.append(item.location.as_wire())
+ return locations
+
+
[email protected](loop_scope="class")
+class TestNameConflictLocation:
+ @pytest.mark.parametrize(
+ ("sources", "expected_locations"),
+ [
+ pytest.param(["bundle.mthds"], [{"field": "concept.Rating", "file": "bundle.mthds"}], id="named_file"),
+ pytest.param(None, [{"field": "concept.Rating"}], id="unnamed_content"),
+ ],
+ )
+ async def test_a_conflict_inside_one_bundle_is_located_on_its_declaration(
+ self, sources: list[str | None] | None, expected_locations: list[dict[str, Any]]
+ ) -> None:
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[_NameConflictData.NATIVE_REDECLARATION], mthds_sources=sources)
+
+ assert _name_conflict_locations(exc_info.value) == expected_locations
+
+ async def test_a_conflict_across_two_bundles_is_located_on_each_declaration(self) -> None:
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[_NameConflictData.FIRST, _NameConflictData.SECOND], mthds_sources=["first.mthds", "second.mthds"])
+
+ assert sorted(_name_conflict_locations(exc_info.value), key=itemgetter("file")) == [
+ {"field": "concept.Doc", "file": "first.mthds"},
+ {"field": "concept.Doc", "file": "second.mthds"},
+ ]
+
+ async def test_a_pipe_declared_twice_is_located_by_its_path_from_the_bundle_root_alone(self) -> None:
+ """A pipe's declaration is located by its bundle-root path, with no `pipe` beside it that a reader would join to it."""
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(
+ mthds_contents=[_NameConflictData.FIRST, _NameConflictData.SECOND_PIPE], mthds_sources=["first.mthds", "second.mthds"]
+ )
+
+ assert sorted(_name_conflict_locations(exc_info.value), key=itemgetter("file")) == [
+ {"field": "pipe.echo", "file": "first.mthds"},
+ {"field": "pipe.echo", "file": "second.mthds"},
+ ]
+
+ @pytest.mark.parametrize(
+ ("content", "expected_location"),
+ [
+ pytest.param(
+ _NameConflictData.BATCH_ITEM_AS_LIST, {"pipe": "batch_echo", "field": "input_item_name", "file": "bundle.mthds"}, id="pipe_batch"
+ ),
+ pytest.param(
+ _NameConflictData.STEP_BATCH_AS_LIST, {"pipe": "run_all", "field": "steps.0.batch_as", "file": "bundle.mthds"}, id="sequence_step"
+ ),
+ ],
+ )
+ async def test_a_batch_item_collision_is_located_on_its_pipe_and_the_field_it_collides_on(
+ self, content: str, expected_location: dict[str, Any]
+ ) -> None:
+ """A batch item named as its list is no declaration: it stays on its pipe, with the field relative to that pipe."""
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[content], mthds_sources=["bundle.mthds"])
+
+ assert _name_conflict_locations(exc_info.value) == [expected_location]
+
+ @pytest.mark.parametrize(
+ ("contents", "expected_locations"),
+ [
+ pytest.param([_NameConflictData.NATIVE_REDECLARATION], [{"field": "concept.Rating"}], id="one_bundle"),
+ pytest.param(
+ [_NameConflictData.FIRST, _NameConflictData.SECOND],
+ [{"field": "concept.Doc"}, {"field": "concept.Doc"}],
+ id="two_bundles",
+ ),
+ ],
+ )
+ async def test_a_run_s_refusal_locates_the_conflict_on_its_declaration(
+ self, contents: list[str], expected_locations: list[dict[str, Any]]
+ ) -> None:
+ """A run of content refuses the method before any pipe runs, its items located as the verdict's are."""
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol().execute(mthds_contents=contents, inputs={"text": "x"})
+
+ assert _name_conflict_locations(exc_info.value) == expected_locations
diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_consumer_check.py b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_consumer_check.py
index bdda01851..3a9fe488e 100644
--- a/tests/integration/pipelex/pipeline/test_pipeline_run_setup_consumer_check.py
+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_setup_consumer_check.py
@@ -173,7 +173,9 @@ class TestPipelineRunSetupConsumerCheck:
assert problem.code == CoreCode.INPUT_FILE_TYPE_UNSUPPORTED
assert problem.domain == ProblemDomain.INPUT
assert error_code_spec(CoreCode.INPUT_FILE_TYPE_UNSUPPORTED).status == 422
- assert problem.to_wire().get("params", {}).get("input") == "transcripts[0]", problem.to_wire()
+ # The root input is the `input`, and the path down to the first refused file the location's `field`.
+ assert problem.to_wire().get("params", {}).get("input") == "transcripts", problem.to_wire()
+ assert problem.to_wire().get("location") == {"input": "transcripts", "field": "transcripts[0]"}, problem.to_wire()
message = exc_info.value.message
for index in range(3):
assert (
diff --git a/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py b/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py
index fa046a9f2..c7bdba960 100644
--- a/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py
+++ b/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py
@@ -64,21 +64,31 @@ def _assert_is_the_refusal(*, error: PipelineExecutionError, message: str, detai
@pytest.mark.asyncio(loop_scope="class")
class TestRenderTimeTemplateRefusals:
- async def test_a_condition_expression_naming_an_unknown_filter_in_a_branch_is_refused(self) -> None:
- """A live run taking the branch: `method.template_invalid` at the condition, its expression and the unknown filter named."""
+ @pytest.mark.parametrize(
+ ("expression_field", "expression_line"),
+ [
+ ("expression_template", RenderTimeTemplateTestData.EXPRESSION_TEMPLATE_LINE),
+ ("expression", RenderTimeTemplateTestData.EXPRESSION_LINE),
+ ],
+ )
+ async def test_a_condition_expression_naming_an_unknown_filter_in_a_branch_is_refused(self, expression_field: str, expression_line: str) -> None:
+ """A live run taking the branch: `method.template_invalid` at the condition, on the field the bundle wrote, the filter named."""
error = await _failed_run(
pipe_code="route_parcel",
- bundle=RenderTimeTemplateTestData.CONDITION_MTHDS,
+ bundle=RenderTimeTemplateTestData.CONDITION_MTHDS.replace(RenderTimeTemplateTestData.EXPRESSION_LINE_SLOT, expression_line),
inputs={"parcel": "a box of books", "lane": "express"},
pipe_run_mode=PipeRunMode.LIVE,
)
_assert_is_the_refusal(
error=error,
- message=f"PipeCondition 'route_parcel': its expression cannot render: {_UNKNOWN_FILTER_FAULT}",
- detail=f"The template 'expression' of pipe 'route_parcel' is invalid ({_UNKNOWN_FILTER_FAULT}).",
+ message=f"PipeCondition 'route_parcel': its {expression_field} cannot render: {_UNKNOWN_FILTER_FAULT}",
+ detail=f"The template '{expression_field}' of pipe 'route_parcel' is invalid ({_UNKNOWN_FILTER_FAULT}).",
pipe_code="route_parcel",
)
+ caller = error.to_problem(view=ProblemView.CALLER)
+ assert caller.location is not None
+ assert caller.location.field == expression_field
@pytest.mark.parametrize("prompt_field", ["prompt", "system_prompt"])
async def test_an_llm_prompt_naming_an_unknown_filter_in_a_branch_is_refused(self, prompt_field: str) -> None:
diff --git a/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py b/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py
index e7955db56..5883587ae 100644
--- a/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py
+++ b/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py
@@ -106,7 +106,12 @@ class TestResolveCrateFromMethodDir:
with _written_tree(destination=tmp_path / "method", files=files) as method_dir, pytest.raises(ValidateBundleError) as exc_info:
resolve_crate_from_method_dir(method_dir=method_dir)
- assert "['first.mthds', 'second.mthds']" in exc_info.value.message
+ # Each declaration is an item located on its own bundle, its message naming the other bundle by its tree path.
+ items = exc_info.value.validation_error_items()
+ assert sorted((item.source, item.message) for item in items) == [
+ ("first.mthds", "Concept 'pipeline.Report' is declared here and in 'second.mthds'."),
+ ("second.mthds", "Concept 'pipeline.Report' is declared here and in 'first.mthds'."),
+ ]
report_text = str(exc_info.value.to_problem(view=ProblemView.OPERATOR).to_wire())
assert str(tmp_path) not in report_text
assert str(tmp_path.resolve()) not in report_text
diff --git a/tests/integration/pipelex/pipeline/test_template_refusal_names.py b/tests/integration/pipelex/pipeline/test_template_refusal_names.py
new file mode 100644
index 000000000..af01d4f1d
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_template_refusal_names.py
@@ -0,0 +1,223 @@
+import json
+
+import pytest
+import typer
+from mthds.protocol.problem.registry import CoreCode
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, set_agent_cli_error_format, start_agent_cli_error_format
+from pipelex.errors.problem import ProblemView, problem_metadata
+from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from tests.integration.pipelex.pipeline.test_data import SecurityRefusalTestData
+
+# A construct whose fields render templates, one at its root and one inside a nested field.
+_CONSTRUCT_MTHDS = """
+domain = "template_refusal_construct"
+description = "Compose a photo from a topic"
+main_pipe = "make_photo"
+
+[concept.Photo]
+description = "A photo with a caption"
+
+[concept.Photo.structure]
+caption = { type = "text", description = "The caption" }
+picture = { type = "concept", concept_ref = "native.Image", description = "The picture" }
+
+[pipe.make_photo]
+type = "PipeCompose"
+description = "Build a photo"
+inputs = { topic = "Text" }
+output = "Photo"
+
+[pipe.make_photo.construct]
+caption = { template = "CAPTION_SLOT" }
+
+[pipe.make_photo.construct.picture]
+url = { template = "URL_SLOT" }
+"""
+
+# A compose whose template is a table of its own, its source written under the table's `template` key.
+_TEMPLATE_TABLE_MTHDS = """
+domain = "template_refusal_table"
+description = "Compose a line about a topic"
+main_pipe = "say"
+
+[pipe.say]
+type = "PipeCompose"
+description = "Say something about the topic"
+inputs = { topic = "Text" }
+output = "Text"
+
+[pipe.say.template]
+template = "Talk about {{ topic['_owner'] }}"
+category = "basic"
+"""
+
+# A condition whose field, written as a template or as an expression, reads a private name its own source spells.
+_CONDITION_MTHDS = """
+domain = "template_refusal_condition"
+description = "Route a topic"
+main_pipe = "route_topic"
+
+[pipe.route_topic]
+type = "PipeCondition"
+description = "Choose where a topic goes"
+inputs = { topic = "Text" }
+output = "Text"
+EXPRESSION_LINE
+outcomes = { loud = "say_it" }
+default_outcome = "say_it"
+
+[pipe.say_it]
+type = "PipeCompose"
+description = "Say the topic"
+inputs = { topic = "Text" }
+output = "Text"
+template = "$topic"
+"""
+
+
+def _compose_bundle(*, template: str) -> str:
+ return SecurityRefusalTestData.COMPOSE_MTHDS.replace(SecurityRefusalTestData.COMPOSE_MTHDS_SLOT, template)
+
+
+async def _refused_run(*, template: str, topic: str) -> PipelineExecutionError:
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol().execute(mthds_contents=[_compose_bundle(template=template)], inputs={"topic": topic})
+ error = exc_info.value
+ assert isinstance(error, PipelineExecutionError)
+ return error
+
+
+def _agent_markdown(*, error: PipelineExecutionError, capsys: pytest.CaptureFixture[str]) -> str:
+ """What `pipelex-agent run --error-format markdown` prints for the failed run, as its run commands report it."""
+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)
+ try:
+ with pytest.raises(typer.Exit):
+ agent_error(error.message, cause=error)
+ finally:
+ start_agent_cli_error_format()
+ return capsys.readouterr().err
+
+
[email protected](loop_scope="class")
+class TestTemplateRefusalNames:
+ @pytest.mark.parametrize(
+ "template",
+ [SecurityRefusalTestData.PRIVATE_READ_TEMPLATE, SecurityRefusalTestData.FORMAT_LITERAL_TEMPLATE],
+ ids=["read_by_key", "read_through_a_format_string_literal"],
+ )
+ async def test_a_name_the_template_spells_reaches_the_caller_located_on_the_template_field(self, template: str) -> None:
+ """The refused name is the template's own, so the problem names it and locates it on the pipe and its template field.
+
+ A name written inside a string literal, which a format string reads, is the template's own text too: naming it
+ leaks nothing of the run's data.
+ """
+ error = await _refused_run(template=template, topic=SecurityRefusalTestData.TOPIC)
+
+ caller = error.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "say", "name": "_owner"}
+ assert caller.detail == "A template of pipe 'say' reached for '_owner', which the template sandbox forbids."
+ assert caller.next_step.detail == "Remove '_owner' from the templates of pipe 'say', then run the method again."
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "say", "path": ["say"], "field": "template"}
+
+ async def test_a_name_the_run_s_data_gave_reaches_no_reader(self, capsys: pytest.CaptureFixture[str]) -> None:
+ """A template looking the refused name up from the run's data: the input value reaches no view, no message and no Markdown.
+
+ The problem carries no `name`, its sentences say that the template looked a name up from the run's data, and it
+ is located on the pipe and its template field.
+ """
+ marker = SecurityRefusalTestData.DATA_NAMED_TOPIC
+ error = await _refused_run(template=SecurityRefusalTestData.DATA_NAMED_TEMPLATE, topic=marker)
+
+ operator = error.to_problem(view=ProblemView.OPERATOR)
+ caller = error.to_problem(view=ProblemView.CALLER)
+ markdown = _agent_markdown(error=error, capsys=capsys)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert marker not in error.message
+ assert marker not in json.dumps(operator.to_wire())
+ assert marker not in json.dumps(caller.to_wire())
+ assert marker not in json.dumps(problem_metadata(problem=operator).to_wire())
+ assert marker not in markdown
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "say"}
+ assert caller.detail == "A template of pipe 'say' looked a name up from the run's data, and the template sandbox refused that name."
+ assert caller.next_step.detail == (
+ "Change the templates of pipe 'say' so that the run's data no longer chooses the names they look up, then run the method again."
+ )
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "say", "path": ["say"], "field": "template"}
+ assert markdown.startswith(f"## {operator.title}\n")
+
+ async def test_a_name_another_string_literal_holds_is_still_the_run_s_data(self) -> None:
+ """A word a string literal holds, outside any format string, is not what the template reached for.
+
+ In `{% if topic.text == 'debug _token' %}…{{ topic[topic.text] }}`, the key `_token` is the run's data, which the
+ refusal withholds even though the template's condition writes the same word.
+ """
+ marker = SecurityRefusalTestData.DATA_NAMED_BESIDE_LITERAL_TOPIC
+ error = await _refused_run(template=SecurityRefusalTestData.DATA_NAMED_BESIDE_LITERAL_TEMPLATE, topic=marker)
+
+ caller = error.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "say"}
+ assert caller.detail == "A template of pipe 'say' looked a name up from the run's data, and the template sandbox refused that name."
+ assert marker not in json.dumps(caller.to_wire())
+ assert marker not in error.message
+
+ async def test_a_template_written_as_a_table_is_located_on_the_key_holding_its_source(self) -> None:
+ """A compose template written as a table of its own holds its source under the table's `template` key."""
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol().execute(mthds_contents=[_TEMPLATE_TABLE_MTHDS], inputs={"topic": SecurityRefusalTestData.TOPIC})
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "say", "path": ["say"], "field": "template.template"}
+
+ @pytest.mark.parametrize(
+ ("caption_template", "url_template", "expected_field"),
+ [
+ ("{{ topic['_owner'] }}", "https://example.com/photo.png", "construct.caption"),
+ ("A caption", "{{ topic['_owner'] }}", "construct.picture.url"),
+ ],
+ )
+ async def test_a_construct_field_s_template_is_located_on_its_path(self, caption_template: str, url_template: str, expected_field: str) -> None:
+ """A construct's template is located by its path from the construct's root, through a nested field too."""
+ bundle = _CONSTRUCT_MTHDS.replace("CAPTION_SLOT", caption_template).replace("URL_SLOT", url_template)
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol().execute(mthds_contents=[bundle], inputs={"topic": SecurityRefusalTestData.TOPIC})
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "make_photo", "path": ["make_photo"], "field": expected_field}
+
+ @pytest.mark.parametrize(
+ ("expression_line", "expected_field"),
+ [
+ ("expression_template = \"{{ topic['_owner'] }}\"", "expression_template"),
+ ("expression = \"topic['_owner']\"", "expression"),
+ ],
+ )
+ async def test_a_condition_s_refusal_is_located_on_the_field_the_bundle_wrote(self, expression_line: str, expected_field: str) -> None:
+ """A condition writes its expression as a template or as an expression: its refusal names the field it wrote."""
+ bundle = _CONDITION_MTHDS.replace("EXPRESSION_LINE", expression_line)
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol().execute(mthds_contents=[bundle], inputs={"topic": SecurityRefusalTestData.TOPIC})
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "route_topic", "path": ["route_topic"], "field": expected_field}
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py b/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py
index ee32df32b..31a29f64f 100644
--- a/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_load_refusals.py
@@ -32,6 +32,7 @@ from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexError, ValidationErrorCategory, ValidationErrorItem
from pipelex.cogt.model_backends.model_type import ModelType
+from pipelex.cogt.models.model_deck import ModelDeck
from pipelex.config import get_config
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.errors.error_codes import PipelexErrorCode, error_code_spec
@@ -77,6 +78,9 @@ model = "nano-banana-9"
prompt = "A painted wooden harbour board announcing the tide times, morning light"
"""
+# A model a catalog of the deployment declares on a backend it does not enable, which the session deck does not serve.
+_SWITCHED_OFF_HANDLE = "switched-off-model"
+
# An LLM the session deck serves, named in an image-generation pipe.
_LLM_HANDLE_SERVED = "gpt-5.6-luna"
@@ -384,6 +388,24 @@ class TestValidateBundleLoadRefusals:
assert raised.value is fault
+ async def test_a_model_no_enabled_backend_serves_is_no_verdict(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """A model a catalog of this deployment knows but no enabled backend serves leaves the method sound: no verdict, the operator's code."""
+
+ def _switched_off(_deck: ModelDeck, *, name: str, model_type: ModelType) -> bool:
+ return name == _SWITCHED_OFF_HANDLE and model_type == ModelType.LLM
+
+ mocker.patch.object(ModelDeck, "is_cataloged_but_unserved", autospec=True, side_effect=_switched_off)
+ bundle_path = _write_bundle(directory=tmp_path, content=_llm_bundle(model_line=f'model = "{_SWITCHED_OFF_HANDLE}"'))
+
+ with pytest.raises(PipelexError) as raised:
+ await validate_bundle(mthds_file_path=bundle_path, library_dirs=[bundle_path.parent])
+
+ assert not isinstance(raised.value, ValidateBundleError)
+ caller = raised.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.MODEL_UNAVAILABLE
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"model": _SWITCHED_OFF_HANDLE, "model_type": "llm", "reason": "not_served"}
+
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)
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
index 94c4348f5..7010c1a70 100644
--- a/tests/integration/pipelex/pipeline/test_verdict_names_no_host_path.py
+++ b/tests/integration/pipelex/pipeline/test_verdict_names_no_host_path.py
@@ -151,6 +151,28 @@ prompt = "Write a short notice for the harbour board from these tide times:
"""
+# The caller's bundle whose sequence calls a pipe by a code that is a slip from the host's `pin_board_notice`.
+_MISTYPED_STEP_CALLER_BUNDLE = """
+domain = "harbour_notices"
+description = "Post notices on the harbour board"
+main_pipe = "post_board_notice"
+
+[pipe.post_board_notice]
+type = "PipeSequence"
+description = "Write the notice, then post it"
+inputs = { tide_times = "Text" }
+output = "Text"
+steps = [{ pipe = "pin_board_notic", result = "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 host library bundle whose PipeFunc's tree holds a module named like a standard-library module: the
# refusal names the module, the tree file and the bundle, never the tree's directory on the host.
_HOST_PIPE_FUNC_BUNDLE = """
@@ -317,9 +339,13 @@ class TestVerdictNamesNoHostPath:
verdict = await _verdict_on(surface=surface, caller_bundle=_CALLER_BUNDLE, tmp_path=tmp_path)
items: list[ValidationErrorItem] = verdict.validation_error_items() 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
+ # One item per bundle declaring it, each located on its bundle and naming the other by the dependency's address.
+ first_file = f"{_DEPENDENCY_ADDRESS}/notices/tide_notices.mthds"
+ copy_file = f"{_DEPENDENCY_ADDRESS}/notices/tide_notices_copy.mthds"
+ assert sorted((item.source, item.message) for item in items) == [
+ (first_file, f"Pipe 'tides.write_tide_notice' is declared here and in '{copy_file}'."),
+ (copy_file, f"Pipe 'tides.write_tide_notice' is declared here and in '{first_file}'."),
+ ], surface.description
_assert_names_no_host_path(payload=_caller_payload(verdict), tmp_path=tmp_path)
@pytest.mark.parametrize("surface", _SURFACES, ids=[surface.surface_id for surface in _SURFACES])
@@ -398,11 +424,29 @@ class TestVerdictNamesNoHostPath:
with pytest.raises(ValidateBundleError) as raised:
await validate_bundle(mthds_contents=[_BOARD_NOTICE_PIPE_BUNDLE], library_dirs=[host_library_dir])
+ # The host's own declaration is no item of the caller's: the caller's declaration is, naming the host's file by a placeholder.
(item,) = raised.value.validation_error_items() or []
assert "harbour_board.pin_board_notice" in item.message
assert HOST_LIBRARY_FILE_PLACEHOLDER in item.message
_assert_names_no_host_path(payload=_caller_payload(raised.value), tmp_path=tmp_path)
+ async def test_a_mistyped_selection_is_offered_no_pipe_of_the_host_s_library(self, tmp_path: Path) -> None:
+ with pytest.raises(PipelexError) as raised:
+ await _run_setup(
+ mthds_contents=[_VALID_CALLER_BUNDLE], library_dirs=[str(_valid_host_library(tmp_path=tmp_path))], pipe_code="pin_board_notic"
+ )
+
+ assert raised.value.caller_params() == {"pipe": "pin_board_notic", "suggestions": ["harbour_notices.write_board_notice"]}
+
+ async def test_a_mistyped_reference_is_offered_no_pipe_of_the_host_s_library(self, tmp_path: Path) -> None:
+ with pytest.raises(ValidateBundleError) as raised:
+ await validate_bundle(mthds_contents=[_MISTYPED_STEP_CALLER_BUNDLE], library_dirs=[_valid_host_library(tmp_path=tmp_path)])
+
+ (item,) = raised.value.validation_error_items() or []
+ assert item.params is not None
+ assert item.params["candidates"] == ["harbour_notices.post_board_notice", "harbour_notices.write_board_notice"]
+ assert "pin_board_notice" not in item.message
+
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)
diff --git a/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_refusal_location.py b/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_refusal_location.py
new file mode 100644
index 000000000..588d0f371
--- /dev/null
+++ b/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_template_refusal_location.py
@@ -0,0 +1,45 @@
+"""A PipeDocGen template the template sandbox refuses is located on the field the bundle writes it in."""
+
+import pytest
+from mthds.protocol.problem.registry import CoreCode
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.errors.problem import ProblemView
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from tests.integration.pipelex.pipes.operator.pipe_doc_gen.test_data import PipeDocGenTestData
+
+# A template that reads a private name its own source spells, which the sandbox refuses whatever the run's data.
+_REFUSED_TEMPLATE = "<p>{{ invoice['_owner'] }}</p>"
+
+
[email protected](loop_scope="class")
[email protected]("stub_engines")
+class TestPipeDocGenTemplateRefusalLocation:
+ @pytest.mark.parametrize(
+ ("step_fields", "submitted_files", "expected_field"),
+ [
+ pytest.param(f'format = "pdf"\nfilename = "{_REFUSED_TEMPLATE}"', None, "filename", id="filename"),
+ pytest.param(f'format = "pdf"\ntemplate = "{_REFUSED_TEMPLATE}"', None, "template", id="inline_template"),
+ pytest.param(
+ 'format = "pdf"\ntemplate_file = "templates/invoice.html"',
+ {"./templates/invoice.html": _REFUSED_TEMPLATE.encode()},
+ "template_file",
+ id="template_file",
+ ),
+ ],
+ )
+ async def test_a_refused_template_is_located_on_its_field(
+ self, step_fields: str, submitted_files: dict[str, bytes] | None, expected_field: str
+ ) -> None:
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol(submitted_files=submitted_files).execute(
+ mthds_contents=[PipeDocGenTestData.bundle(step_fields=step_fields)], inputs=PipeDocGenTestData.INVOICE_INPUTS
+ )
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED, caller.to_wire()
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "print_invoice", "name": "_owner"}
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "print_invoice", "path": ["print_invoice"], "field": expected_field}
diff --git a/tests/integration/pipelex/pipes/operator/pipe_judge/test_data.py b/tests/integration/pipelex/pipes/operator/pipe_judge/test_data.py
index f625457bd..0d19ac1f1 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_judge/test_data.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_judge/test_data.py
@@ -14,6 +14,16 @@ class PipeJudgeLoadTestData:
JUDGMENT_MODEL = "jev-1.13.0"
+ # A concept whose structure holds a file, which a question may read by a path into the input.
+ CLAIM_CONCEPT_TABLES = """
+[concept.Claim]
+description = "An insurance claim"
+
+[concept.Claim.structure]
+summary = { type = "text", description = "What happened" }
+photo = { type = "concept", concept_ref = "native.Image", description = "The damage" }
+"""
+
@classmethod
def bundle(
cls,
@@ -23,10 +33,12 @@ class PipeJudgeLoadTestData:
prompt: str | None = "@message",
question: str | None = "Is it urgent?",
step_fields: str = "",
+ concept_tables: str = "",
) -> str:
"""The step's fields as written: a `prompt` or a `question` given as `None` is left out of the table.
A JSON string is a TOML basic string, escapes included, so the two templates are written that way.
+ `concept_tables` holds tables of further concepts, written after the bundle's own.
"""
prompt_line = f"prompt = {json.dumps(prompt)}" if prompt is not None else ""
question_line = f"question = {json.dumps(question)}" if question is not None else ""
@@ -37,6 +49,7 @@ description = "Loading a PipeJudge step"
[concept]
Team = {{ description = "The team a ticket goes to", refines = "Choice" }}
Ticket = "A support ticket"
+{concept_tables}
[pipe.judge_it]
type = "PipeJudge"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_load_refusals.py b/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_load_refusals.py
index 57cd5f948..b783b40ae 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_load_refusals.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_load_refusals.py
@@ -118,6 +118,22 @@ class TestPipeJudgeLoadRefusals:
assert "only the prompt presents files" in report
assert "'input_stuff_spec_mismatch'" in report
+ @pytest.mark.usefixtures("judgment_model_reading_files")
+ async def test_a_question_reading_a_file_field_names_the_input_and_its_concept(self) -> None:
+ """The code's `input` is the step's input, the root of the path the question reads, with the concept it declares."""
+ bundle = PipeJudgeLoadTestData.bundle(
+ inputs='{ message = "Text", claim = "Claim" }',
+ question="Is $claim.photo damaged?",
+ step_fields=_MODEL,
+ concept_tables=PipeJudgeLoadTestData.CLAIM_CONCEPT_TABLES,
+ )
+
+ item = _only_problem_item(await _refusal(bundle))
+
+ assert item.code == CoreCode.METHOD_INPUT_CONCEPT_MISMATCH
+ assert item.params is not None
+ assert item.params.as_wire() == {"pipe": "judge_it", "input": "claim", "declared": "judge_load.Claim"}
+
@pytest.mark.parametrize(
("prompt", "question"),
[
diff --git a/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_template_refusal_location.py b/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_template_refusal_location.py
new file mode 100644
index 000000000..16b61bd08
--- /dev/null
+++ b/tests/integration/pipelex/pipes/operator/pipe_judge/test_pipe_judge_template_refusal_location.py
@@ -0,0 +1,50 @@
+"""A PipeJudge question the template sandbox refuses is located on the question's own field, in either form of the step."""
+
+import pytest
+from mthds.protocol.problem.registry import CoreCode
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.cogt.content_generation.content_generator import ContentGenerator
+from pipelex.errors.problem import ProblemView
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from tests.integration.pipelex.pipes.operator.pipe_judge.test_data import PipeJudgeLoadTestData, PipeJudgeSeveralQuestionsTestData
+
+# A question that reads a private name its own source spells, which the sandbox refuses whatever the run's data.
+_REFUSED_QUESTION = "Is {{ message['_owner'] }} urgent?"
+
+
[email protected](loop_scope="class")
+class TestPipeJudgeTemplateRefusalLocation:
+ @pytest.mark.parametrize(
+ ("bundle", "expected_field"),
+ [
+ pytest.param(
+ PipeJudgeLoadTestData.bundle(question=_REFUSED_QUESTION, step_fields=f'model = "{PipeJudgeLoadTestData.JUDGMENT_MODEL}"'),
+ "question",
+ id="one_question",
+ ),
+ pytest.param(
+ PipeJudgeSeveralQuestionsTestData.bundle(
+ questions={
+ **PipeJudgeSeveralQuestionsTestData.QUESTIONS,
+ "team": f'question = "{_REFUSED_QUESTION}"\noptions = {{ billing = "Charges", technical = "Errors" }}',
+ }
+ ),
+ "questions.team.question",
+ id="several_questions",
+ ),
+ ],
+ )
+ async def test_a_refused_question_is_located_on_its_field(self, bundle: str, expected_field: str, mocker: MockerFixture) -> None:
+ asked = mocker.patch.object(ContentGenerator, "make_judgment_answers")
+
+ with pytest.raises(PipelexError) as exc_info:
+ await PipelexMTHDSProtocol().execute(mthds_contents=[bundle], pipe_code="judge_it", inputs={"message": "The site is down"})
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED, caller.to_wire()
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"pipe": "judge_it", "path": ["judge_it"], "field": expected_field}
+ asked.assert_not_called()
diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py
new file mode 100644
index 000000000..afe1d8e63
--- /dev/null
+++ b/tests/unit/conftest.py
@@ -0,0 +1,19 @@
+from collections.abc import Generator
+
+import pytest
+from pytest import FixtureRequest
+from pytest_mock import MockerFixture
+
+from pipelex.test_extras.required_params_sweep import assert_problems_carried_required_params, spy_on_problem_warnings
+
+
[email protected](autouse=True)
+def problems_carry_their_required_params_fixture(request: FixtureRequest, mocker: MockerFixture) -> Generator[None, None, None]:
+ """Fail a unit test during which a problem or an item was built without a parameter its code requires.
+
+ The API server's unit tests run the same sweep (`pipelex.test_extras.required_params_sweep`): a test that builds
+ such a problem on purpose says so with the `builds_problems_without_required_params` marker and its reason.
+ """
+ warn_spy = spy_on_problem_warnings(mocker=mocker)
+ yield
+ assert_problems_carried_required_params(warn_spy=warn_spy, keywords=request.keywords)
diff --git a/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
index 5ecb8cccd..0bf30bbf7 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
@@ -70,6 +70,9 @@ class TestAgentErrorFormat:
assert "Traceback" not in err
@pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its verdict's items in the test, without an unresolved pipe's candidates or a residual's field path"
+ )
def test_both_formats_list_the_one_problem_s_errors(self, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat) -> None:
"""A wrapper adding a fault of its own above a verdict: both formats list the verdict's item and the wrapper's."""
set_agent_cli_error_format(error_format)
diff --git a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
index 6284a1e63..7f853513f 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
@@ -153,6 +153,9 @@ class TestFixFormat:
assert parsed["is_runnable"] is False
assert parsed["pending_signatures"] == ["fix_format.pending_pipe"]
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_still_invalid_emits_json_error(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
bundle_path = tmp_path / "bundle.mthds"
bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")
@@ -206,6 +209,9 @@ class TestFixFormat:
assert item["params"] == {"finding": "Expected a value"}
assert "remaining_error_codes" not in parsed
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_still_invalid_markdown_renders_prose(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
"""Default (markdown) still-invalid renders the remaining errors as prose on stderr, not a JSON dump."""
bundle_path = tmp_path / "bundle.mthds"
diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py
index d3a85685b..98cc9b93a 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py
@@ -409,6 +409,9 @@ class TestRunHostedRefusal:
assert problem["next_step"] == {"kind": "upgrade", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]}
_assert_no_retired_member(problem=problem)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the hosted plane's former-shape refusal names none of its code's parameters; the agent reads its status and own code alone"
+ )
@pytest.mark.usefixtures("tty_stdin")
@pytest.mark.parametrize(
("status", "body", "headers", "expected"),
@@ -439,6 +442,7 @@ class TestRunHostedRefusal:
"status": 403,
"detail": "Your role in this organization does not allow running methods.",
"code": "auth.forbidden",
+ "params": {},
"domain": "account",
"retry": "no",
"next_step": {"kind": "request_access", "detail": HOSTED_FORBIDDEN_NEXT_STEP},
@@ -455,6 +459,7 @@ class TestRunHostedRefusal:
"status": 403,
"detail": "This route is served to a web session only.",
"code": "auth.forbidden",
+ "params": {},
"domain": "account",
"retry": "no",
"next_step": {"kind": "request_access", "detail": HOSTED_FORBIDDEN_NEXT_STEP},
@@ -501,6 +506,7 @@ class TestRunHostedRefusal:
"status": 404,
"detail": "No run run_9 is visible to this key.",
"code": "run.not_found",
+ "params": {},
"domain": "input",
"retry": "no",
"next_step": {"kind": "change_input", "detail": "Check the run id, then read the run again."},
@@ -516,6 +522,7 @@ class TestRunHostedRefusal:
"status": 404,
"detail": "The method mt_7 has no published version 3.",
"code": "method.not_found",
+ "params": {},
"domain": "input",
"retry": "no",
"next_step": {"kind": "change_input", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]},
@@ -531,6 +538,7 @@ class TestRunHostedRefusal:
"status": 429,
"detail": "Too many runs started in the last minute.",
"code": "account.rate_limited",
+ "params": {},
"domain": "account",
"retry": "yes",
"retry_after": 30,
@@ -548,6 +556,7 @@ class TestRunHostedRefusal:
"status": 429,
"detail": "Too many runs started in the last minute.",
"code": "account.rate_limited",
+ "params": {},
"domain": "account",
"retry": "yes",
"retry_after": 12,
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 9c83368ca..bac4eb7e0 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
@@ -80,6 +80,9 @@ class TestValidateBundleErrorFormat:
assert captured.out == ""
return captured.err
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_markdown_renders_the_items_and_a_fix_aware_footer(
self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path
) -> None:
@@ -103,6 +106,9 @@ class TestValidateBundleErrorFormat:
with pytest.raises(json.JSONDecodeError):
json.loads(markdown)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_markdown_says_an_unsafe_fix_needs_confirmation(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], 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"
@@ -124,6 +130,9 @@ class TestValidateBundleErrorFormat:
assert "(`rename-model`, safe)" not in markdown
assert "💡 1 of these errors can be fixed automatically" in markdown
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_markdown_no_fix_footer_when_nothing_fixable(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], 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")
@@ -133,6 +142,9 @@ class TestValidateBundleErrorFormat:
assert "no automatic fix" in markdown
assert "pipelex-agent fix bundle" not in markdown
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_json_is_the_method_s_problem_with_the_verdict_beside_it(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:
"""In JSON the verdict is the problem a hook branches on: its code and errors, with is_valid and the bundle beside them."""
set_agent_cli_error_format(CliOutputFormat.JSON)
diff --git a/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py b/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py
index 17f92ab3c..01ba62d50 100644
--- a/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py
+++ b/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py
@@ -83,6 +83,7 @@ class TestAgentCodegenCheckCmd:
assert error["code"] == "pipelex.codegen.lock_not_found"
assert error["params"] == {"path": str(tmp_path)}
+ @pytest.mark.builds_problems_without_required_params(reason="hands the command an error built in the test, without the file its raise site names")
def test_unreadable_lock_is_no_verdict_exit_2(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
mocker.patch(f"{CMD_MODULE}.run_codegen_check", side_effect=CodegenLockError("codegen.lock is not valid TOML"))
@@ -95,6 +96,7 @@ class TestAgentCodegenCheckCmd:
assert error["diagnostics"]["error_class"] == "CodegenLockError"
assert "not valid TOML" in error["message"]
+ @pytest.mark.builds_problems_without_required_params(reason="hands the command an error built in the test, without the file its raise site names")
def test_unreadable_lock_markdown_follows_the_success_format(
self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]
) -> None:
diff --git a/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py b/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py
index 27a266556..af5dacfe2 100644
--- a/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py
+++ b/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py
@@ -103,6 +103,9 @@ class TestAgentCodegenTypesCmd:
assert error["diagnostics"]["error_class"] == "LibraryLoadingError"
assert "duplicate pipe" in error["message"]
+ @pytest.mark.builds_problems_without_required_params(
+ reason="hands the command an error built in the test, without the method reference its raise site names"
+ )
@pytest.mark.parametrize(
("raised", "expected_code"),
[
diff --git a/tests/unit/pipelex/cli/test_agent_output.py b/tests/unit/pipelex/cli/test_agent_output.py
index 1001a209c..c4d3c8dc3 100644
--- a/tests/unit/pipelex/cli/test_agent_output.py
+++ b/tests/unit/pipelex/cli/test_agent_output.py
@@ -127,6 +127,9 @@ class TestAgentOutput:
assert payload["is_valid"] is False
assert "empty" not in payload
+ @pytest.mark.builds_problems_without_required_params(
+ reason="hands the command a fetch failure built in the test, which names neither the input nor the host"
+ )
def test_agent_error_reports_a_pipelex_cause_by_its_own_problem_in_the_operator_view(self, capsys: pytest.CaptureFixture[str]) -> None:
cause = _url_refusal()
with pytest.raises(typer.Exit):
@@ -166,6 +169,9 @@ class TestAgentOutput:
assert parsed["code"] == CoreCode.RUNTIME_UNEXPECTED
assert "errors" not in parsed
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_agent_error_lists_the_items_of_a_verdict_under_pipelex_wrappers(self, capsys: pytest.CaptureFixture[str]) -> None:
verdict = ValidateBundleError(message="Pipe 'post_notice' could not be loaded")
wrapper = PipelexError("the run was refused")
@@ -271,6 +277,9 @@ class TestAgentOutput:
agent_error(cause.message, cause=cause)
assert advice.detail not in capsys.readouterr().err
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its problem's items in the test, with only the parameters the Markdown is checked for"
+ )
def test_render_problem_markdown_states_the_facts_the_faults_and_the_diagnostics(self) -> None:
location = make_location(pipe="summarize", path=["main", "summarize"], file="contracts.mthds", line=12)
item = make_problem_item(code=CoreCode.METHOD_CONCEPT_UNRESOLVED, params={"concept": "Missing"}, location=make_location(pipe="summarize"))
@@ -296,6 +305,9 @@ class TestAgentOutput:
assert "- **bundle_path:** /w/b.mthds" in rendered
assert "is_valid" not in rendered
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its problem's items in the test, with only the parameters the Markdown is checked for"
+ )
def test_render_problem_markdown_nests_the_run_s_own_problem(self) -> None:
"""A read of a failed run's results renders the run's own problem under it as the problem itself renders, one heading
level down: its title, sentence, step, code, location and items.
diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.py
index 2b590aa7d..688013631 100644
--- a/tests/unit/pipelex/cli/test_agent_output_drift.py
+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py
@@ -2,6 +2,7 @@ import ast
from pathlib import Path
from typing import Any, cast
+import pytest
from mthds.protocol.exceptions import PipelineRequestError
from pipelex_sdk.error_models import RunErrorReport
from pipelex_sdk.errors import ApiResponseError, RunFailedError
@@ -175,6 +176,9 @@ class TestAgentOutputDrift:
offenders.append(f"{source_file.relative_to(package_dir)}:{getattr(node, 'lineno', 0)} writes '{member}'")
assert not offenders, f"These lines write a member of the envelope the problem replaced: {offenders}"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the hosted plane's former-shape refusal names none of its code's parameters; the agent reads its status and own code alone"
+ )
def test_no_reported_problem_carries_a_member_its_reader_does_not_declare(self) -> None:
"""The document a run on a runner reports holds only the members the standard and Pipelex declare, at every level.
diff --git a/tests/unit/pipelex/cli/test_error_handlers.py b/tests/unit/pipelex/cli/test_error_handlers.py
index a53d50b83..8067b4f83 100644
--- a/tests/unit/pipelex/cli/test_error_handlers.py
+++ b/tests/unit/pipelex/cli/test_error_handlers.py
@@ -48,6 +48,9 @@ class TestErrorHandlers:
assert exc_info.value.exit_code == 1
spy.assert_called_once()
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds a model availability failure in the test with no cause, whose code and parameters the failed lookup gives"
+ )
def test_handle_model_availability_error_exits_and_reads_the_advice(self, mocker: MockerFixture) -> None:
"""handle_model_availability_error should read the advice for its tip and exit with code 1."""
mocker.patch("pipelex.cli.error_handlers.get_error_console")
@@ -86,6 +89,9 @@ class TestErrorHandlers:
assert exc_info.value.exit_code == 1
spy.assert_called_once()
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_handle_validate_bundle_error_exits_and_reads_its_items(self, mocker: MockerFixture) -> None:
"""handle_validate_bundle_error should read the verdict's items and exit with code 1.
diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.py
index b71c4c7a8..b0157ec4e 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_more.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py
@@ -170,6 +170,9 @@ class TestErrorHandlersExtended:
assert "Possible solutions:" not in output
assert "Enabled Backends:" not in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_handle_validate_bundle_error_prints_a_bracketed_tip_as_written(self, console: Console) -> None:
"""The verdict's advice is plain text: `SDK[openai]` prints as written, neither swallowed as a style tag nor escaped twice."""
exc = ValidateBundleError(message="validation failed")
@@ -182,6 +185,9 @@ class TestErrorHandlersExtended:
assert "💡 Tip: use 'gpt-4o → SDK[openai]' in the pipe" in output
assert "\\[" not in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors and its dry-run failure in the test, without the facts their raise sites give their items' codes"
+ )
def test_handle_validate_bundle_error_renders_all_sections(self, console: Console) -> None:
"""Blueprint, pipe, and dry-run sections all render with their details."""
blueprint_error = PipelexBundleBlueprintValidationErrorData(
@@ -237,6 +243,9 @@ class TestErrorHandlersExtended:
assert "Pipe: third_pipe" in output
assert "Pipe 'third_pipe' failed its dry run: dry run exploded" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
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 402922af4..31f9d7cf9 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_snapshot.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_snapshot.py
@@ -107,6 +107,9 @@ class TestErrorHandlersSnapshot:
output = self._render(mocker, lambda: handle_model_choice_error(exc, context=ErrorContext.PIPE_RUN))
assert output == EXPECTED_MODEL_CHOICE_PANEL
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds a causeless model availability failure and a message-only verdict, neither with its raise site's facts"
+ )
def test_model_availability_error_panel_snapshot(self, mocker: MockerFixture) -> None:
"""handle_model_availability_error renders the panel with its conditional fields."""
exc = PipeOperatorModelAvailabilityError(
diff --git a/tests/unit/pipelex/cli/test_failure_panels_on_stderr.py b/tests/unit/pipelex/cli/test_failure_panels_on_stderr.py
index 67509a0ba..7431e5e6f 100644
--- a/tests/unit/pipelex/cli/test_failure_panels_on_stderr.py
+++ b/tests/unit/pipelex/cli/test_failure_panels_on_stderr.py
@@ -111,6 +111,9 @@ class TestFailurePanelsOnStderr:
],
)
@pytest.mark.parametrize("traceback_requested", [False, True])
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its failures in the test with a message alone, to check which stream their panels go to"
+ )
def test_a_dedicated_panel_and_its_traceback_go_to_stderr(
self,
mocker: MockerFixture,
diff --git a/tests/unit/pipelex/cli/test_validate_exit_codes.py b/tests/unit/pipelex/cli/test_validate_exit_codes.py
index 794669fc5..e20e4892a 100644
--- a/tests/unit/pipelex/cli/test_validate_exit_codes.py
+++ b/tests/unit/pipelex/cli/test_validate_exit_codes.py
@@ -155,6 +155,9 @@ class TestValidateExitCodes:
mocker.patch(f"{AGENT_BUNDLE_MODULE}.make_pipelex_for_agent_cli")
mocker.patch(f"{AGENT_BUNDLE_MODULE}.Pipelex.teardown_if_needed")
+ @pytest.mark.builds_problems_without_required_params(
+ reason="hands the command dry-run failures built in the test, without the parameters a sweep records"
+ )
def test_invalid_bundle_is_negative_verdict_exit_1(self, mocker: MockerFixture, tmp_path: Path) -> None:
self._patch_boot(mocker)
mocker.patch(
@@ -230,6 +233,9 @@ class TestValidateExitCodes:
mocker.patch(f"{AGENT_PIPE_MODULE}.make_pipelex_for_agent_cli")
mocker.patch(f"{AGENT_PIPE_MODULE}.Pipelex.teardown_if_needed")
+ @pytest.mark.builds_problems_without_required_params(
+ reason="hands the command dry-run failures built in the test, without the parameters a sweep records"
+ )
def test_agent_validate_all_dry_run_failure_is_negative_verdict_exit_1(self, mocker: MockerFixture) -> None:
# `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
@@ -240,6 +246,9 @@ class TestValidateExitCodes:
agent_validate_pipe_cmd(pipe_code=None, validate_all=True, output_format=CliOutputFormat.JSON)
assert exc_info.value.exit_code == 1
+ @pytest.mark.builds_problems_without_required_params(
+ reason="hands the command dry-run failures built in the test, without the parameters a sweep records"
+ )
def test_agent_validate_pipe_dry_run_failure_is_negative_verdict_exit_1(self, mocker: MockerFixture) -> None:
# Single-pipe validate_pipe_core sweeps through the same cascade.
self._patch_pipe_boot(mocker)
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 3db70db2d..a6f9f7187 100644
--- a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
+++ b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py
@@ -73,6 +73,9 @@ class TestValidateSuggestedFixRendering:
mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)
return recorded_console
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_fixable_error_renders_suggested_fix_line_and_actionable_footer(self, console: Console) -> None:
exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error(source="methods/demo.mthds")])
@@ -87,6 +90,9 @@ class TestValidateSuggestedFixRendering:
# The actionable footer replaces the generic tip — two stacked 💡 tips would be noise.
assert "💡 Tip:" not in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_footer_echoes_library_dirs(self, console: Console) -> None:
exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error(source="methods/demo.mthds")])
@@ -100,6 +106,9 @@ class TestValidateSuggestedFixRendering:
output = console.export_text()
assert "pipelex fix bundle methods/demo.mthds -L libs -L shared" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_footer_preserves_allow_signatures(self, console: Console) -> None:
exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error()])
@@ -113,6 +122,9 @@ class TestValidateSuggestedFixRendering:
output = console.export_text()
assert "pipelex fix bundle methods/demo.mthds --allow-signatures" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_footer_shell_quotes_paths_with_spaces(self, console: Console) -> None:
"""A path with a space must stay one argument when the footer command is copy-pasted."""
exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_fixable_pipe_error(source="my methods/demo.mthds")])
@@ -127,6 +139,9 @@ class TestValidateSuggestedFixRendering:
output = console.export_text()
assert "pipelex fix bundle 'my methods/demo.mthds' -L 'shared libs'" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_ambient_source_is_not_advertised_as_applicable(self, console: Console, tmp_path: Path, mocker: MockerFixture) -> None:
bundle_path = tmp_path / "entry.mthds"
ambient_dir = tmp_path / "ambient"
@@ -146,6 +161,9 @@ class TestValidateSuggestedFixRendering:
assert "pipelex fix bundle" not in output
assert "💡 Tip:" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_non_fixable_errors_keep_generic_tip_and_no_fix_line(self, console: Console) -> None:
exc = ValidateBundleError(message="validation failed", pipe_validation_errors=[_non_fixable_pipe_error()])
@@ -157,6 +175,9 @@ class TestValidateSuggestedFixRendering:
assert "can be fixed automatically" not in output
assert "💡 Tip:" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
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(
@@ -188,6 +209,9 @@ class TestValidateSuggestedFixRendering:
assert "pipelex fix bundle" not in output
assert "💡 Tip:" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors in the test, without the facts their raise sites give their items' codes"
+ )
def test_fixable_count_sums_only_fixable_items(self, console: Console) -> None:
exc = ValidateBundleError(
message="validation failed",
@@ -222,6 +246,9 @@ class TestValidateSuggestedFixRendering:
assert "concept 'MissingConcept' is not declared in domain 'demo'" in output
assert "Declared Concepts: Idea, Report" in output
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds its validation errors and its dry-run failure in the test, without the facts their raise sites give their items' codes"
+ )
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(
diff --git a/tests/unit/pipelex/cogt/doc_gen/test_formatted_markdown.py b/tests/unit/pipelex/cogt/doc_gen/test_formatted_markdown.py
index c77c3097a..1ee5894c8 100644
--- a/tests/unit/pipelex/cogt/doc_gen/test_formatted_markdown.py
+++ b/tests/unit/pipelex/cogt/doc_gen/test_formatted_markdown.py
@@ -105,12 +105,18 @@ class TestFormattedMarkdown:
formatted = format_markdown(markdown=MarkdownFormattingTestData.LONG_REPORT)
assert sum(isinstance(block, FormattedHeading) for block in formatted.blocks) == 300
+ @pytest.mark.builds_problems_without_required_params(
+ reason="outside a render, the Markdown conversion knows neither the input it formats nor the size it would reach; the engine that called it "
+ "names where the value goes"
+ )
def test_the_budget_error_is_the_caller_s(self) -> None:
with pytest.raises(MarkdownFormattingBudgetError) as caught:
format_markdown(markdown=MarkdownFormattingTestData.PADDED_TABLE)
caller = caught.value.to_problem(view=ProblemView.CALLER)
assert caller.code == CoreCode.INPUT_TOO_LARGE
assert caller.domain == ProblemDomain.INPUT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"limit": DEFAULT_RENDER_BUDGET_UNITS}
assert f"{DEFAULT_RENDER_BUDGET_UNITS:,} work units" in caught.value.message
def test_inside_a_render_the_render_s_budget_is_charged_for_the_source_the_tables_and_the_result(self) -> None:
diff --git a/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.py b/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.py
index bed32705d..8507b80a7 100644
--- a/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.py
+++ b/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.py
@@ -61,14 +61,20 @@ class TestExtractFetchFailure:
@pytest.mark.parametrize(
("input_name", "expected_params", "expected_detail"),
[
- (
+ pytest.param(
"scans[2]",
{"input": "scans[2]", "host": "example.com"},
"The URL of the input 'scans[2]', on 'example.com', did not answer or answered with an error.",
+ id="named_input",
+ ),
+ pytest.param(
+ None,
+ {"host": "example.com"},
+ "An input's URL could not be fetched",
+ id="unnamed_input",
+ marks=pytest.mark.builds_problems_without_required_params(reason="a URL no input gave names no input"),
),
- (None, {"host": "example.com"}, "An input's URL could not be fetched"),
],
- ids=["named_input", "unnamed_input"],
)
async def test_the_input_whose_url_could_not_be_fetched_is_named(
self, input_name: str | None, expected_params: dict[str, str], expected_detail: str
diff --git a/tests/unit/pipelex/cogt/extract/test_extract_input_format_check.py b/tests/unit/pipelex/cogt/extract/test_extract_input_format_check.py
index 9cfb5e936..e316d09f9 100644
--- a/tests/unit/pipelex/cogt/extract/test_extract_input_format_check.py
+++ b/tests/unit/pipelex/cogt/extract/test_extract_input_format_check.py
@@ -83,7 +83,10 @@ class TestExtractInputFormatCheck:
"Input 'transcripts[0]' is a Word document (.docx), which model 'azure-document-intelligence' cannot extract: "
"it reads PDF and images. Give a file in one of those formats, or use an extract model that reads this one."
)
- assert exc_info.value.to_problem(view=ProblemView.CALLER).domain == ProblemDomain.INPUT
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.domain == ProblemDomain.INPUT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"format": "docx", "model": "azure-document-intelligence", "input": "transcripts[0]"}
assert worker.nb_provider_calls == 0
async def test_a_file_with_no_input_name_is_named_as_the_file_to_extract(self):
diff --git a/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py b/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py
index bbc37bfc7..3825608d0 100644
--- a/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py
+++ b/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py
@@ -307,6 +307,8 @@ class TestWhatItAnswersOverHTTP:
assert problem.code == CoreCode.MODEL_UNAVAILABLE
assert problem.domain == ProblemDomain.OPERATOR
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"model": _MODEL_NOT_ALLOWED_HANDLE, "model_type": "llm", "reason": "not_allowed"}
assert error_code_spec(CoreCode.MODEL_UNAVAILABLE).status == 501
assert unrecognized_problem.code == CoreCode.RUNTIME_UNEXPECTED
assert unrecognized_problem.domain == ProblemDomain.RUNTIME
diff --git a/tests/unit/pipelex/cogt/inference/test_render_inference_error.py b/tests/unit/pipelex/cogt/inference/test_render_inference_error.py
index a51cf2496..b3b47d3d2 100644
--- a/tests/unit/pipelex/cogt/inference/test_render_inference_error.py
+++ b/tests/unit/pipelex/cogt/inference/test_render_inference_error.py
@@ -28,7 +28,7 @@ from pipelex.cogt.exceptions import (
)
from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserActionKind
from pipelex.cogt.inference.error_classify import ClassificationResult, InferenceErrorFamily
-from pipelex.cogt.inference.error_render import render_inference_error
+from pipelex.cogt.inference.error_render import _FAMILY_MODEL_TYPES, render_inference_error # pyright: ignore[reportPrivateUsage]
from pipelex.cogt.inference.provider_name import ProviderName
from pipelex.errors.problem import ProblemView
from pipelex.pipe_run.exceptions import PipeRouterError
@@ -126,6 +126,10 @@ class TestRenderInferenceError:
assert rendered.error_category == InferenceErrorCategory.CONFIGURATION
assert rendered.model_handle == "fake-handle"
assert rendered.provider_metadata is metadata
+ # The provider does not know the model the deck resolved, which the problem names with the family's kind of model.
+ caller = rendered.to_problem(view=ProblemView.CALLER)
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"model": "fake-handle", "model_type": _FAMILY_MODEL_TYPES[family], "reason": "unknown_at_provider"}
def test_content_policy_detail_when_violation_present(self) -> None:
metadata = ProviderErrorMetadata(
@@ -151,6 +155,9 @@ class TestRenderInferenceError:
assert rendered.user_action is not None
assert "safety filters" in rendered.user_action.detail
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the rendered failure is built below the worker, whose enrichment names the model and the provider"
+ )
@pytest.mark.parametrize(
("retry_after_seconds", "expected_detail"),
[
diff --git a/tests/unit/pipelex/cogt/llm/test_llm_worker_document_format.py b/tests/unit/pipelex/cogt/llm/test_llm_worker_document_format.py
index 0ee1a8f99..037a59ccb 100644
--- a/tests/unit/pipelex/cogt/llm/test_llm_worker_document_format.py
+++ b/tests/unit/pipelex/cogt/llm/test_llm_worker_document_format.py
@@ -105,6 +105,7 @@ def _make_llm_job(*, user_documents: list[PromptDocument]) -> LLMJob:
@pytest.mark.asyncio(loop_scope="class")
class TestLLMWorkerDocumentFormat:
+ @pytest.mark.builds_problems_without_required_params(reason="a prompt document reaches the worker by its position, with no input name")
async def test_a_document_format_the_model_does_not_read_is_an_input_error(self):
worker = _make_worker(inputs=["text", "pdf"])
documents: list[PromptDocument] = [
@@ -118,7 +119,10 @@ class TestLLMWorkerDocumentFormat:
assert str(exc_info.value) == (
"Prompt document 2 given to model 'gpt-docs-test' is a Word document (.docx), which it does not read: it reads PDF."
)
- assert exc_info.value.to_problem(view=ProblemView.CALLER).domain == ProblemDomain.INPUT
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.domain == ProblemDomain.INPUT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"format": "docx", "model": "gpt-docs-test"}
assert worker.nb_provider_calls == 0
async def test_a_model_reading_no_documents_is_still_a_capability_error(self):
diff --git a/tests/unit/pipelex/cogt/llm/test_llm_worker_prompt_image_format.py b/tests/unit/pipelex/cogt/llm/test_llm_worker_prompt_image_format.py
index 19978c137..ca5f8e042 100644
--- a/tests/unit/pipelex/cogt/llm/test_llm_worker_prompt_image_format.py
+++ b/tests/unit/pipelex/cogt/llm/test_llm_worker_prompt_image_format.py
@@ -82,6 +82,7 @@ def _make_llm_job(*, user_images: list[PromptImage]) -> LLMJob:
@pytest.mark.asyncio(loop_scope="class")
class TestLLMWorkerPromptImageFormat:
+ @pytest.mark.builds_problems_without_required_params(reason="a prompt image reaches the worker by its position, with no input name")
@pytest.mark.parametrize(
"pdf_image",
[
@@ -98,7 +99,10 @@ class TestLLMWorkerPromptImageFormat:
await worker.gen_text(llm_job=_make_llm_job(user_images=[png_image, pdf_image]))
assert str(exc_info.value) == ("Prompt image 2 given to model 'gpt-vision-test' is a PDF document (.pdf), not an image.")
- assert exc_info.value.to_problem(view=ProblemView.CALLER).domain == ProblemDomain.INPUT
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.domain == ProblemDomain.INPUT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"format": "pdf", "model": "gpt-vision-test"}
assert worker.nb_provider_calls == 0
@pytest.mark.parametrize(
diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_library_disabled_declarations.py b/tests/unit/pipelex/cogt/model_backends/test_backend_library_disabled_declarations.py
new file mode 100644
index 000000000..d7c8de8fb
--- /dev/null
+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_library_disabled_declarations.py
@@ -0,0 +1,49 @@
+"""A disabled backend's file tells the deck which models this deployment knows of but does not serve, and never stops a boot."""
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.cogt.model_backends.backend_library import InferenceBackendLibrary
+from pipelex.cogt.model_backends.credential_resolution import CredentialResolution
+from pipelex.cogt.model_backends.model_type import ModelType
+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
+from tests.unit.pipelex.cogt.model_backends.test_data import BackendLibraryTomls
+
+
+class TestBackendLibraryDisabledDeclarations:
+ @pytest.mark.parametrize(
+ ("_topic", "disabled_file_bytes", "expected_cataloged"),
+ [
+ (
+ "declares_a_model",
+ BackendLibraryTomls.DISABLED_MODEL_SPECS_TOML.encode(),
+ {"acme-one": [ModelType.LLM], "dormant-one": [ModelType.LLM]},
+ ),
+ ("not_utf8", b'["dormant-one"]\nmodel_id = "\xff"\n', {"acme-one": [ModelType.LLM]}),
+ ("not_toml", b"[dormant-one\n", {"acme-one": [ModelType.LLM]}),
+ ("missing", None, {"acme-one": [ModelType.LLM]}),
+ ],
+ )
+ def test_a_disabled_backend_s_file_never_stops_the_boot(
+ self, tmp_path: Path, _topic: str, disabled_file_bytes: bytes | None, expected_cataloged: dict[str, list[ModelType]]
+ ) -> None:
+ """A disabled backend's models are cataloged, never served, and a file of its that cannot be read declares nothing."""
+ backends_dir = tmp_path / "backends"
+ backends_dir.mkdir()
+ if disabled_file_bytes is not None:
+ (backends_dir / "dormant.toml").write_bytes(disabled_file_bytes)
+ (backends_dir / "acme.toml").write_text(BackendLibraryTomls.MODEL_SPECS_TOML)
+ backends_library_path = tmp_path / "backends.toml"
+ backends_library_path.write_text(BackendLibraryTomls.BACKENDS_TOML_WITH_A_DISABLED_BACKEND)
+ library = InferenceBackendLibrary.make_empty()
+
+ library.load(
+ secrets_provider=EnvSecretsProvider(),
+ backends_library_paths=[backends_library_path],
+ backends_dir_path=str(backends_dir),
+ credentials=CredentialResolution.SKIP,
+ )
+
+ assert library.list_backend_names() == ["acme"]
+ assert library.get_cataloged_types_by_handle() == expected_cataloged
diff --git a/tests/unit/pipelex/cogt/model_backends/test_data.py b/tests/unit/pipelex/cogt/model_backends/test_data.py
index cea8f3fdc..72f40e191 100644
--- a/tests/unit/pipelex/cogt/model_backends/test_data.py
+++ b/tests/unit/pipelex/cogt/model_backends/test_data.py
@@ -15,6 +15,26 @@ api_key = "sk-not-a-real-key"
[acme]
enabled = true
api_key = "${{{ABSENT_VAR}}}"
+"""
+
+ # A served backend beside one switched off, whose file declares a model this deployment knows but does not serve.
+ BACKENDS_TOML_WITH_A_DISABLED_BACKEND = """
+[acme]
+enabled = true
+api_key = "sk-not-a-real-key"
+
+[dormant]
+enabled = false
+api_key = "sk-not-a-real-key"
+"""
+
+ DISABLED_MODEL_SPECS_TOML = """
+[defaults]
+model_type = "llm"
+sdk = "openai_responses"
+
+["dormant-one"]
+model_id = "dormant-one"
"""
MODEL_SPECS_TOML = """
diff --git a/tests/unit/pipelex/cogt/models/test_data.py b/tests/unit/pipelex/cogt/models/test_data.py
index 64cfb40f8..9ff509f0a 100644
--- a/tests/unit/pipelex/cogt/models/test_data.py
+++ b/tests/unit/pipelex/cogt/models/test_data.py
@@ -35,3 +35,14 @@ class ModelDeckCheckTestData:
"held-nowhere",
"@held-nowhere",
]
+
+
+class UnservedReferenceTestData:
+ # The one model the deck serves, as an LLM.
+ SERVED_HANDLE = "served-model"
+ # A model a catalog of the deployment declares on a backend it does not enable, as `claude-4.5-haiku` is with
+ # `anthropic` switched off.
+ CATALOGED_HANDLE = "switched-off-model"
+ # Names no catalog knows: one a letter away from the served handle, one near nothing.
+ NEAR_HANDLE = "served-modle"
+ FAR_HANDLE = "zzz"
diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_lookups_per_pair.py b/tests/unit/pipelex/cogt/models/test_model_deck_lookups_per_pair.py
index 4c3ebd2b5..24afb61a9 100644
--- a/tests/unit/pipelex/cogt/models/test_model_deck_lookups_per_pair.py
+++ b/tests/unit/pipelex/cogt/models/test_model_deck_lookups_per_pair.py
@@ -57,5 +57,5 @@ class TestLookupsPerPair:
assert caller.code == CoreCode.MODEL_UNKNOWN
assert caller.next_step.kind == StepKind.CHANGE_MODEL
assert caller.params is not None
- assert caller.params.as_wire() == {"model": "verdict", "model_type": ModelType.LLM}
+ assert caller.params.as_wire() == {"model": "verdict", "model_type": ModelType.LLM, "suggestions": []}
assert "judgment" not in str(caller.to_wire())
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
index b041f50be..3da7ad018 100644
--- a/tests/unit/pipelex/cogt/models/test_model_deck_unknown_reference.py
+++ b/tests/unit/pipelex/cogt/models/test_model_deck_unknown_reference.py
@@ -73,18 +73,19 @@ def _raise_not_found(*, model_handle: str, model_type: ModelType) -> ModelNotFou
class TestModelDeckUnknownReference:
@pytest.mark.parametrize(
- ("_topic", "model_handle", "model_type"),
+ ("_topic", "model_handle", "model_type", "expected_suggestions"),
[
- ("handle", "method-only-model", ModelType.LLM),
- ("alias", "@method-only-alias", ModelType.LLM),
- ("waterfall", "~method-only-waterfall", ModelType.LLM),
- ("preset_used_as_a_model", "$deck-preset", ModelType.LLM),
- ("extract_handle", "method-only-extractor", ModelType.TEXT_EXTRACTOR),
- ("search_handle", "method-only-search", ModelType.SEARCH),
+ # A handle near one the deck serves as that type is offered it.
+ ("handle", "method-only-model", ModelType.LLM, ["served-model"]),
+ ("alias", "@method-only-alias", ModelType.LLM, []),
+ ("waterfall", "~method-only-waterfall", ModelType.LLM, []),
+ ("preset_used_as_a_model", "$deck-preset", ModelType.LLM, []),
+ ("extract_handle", "method-only-extractor", ModelType.TEXT_EXTRACTOR, []),
+ ("search_handle", "method-only-search", ModelType.SEARCH, []),
# An LLM preset names it, but no image-generation entry does.
- ("img_gen_handle", "deck-preset-model", ModelType.IMG_GEN),
+ ("img_gen_handle", "deck-preset-model", ModelType.IMG_GEN, []),
# The deck serves it, but as an LLM, which an image-generation lookup refuses.
- ("served_handle_of_another_type", "served-model", ModelType.IMG_GEN),
+ ("served_handle_of_another_type", "served-model", ModelType.IMG_GEN, []),
],
)
def test_a_reference_only_the_method_names_is_the_callers_fault(
@@ -92,6 +93,7 @@ class TestModelDeckUnknownReference:
_topic: str,
model_handle: str,
model_type: ModelType,
+ expected_suggestions: list[str],
) -> None:
"""A reference the deck neither defines nor names came from the method: `model.unknown`, in the method's domain."""
error = _raise_not_found(model_handle=model_handle, model_type=model_type)
@@ -105,7 +107,7 @@ class TestModelDeckUnknownReference:
# The caller reads 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.
assert caller.params is not None
- assert caller.params.as_wire() == {"model": model_handle, "model_type": model_type}
+ assert caller.params.as_wire() == {"model": model_handle, "model_type": model_type, "suggestions": expected_suggestions}
assert caller.detail == f"The method names the {model_type} model '{model_handle}', which no catalog knows."
assert caller.next_step.kind == StepKind.CHANGE_MODEL
assert caller.diagnostics is None
diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_unserved_reference.py b/tests/unit/pipelex/cogt/models/test_model_deck_unserved_reference.py
new file mode 100644
index 000000000..e3bfca9d0
--- /dev/null
+++ b/tests/unit/pipelex/cogt/models/test_model_deck_unserved_reference.py
@@ -0,0 +1,98 @@
+import pytest
+from mthds.protocol.problem.registry import CoreCode, ModelUnavailableReason, ProblemDomain
+
+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.llm.llm_setting import LLMSetting, LLMSettingChoicesDefaults
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
+from pipelex.cogt.model_backends.model_spec_index import ModelSpecIndex
+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.errors.problem import ProblemView
+from pipelex.system.runtime import ProblemReaction
+from tests.unit.pipelex.cogt.models.test_data import UnservedReferenceTestData as Data
+
+
+def _make_deck() -> ModelDeck:
+ """A deck serving one model, whose catalogs also declare a model on a backend this deployment does not enable."""
+ served_model = InferenceModelSpec(
+ backend_name="test_backend",
+ name=Data.SERVED_HANDLE,
+ 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=ModelSpecIndex.make_from_specs(model_specs=[served_model]),
+ cataloged_handles={Data.SERVED_HANDLE: [ModelType.LLM], Data.CATALOGED_HANDLE: [ModelType.LLM]},
+ llm_default_temperature=0.7,
+ llm_aliases={},
+ llm_waterfalls={},
+ llm_presets={},
+ llm_choice_defaults=LLMSettingChoicesDefaults(
+ default_temperature=0.7,
+ for_text=LLMSetting(model=Data.SERVED_HANDLE, temperature=0.7),
+ for_object=LLMSetting(model=Data.SERVED_HANDLE, temperature=0.7),
+ ),
+ extract_aliases={},
+ extract_waterfalls={},
+ extract_presets={"deck-extract-preset": ExtractSetting(model=Data.SERVED_HANDLE)},
+ extract_choice_default="$deck-extract-preset",
+ img_gen_default_quality=Quality.MEDIUM,
+ img_gen_aliases={},
+ img_gen_waterfalls={},
+ img_gen_presets={},
+ img_gen_choice_default=Data.SERVED_HANDLE,
+ search_aliases={},
+ search_waterfalls={},
+ search_presets={},
+ search_choice_default=Data.SERVED_HANDLE,
+ 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 TestModelDeckUnservedReference:
+ def test_a_model_a_catalog_knows_but_no_enabled_backend_serves_is_unavailable(self) -> None:
+ """The model exists on a backend this deployment switched off: the deployment's `model.unavailable`, never `model.unknown`."""
+ deck = _make_deck()
+ assert deck.is_cataloged_but_unserved(name=Data.CATALOGED_HANDLE, model_type=ModelType.LLM)
+ assert not deck.is_cataloged_but_unserved(name=Data.SERVED_HANDLE, model_type=ModelType.LLM)
+ assert not deck.is_cataloged_but_unserved(name=Data.CATALOGED_HANDLE, model_type=ModelType.IMG_GEN)
+
+ caller = _raise_not_found(model_handle=Data.CATALOGED_HANDLE, model_type=ModelType.LLM).to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.MODEL_UNAVAILABLE
+ assert caller.domain == ProblemDomain.OPERATOR
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"model": Data.CATALOGED_HANDLE, "model_type": "llm", "reason": ModelUnavailableReason.NOT_SERVED}
+
+ @pytest.mark.parametrize(
+ ("_topic", "model_handle", "expected_suggestions"),
+ [
+ ("near_a_served_handle", Data.NEAR_HANDLE, [Data.SERVED_HANDLE]),
+ ("near_no_served_handle", Data.FAR_HANDLE, []),
+ ],
+ )
+ def test_a_model_no_catalog_knows_offers_the_nearest_served_handles(
+ self, _topic: str, model_handle: str, expected_suggestions: list[str]
+ ) -> None:
+ """A name no catalog knows is the method's `model.unknown`, which always offers the nearest handles, an empty list when none is near."""
+ caller = _raise_not_found(model_handle=model_handle, model_type=ModelType.LLM).to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.MODEL_UNKNOWN
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"model": model_handle, "model_type": "llm", "suggestions": expected_suggestions}
diff --git a/tests/unit/pipelex/cogt/test_exceptions.py b/tests/unit/pipelex/cogt/test_exceptions.py
index 0c586afd6..c402b912d 100644
--- a/tests/unit/pipelex/cogt/test_exceptions.py
+++ b/tests/unit/pipelex/cogt/test_exceptions.py
@@ -167,6 +167,9 @@ class TestErrorCategoryInfrastructure:
assert problem.code == CoreCode.RUNTIME_UNEXPECTED
assert problem.is_retryable is False
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
def test_to_problem_with_all_cogt_fields(self) -> None:
"""The advice rides the error, never the problem, and a transient failure with no code reports a code that invites a retry."""
err = LLMCompletionError(
@@ -184,6 +187,9 @@ class TestErrorCategoryInfrastructure:
assert advice.detail == "Retry in a moment"
assert "Retry in a moment" not in json.dumps(problem.to_wire())
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds a not-found failure by hand, without the kind of model and the reason its raise site gives"
+ )
def test_to_problem_with_model_handle(self) -> None:
"""The operator's diagnostics name the model of an error carrying a model_handle."""
err = LLMModelNotFoundError(message="missing", model_handle="gpt-4o")
@@ -225,6 +231,9 @@ class TestErrorCategoryInfrastructure:
assert "model" not in operator_wire["diagnostics"]
assert "provider" not in operator_wire["diagnostics"]
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds a not-found failure by hand, without the kind of model and the reason its raise site gives"
+ )
def test_to_problem_to_wire_json_serializable(self) -> None:
"""to_wire() output can be serialized to JSON and read back as the same problem."""
err = LLMModelNotFoundError(message="not found", model_handle="gpt-4o")
@@ -233,6 +242,9 @@ class TestErrorCategoryInfrastructure:
assert deserialized == problem_wire
assert PipelexProblem.model_validate(deserialized).to_wire() == problem_wire
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
def test_from_exc_chain_preserved(self) -> None:
"""Exception cause chain is preserved with from exc."""
original = ValueError("original error")
diff --git a/tests/unit/pipelex/cogt/test_inference_error_domain.py b/tests/unit/pipelex/cogt/test_inference_error_domain.py
index 01513eca2..95c1e67f8 100644
--- a/tests/unit/pipelex/cogt/test_inference_error_domain.py
+++ b/tests/unit/pipelex/cogt/test_inference_error_domain.py
@@ -31,6 +31,9 @@ class _WrapperError(PipelexError):
class TestInferenceErrorDomain:
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds inference failures by hand, below the worker that names their model and provider"
+ )
@pytest.mark.parametrize(
("_topic", "category", "expected_code", "expected_domain", "expected_retryable"),
ExceptionTestData.CATEGORY_CODE_CASES,
@@ -57,6 +60,9 @@ class TestInferenceErrorDomain:
covered = {category for _topic, category, _code, _domain, _retryable in ExceptionTestData.CATEGORY_CODE_CASES}
assert covered == set(InferenceErrorCategory)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds inference failures by hand, below the worker that names their model and provider"
+ )
def test_a_retryable_category_never_reports_a_code_no_retry_clears(self) -> None:
"""The run repeats a call whose category is retryable, so the problem of one built with no code must invite a retry too."""
for category in InferenceErrorCategory:
@@ -84,6 +90,9 @@ class TestInferenceErrorDomain:
assert error.resolve_error_code() == CoreCode.PROVIDER_UNAVAILABLE
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
def test_a_wrapper_reports_the_category_s_code(self) -> None:
"""The pipe and run wrappers take their cause's code, so a transient failure stays retryable through them."""
failure = LLMCompletionError("connection reset", error_category=InferenceErrorCategory.TRANSIENT)
@@ -95,6 +104,9 @@ class TestInferenceErrorDomain:
assert problem.code == CoreCode.PROVIDER_UNAVAILABLE
assert problem.is_retryable is True
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds inference failures by hand, below the worker that names their model and provider"
+ )
def test_a_cyclic_pair_of_category_failures_reports_without_recursing(self) -> None:
"""Two failures chained to each other report the category's code, under a wrapper too, where the walk of each recursed."""
outer = LLMCompletionError("connection reset", error_category=InferenceErrorCategory.TRANSIENT)
diff --git a/tests/unit/pipelex/cogt/test_llm_completion_stop_errors.py b/tests/unit/pipelex/cogt/test_llm_completion_stop_errors.py
index a3bcb39e5..57a60083f 100644
--- a/tests/unit/pipelex/cogt/test_llm_completion_stop_errors.py
+++ b/tests/unit/pipelex/cogt/test_llm_completion_stop_errors.py
@@ -208,6 +208,9 @@ class TestLLMCompletionStopErrors:
"so the text cannot be used. Revise the prompt or the input."
)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a context-window stop signal carries neither the prompt's size nor the window's, the counts of model.context_exceeded"
+ )
@pytest.mark.parametrize(
("error_class", "error", "expected_code", "expected_domain", "user_action_detail"),
[
@@ -253,6 +256,9 @@ class TestLLMCompletionStopErrors:
assert advice.kind == UserActionKind.CHANGE_INPUT
assert advice.detail == user_action_detail
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a context-window stop signal carries neither the prompt's size nor the window's, the counts of model.context_exceeded"
+ )
@pytest.mark.parametrize("error", [_truncated_error(), _context_window_error(), _refused_error()])
def test_the_caller_reads_the_model_without_the_partial_text(self, error: LLMCompletionError) -> None:
"""The caller's problem names the model in the code's parameters, and no view carries the partial text."""
@@ -286,3 +292,14 @@ class TestLLMCompletionStopErrors:
assert problem.diagnostics is not None
assert problem.diagnostics.error_class == "LLMCompletionTruncatedError"
assert problem.diagnostics.message == TRUNCATED_MESSAGE
+
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a context-window stop signal carries neither the prompt's size nor the window's, the counts of model.context_exceeded"
+ )
+ def test_a_context_window_stop_names_the_bound_it_passed(self) -> None:
+ """The stop signal names the bound, the context window, and neither the prompt's size nor the window's."""
+ caller = _context_window_error().to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.MODEL_CONTEXT_EXCEEDED
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"model": "claude-5-sonnet", "limit": "context_window"}
diff --git a/tests/unit/pipelex/cogt/test_worker_error_enrichment.py b/tests/unit/pipelex/cogt/test_worker_error_enrichment.py
index 5404da2ef..68d265f05 100644
--- a/tests/unit/pipelex/cogt/test_worker_error_enrichment.py
+++ b/tests/unit/pipelex/cogt/test_worker_error_enrichment.py
@@ -178,6 +178,9 @@ class TestWorkerErrorEnrichment:
assert diagnostics.provider is not None
assert diagnostics.provider.name == WORKER_PROVIDER
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises a not-found failure built in the test, without the kind of model and the reason its raise site gives"
+ )
async def test_llm_worker_does_not_overwrite_existing_model(self, mocker: MockerFixture) -> None:
"""An inner error that already set model_handle keeps its value; only the missing provider is filled."""
inner_model = "preset-only-model"
@@ -192,6 +195,9 @@ class TestWorkerErrorEnrichment:
assert diagnostics.provider is not None
assert diagnostics.provider.name == WORKER_PROVIDER
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a worker that does not know its provider leaves the provider unnamed, which is what the test checks"
+ )
async def test_llm_worker_skips_unknown_provider(self, mocker: MockerFixture) -> None:
"""A worker that does not know its provider ('unknown' default) leaves provider unset."""
error = LLMCompletionError("LLM worker failed", error_category=InferenceErrorCategory.TRANSIENT)
diff --git a/tests/unit/pipelex/core/bundle_resources/test_bundle_resource_exceptions.py b/tests/unit/pipelex/core/bundle_resources/test_bundle_resource_exceptions.py
index 6288d9ff1..062f5568e 100644
--- a/tests/unit/pipelex/core/bundle_resources/test_bundle_resource_exceptions.py
+++ b/tests/unit/pipelex/core/bundle_resources/test_bundle_resource_exceptions.py
@@ -8,6 +8,7 @@ from pipelex.errors.problem import ProblemView
class TestBundleResourceExceptions:
+ @pytest.mark.builds_problems_without_required_params(reason="builds each refusal with a message alone, to check its retry verdict")
@pytest.mark.parametrize(
("error_class", "expected_code"),
[
@@ -28,6 +29,7 @@ class TestBundleResourceExceptions:
assert problem.retry == RetryVerdict.NO
assert problem.to_wire()["retry"] == "no"
+ @pytest.mark.builds_problems_without_required_params(reason="builds the refusal with a message alone, to check what its wrapper reports")
def test_a_wrapper_raised_from_one_carries_its_code_and_retry(self) -> None:
try:
try:
@@ -45,6 +47,7 @@ class TestBundleResourceExceptions:
assert problem.diagnostics.error_class == "PipelexError"
assert [cause.error_class for cause in problem.diagnostics.causes or []] == ["BundleResourceNotNamedError"]
+ @pytest.mark.builds_problems_without_required_params(reason="builds the refusal with a message alone, to check the code its raise site chooses")
def test_two_paths_naming_one_file_are_an_invalid_request(self) -> None:
"""A raise site that refuses paths that cannot make one tree chooses the request's code, not the path refusal's."""
problem = BundleResourcePathError("Two files name one file.").with_error_code(CoreCode.REQUEST_INVALID).to_problem(view=ProblemView.CALLER)
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py b/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py
index 153d0a509..098142e73 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_csv_by_signature.py
@@ -11,14 +11,18 @@ from typing import Any, cast
import pytest
from mthds.protocol.problem.registry import CoreCode
+from pytest_mock import MockerFixture
+from pipelex.core.concepts.exceptions import ConceptStructureClassNotFoundError
from pipelex.core.memory.exceptions import MultiplicityCountMismatchError, StructureValidationError, WrongScalarKindError
from pipelex.core.memory.input_shaper import InputShaper
from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.errors.problem import ProblemView
+from pipelex.errors.unsupported_reasons import REMOTE_TABLE_UNSUPPORTED_REASON
from pipelex.interpreter_hub import get_concept_library
-from pipelex.tools.tabular.exceptions import CsvError
+from pipelex.tools.tabular.exceptions import CsvCoercionError, CsvError
from tests.unit.pipelex.core.memory.input_shaper.data import ShaperPerson, build_input_specs
PEOPLE_CSV_CONTENT = "name\nAda Lovelace\nGrace Hopper\n"
@@ -130,6 +134,71 @@ class TestInputShaperCsvBySignature:
), topic
operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)
assert "confidential" not in json.dumps(operator.to_wire()), topic
+ # Only a local path is read as a table: the form the input uses is one this runtime does not accept.
+ assert operator.code == CoreCode.REQUEST_UNSUPPORTED, topic
+ assert operator.params is not None
+ assert operator.params.as_wire() == {"field": "inputs.people", "reason": REMOTE_TABLE_UNSUPPORTED_REASON}, topic
+ assert operator.location is not None
+ assert operator.location.as_wire() == {"input": "people"}, topic
+
+ def test_a_table_url_that_does_not_parse_is_an_unreadable_file(self):
+ """A url that does not parse names no file to read: the input's file is unreadable, and the url stays out."""
+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
+
+ with pytest.raises(CsvError) as exc_info:
+ InputShaper.shape(
+ {"people": {"url": "https://[confidential-patient-diagnosis/people.csv"}},
+ input_specs=input_specs,
+ concept_provider=get_concept_library(),
+ read_scope=None,
+ )
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.INPUT_FILE_UNREADABLE
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"input": "people", "file_type": "csv", "reason": "the URL does not parse"}
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"input": "people"}
+ operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)
+ assert "confidential" not in json.dumps(operator.to_wire())
+
+ def test_a_concept_with_no_structure_class_is_the_method_s_concept_failing(self, people_csv: Path, mocker: MockerFixture):
+ """A concept whose rows have no class to be read into is no fault of the caller's table: its concept cannot be built."""
+ concept_library = get_concept_library()
+ concept = concept_library.get_required_concept(concept_ref="shaper_test.ShaperPerson")
+ mocker.patch.object(
+ type(concept_library), "get_structure_class", side_effect=ConceptStructureClassNotFoundError("no class registered for the concept")
+ )
+
+ with pytest.raises(CsvError) as exc_info:
+ StuffFactory.try_make_csv_list_content(
+ concept, concept_provider=concept_library, content={"url": str(people_csv)}, name="people", read_scope=None
+ )
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_CONCEPT_INVALID
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"concept": "shaper_test.ShaperPerson", "finding": "it has no structure class to read rows into"}
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"input": "people"}
+
+ def test_a_row_the_codec_refuses_without_a_location_names_the_input_as_its_field(self, people_csv: Path, mocker: MockerFixture):
+ """A row refused as a whole, which pydantic locates nowhere, is the input's own fault, as a table refused whole is."""
+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])
+ mocker.patch(
+ "pipelex.core.stuffs.stuff_factory.list_content_from_csv",
+ side_effect=CsvCoercionError("Could not coerce row 2 of the CSV file").with_params(field=None),
+ )
+
+ with pytest.raises(CsvError) as exc_info:
+ InputShaper.shape({"people": str(people_csv)}, input_specs=input_specs, concept_provider=get_concept_library(), read_scope=None)
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.INPUT_INVALID
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"input": "people", "field": "people"}
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"input": "people"}
def test_a_table_that_does_not_fit_names_the_input_never_the_file(self, tmp_path: Path):
"""The codec knows the file alone: the input it was given as completes the problem's sentence, and the path stays out."""
@@ -143,6 +212,8 @@ class TestInputShaperCsvBySignature:
caller = exc_info.value.to_problem(view=ProblemView.CALLER)
assert caller.code == CoreCode.INPUT_INVALID
assert caller.params is not None
- assert caller.params.as_wire() == {"input": "people"}
+ assert caller.params.as_wire() == {"input": "people", "field": "people"}
+ assert caller.location is not None
+ assert caller.location.as_wire() == {"input": "people"}
operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)
assert "confidential" not in json.dumps(operator.to_wire())
diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_errors.py b/tests/unit/pipelex/core/memory/input_shaper/test_errors.py
index 41dd29d6b..05b4ddb34 100644
--- a/tests/unit/pipelex/core/memory/input_shaper/test_errors.py
+++ b/tests/unit/pipelex/core/memory/input_shaper/test_errors.py
@@ -181,9 +181,25 @@ CALLER_VIEW_CASES: list[tuple[str, str, VariableMultiplicity | None, Any, CoreCo
{"input": "my_input", "field": "scores.<key>"},
"The input 'my_input' does not fit its concept's structure at 'scores.<key>'.",
),
- # `input.invalid` names the field at fault, and a value wrong as a whole has none: its sentence is the code's title.
- ("wrong-str-for-number", "shaper_test.Priority", None, "42", CoreCode.INPUT_INVALID, {"input": "my_input"}, None),
- ("null-top-level", "native.Text", None, None, CoreCode.INPUT_INVALID, {"input": "my_input"}, None),
+ # `input.invalid` names the field at fault, and a value wrong as a whole names the input itself, the root of every field path.
+ (
+ "wrong-str-for-number",
+ "shaper_test.Priority",
+ None,
+ "42",
+ CoreCode.INPUT_INVALID,
+ {"input": "my_input", "field": "my_input"},
+ "The input 'my_input' does not fit its concept's structure at 'my_input'.",
+ ),
+ (
+ "null-top-level",
+ "native.Text",
+ None,
+ None,
+ CoreCode.INPUT_INVALID,
+ {"input": "my_input", "field": "my_input"},
+ "The input 'my_input' does not fit its concept's structure at 'my_input'.",
+ ),
]
diff --git a/tests/unit/pipelex/core/method_trees/test_tree_python.py b/tests/unit/pipelex/core/method_trees/test_tree_python.py
index e44c6dd09..7b5a2f1c6 100644
--- a/tests/unit/pipelex/core/method_trees/test_tree_python.py
+++ b/tests/unit/pipelex/core/method_trees/test_tree_python.py
@@ -6,7 +6,7 @@ from pathlib import Path
import pytest
from mthds.method_tree.lister import list_method_tree
from mthds.method_tree.models import MethodTree
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
from pytest_mock import MockerFixture
from pipelex.core.method_trees import tree_python
@@ -210,6 +210,8 @@ class TestTreePython:
TREE_PYTHON_HOLD.acquire(tree=shadowing, holder="run-shadowing", label="the method tree holding shadowing.mthds")
shadowing_problem = shadowing_info.value.to_problem(view=ProblemView.CALLER)
assert shadowing_problem.code == CoreCode.METHOD_NAME_CONFLICT
+ assert shadowing_problem.params is not None
+ assert shadowing_problem.params.as_wire() == {"name": "json", "conflict": MethodNameConflictConflict.DUPLICATE_DECLARATION}
operator_report = json.dumps(shadowing_info.value.to_problem(view=ProblemView.OPERATOR).to_wire())
assert "the method tree holding shadowing.mthds" in operator_report
assert "json.py" in operator_report
@@ -249,3 +251,18 @@ class TestTreePython:
check_tree_module_names(top_level_modules=top_level_modules, tree_label=_LABEL, root=tmp_path, checks_this_process=True)
assert judged_spy.call_count == 2 * len(top_level_modules)
+
+ def test_a_module_resolving_outside_the_tree_is_a_name_conflict_naming_it(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """A module of that name imported before the tree's Python loaded hides the tree's own: the conflict names the module."""
+ tree = _write_tree(root=tmp_path / "hidden", files={"hidden.mthds": 'domain = "hidden"\n', "tree_probe_hidden_by.py": "X = 1\n"})
+ identity = TREE_PYTHON_HOLD.acquire(tree=tree, holder="run-hidden", label=_LABEL)
+ # Only the tree module's own reference to `importlib` is replaced, so no other import of the test resolves to it.
+ mocker.patch.object(tree_python, "importlib", mocker.MagicMock(import_module=mocker.MagicMock(return_value=json)))
+
+ with pytest.raises(TreePythonError) as raised:
+ import_held_tree_module(identity=identity, module_name="tree_probe_hidden_by")
+
+ caller = raised.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_NAME_CONFLICT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"name": "tree_probe_hidden_by", "conflict": MethodNameConflictConflict.DUPLICATE_DECLARATION}
diff --git a/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py b/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py
index 7b4ba8008..e0dea586a 100644
--- a/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py
+++ b/tests/unit/pipelex/core/pipes/test_multiplicity_helpers.py
@@ -8,11 +8,13 @@ the way a `[1]` does.
"""
import pytest
+from mthds.protocol.problem.registry import MethodOutputMultiplicityMismatchExpected
from pipelex.core.pipes.variable_multiplicity import (
VariableMultiplicity,
fixed_item_count,
is_multiple_multiplicity,
+ multiplicity_kind,
normalize_variable_multiplicity,
)
@@ -65,6 +67,20 @@ class TestMultiplicityHelpers:
"""
assert normalize_variable_multiplicity(multiplicity=multiplicity) == expected
+ @pytest.mark.parametrize(
+ ("multiplicity", "expected"),
+ [
+ (None, MethodOutputMultiplicityMismatchExpected.SINGLE),
+ (False, MethodOutputMultiplicityMismatchExpected.SINGLE),
+ (1, MethodOutputMultiplicityMismatchExpected.SINGLE),
+ (True, MethodOutputMultiplicityMismatchExpected.LIST),
+ (2, MethodOutputMultiplicityMismatchExpected.FIXED),
+ ],
+ )
+ def test_multiplicity_kind(self, multiplicity: VariableMultiplicity | None, expected: MethodOutputMultiplicityMismatchExpected):
+ """The kind a multiplicity problem names: `[1]` is one item, `[]` a list, and a count above one a fixed-length list."""
+ assert multiplicity_kind(multiplicity=multiplicity) == expected
+
def test_normalize_leaves_a_variable_list_alone(self):
"""`bool` is a subclass of `int` and `True == 1`, so `[]` must not collapse the way `[1]` does."""
assert normalize_variable_multiplicity(multiplicity=True) is True
diff --git a/tests/unit/pipelex/errors/test_data.py b/tests/unit/pipelex/errors/test_data.py
index 41ecd191c..6b7fa22c9 100644
--- a/tests/unit/pipelex/errors/test_data.py
+++ b/tests/unit/pipelex/errors/test_data.py
@@ -18,6 +18,13 @@ class ProblemViewsTestData:
# A problem whose code no registry of this process holds, as a newer worker or a stored record carries it, built in
# the operator's view: its step and its diagnostics name a file of the host that a caller must never read.
+ # A suggested fix as an item carries it on the wire.
+ RENAME_MODEL_FIX: ClassVar[dict[str, Any]] = {
+ "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": [{"kind": "set_key", "table_path": ["pipe", "write"], "key": "model", "value": "gpt-5"}],
+ }
PRIVATE_HOST_FILE: ClassVar[str] = "/srv/pipelex/private/settings.toml"
UNKNOWN_OPERATOR_CODE: ClassVar[str] = "pipelex.config.future_setting_missing"
UNKNOWN_METHOD_CODE: ClassVar[str] = "method.future_fault"
diff --git a/tests/unit/pipelex/errors/test_error_code_resolution.py b/tests/unit/pipelex/errors/test_error_code_resolution.py
index eb5a0fda7..fcf501159 100644
--- a/tests/unit/pipelex/errors/test_error_code_resolution.py
+++ b/tests/unit/pipelex/errors/test_error_code_resolution.py
@@ -48,6 +48,9 @@ def _raise_chain(*errors: BaseException) -> BaseException:
class TestErrorCodeResolution:
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds errors of test classes with a message alone, to check how their code resolves"
+ )
def test_a_class_code_decides_the_problem(self) -> None:
problem = _ModelUnknownError("no such model").to_problem(view=ProblemView.CALLER)
spec = CORE_CODE_SPECS[CoreCode.MODEL_UNKNOWN]
@@ -64,6 +67,9 @@ class TestErrorCodeResolution:
assert problem.title == error_code_spec(PipelexErrorCode.CONFIG_INVALID).title
assert problem.domain == ProblemDomain.OPERATOR
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds errors of test classes with a message alone, to check how their code resolves"
+ )
def test_a_raise_site_chooses_from_the_set(self) -> None:
assert _ProviderError("boom").to_problem(view=ProblemView.CALLER).code == CoreCode.PROVIDER_FAILED
chosen = _ProviderError("slow down").with_error_code(CoreCode.PROVIDER_RATE_LIMITED).to_problem(view=ProblemView.CALLER)
@@ -74,6 +80,9 @@ class TestErrorCodeResolution:
with pytest.raises(ValueError, match=re.escape("does not declare the code 'model.unknown'")):
_ProviderError("boom").with_error_code(CoreCode.MODEL_UNKNOWN)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds errors of test classes with a message alone, to check how their code resolves"
+ )
def test_an_inheriting_wrapper_takes_its_cause_code(self) -> None:
error = _raise_chain(_WrapperError("outer"), _ModelUnknownError("inner"))
assert isinstance(error, PipelexError)
@@ -98,6 +107,9 @@ class TestErrorCodeResolution:
assert isinstance(error, PipelexError)
assert error.resolve_error_code() == CoreCode.INPUT_INVALID
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds errors of test classes with a message alone, to check what crosses a foreign exception"
+ )
def test_nothing_crosses_a_foreign_exception(self) -> None:
"""An earlier failure below a foreign exception lends the error above it no fact and no advice."""
earlier_failure = LLMCompletionError(
diff --git a/tests/unit/pipelex/errors/test_failure_problem.py b/tests/unit/pipelex/errors/test_failure_problem.py
index 32623d291..f227f631f 100644
--- a/tests/unit/pipelex/errors/test_failure_problem.py
+++ b/tests/unit/pipelex/errors/test_failure_problem.py
@@ -9,6 +9,7 @@ from pydantic import BaseModel, ValidationError
from pipelex.base_exceptions import PipelexError
from pipelex.errors.failure_problem import (
MAX_LOGGED_FRAMES,
+ failure_diagnostics,
failure_log_fields,
failure_problem,
format_problem_location,
@@ -16,6 +17,7 @@ from pipelex.errors.failure_problem import (
)
from pipelex.errors.problem import ProblemView, make_location
from pipelex.migration.exceptions import FormerReleaseConfigError
+from pipelex.tools.misc.exceptions import JsonTypeError
if TYPE_CHECKING:
from mthds.protocol.problem.models import ProblemLocation
@@ -82,6 +84,23 @@ class TestFailureProblem:
assert failure_problem(error=failure) == failure.to_problem(view=ProblemView.OPERATOR)
+ def test_a_caught_pipelex_error_s_diagnostics_are_its_operator_view_s(self) -> None:
+ failure = FormerReleaseConfigError("a former release left its gateway backend enabled")
+ failure.__cause__ = KeyError("gateway")
+
+ assert failure_diagnostics(cause=failure) == failure.to_problem(view=ProblemView.OPERATOR).diagnostics
+
+ def test_a_caught_error_s_diagnostics_ask_nothing_of_its_code_s_parameters(self) -> None:
+ """A refusal coded by the command reads the caught error's diagnostics alone, so its code's parameters go unasked.
+
+ The JSON loader's refusal is `request.invalid`, whose `field` it cannot know; the sweep this test runs under
+ fails it if reading the diagnostics built that refusal's problem.
+ """
+ diagnostics = failure_diagnostics(cause=JsonTypeError("the file does not hold a JSON object"))
+
+ assert diagnostics is not None
+ assert diagnostics.error_class == "JsonTypeError"
+
def test_the_log_fields_name_the_code_and_the_chain_s_classes_and_no_text(self) -> None:
"""No chained exception's text reaches the fields, the foreign ``ValidationError``'s included."""
failure = _chained_failure()
diff --git a/tests/unit/pipelex/errors/test_problem_views.py b/tests/unit/pipelex/errors/test_problem_views.py
index 33679e6a2..ff5207d8f 100644
--- a/tests/unit/pipelex/errors/test_problem_views.py
+++ b/tests/unit/pipelex/errors/test_problem_views.py
@@ -19,12 +19,15 @@ from pipelex.errors.error_code_declaration import ErrorCodeDeclaration
from pipelex.errors.error_codes import ErrorCode, error_code_spec
from pipelex.errors.problem import (
MAX_PROBLEM_TEXT_LENGTH,
+ MISSING_REQUIRED_PARAMS_MESSAGE,
TRUNCATION_MARKER,
UNKNOWN_CODE_ITEM_DETAIL,
PipelexProblem,
ProblemView,
caller_view_of,
+ make_location,
make_problem,
+ make_problem_item,
problem_metadata,
)
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
@@ -171,6 +174,9 @@ class TestProblemViews:
assert caller.params.as_wire() == {"pipe": "summarize", "template": "prompt", "finding": "unexpected '}'"}
assert "the raise site's own words" not in str(caller.to_wire())
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds a problem lacking its parameters, to check that its sentence falls back on the title"
+ )
def test_a_template_missing_a_parameter_falls_back_on_the_title(self, caplog: pytest.LogCaptureFixture) -> None:
"""Rendering is total: a missing parameter costs the sentence, never the problem, and the raise site is logged."""
error = _TemplateRefusalError("no parameters given")
@@ -184,6 +190,34 @@ class TestProblemViews:
assert caller.next_step.detail
assert any(record.getMessage() == "A problem's sentence could not be rendered from its template" for record in caplog.records)
+ def test_a_withheld_name_reads_its_own_sentences_in_every_view(self, caplog: pytest.LogCaptureFixture) -> None:
+ """A template refusal without its `name` says what happened without it, in each view and in the caller view of the operator's.
+
+ The name is withheld by rule, which no raise site is at fault for, so nothing is logged about the parameter it
+ lacks, and no sentence falls back on the title or the generic step.
+ """
+ with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):
+ operator = make_problem(code=CoreCode.SECURITY_TEMPLATE_REFUSED, view=ProblemView.OPERATOR, params={"pipe": "say"})
+ caller = make_problem(code=CoreCode.SECURITY_TEMPLATE_REFUSED, view=ProblemView.CALLER, params={"pipe": "say"})
+ item = make_problem_item(code=CoreCode.SECURITY_TEMPLATE_REFUSED, params={"pipe": "say"})
+
+ detail = "A template of pipe 'say' looked a name up from the run's data, and the template sandbox refused that name."
+ step = "Change the templates of pipe 'say' so that the run's data no longer chooses the names they look up, then run the method again."
+ assert operator.detail == caller.detail == item.detail == detail
+ assert operator.next_step.detail == caller.next_step.detail == caller_view_of(problem=operator).next_step.detail == step
+ messages = [record.getMessage() for record in caplog.records]
+ assert "A problem lacks a parameter its code requires" not in messages
+ assert "A problem's sentence could not be rendered from its template" not in messages
+
+ @pytest.mark.builds_problems_without_required_params(reason="builds a template refusal lacking its pipe, to check that it is still logged")
+ def test_a_withheld_code_still_logs_another_parameter_it_lacks(self, caplog: pytest.LogCaptureFixture) -> None:
+ """Only the parameter withheld by rule goes unreported: a refusal lacking its `pipe` is still a raise site to fix."""
+ with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):
+ make_problem(code=CoreCode.SECURITY_TEMPLATE_REFUSED, view=ProblemView.CALLER, params={})
+
+ lacking = [getattr(record, "params", None) for record in caplog.records if record.getMessage() == MISSING_REQUIRED_PARAMS_MESSAGE]
+ assert lacking == [["pipe"]]
+
def test_an_undeclared_or_mistyped_parameter_is_dropped(self, caplog: pytest.LogCaptureFixture) -> None:
error = _TemplateRefusalError("refused").with_params(pipe="summarize", template="prompt", finding="bad", undeclared="secret value")
@@ -195,6 +229,9 @@ class TestProblemViews:
assert "secret value" not in str(caller.to_wire())
assert any(record.getMessage() == "An error gives a parameter its code does not declare" for record in caplog.records)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds every code's problem with no parameter, to check that none holds a null member"
+ )
@pytest.mark.parametrize("view", list(ProblemView))
def test_no_problem_holds_a_null_member(self, view: ProblemView) -> None:
"""Every code, in every view, with no parameter given: no member at any depth is written as null."""
@@ -270,6 +307,7 @@ class TestProblemViews:
assert caller.next_step.detail == "Report this to whoever runs the runtime."
assert "sk-" not in str(caller.to_wire())
+ @pytest.mark.builds_problems_without_required_params(reason="builds every code's problem with no parameter, to check the steps alone")
def test_no_step_points_at_text_a_caller_cannot_see(self) -> None:
"""Every step of every code stands alone: none sends its reader to an error message the view may not show."""
for code in _all_codes():
@@ -302,6 +340,7 @@ class TestProblemViews:
assert operator.diagnostics.provider is not None
assert operator.diagnostics.provider.message == ProblemViewsTestData.GATEWAY_PROVIDER_TEXT
+ @pytest.mark.builds_problems_without_required_params(reason="builds problems with a retry delay alone, to check which delays are kept")
def test_an_unusable_retry_delay_is_left_out(self) -> None:
for delay in (float("inf"), float("nan"), -1.0):
problem = make_problem(code=CoreCode.PROVIDER_RATE_LIMITED, view=ProblemView.CALLER, retry_after=delay)
@@ -310,6 +349,9 @@ class TestProblemViews:
# A code whose verdict is not `yes` never carries a delay.
assert make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.CALLER, retry_after=3.5).retry_after is None
+ @pytest.mark.builds_problems_without_required_params(
+ reason="gives parameters the code refuses as a whole, which are dropped, to check that they are"
+ )
def test_a_parameter_set_refused_as_a_whole_is_dropped(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:
"""A refusal naming no parameter, a model-level one, drops them all: the error is reported, never replaced."""
spec = error_code_spec(CoreCode.METHOD_TEMPLATE_INVALID).model_copy(
@@ -321,10 +363,13 @@ class TestProblemViews:
problem = make_problem(code=CoreCode.METHOD_TEMPLATE_INVALID, view=ProblemView.CALLER, params={"pipe": "summarize", "template": "x"})
assert problem.code == CoreCode.METHOD_TEMPLATE_INVALID
- assert problem.params is None
+ # The code declares parameters, so the member is present, holding none of those refused.
+ assert problem.params is not None
+ assert problem.params.as_wire() == {}
assert problem.detail == spec.title
assert any(record.getMessage() == "An error gives parameters its code refuses as a whole" for record in caplog.records)
+ @pytest.mark.builds_problems_without_required_params(reason="gives a parameter the wire refuses, which is dropped, to check that it is")
def test_a_parameter_the_wire_refuses_is_dropped(self, mocker: MockerFixture) -> None:
"""A value the code's model takes but the problem's own `params` model refuses never fails the problem."""
spec = error_code_spec(CoreCode.REQUEST_BLOBS_MISSING).model_copy(update={"params_model": _LaxBlobsParams})
@@ -333,7 +378,9 @@ class TestProblemViews:
problem = make_problem(code=CoreCode.REQUEST_BLOBS_MISSING, view=ProblemView.CALLER, params={"missing_blobs": ["not-a-sha256"]})
assert problem.code == CoreCode.REQUEST_BLOBS_MISSING
- assert problem.params is None
+ # The code declares parameters, so the member is present, holding none of those refused.
+ assert problem.params is not None
+ assert problem.params.as_wire() == {}
@pytest.mark.parametrize(
("wire", "expected_kind", "expected_detail"),
@@ -460,6 +507,9 @@ class TestProblemViews:
assert built.errors is not None
assert built.errors[0].as_wire() == ProblemViewsTestData.UNKNOWN_CODE_ITEM
+ @pytest.mark.builds_problems_without_required_params(
+ reason="gives a required parameter a value the wire refuses, which is dropped, to check that it is"
+ )
@pytest.mark.parametrize(
"unreadable",
[
@@ -482,6 +532,7 @@ class TestProblemViews:
assert problem.params.as_wire() == {"pipe": "summarize"}
assert any(record.getMessage() == "An error gives a parameter of the wrong type for its code" for record in caplog.records)
+ @pytest.mark.builds_problems_without_required_params(reason="gives a parameter the wire refuses, which is dropped, to check that it is")
@pytest.mark.parametrize(
("code", "params"),
[
@@ -495,8 +546,44 @@ class TestProblemViews:
with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):
problem = make_problem(code=code, view=ProblemView.CALLER, params=params)
- assert problem.params is None
+ # The code declares parameters, so the member is present, holding none of those refused.
+ assert problem.params is not None
+ assert problem.params.as_wire() == {}
assert problem.detail == error_code_spec(code).title
assert "inf" not in problem.detail
json.dumps(problem.to_wire(), allow_nan=False)
assert any(record.getMessage() == "An error gives a parameter of the wrong type for its code" for record in caplog.records)
+
+ def test_a_lone_item_restating_its_problem_is_folded_into_it(self) -> None:
+ """One fault carries no list: the item's parameters and location become the problem's."""
+ item = make_problem_item(
+ code=CoreCode.MODEL_UNKNOWN,
+ params={"model": "gpt-5.1", "model_type": "llm", "suggestions": []},
+ location=make_location(pipe="write", field="model"),
+ )
+
+ problem = make_problem(code=CoreCode.MODEL_UNKNOWN, view=ProblemView.CALLER, errors=[item])
+
+ assert problem.errors is None
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"model": "gpt-5.1", "model_type": "llm", "suggestions": []}
+ assert problem.location is not None
+ assert problem.location.as_wire() == {"pipe": "write", "field": "model"}
+
+ def test_a_lone_item_carrying_suggestions_or_a_fix_stays_listed(self) -> None:
+ """A problem has no member for an item's suggestions or its fix: the item gives the problem its facts and stays listed."""
+ item = make_problem_item(
+ code=CoreCode.MODEL_UNKNOWN,
+ params={"model": "gpt-5.1", "model_type": "llm", "suggestions": ["gpt-5"]},
+ location=make_location(pipe="write", field="model"),
+ suggestions=["gpt-5"],
+ suggested_fix=ProblemViewsTestData.RENAME_MODEL_FIX,
+ )
+
+ wire = make_problem(code=CoreCode.MODEL_UNKNOWN, view=ProblemView.CALLER, errors=[item]).to_wire()
+
+ assert wire["params"] == {"model": "gpt-5.1", "model_type": "llm", "suggestions": ["gpt-5"]}
+ assert wire["location"] == {"pipe": "write", "field": "model"}
+ (listed,) = wire["errors"]
+ assert listed["suggestions"] == ["gpt-5"]
+ assert listed["suggested_fix"] == ProblemViewsTestData.RENAME_MODEL_FIX
diff --git a/tests/unit/pipelex/errors/test_security_event.py b/tests/unit/pipelex/errors/test_security_event.py
index 29bc315a1..defd3538b 100644
--- a/tests/unit/pipelex/errors/test_security_event.py
+++ b/tests/unit/pipelex/errors/test_security_event.py
@@ -147,6 +147,7 @@ class TestSecurityEvent:
assert security_codes
assert set(SECURITY_TARGET_KIND_BY_CODE) == security_codes
+ @pytest.mark.builds_problems_without_required_params(reason="builds each refusal with a message alone, to check its code and the event it logs")
@pytest.mark.parametrize(
("error", "code", "domain", "error_type", "target_kind", "target_class"),
[
diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
index 0a6cc814d..b3cdb98ec 100644
--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py
+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
@@ -48,6 +48,7 @@ _PIPELINE_EXEC_ERROR = PipelineExecutionError(
class TestClassLevelMetadata:
"""Key exceptions self-describe their code, their advice and their error_category at the class level."""
+ @pytest.mark.builds_problems_without_required_params(reason="builds each class with a message alone, to check the code it decides")
@pytest.mark.parametrize(
("_topic", "exc", "expected_code", "expected_domain"),
[
@@ -72,6 +73,7 @@ class TestClassLevelMetadata:
assert problem.code == expected_code
assert problem.domain == expected_domain
+ @pytest.mark.builds_problems_without_required_params(reason="builds each class with a message alone, to check the advice it carries")
@pytest.mark.parametrize(
("_topic", "exc", "expected_detail"),
[
@@ -122,6 +124,7 @@ class TestClassLevelMetadata:
assert exc.error_category is expected_category
assert find_inference_error_category_in_chain(exc) is expected_category
+ @pytest.mark.builds_problems_without_required_params(reason="builds each class with a message alone, to check where the message goes")
@pytest.mark.parametrize(
("_topic", "exc"),
[
diff --git a/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py b/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
index 8822f2b84..c020065b2 100644
--- a/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
+++ b/tests/unit/pipelex/exceptions/test_wrapper_error_enrichment.py
@@ -1,3 +1,4 @@
+import pytest
from mthds.protocol.problem.registry import CoreCode, ProblemDomain, StepKind
from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError, find_inference_error_category_in_chain
@@ -26,6 +27,9 @@ def _make_pipeline_execution_error(cause: BaseException | None) -> PipelineExecu
class TestWrapperErrorEnrichment:
"""PipelineExecutionError must surface the wrapped cause's code and categorized action, not mask them."""
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
def test_preserves_categorized_cause_action(self) -> None:
"""A transient inference failure wrapped through PipeRunError/PipeRouterError keeps its action, its category and its retryable code."""
cogt_error = LLMCompletionError(
@@ -56,6 +60,7 @@ class TestWrapperErrorEnrichment:
assert problem.code == CoreCode.PROVIDER_UNAVAILABLE
assert problem.is_retryable is True
+ @pytest.mark.builds_problems_without_required_params(reason="builds an inference failure by hand, below the worker that names its model")
def test_surfaces_the_code_of_a_caller_fixable_cause(self) -> None:
"""A content refusal coded `model.content_refused` reaches the wrapper as its code, the input's at 422, not a runtime fault.
diff --git a/tests/unit/pipelex/graph/test_graph_tracer_event_emission.py b/tests/unit/pipelex/graph/test_graph_tracer_event_emission.py
index 8c4b26f59..a3916bd05 100644
--- a/tests/unit/pipelex/graph/test_graph_tracer_event_emission.py
+++ b/tests/unit/pipelex/graph/test_graph_tracer_event_emission.py
@@ -6,6 +6,7 @@ correct trace events as a side effect alongside its existing in-memory accumulat
from datetime import UTC, datetime, timedelta
+import pytest
from mthds.protocol.problem.registry import CoreCode
from pipelex.core.stuffs.exceptions import StuffFactoryError
@@ -219,6 +220,9 @@ class TestGraphTracerEventEmission:
# An end event names the pipe it ends, as its start does, and the invocation's path.
assert (evt.pipe_code, evt.pipe_ref, evt.pipe_type, evt.path) == ("test_pipe", "tests.test_pipe", "PipeLLM", "tests.test_pipe")
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds the step's failure with a message alone, to check where its problem is recorded"
+ )
def test_pipe_end_error_records_the_same_caller_view_on_the_event_and_the_node(self) -> None:
"""The node's problem reaches the event and the node of the graph alike, in the caller's view, without the error's message."""
tracer, event_log = self._make_tracer_with_event_log()
diff --git a/tests/unit/pipelex/graph/test_node_problem.py b/tests/unit/pipelex/graph/test_node_problem.py
index 494f2c3cf..48e2c7e3c 100644
--- a/tests/unit/pipelex/graph/test_node_problem.py
+++ b/tests/unit/pipelex/graph/test_node_problem.py
@@ -9,6 +9,9 @@ from pipelex.graph.node_problem import NODE_PROBLEM_FAULT_MESSAGE, make_node_pro
class TestNodeProblem:
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds the step's failure with a message alone, to check where its problem is located"
+ )
def test_a_pipelex_error_records_its_problem_located_at_the_node(self) -> None:
error = StuffFactoryError("Error combining stuffs for concept Report").with_error_code(CoreCode.PIPE_OUTPUT_INVALID)
@@ -20,6 +23,7 @@ class TestNodeProblem:
assert problem.params is not None
assert problem.params.as_wire()["pipe"] == "analyze"
+ @pytest.mark.builds_problems_without_required_params(reason="builds the step's failure with a message alone, to check the view its node records")
def test_the_node_records_the_caller_view(self) -> None:
"""The graph is read by whoever reads the run: no diagnostics, and never the error's own message."""
error = StuffFactoryError("a deployment's validator said: secret-ish text")
@@ -29,6 +33,9 @@ class TestNodeProblem:
assert problem.diagnostics is None
assert "secret-ish text" not in str(problem.to_wire())
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds the step's failure with a message alone, to check where its problem is located"
+ )
def test_an_entry_pipe_names_itself_as_its_path(self) -> None:
problem = make_node_problem(error=StuffFactoryError("refused"), pipe_code="flow", pipe_path=[])
diff --git a/tests/unit/pipelex/kernel/test_check_llm_setting_with_served_model.py b/tests/unit/pipelex/kernel/test_check_llm_setting_with_served_model.py
index 5dd75c07e..8b61e003a 100644
--- a/tests/unit/pipelex/kernel/test_check_llm_setting_with_served_model.py
+++ b/tests/unit/pipelex/kernel/test_check_llm_setting_with_served_model.py
@@ -93,6 +93,9 @@ class TestCheckLLMSettingWithServedModel:
assert internal_name not in message
assert internal_name not in str(caller.to_wire())
+ @pytest.mark.builds_problems_without_required_params(
+ reason="an external plugin's refusal is raised as the plugin wrote it, which the test builds with a message alone"
+ )
def test_an_external_plugin_s_refusal_is_raised_as_it_wrote_it(self, mocker: MockerFixture) -> None:
"""Its text may carry what the plugin keeps private, so it rides the operator's diagnostics alone."""
refusal = LLMCapabilityError("Model 'some-model' is refused by tenant 1234 at internal.example")
diff --git a/tests/unit/pipelex/libraries/test_data.py b/tests/unit/pipelex/libraries/test_data.py
index 1eda280c4..59f92e9c5 100644
--- a/tests/unit/pipelex/libraries/test_data.py
+++ b/tests/unit/pipelex/libraries/test_data.py
@@ -130,3 +130,43 @@ class MethodRequirementsTestData:
distributions=distributions,
marker_environment=dict(cls.SANDBOX_MARKER_ENVIRONMENT),
)
+
+
+class PackageVisibilityTestData:
+ """Bundles of one package whose `legal` domain calls a pipe its `scoring` domain does not export."""
+
+ PACKAGE_ADDRESS = "github.com/harbour-board/legal-tools"
+ UNEXPORTED_PIPE_REF = "scoring.compute_score"
+
+ SCORING_MTHDS = """
+domain = "scoring"
+description = "Scores a clause"
+
+[pipe.compute_score]
+type = "PipeLLM"
+description = "Score a clause"
+inputs = { clause = "Text" }
+output = "Text"
+prompt = "Score $clause"
+"""
+
+ LEGAL_MTHDS = """
+domain = "legal"
+description = "Reviews a contract"
+main_pipe = "review"
+
+[pipe.review]
+type = "PipeSequence"
+description = "Review a contract by scoring its clause"
+inputs = { clause = "Text" }
+output = "Text"
+steps = [{ pipe = "scoring.compute_score", result = "score" }]
+"""
+
+ RESERVED_DOMAIN_MTHDS = """
+domain = "native"
+description = "Declares a domain the standard reserves"
+
+[concept.Thing]
+description = "A thing"
+"""
diff --git a/tests/unit/pipelex/libraries/test_duplicate_ref_items.py b/tests/unit/pipelex/libraries/test_duplicate_ref_items.py
new file mode 100644
index 000000000..23e89031a
--- /dev/null
+++ b/tests/unit/pipelex/libraries/test_duplicate_ref_items.py
@@ -0,0 +1,67 @@
+"""A declaration made twice is one fault per bundle that makes it, and one bundle's only when both sources name it."""
+
+import pytest
+
+from pipelex.libraries.collision_messages import DeclarationKind, duplicate_ref_items
+
+
+class TestDuplicateRefItems:
+ @pytest.mark.parametrize(
+ ("existing_source", "incoming_source", "expected_items"),
+ [
+ pytest.param(
+ "first.mthds",
+ "second.mthds",
+ [
+ ("second.mthds", "Pipe 'scoring.compute_score' is declared here and in 'first.mthds'."),
+ ("first.mthds", "Pipe 'scoring.compute_score' is declared here and in 'second.mthds'."),
+ ],
+ id="two_bundles",
+ ),
+ pytest.param(
+ "first.mthds",
+ "first.mthds",
+ [("first.mthds", "Pipe 'scoring.compute_score' is declared twice in this bundle.")],
+ id="one_bundle",
+ ),
+ pytest.param(
+ None,
+ "second.mthds",
+ [
+ ("second.mthds", "Pipe 'scoring.compute_score' is declared here and in 'unknown'."),
+ (None, "Pipe 'scoring.compute_score' is declared here and in 'second.mthds'."),
+ ],
+ id="one_source_unknown",
+ ),
+ pytest.param(
+ None,
+ None,
+ [
+ (None, "Pipe 'scoring.compute_score' is declared here and in 'unknown'."),
+ (None, "Pipe 'scoring.compute_score' is declared here and in 'unknown'."),
+ ],
+ id="both_sources_unknown_are_not_one_bundle",
+ ),
+ ],
+ )
+ def test_each_declaration_is_an_item_on_its_bundle(
+ self, existing_source: str | None, incoming_source: str | None, expected_items: list[tuple[str | None, str]]
+ ) -> None:
+ items = duplicate_ref_items(
+ ref_kind=DeclarationKind.PIPE, ref="scoring.compute_score", existing_source=existing_source, incoming_source=incoming_source
+ )
+
+ assert [(item.source, item.message) for item in items] == expected_items
+ assert all(item.params == {"name": "scoring.compute_score", "conflict": "duplicate_declaration"} for item in items)
+ # Each item names the table that declares the name, where a caller edits its bundle.
+ assert all(item.field_path == "pipe.compute_score" for item in items)
+
+ def test_a_concept_declared_twice_is_located_on_its_table(self) -> None:
+ items = duplicate_ref_items(
+ ref_kind=DeclarationKind.CONCEPT, ref="scoring.Score", existing_source="first.mthds", incoming_source="second.mthds"
+ )
+
+ assert [(item.source, item.concept_code, item.field_path) for item in items] == [
+ ("second.mthds", "Score", "concept.Score"),
+ ("first.mthds", "Score", "concept.Score"),
+ ]
diff --git a/tests/unit/pipelex/libraries/test_method_requirements_check.py b/tests/unit/pipelex/libraries/test_method_requirements_check.py
index cda729231..56b2fcd94 100644
--- a/tests/unit/pipelex/libraries/test_method_requirements_check.py
+++ b/tests/unit/pipelex/libraries/test_method_requirements_check.py
@@ -1,6 +1,7 @@
import shlex
import sys
from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError
from pathlib import Path
import pytest
@@ -134,6 +135,35 @@ class TestMethodRequirementsCheck:
assert [item.line for item in items] == [2, 3]
assert all(item.source == "requirements.txt" for item in items)
+ def test_an_unmet_extra_names_the_distribution_it_needs(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """The distribution an extra needs is the one named: missing is `not_found`, held at a refused version `no_matching_version`."""
+ installed: dict[str, tuple[str, list[str]]] = {
+ "fastlib": ("1.4", ['turbo>=2; extra == "speed"', 'unrelated; extra == "other"']),
+ "turbo": ("1.5", []),
+ }
+
+ def fake_distribution(distribution_name: str) -> object:
+ normalized = distribution_name.lower().replace("_", "-")
+ if normalized not in installed:
+ raise PackageNotFoundError(distribution_name)
+ version, requires = installed[normalized]
+ return mocker.Mock(version=version, requires=requires)
+
+ mocker.patch("pipelex.libraries.package_environments.distribution", side_effect=fake_distribution)
+ _method(directory=tmp_path, requirements="fastlib[speed]>=1\nfastlib[other]\n")
+
+ with pytest.raises(MethodRequirementsNotMetError) as exc_info:
+ ensure_method_requirements_met(trees=[list_method_tree(tmp_path)], names_host_paths=True)
+
+ assert [item.params for item in exc_info.value.blueprint_validation_errors] == [
+ {"kind": "requirement", "name": "turbo", "reason": "no_matching_version"},
+ {"kind": "requirement", "name": "unrelated", "reason": "not_found"},
+ ]
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_DEPENDENCY_MISSING
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"kind": "requirement", "name": "turbo", "reason": "no_matching_version"}
+
def test_where_host_paths_may_not_be_named_the_refusal_names_none(self, mocker: MockerFixture, tmp_path: Path) -> None:
mocker.patch(
f"{_MODULE}.resolve_pipe_func_package_environment",
@@ -253,6 +283,9 @@ class TestMethodRequirementsCheck:
refusal = refusal_info.value.to_problem(view=ProblemView.CALLER)
assert refusal.code == CoreCode.METHOD_DEPENDENCY_MISSING
assert refusal.domain == ProblemDomain.METHOD
+ # The refusal names the first requirement, as one of several unmet requirements names the first.
+ assert refusal.params is not None
+ assert refusal.params.as_wire() == {"kind": "requirement", "name": "pandas", "reason": "no_matching_version"}
(item,) = verdict_info.value.validation_error_items()
assert (item.source, item.line) == ("requirements.txt", None)
assert item.message == f"The requirements are refused by the Daytona sandbox: {reason}"
diff --git a/tests/unit/pipelex/libraries/test_method_trees.py b/tests/unit/pipelex/libraries/test_method_trees.py
index c3d2991d1..705303819 100644
--- a/tests/unit/pipelex/libraries/test_method_trees.py
+++ b/tests/unit/pipelex/libraries/test_method_trees.py
@@ -2,7 +2,8 @@ from pathlib import Path
import pytest
from mthds.method_tree.models import TreeLimits
-from mthds.protocol.problem.registry import ProblemDomain
+from mthds.method_tree.vocabulary import TreeRefusalCode
+from mthds.protocol.problem.registry import CoreCode, ProblemDomain
from pytest_mock import MockerFixture
from pipelex.errors.problem import ProblemView
@@ -20,6 +21,7 @@ from pipelex.libraries.method_trees import (
tree_bundle_of_lone_file,
tree_python_sources,
)
+from pipelex.methods.package_reason import MethodPackageReason
_MANIFEST = '[package]\naddress = "github.com/pipelex-tests/nested"\nversion = "1.0.0"\ndescription = "A nested package"\n'
@@ -102,6 +104,11 @@ class TestMethodTrees:
list_library_bundle_files(library_dirs=[tmp_path])
assert exc_info.value.message.endswith(LIMITS_ADVICE)
+ # The caller reads the limit the tree passed, by the reason the listing stopped at it.
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_PACKAGE_INVALID
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"reason": MethodPackageReason.TOO_MANY_FILES, "limit": 1}
def test_a_bundle_file_named_alone_is_rooted_at_the_manifest_above_it_else_alone(self, tmp_path: Path) -> None:
"""Named alone, a bundle reads the files of the method a METHODS.toml above it roots, and with none only itself."""
@@ -156,8 +163,10 @@ class TestMethodTrees:
assert [bundle_file.tree_bundle.tree_path for bundle_file in list_library_bundle_files(library_dirs=[tmp_path])] == ["top.mthds"]
_touch(directory=tmp_path, tree_path="vendor/tool/tool.mthds")
- with pytest.raises(MethodTreeLoadError, match="symbolic link"):
+ with pytest.raises(MethodTreeLoadError, match="symbolic link") as exc_info:
list_library_bundle_files(library_dirs=[tmp_path])
+ # The reason is the standard's refusal code, which the listing refused the tree with.
+ assert exc_info.value.problem_params() == {"reason": TreeRefusalCode.SYMBOLIC_LINK}
def test_this_machine_s_limits_are_read_once_per_listing(self, tmp_path: Path, mocker: MockerFixture) -> None:
limits_spy = mocker.patch("pipelex.libraries.method_trees.local_tree_limits", return_value=TreeLimits())
diff --git a/tests/unit/pipelex/libraries/test_package_visibility_refusals.py b/tests/unit/pipelex/libraries/test_package_visibility_refusals.py
new file mode 100644
index 000000000..078c3f490
--- /dev/null
+++ b/tests/unit/pipelex/libraries/test_package_visibility_refusals.py
@@ -0,0 +1,63 @@
+from pathlib import Path
+
+import pytest
+from mthds.package.manifest.schema import MethodsManifest
+from mthds.protocol.problem.registry import CoreCode
+from pytest_mock import MockerFixture
+
+from pipelex.errors.problem import ProblemView
+from pipelex.libraries.library_manager import LibraryManager
+from pipelex.mthds_parsing.parser import MthdsParser
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
+from tests.unit.pipelex.libraries.test_data import PackageVisibilityTestData
+
+
+def _refused_items(
+ *, mocker: MockerFixture, tmp_path: Path, bundles: dict[str, str]
+) -> list[tuple[str, dict[str, object] | None, dict[str, object] | None]]:
+ """The code, location and parameters of each item refusing the bundles of a package whose METHODS.toml exports nothing."""
+ manifest = MethodsManifest(address=PackageVisibilityTestData.PACKAGE_ADDRESS, version="1.0.0", description="A package exporting nothing")
+ mocker.patch("pipelex.libraries.library_manager.find_package_manifest", return_value=manifest)
+ blueprints = [MthdsParser.make_pipelex_bundle_blueprint(mthds_content=content, mthds_source=source) for source, content in bundles.items()]
+ first_path = tmp_path / next(iter(bundles))
+ first_path.touch()
+
+ with pytest.raises(ValidateBundleError) as exc_info, translate_to_validate_bundle_error():
+ LibraryManager()._check_package_visibility( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ blueprints=blueprints,
+ mthds_paths=[first_path],
+ )
+
+ items = exc_info.value.to_problem(view=ProblemView.CALLER).errors or []
+ return [(item.code, item.location.as_wire() if item.location else None, item.params.as_wire() if item.params else None) for item in items]
+
+
+class TestPackageVisibilityRefusals:
+ def test_a_pipe_another_domain_does_not_export_is_refused_naming_the_pipe_and_the_package(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ items = _refused_items(
+ mocker=mocker,
+ tmp_path=tmp_path,
+ bundles={"scoring.mthds": PackageVisibilityTestData.SCORING_MTHDS, "legal.mthds": PackageVisibilityTestData.LEGAL_MTHDS},
+ )
+
+ assert items == [
+ (
+ CoreCode.METHOD_PIPE_NOT_EXPORTED,
+ {"pipe": "review", "field": "pipe.review.steps[0].pipe", "file": "legal.mthds"},
+ {"pipe": PackageVisibilityTestData.UNEXPORTED_PIPE_REF, "package": PackageVisibilityTestData.PACKAGE_ADDRESS},
+ )
+ ]
+
+ def test_a_reserved_domain_in_a_package_is_a_name_conflict_never_an_export_refusal(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ items = _refused_items(
+ mocker=mocker,
+ tmp_path=tmp_path,
+ bundles={
+ "native.mthds": PackageVisibilityTestData.RESERVED_DOMAIN_MTHDS,
+ "scoring.mthds": PackageVisibilityTestData.SCORING_MTHDS,
+ "legal.mthds": PackageVisibilityTestData.LEGAL_MTHDS,
+ },
+ )
+
+ assert items == [(CoreCode.METHOD_NAME_CONFLICT, {"file": "native.mthds"}, {"name": "native", "conflict": "reserved_domain"})]
diff --git a/tests/unit/pipelex/libraries/test_pipe_library_lookup.py b/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
index 036754064..ea1891531 100644
--- a/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
+++ b/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
@@ -178,16 +178,56 @@ class TestPipeLibraryLookup:
assert problem.domain == ProblemDomain.METHOD
assert exc_info.value.message not in str(problem.to_wire())
- def test_in_body_required_miss_carries_the_method_code(self):
+ def test_in_body_required_miss_carries_the_method_code(self, mocker: MockerFixture):
"""`get_required_pipe` is the in-body door and keeps raising the plain error, with the method's code."""
library = PipeLibrary.make_empty()
+ library.root["scoring.compute_score"] = _make_stub_pipe(mocker, code="compute_score", domain_code="scoring")
with pytest.raises(PipeNotFoundError) as exc_info:
- library.get_required_pipe("scoring.nonexistent")
+ library.get_required_pipe("scoring.compute_scor", referring_pipe_code="review")
assert not isinstance(exc_info.value, EntryPipeNotFoundError)
problem = exc_info.value.to_problem(view=ProblemView.CALLER)
assert problem.code == CoreCode.METHOD_PIPE_UNRESOLVED
assert problem.domain == ProblemDomain.METHOD
assert exc_info.value.message not in str(problem.to_wire())
+ # The pipe whose body writes the ref, the ref that names nothing, and the pipes nearest it.
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"pipe": "review", "missing": "scoring.compute_scor", "candidates": ["scoring.compute_score"]}
+
+ @pytest.mark.parametrize(
+ ("selection", "expected_suggestions"),
+ [
+ pytest.param("compute_scor", ["scoring.compute_score"], id="bare_code_offers_the_entry_package_s_own_pipes"),
+ pytest.param("lib->compute_scor", ["lib->scoring.compute_score"], id="aliased_offers_that_package_s_exported_pipes"),
+ ],
+ )
+ def test_an_entry_miss_offers_only_the_pipes_the_caller_may_select(self, mocker: MockerFixture, selection: str, expected_suggestions: list[str]):
+ """A dependency's private pipe, another package's pipe and the host's pipes for an aliased selection are never offered."""
+ library = PipeLibrary.make_empty()
+ library.root["scoring.compute_score"] = _make_stub_pipe(mocker, code="compute_score", domain_code="scoring")
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"), is_exported=True)
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_scores", domain_code="scoring"), is_exported=False)
+ library.add_dependency_pipe(alias="other", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"), is_exported=True)
+
+ with pytest.raises(EntryPipeNotFoundError) as exc_info:
+ library.get_required_entry_pipe(selection)
+
+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"pipe": selection, "suggestions": expected_suggestions}
+ # The message names what the caller typed and nothing from the loaded library.
+ assert "scoring.compute_score" not in exc_info.value.message
+
+ def test_a_pipe_added_twice_names_its_ref_and_the_conflict(self, mocker: MockerFixture):
+ library = PipeLibrary.make_empty()
+ library.add_new_pipe(pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"))
+
+ with pytest.raises(PipeLibraryError) as exc_info:
+ library.add_new_pipe(pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"))
+
+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert problem.code == CoreCode.METHOD_NAME_CONFLICT
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"name": "scoring.compute_score", "conflict": "duplicate_declaration"}
def test_entry_pipe_ignores_aliased_dependency_entries(self, mocker: MockerFixture):
"""An installed package must not make a host pipe's bare code ambiguous.
diff --git a/tests/unit/pipelex/libraries/test_standalone_reserved_domains.py b/tests/unit/pipelex/libraries/test_standalone_reserved_domains.py
index e44390ec7..cf8b445c4 100644
--- a/tests/unit/pipelex/libraries/test_standalone_reserved_domains.py
+++ b/tests/unit/pipelex/libraries/test_standalone_reserved_domains.py
@@ -2,11 +2,15 @@ from pathlib import Path
import pytest
from mthds.package.exceptions import ManifestError
+from mthds.protocol.problem.registry import CoreCode
from pytest_mock import MockerFixture
+from pipelex.errors.problem import ProblemView
from pipelex.libraries.exceptions import LibraryLoadingError
from pipelex.libraries.library_manager import LibraryManager
from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprint
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
class TestStandaloneReservedDomains:
@@ -128,3 +132,27 @@ class TestStandaloneReservedDomains:
mthds_paths=[dummy_path],
)
assert result is None
+
+ def test_two_bundles_declaring_one_reserved_domain_are_each_located_on_their_own_file(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """One item per bundle, each on its own file, never every item on the last bundle of the domain."""
+ mocker.patch("pipelex.libraries.library_manager.find_package_manifest", return_value=None)
+ blueprints = [PipelexBundleBlueprint(domain="native", source=source) for source in ("first.mthds", "second.mthds")]
+ dummy_path = tmp_path / "first.mthds"
+ dummy_path.touch()
+
+ manager = LibraryManager()
+ with pytest.raises(ValidateBundleError) as exc_info, translate_to_validate_bundle_error():
+ manager._check_package_visibility( # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ blueprints=blueprints,
+ mthds_paths=[dummy_path],
+ )
+
+ items = exc_info.value.to_problem(view=ProblemView.CALLER).errors or []
+ assert [(item.code, item.location.file if item.location else None) for item in items] == [
+ (CoreCode.METHOD_NAME_CONFLICT, "first.mthds"),
+ (CoreCode.METHOD_NAME_CONFLICT, "second.mthds"),
+ ]
+ assert [item.params.as_wire() if item.params else None for item in items] == [
+ {"name": "native", "conflict": "reserved_domain"},
+ {"name": "native", "conflict": "reserved_domain"},
+ ]
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 e079cfe74..4e96de718 100644
--- a/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
+++ b/tests/unit/pipelex/mthds_parsing/test_validation_error_categorizer.py
@@ -71,10 +71,10 @@ prompt = "Translate these notes into $language: $notes"
class TestBlueprintValidationErrorCategorizer:
@pytest.mark.parametrize(
- ("test_name", "mthds_content", "expected_pipe_code", "expected_domain_code"),
+ ("test_name", "mthds_content", "expected_pipe_code", "expected_domain_code", "expected_field_name"),
[
- ("pipe_batch", _PIPE_BATCH_COLLISION_MTHDS, "run_batch", "batch_collision"),
- ("sub_pipe_sequence_step", _SUB_PIPE_COLLISION_MTHDS, "run_seq", "subpipe_collision"),
+ ("pipe_batch", _PIPE_BATCH_COLLISION_MTHDS, "run_batch", "batch_collision", "input_item_name"),
+ ("sub_pipe_sequence_step", _SUB_PIPE_COLLISION_MTHDS, "run_seq", "subpipe_collision", "steps.0.batch_as"),
],
)
def test_wrapped_batch_collision_keeps_its_error_type(
@@ -83,6 +83,7 @@ class TestBlueprintValidationErrorCategorizer:
mthds_content: str,
expected_pipe_code: str,
expected_domain_code: str,
+ expected_field_name: str,
) -> None:
"""A blueprint-stage ``PipeValidationError`` is categorized with its ``error_type``, not dropped.
@@ -107,6 +108,8 @@ class TestBlueprintValidationErrorCategorizer:
assert item.pipe_code == expected_pipe_code
assert item.domain_code == expected_domain_code
assert item.source == source
+ # The field it collides on, inside its pipe's table, with no shape tag pydantic routed a step through.
+ assert item.field_name == expected_field_name
assert item.message, "The categorized item must carry the explanatory message"
# The recovered message is the PipeValidationError's own clean text, not pydantic's
# "Value error, " prefixed wrapper.
@@ -128,6 +131,15 @@ class TestBlueprintValidationErrorCategorizer:
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)
+ def test_a_misspelled_step_key_is_named_without_the_step_shape(self) -> None:
+ """A sequence step validates through a union tagged by its shape, which is not a field of the bundle either."""
+ mthds_content = _SUB_PIPE_COLLISION_MTHDS.replace('batch_as = "items", ', 'batch_as = "item", reslt = "x", ')
+ with pytest.raises(MthdsParserError) as exc_info:
+ MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content, mthds_source="steps.mthds")
+
+ typo_error = next(error for error in exc_info.value.validation_errors if error.error_type is None)
+ assert typo_error.field_path == "pipe.run_seq.steps.0.reslt"
+
@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."""
diff --git a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_missing_branch.py b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_missing_branch.py
new file mode 100644
index 000000000..aa0f9409d
--- /dev/null
+++ b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_missing_branch.py
@@ -0,0 +1,25 @@
+from typing import Callable
+
+import pytest
+from mthds.protocol.problem.registry import CoreCode
+
+from pipelex.errors.problem import ProblemView
+from pipelex.libraries.pipe.exceptions import PipeNotFoundError
+from pipelex.pipe_controllers.batch.pipe_batch import PipeBatch
+from pipelex.pipe_machinery.pipe_factory import PipeFactory
+from tests.unit.pipelex.pipe_controllers.batch.data import PipeBatchInputTestCases
+
+
+class TestPipeBatchMissingBranch:
+ def test_a_branch_pipe_no_bundle_declares_is_refused_naming_the_batch(self, load_empty_library: Callable[[], None]) -> None:
+ load_empty_library()
+ _, blueprint = PipeBatchInputTestCases.VALID_SIMPLE_BATCH
+ pipe_batch = PipeFactory[PipeBatch].make_from_blueprint(domain_code="test_domain", pipe_code="sort_items", blueprint=blueprint)
+
+ with pytest.raises(PipeNotFoundError) as exc_info:
+ pipe_batch.required_variables()
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_PIPE_UNRESOLVED
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "sort_items", "missing": "process_item", "candidates": []}
diff --git a/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_branch_output_name.py b/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_branch_output_name.py
new file mode 100644
index 000000000..edaf331ae
--- /dev/null
+++ b/tests/unit/pipelex/pipe_controllers/parallel/test_pipe_parallel_branch_output_name.py
@@ -0,0 +1,33 @@
+import pytest
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict
+
+from pipelex.core.pipes.exceptions import PipeRunError
+from pipelex.errors.problem import ProblemView
+from pipelex.pipe_controllers.parallel.pipe_parallel import branch_output_name
+from pipelex.pipe_controllers.sub_pipe import SubPipe
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
+class TestPipeParallelBranchOutputName:
+ def test_a_branch_output_name_is_taken_once(self) -> None:
+ seen: set[str] = set()
+ assert (
+ branch_output_name(
+ pipe_code="fan_out", sub_pipe=SubPipe(pipe_code="draft", output_name="draft"), seen_output_names=seen, run_mode=PipeRunMode.DRY
+ )
+ == "draft"
+ )
+
+ def test_a_name_an_earlier_branch_took_is_a_name_conflict_naming_it(self) -> None:
+ with pytest.raises(PipeRunError) as raised:
+ branch_output_name(
+ pipe_code="fan_out",
+ sub_pipe=SubPipe(pipe_code="review", output_name="draft"),
+ seen_output_names={"draft"},
+ run_mode=PipeRunMode.DRY,
+ )
+
+ caller = raised.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_NAME_CONFLICT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"name": "draft", "conflict": MethodNameConflictConflict.DUPLICATE_DECLARATION}
diff --git a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py
index 04f9a31c1..53b4f5e60 100644
--- a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py
+++ b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_condition.py
@@ -52,7 +52,7 @@ class TestCollectPossibleOutputsCondition:
result = _collect_possible_outputs(condition_pipe, output_format=ConceptRepresentationFormat.JSON)
assert result == [{"concept_ref": "test.Summary", "content": {"text": "summary text"}}]
- get_pipe_mock.assert_called_once_with(pipe_code="make_summary")
+ get_pipe_mock.assert_called_once_with(pipe_code="make_summary", referring_pipe_code=condition_pipe.code)
mapped_pipe.output.render_stuff_spec.assert_called_once_with(
concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON
)
@@ -66,7 +66,8 @@ class TestCollectPossibleOutputsCondition:
mapped_pipe.output.render_stuff_spec.return_value = {"content": {"from": pipe_code}}
mapped_pipes[pipe_code] = mapped_pipe
- def resolve_pipe(pipe_code: str) -> Any:
+ def resolve_pipe(pipe_code: str, referring_pipe_code: object) -> Any:
+ assert referring_pipe_code is condition_pipe.code
return mapped_pipes[pipe_code]
mocker.patch(GET_REQUIRED_PIPE_TARGET, side_effect=resolve_pipe)
diff --git a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py
index 5511df741..bb4f72db1 100644
--- a/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py
+++ b/tests/unit/pipelex/pipe_machinery/rendering/test_output_renderer_collect_sequence.py
@@ -72,7 +72,7 @@ class TestCollectPossibleOutputsSequence:
result = _collect_possible_outputs(sequence_pipe, output_format=ConceptRepresentationFormat.JSON)
assert result == [{"concept_ref": "test.Final", "content": {"text": "final output"}}]
- get_pipe_mock.assert_called_once_with(pipe_code="final_step")
+ get_pipe_mock.assert_called_once_with(pipe_code="final_step", referring_pipe_code=sequence_pipe.code)
final_pipe.output.render_stuff_spec.assert_called_once_with(
concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON
)
@@ -108,7 +108,7 @@ class TestCollectPossibleOutputsSequence:
}
pipes_by_code = {"mid_sequence": mid_pipe, "leaf_step": leaf_pipe}
- def fake_get_required_pipe(pipe_code: str) -> Any:
+ def fake_get_required_pipe(pipe_code: str, referring_pipe_code: object) -> Any: # ruff: ignore[unused-function-argument]
return pipes_by_code[pipe_code]
get_pipe_mock = mocker.patch(GET_REQUIRED_PIPE_TARGET, side_effect=fake_get_required_pipe)
@@ -117,8 +117,8 @@ class TestCollectPossibleOutputsSequence:
assert result == [{"concept_ref": "test.Leaf", "content": {"text": "leaf output"}}]
assert get_pipe_mock.call_count == 2
- get_pipe_mock.assert_any_call(pipe_code="mid_sequence")
- get_pipe_mock.assert_any_call(pipe_code="leaf_step")
+ get_pipe_mock.assert_any_call(pipe_code="mid_sequence", referring_pipe_code=outer_pipe.code)
+ get_pipe_mock.assert_any_call(pipe_code="leaf_step", referring_pipe_code=mid_pipe.code)
leaf_pipe.output.render_stuff_spec.assert_called_once_with(
concept_provider=renderer_concept_library, output_format=ConceptRepresentationFormat.JSON
)
diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py
index fd66605f8..add24c9f3 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_direct_executor_workdir.py
@@ -4,6 +4,7 @@ from contextlib import contextmanager
from pathlib import Path
import pytest
+from mthds.protocol.problem.registry import CoreCode
from pydantic import ValidationError
from pytest_mock import MockerFixture
@@ -12,6 +13,7 @@ from pipelex.config import get_config
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.method_trees.method_file_store import LOCAL_METHOD_FILES, HeldFile
from pipelex.core.method_trees.tree_files import write_call_files
+from pipelex.errors.problem import ProblemView
from pipelex.interpreter_hub import get_library_manager, scoped_current_library, set_current_library
from pipelex.libraries.library_crate import LibraryCrate
from pipelex.libraries.pipe_func_call_files import read_pipe_func_call_files
@@ -214,3 +216,17 @@ class TestDirectExecutorWorkdir:
assert response.function_qualname == "greet_it"
assert (tree_root / "structures.py").is_file()
assert not list(tree_root.rglob("__pycache__"))
+
+ @pytest.mark.builds_problems_without_required_params(reason="the transported call runs below the PipeFunc step, whose wrapper names the pipe")
+ @pytest.mark.asyncio
+ async def test_a_transported_run_past_its_deadline_names_the_function_and_the_limit(self, tmp_path: Path, mocker: MockerFixture):
+ """The runaway-code guard's refusal is `pipe.function_timed_out`, naming the function and the limit it passed."""
+ mocker.patch.object(DirectPipeFuncExecutor, "run_pipe_func", side_effect=TimeoutError)
+
+ with _greet_request(tmp_path=tmp_path) as request, pytest.raises(PipelexError) as raised:
+ await _run_transported(request=request.model_copy(update={"timeout_seconds": 7}))
+
+ caller = raised.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.PIPE_FUNCTION_TIMED_OUT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"function": "greet_demo_funcs.greeting.greet_it", "timeout": 7}
diff --git a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_failure_code.py b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_failure_code.py
index 6b455d437..737991876 100644
--- a/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_failure_code.py
+++ b/tests/unit/pipelex/pipe_operators/pipe_func/test_pipe_func_failure_code.py
@@ -72,7 +72,8 @@ class _TimedOutExecutor(PipeFuncExecutorProtocol):
pipe_run_params: PipeRunParams,
) -> PipeFuncExecutionResult:
msg = f"PipeFunc '{function_name}' exceeded its 30s timeout"
- raise PipeFuncExecutionError(msg).with_error_code(CoreCode.PIPE_FUNCTION_TIMED_OUT)
+ # As the executor's own deadline raises it: the function and the limit it passed.
+ raise PipeFuncExecutionError(msg).with_error_code(CoreCode.PIPE_FUNCTION_TIMED_OUT).with_params(function=function_name, timeout=30)
@override
async def run_pipe_func_transported(self, *, request: PipeFuncExecutionRequest) -> PipeFuncExecutionResponse:
@@ -246,6 +247,9 @@ class TestPipeFuncFailureCode:
assert step_failure.message.endswith(expected_error)
assert _FUNCTION_TEXT not in step_failure.message
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the coercion of a function's return knows neither the step's output concept nor a field of it"
+ )
@pytest.mark.parametrize(
"function",
[_returns_a_list_holding_a_dict, _returns_a_list_holding_a_number],
diff --git a/tests/unit/pipelex/pipe_operators/shared/test_llm_setting_check.py b/tests/unit/pipelex/pipe_operators/shared/test_llm_setting_check.py
index 2cb2c1201..c555c558e 100644
--- a/tests/unit/pipelex/pipe_operators/shared/test_llm_setting_check.py
+++ b/tests/unit/pipelex/pipe_operators/shared/test_llm_setting_check.py
@@ -1,10 +1,11 @@
from __future__ import annotations
from types import SimpleNamespace
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
import pytest
from mthds.protocol.problem.registry import CoreCode
+from typing_extensions import override
from pipelex.cogt.exceptions import LLMCapabilityError, LLMSettingRefusedError
from pipelex.cogt.llm.llm_job_components import ReasoningEffort
@@ -12,6 +13,7 @@ from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting
from pipelex.cogt.models.model_reference import ModelReference
from pipelex.core.pipes.exceptions import PipeValidationError
from pipelex.errors.error_codes import error_code_spec
+from pipelex.errors.problem import ProblemView
from pipelex.pipe_operators.shared.llm_setting_check import refuse_llm_setting_its_model_refuses
from pipelex.validation_error_types import PipeValidationErrorType
@@ -22,6 +24,14 @@ _SETTING = LLMSetting(model="@some-alias", temperature=0.2, reasoning_effort=Rea
_WORKER_REFUSAL = "Model 'some-model' does not support reasoning (thinking_mode=none)"
+class _ClassNamedCapabilityError(LLMCapabilityError):
+ """A refusal whose class, not its raise site, names the capability the model lacks, as a plugin's may."""
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"model": "some-model", "capability": "reasoning"}
+
+
class TestLLMSettingCheck:
@classmethod
def _patch_deck_overrides(cls, mocker: MockerFixture, *, for_text: LLMModelChoice | None, for_object: LLMModelChoice | None) -> None:
@@ -158,6 +168,9 @@ class TestLLMSettingCheck:
assert message.endswith(expected_remedy)
assert "choice_defaults" not in message
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a worker's own refusal, built with a message alone, is named by its code's title, which is what the test checks"
+ )
def test_a_refusal_not_worded_for_the_caller_is_named_by_its_title(self, mocker: MockerFixture) -> None:
"""A worker's own refusal names the SDK and the backend, which a verdict kept under strict disclosure must not show."""
self._patch_deck_overrides(mocker, for_text=None, for_object=None)
@@ -179,3 +192,25 @@ class TestLLMSettingCheck:
assert "internal" not in message
capability_title = error_code_spec(CoreCode.MODEL_CAPABILITY_UNSUPPORTED).title.rstrip(".")
assert f"which the model it resolves to refuses: {capability_title}. " in message
+
+ def test_the_capability_a_refusal_s_class_names_reaches_the_verdict(self, mocker: MockerFixture) -> None:
+ """The capability is read from both channels a refusal gives it by, its class's facts as well as its raise site's."""
+ self._patch_deck_overrides(mocker, for_text=None, for_object=None)
+ mocker.patch(
+ "pipelex.pipe_operators.shared.llm_setting_check.check_llm_setting_with_served_model",
+ side_effect=_ClassNamedCapabilityError("Model 'some-model' does not reason"),
+ )
+ with pytest.raises(PipeValidationError) as exc_info:
+ refuse_llm_setting_its_model_refuses(
+ pipe_type="PipeLLM",
+ pipe_code="answer_it",
+ domain_code="some_domain",
+ llm_setting=_SETTING,
+ llm_choice=_SETTING,
+ field_name="model",
+ is_structured=False,
+ )
+
+ params = exc_info.value.to_problem(view=ProblemView.CALLER).params
+ assert params is not None
+ assert params.as_wire().get("capability") == "reasoning"
diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.py
index d62ce3621..e64c2081b 100644
--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py
+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py
@@ -31,6 +31,7 @@ from pipelex.core.stuffs.number_content import NumberContent
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.text_content import TextContent
from pipelex.errors.problem import PipelexProblem, ProblemView, caller_view_of
+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.graph.graphspec import GraphSpec, PipelineRef
from pipelex.interpreter_hub import get_concept_library, get_current_library_id_or_none, get_library_manager, scoped_current_library
from pipelex.pipe_run import delivery_executor as delivery_executor_module
@@ -304,7 +305,9 @@ class TestDeliveryExecutor:
)
async def test_storage_failure_raises(self, mocker: MockerFixture) -> None:
+ """An uncoded failure of the storage is the storage being unavailable, naming the storage's kind."""
mock_storage = mocker.AsyncMock()
+ mock_storage.storage_kind = "s3"
mock_storage.store = mocker.AsyncMock(side_effect=Exception("S3 down"))
mocker.patch("pipelex.pipe_run.delivery_executor.get_storage_provider", return_value=mock_storage)
@@ -317,7 +320,7 @@ class TestDeliveryExecutor:
executor = DeliveryExecutor()
assignment = DeliveryAssignment(storage=StorageTarget())
- with pytest.raises(StorageDeliveryError):
+ with pytest.raises(StorageDeliveryError) as raised:
await executor.execute(
pipe_output=mock_output,
storage_scope="test-user",
@@ -326,6 +329,11 @@ class TestDeliveryExecutor:
status=DeliveryStatus.COMPLETED,
)
+ caller = raised.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == PipelexErrorCode.STORAGE_UNAVAILABLE
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"scheme": "s3"}
+
async def test_generate_result_files_raises_without_main_stuff_typed(self, mocker: MockerFixture) -> None:
"""A completed run always resolves its declared output — a typed working memory with neither
a main stuff nor a recorded absence is a contract violation, not an empty envelope.
@@ -890,6 +898,9 @@ class TestDeliveryExecutor:
assert "Page 1 contents" in json_text
assert "https://example.com/img.png" in json_text
+ @pytest.mark.builds_problems_without_required_params(
+ reason="delivers a run's problem built in the test, without the model and provider of its failure"
+ )
@pytest.mark.parametrize("problem_view", [ProblemView.OPERATOR, ProblemView.CALLER])
async def test_webhook_includes_the_problem_in_its_own_view_on_failed_status(self, mocker: MockerFixture, problem_view: ProblemView) -> None:
"""A FAILED delivery sends the run's problem in the webhook's own view, which the receiver can rehydrate.
@@ -1062,6 +1073,9 @@ class TestDeliveryExecutor:
assert isinstance(vars(record).get("file_count"), int)
assert vars(record)["file_count"] > 0
+ @pytest.mark.builds_problems_without_required_params(
+ reason="delivers a run's problem built in the test, without the model and provider of its failure"
+ )
@pytest.mark.parametrize(
("status", "has_problem"),
[
diff --git a/tests/unit/pipelex/pipe_run/test_located_failure.py b/tests/unit/pipelex/pipe_run/test_located_failure.py
index 20810f64b..3e73da1fa 100644
--- a/tests/unit/pipelex/pipe_run/test_located_failure.py
+++ b/tests/unit/pipelex/pipe_run/test_located_failure.py
@@ -13,7 +13,7 @@ from pipelex.cogt.inference.error_classification import ProviderErrorMetadata
from pipelex.cogt.inference.provider_name import ProviderName
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
-from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError, PipeRunError
+from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError, PipeRunError, PipeValidationError
from pipelex.core.pipes.inputs.exceptions import OptionalValueAbsentError
from pipelex.errors.error_codes import error_code_spec
from pipelex.errors.problem import PipelexProblem, ProblemView, caller_view_of, make_location, make_problem_item
@@ -22,6 +22,7 @@ from pipelex.pipe_run.located_failure import compose_located_message, find_forei
from pipelex.pipeline.exceptions import PipelineExecutionError
from pipelex.runtime_bridge.exceptions import PipelexBridgeDispatchError
from pipelex.system.pipe_run_mode import PipeRunMode
+from pipelex.validation_error_types import PipeValidationErrorType
class _RecoveredProblemError(PipelexError):
@@ -150,6 +151,9 @@ class TestLocatedFailureProblem:
assert problem.diagnostics is not None
assert problem.diagnostics.message == "Size tier '4k' is not satisfiable: use '1k' or '2k'"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
def test_the_problem_is_the_root_faults_located_at_the_failing_pipe(self) -> None:
"""Through the router, a bridge and the runner, the problem is the root fault's, located once at the innermost pipe."""
root_fault = LLMCompletionError(message="rate limited", error_category=InferenceErrorCategory.TRANSIENT).with_error_code(
@@ -296,6 +300,22 @@ class TestLocatedFailureProblem:
assert run_problem.location is not None
assert run_problem.location.as_wire() == {"pipe": "summarize", "path": ["flow", "summarize"], "field": "model", "file": "docs.mthds"}
+ def test_a_fact_the_root_fault_does_not_hold_is_filled_from_its_location(self) -> None:
+ """A pipe refusal raised without its pipe still names the pipe the run located it at."""
+ refusal = PipeValidationError(
+ "the prompt reads a variable no input declares",
+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
+ pipe_code=None,
+ variable_names=["topic"],
+ )
+ run_failure = _wrap_in_runner(_locate(refusal, pipe_stack=["flow", "summarize"]), entry_pipe_code="flow")
+
+ caller = run_failure.to_problem(view=ProblemView.CALLER)
+
+ assert caller.code == CoreCode.METHOD_INPUT_UNDECLARED
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "summarize", "variables": ["topic"]}
+
def test_a_cyclic_chain_reports_the_wrapper_as_itself(self) -> None:
"""A chain that loops back to the wrapper cannot make the problem recurse."""
root_fault = PipelexError("combine failed")
@@ -308,6 +328,9 @@ class TestLocatedFailureProblem:
assert problem.diagnostics.error_class == "PipeRouterError"
assert problem.diagnostics.message.endswith("combine failed")
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds items with no parameters, to check how the wrappers' items follow their cause's"
+ )
def test_what_the_wrappers_above_a_coded_cause_give_reaches_its_problem(self, caplog: pytest.LogCaptureFixture) -> None:
"""A wrapper fills a parameter its coded cause did not give, the nearest one winning, and its items follow the cause's."""
carrier = (
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 f3766e4eb..261394b36 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_router_run.py
@@ -108,6 +108,9 @@ def _make_pipe_job() -> PipeJob:
@pytest.mark.asyncio(loop_scope="class")
class TestPipeRouterRun:
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises an inference failure built by hand, below the worker that names its model and provider"
+ )
async def test_transient_cogt_error_surfaces_on_first_attempt(self) -> None:
"""Direct execution is a single pipeline-level attempt: a transient CogtError is not retried.
@@ -147,6 +150,7 @@ class TestPipeRouterRun:
assert exc_info.value.pipe_stack == ["stub_pipe"]
assert router.call_count == 1
+ @pytest.mark.builds_problems_without_required_params(reason="raises a failure built with a message alone, to check where the router locates it")
async def test_any_pipelex_error_is_located_with_its_own_problem(self) -> None:
"""A PipelexError that is neither a CogtError nor a PipeRunError is located too, and its problem is its own."""
stuff_error = StuffFactoryError("Error combining stuffs")
diff --git a/tests/unit/pipelex/pipe_run/test_pipe_run.py b/tests/unit/pipelex/pipe_run/test_pipe_run.py
index d408a5a1a..5dafa47c8 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_run.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_run.py
@@ -168,6 +168,57 @@ class TestPipeRun:
assert record_fields["error.code"] == "runtime.unexpected"
assert failure_record.exc_info is None
+ async def test_a_refusal_the_delivery_raises_logs_its_security_event_once(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:
+ """A webhook the SSRF guard refuses at fire time fails a run that completed: the run that raised it logs its event."""
+ mock_router = mocker.AsyncMock()
+ mock_router.run = mocker.AsyncMock(return_value=mocker.MagicMock())
+ refusal = SsrfBlockedError("Refusing to connect to 'hooks.internal.example'.").with_security_target_class(SecurityTargetClass.PRIVATE)
+ mock_executor = mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")
+ mock_executor.return_value.execute = mocker.AsyncMock(side_effect=refusal)
+ mock_job = mocker.MagicMock()
+ mock_job.job_metadata = JobMetadata(
+ run_metadata=RunMetadata(
+ user_id="pytest", pipeline_run_id="plr-webhook-refused", storage_scope="test/scope", read_scope=None, extras={"org_id": "org_abc"}
+ )
+ )
+
+ with caplog.at_level(logging.WARNING, logger=_SECURITY_EVENT_LOGGER), pytest.raises(SsrfBlockedError):
+ await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job, delivery_assignment=DeliveryAssignment(storage=StorageTarget()))
+
+ (event,) = [record for record in caplog.records if record.getMessage() == SECURITY_EVENT_MESSAGE]
+ event_fields = vars(event)
+ assert event_fields["error.code"] == CoreCode.SECURITY_INPUT_URL_REFUSED
+ assert event_fields["security.target_class"] == SecurityTargetClass.PRIVATE
+ assert event_fields["pipeline_run_id"] == "plr-webhook-refused"
+ assert event_fields["run.extras.org_id"] == "org_abc"
+ assert not emit_security_event(error=refusal)
+
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises SSRF refusals built in the test, without the input and the rule their raise sites name"
+ )
+ async def test_a_run_refused_then_its_webhook_refused_logs_both_refusals(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:
+ """A run its input refused, whose FAILED webhook the SSRF guard then refuses: two refusals of one code, two events."""
+ input_refusal = SsrfBlockedError("Refusing to connect to 'files.internal.example'.").with_security_target_class(SecurityTargetClass.PRIVATE)
+ webhook_refusal = SsrfBlockedError("Refusing to connect to 'hooks.internal.example'.").with_security_target_class(
+ SecurityTargetClass.LOOPBACK
+ )
+ mock_router = mocker.AsyncMock()
+ mock_router.run = mocker.AsyncMock(side_effect=input_refusal)
+ mock_executor = mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")
+ mock_executor.return_value.execute = mocker.AsyncMock(side_effect=webhook_refusal)
+ mock_job = mocker.MagicMock()
+ mock_job.job_metadata = JobMetadata(
+ run_metadata=RunMetadata(user_id="pytest", pipeline_run_id="plr-both-refused", storage_scope="test/scope", read_scope=None)
+ )
+
+ with caplog.at_level(logging.WARNING, logger=_SECURITY_EVENT_LOGGER), pytest.raises(SsrfBlockedError) as exc_info:
+ await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job, delivery_assignment=DeliveryAssignment(storage=StorageTarget()))
+
+ assert exc_info.value is webhook_refusal
+ events = [vars(record) for record in caplog.records if record.getMessage() == SECURITY_EVENT_MESSAGE]
+ assert [event["security.target_class"] for event in events] == [SecurityTargetClass.PRIVATE, SecurityTargetClass.LOOPBACK]
+ assert [event["error.code"] for event in events] == [CoreCode.SECURITY_INPUT_URL_REFUSED] * 2
+
async def test_the_failure_line_carries_the_code_and_never_the_exception_s_text(
self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture
) -> None:
@@ -230,54 +281,6 @@ class TestPipeRun:
assert "error.message" not in record_fields
assert secret not in str(record_fields)
- async def test_a_refusal_the_delivery_raises_logs_its_security_event_once(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:
- """A webhook the SSRF guard refuses at fire time fails a run that completed: the run that raised it logs its event."""
- mock_router = mocker.AsyncMock()
- mock_router.run = mocker.AsyncMock(return_value=mocker.MagicMock())
- refusal = SsrfBlockedError("Refusing to connect to 'hooks.internal.example'.").with_security_target_class(SecurityTargetClass.PRIVATE)
- mock_executor = mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")
- mock_executor.return_value.execute = mocker.AsyncMock(side_effect=refusal)
- mock_job = mocker.MagicMock()
- mock_job.job_metadata = JobMetadata(
- run_metadata=RunMetadata(
- user_id="pytest", pipeline_run_id="plr-webhook-refused", storage_scope="test/scope", read_scope=None, extras={"org_id": "org_abc"}
- )
- )
-
- with caplog.at_level(logging.WARNING, logger=_SECURITY_EVENT_LOGGER), pytest.raises(SsrfBlockedError):
- await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job, delivery_assignment=DeliveryAssignment(storage=StorageTarget()))
-
- (event,) = [record for record in caplog.records if record.getMessage() == SECURITY_EVENT_MESSAGE]
- event_fields = vars(event)
- assert event_fields["error.code"] == CoreCode.SECURITY_INPUT_URL_REFUSED
- assert event_fields["security.target_class"] == SecurityTargetClass.PRIVATE
- assert event_fields["pipeline_run_id"] == "plr-webhook-refused"
- assert event_fields["run.extras.org_id"] == "org_abc"
- assert not emit_security_event(error=refusal)
-
- async def test_a_run_refused_then_its_webhook_refused_logs_both_refusals(self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture) -> None:
- """A run its input refused, whose FAILED webhook the SSRF guard then refuses: two refusals of one code, two events."""
- input_refusal = SsrfBlockedError("Refusing to connect to 'files.internal.example'.").with_security_target_class(SecurityTargetClass.PRIVATE)
- webhook_refusal = SsrfBlockedError("Refusing to connect to 'hooks.internal.example'.").with_security_target_class(
- SecurityTargetClass.LOOPBACK
- )
- mock_router = mocker.AsyncMock()
- mock_router.run = mocker.AsyncMock(side_effect=input_refusal)
- mock_executor = mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")
- mock_executor.return_value.execute = mocker.AsyncMock(side_effect=webhook_refusal)
- mock_job = mocker.MagicMock()
- mock_job.job_metadata = JobMetadata(
- run_metadata=RunMetadata(user_id="pytest", pipeline_run_id="plr-both-refused", storage_scope="test/scope", read_scope=None)
- )
-
- with caplog.at_level(logging.WARNING, logger=_SECURITY_EVENT_LOGGER), pytest.raises(SsrfBlockedError) as exc_info:
- await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job, delivery_assignment=DeliveryAssignment(storage=StorageTarget()))
-
- assert exc_info.value is webhook_refusal
- events = [vars(record) for record in caplog.records if record.getMessage() == SECURITY_EVENT_MESSAGE]
- assert [event["security.target_class"] for event in events] == [SecurityTargetClass.PRIVATE, SecurityTargetClass.LOOPBACK]
- assert [event["error.code"] for event in events] == [CoreCode.SECURITY_INPUT_URL_REFUSED] * 2
-
async def test_run_success_no_delivery_when_none(self, mocker: MockerFixture) -> None:
"""When delivery_assignment is None, the delivery executor is not called."""
mock_output = mocker.MagicMock()
diff --git a/tests/unit/pipelex/pipeline/test_bundle_validator.py b/tests/unit/pipelex/pipeline/test_bundle_validator.py
index b8658c506..aecdf06e6 100644
--- a/tests/unit/pipelex/pipeline/test_bundle_validator.py
+++ b/tests/unit/pipelex/pipeline/test_bundle_validator.py
@@ -332,6 +332,9 @@ class TestBundleValidator:
@pytest.mark.asyncio
@pytest.mark.parametrize("is_met_before_the_run", [True, False], ids=["mock_input_build", "pipe_run"])
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises an SSRF refusal built in the test, without the input and the rule its raise sites name"
+ )
async def test_a_refusal_the_sweep_meets_is_logged_once(
self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, is_met_before_the_run: bool
) -> None:
diff --git a/tests/unit/pipelex/pipeline/test_data.py b/tests/unit/pipelex/pipeline/test_data.py
new file mode 100644
index 000000000..e4bf4b9db
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_data.py
@@ -0,0 +1,86 @@
+import base64
+from typing import Any, ClassVar, NamedTuple
+
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+
+
+class FileInputRefusalCase(NamedTuple):
+ """A list input whose second file is refused, the run's read scope, and how the refusal names the input."""
+
+ native_concept_code: NativeConceptCode
+ input_name: str
+ refused_url: str
+ read_scope: str | None
+ expected_code: str
+ expected_params: dict[str, Any]
+
+
+def _data_url(*, mime_type: str, raw_bytes: bytes) -> str:
+ return f"data:{mime_type};base64,{base64.b64encode(raw_bytes).decode('ascii')}"
+
+
+class InputRefusalNamingTestData:
+ """File-input refusals that each name the root input as `input` and the path down to the file as the location's `field`."""
+
+ FINE_URL = "https://example.com/a.pdf"
+ # The leading bytes of a PDF file, which a sniff identifies as one.
+ PDF_HEAD = b"%PDF-1.7\n%\xe2\xe3\xcf\xd3\n1 0 obj\n<< /Type /Catalog >>\nendobj\n"
+ MISSING_STORED_FILE = "pipelex-storage://org_abc/assets/missing.pdf"
+ UNREADABLE_LOCAL_PATH = "/nonexistent-pipelex-test-directory/nope.pdf"
+
+ CASES: ClassVar[list[tuple[str, FileInputRefusalCase]]] = [
+ (
+ "a_storage_reference_naming_nothing",
+ FileInputRefusalCase(
+ native_concept_code=NativeConceptCode.DOCUMENT,
+ input_name="documents",
+ refused_url=MISSING_STORED_FILE,
+ read_scope=None,
+ expected_code="input.reference_not_found",
+ expected_params={"input": "documents"},
+ ),
+ ),
+ (
+ "a_data_url_that_is_not_base64",
+ FileInputRefusalCase(
+ native_concept_code=NativeConceptCode.DOCUMENT,
+ input_name="documents",
+ refused_url="data:application/pdf;base64,abc",
+ read_scope=None,
+ expected_code="input.file_unreadable",
+ expected_params={"input": "documents", "file_type": "document", "reason": "invalid_base64"},
+ ),
+ ),
+ (
+ "a_local_path_that_cannot_be_read",
+ FileInputRefusalCase(
+ native_concept_code=NativeConceptCode.DOCUMENT,
+ input_name="documents",
+ refused_url=UNREADABLE_LOCAL_PATH,
+ read_scope=None,
+ expected_code="input.file_unreadable",
+ expected_params={"input": "documents", "file_type": "document", "reason": "path_unreadable"},
+ ),
+ ),
+ (
+ "a_local_path_a_scoped_run_may_not_read",
+ FileInputRefusalCase(
+ native_concept_code=NativeConceptCode.DOCUMENT,
+ input_name="documents",
+ refused_url=UNREADABLE_LOCAL_PATH,
+ read_scope="org_abc",
+ expected_code="security.input_url_refused",
+ expected_params={"input": "documents"},
+ ),
+ ),
+ ]
+
+ # An Image input holding a PDF, refused before any model reads it, so its `model` is never known (see the test's marker).
+ IMAGE_HOLDING_A_PDF = FileInputRefusalCase(
+ native_concept_code=NativeConceptCode.IMAGE,
+ input_name="photos",
+ refused_url=_data_url(mime_type="image/png", raw_bytes=PDF_HEAD),
+ read_scope=None,
+ expected_code="input.file_type_unsupported",
+ expected_params={"input": "photos", "format": "pdf"},
+ )
diff --git a/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py b/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py
index 803a7df33..5c5ae6823 100644
--- a/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py
+++ b/tests/unit/pipelex/pipeline/test_direct_bundle_validator.py
@@ -66,6 +66,9 @@ class TestDirectBundleValidator:
methods_dirs=None,
)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
async def test_validate_bundle_error_becomes_the_invalid_arm(self, mocker: MockerFixture) -> None:
"""An invalid bundle's ValidateBundleError is converted to the invalid arm, its operator's problem and its items, not propagated."""
error = ValidateBundleError("bundle is invalid")
diff --git a/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py b/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py
index 73371a6bb..73c7bab4a 100644
--- a/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py
+++ b/tests/unit/pipelex/pipeline/test_dry_run_failure_location.py
@@ -113,6 +113,9 @@ class TestDryRunFailureLocation:
assert raised.value.__cause__ is failure
assert recorder.find_failing_pipe(error=raised.value) is pipe
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises failures built with a message alone, to check that the sweep reads their code's sentence"
+ )
@pytest.mark.parametrize(
("error", "expected_code", "expected_text", "own_text"),
[
@@ -205,6 +208,9 @@ class TestDryRunFailureLocation:
assert failures == [inner_failure_own, other_failure]
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises failures of a test class with a message alone, to check where the sweep locates them"
+ )
@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."""
@@ -232,6 +238,9 @@ class TestDryRunFailureLocation:
(located_failure,) = exc_info.value.failures
assert (located_failure.pipe_code, located_failure.domain_code) == ("run_workshop", "board")
+ @pytest.mark.builds_problems_without_required_params(
+ reason="raises a failure of a test class with a message alone, to check the source it is given"
+ )
@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``."""
diff --git a/tests/unit/pipelex/pipeline/test_dry_run_fault_answer.py b/tests/unit/pipelex/pipeline/test_dry_run_fault_answer.py
index 4b16d8bfb..56aaca0f0 100644
--- a/tests/unit/pipelex/pipeline/test_dry_run_fault_answer.py
+++ b/tests/unit/pipelex/pipeline/test_dry_run_fault_answer.py
@@ -25,6 +25,7 @@ def _failure(*, code: ErrorCode, pipe_code: str) -> DryRunFailureErrorData:
class TestDryRunFaultAnswer:
+ @pytest.mark.builds_problems_without_required_params(reason="builds dry-run failures in the test, without the parameters a sweep records")
def test_a_dry_run_failing_on_a_fault_of_ours_answers_that_fault(self) -> None:
"""No item is the method's, so validation gives no verdict: it answers the fault, every failure among its items."""
failures = [
@@ -46,6 +47,7 @@ class TestDryRunFaultAnswer:
(CoreCode.RUNTIME_UNEXPECTED, "summarize"),
]
+ @pytest.mark.builds_problems_without_required_params(reason="builds dry-run failures in the test, without the parameters a sweep records")
def test_one_failure_of_the_method_makes_the_dry_run_an_invalid_verdict(self) -> None:
failures = [
_failure(code=CoreCode.RUNTIME_UNEXPECTED, pipe_code="summarize"),
@@ -75,6 +77,7 @@ class TestDryRunFaultAnswer:
assert not isinstance(exc_info.value, ValidateBundleError)
assert exc_info.value.to_problem(view=ProblemView.CALLER).code == CoreCode.RUNTIME_UNEXPECTED
+ @pytest.mark.builds_problems_without_required_params(reason="builds the step's failure with a message alone, to check the verdict it makes")
def test_a_pipe_run_failing_on_the_methods_fault_is_a_verdict(self) -> None:
with pytest.raises(ValidateBundleError) as exc_info:
_translate(
@@ -89,6 +92,7 @@ class TestDryRunFaultAnswer:
assert item.location is not None
assert item.location.pipe == "route"
+ @pytest.mark.builds_problems_without_required_params(reason="builds dry-run failures in the test, without the parameters a sweep records")
def test_a_dry_run_error_renders_its_sentence_from_the_failure_whose_code_it_carries(self, caplog: pytest.LogCaptureFixture) -> None:
"""Its code's sentence is rendered whole, from that failure's parameters and pipe, never falling back on the title."""
failures = [
diff --git a/tests/unit/pipelex/pipeline/test_input_format_errors.py b/tests/unit/pipelex/pipeline/test_input_format_errors.py
index bf316fd8a..0f9871644 100644
--- a/tests/unit/pipelex/pipeline/test_input_format_errors.py
+++ b/tests/unit/pipelex/pipeline/test_input_format_errors.py
@@ -24,6 +24,7 @@ NOT_AN_IMAGE_MESSAGE = (
class TestPipelineInputFormatErrors:
+ @pytest.mark.builds_problems_without_required_params(reason="builds each class with a message alone, to check the code and advice of the family")
@pytest.mark.parametrize("error_class", [PipelineInputNotAnImageError, PipelineInputFormatUnsupportedError])
def test_the_family_is_an_input_content_error_the_caller_can_fix(self, error_class: type[PipelineInputFormatError]):
error = error_class(NOT_AN_IMAGE_MESSAGE)
diff --git a/tests/unit/pipelex/pipeline/test_input_normalizer.py b/tests/unit/pipelex/pipeline/test_input_normalizer.py
index 83a6b0ef9..1cc160579 100644
--- a/tests/unit/pipelex/pipeline/test_input_normalizer.py
+++ b/tests/unit/pipelex/pipeline/test_input_normalizer.py
@@ -23,6 +23,7 @@ from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.document_content import DocumentContent
+from pipelex.core.stuffs.list_content import ListContent
from pipelex.core.stuffs.stuff_factory import StuffFactory
from pipelex.errors.problem import ProblemView
from pipelex.pipeline.exceptions import PipelineInputContentError, PipelineInputUrlInvalidError, PipelineInputUrlMissingError
@@ -39,6 +40,15 @@ def _memory_with_document(url: str) -> WorkingMemory:
return WorkingMemoryFactory.make_from_single_stuff(stuff)
+def _memory_with_documents(urls: list[str]) -> WorkingMemory:
+ stuff = StuffFactory.make_stuff(
+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.DOCUMENT),
+ content=ListContent[DocumentContent](items=[DocumentContent(url=url) for url in urls]),
+ name="documents",
+ )
+ return WorkingMemoryFactory.make_from_single_stuff(stuff)
+
+
def _patch_storage_and_config(mocker: MockerFixture) -> None:
mocker.patch(
"pipelex.pipeline.input_normalizer.get_storage_provider",
@@ -72,6 +82,37 @@ class TestInputNormalizerUrlGuards:
assert caller.next_step.kind == StepKind.CHANGE_INPUT
assert "not a valid http(s) URL" in exc_info.value.message
+ @pytest.mark.parametrize(
+ ("memory", "expected_params"),
+ [
+ pytest.param(_memory_with_document(""), {"input": "document", "field": "document.url"}, id="blank_url_of_an_input"),
+ pytest.param(_memory_with_document("https://"), {"input": "document", "field": "document.url"}, id="malformed_url_of_an_input"),
+ pytest.param(
+ _memory_with_documents(["https://example.com/a.pdf", " "]),
+ {"input": "documents", "field": "documents[1].url"},
+ id="blank_url_of_a_list_item",
+ ),
+ pytest.param(
+ _memory_with_documents(["https://example.com/a.pdf", "https://"]),
+ {"input": "documents", "field": "documents[1].url"},
+ id="malformed_url_of_a_list_item",
+ ),
+ ],
+ )
+ async def test_a_url_refusal_names_the_root_input_and_the_full_path_to_its_url(
+ self, mocker: MockerFixture, memory: WorkingMemory, expected_params: dict[str, str]
+ ) -> None:
+ """`input` is the root input's name and `field` the full path ending in `.url`, as every `input.invalid` refusal names them."""
+ _patch_storage_and_config(mocker)
+
+ with pytest.raises(PipelineInputContentError) as exc_info:
+ await prepare_file_inputs(memory, storage_scope="test/scope", read_scope=None, is_relocation_enabled=True)
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.INPUT_INVALID
+ assert caller.params is not None
+ assert caller.params.as_wire() == expected_params
+
async def test_well_formed_http_url_passes_through_unchanged(self, mocker: MockerFixture) -> None:
"""A well-formed http(s) url is not fetched or probed at shaping time, and it becomes its own public_url."""
_patch_storage_and_config(mocker)
diff --git a/tests/unit/pipelex/pipeline/test_input_normalizer_refusal_naming.py b/tests/unit/pipelex/pipeline/test_input_normalizer_refusal_naming.py
new file mode 100644
index 000000000..015890eda
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_input_normalizer_refusal_naming.py
@@ -0,0 +1,79 @@
+"""Every refusal of a file input names it the same way: the root input as `input`, the path down to the file as the location's `field`.
+
+The convention is `InputShapingError`'s. A list item's path, such as `documents[1]`, is never the `input`, which is the
+name a caller gave the run's input.
+"""
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.core.concepts.concept_factory import ConceptFactory
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.stuffs.document_content import DocumentContent
+from pipelex.core.stuffs.image_content import ImageContent
+from pipelex.core.stuffs.list_content import ListContent
+from pipelex.core.stuffs.stuff_content import StuffContent
+from pipelex.core.stuffs.stuff_factory import StuffFactory
+from pipelex.errors.problem import ProblemView
+from pipelex.pipeline.input_normalizer import prepare_file_inputs
+from pipelex.tools.storage.exceptions import StorageFileNotFoundError
+from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract
+from tests.unit.pipelex.pipeline.test_data import FileInputRefusalCase, InputRefusalNamingTestData
+
+
+def _file_content(*, native_concept_code: NativeConceptCode, url: str) -> StuffContent:
+ if native_concept_code == NativeConceptCode.IMAGE:
+ return ImageContent(url=url)
+ return DocumentContent(url=url)
+
+
+async def _refusal_of_the_second_item(*, mocker: MockerFixture, case: FileInputRefusalCase) -> PipelexError:
+ """Normalize a list input whose second file the case refuses, and return the refusal."""
+ storage = mocker.Mock(spec=StorageProviderAbstract)
+ storage.load_head = mocker.AsyncMock(side_effect=StorageFileNotFoundError("no stored file"))
+ mocker.patch("pipelex.pipeline.input_normalizer.get_storage_provider", return_value=storage)
+ mocker.patch(
+ "pipelex.pipeline.input_normalizer.get_config",
+ return_value=mocker.Mock(runtime=mocker.Mock(storage=mocker.Mock(is_upload_local_content_enabled=True))),
+ )
+ urls = (InputRefusalNamingTestData.FINE_URL, case.refused_url)
+ items = [_file_content(native_concept_code=case.native_concept_code, url=url) for url in urls]
+ memory = WorkingMemoryFactory.make_from_single_stuff(
+ StuffFactory.make_stuff(
+ concept=ConceptFactory.make_native_concept(native_concept_code=case.native_concept_code),
+ content=ListContent[StuffContent](items=items),
+ name=case.input_name,
+ )
+ )
+ with pytest.raises(PipelexError) as exc_info:
+ await prepare_file_inputs(memory, storage_scope="org_abc/run_1", read_scope=case.read_scope, is_relocation_enabled=True)
+ return exc_info.value
+
+
+def _assert_named_by_root_and_path(*, refusal: PipelexError, case: FileInputRefusalCase) -> None:
+ caller = refusal.to_problem(view=ProblemView.CALLER)
+ assert caller.code == case.expected_code
+ assert caller.params is not None
+ wire_params = caller.params.as_wire()
+ assert {name: wire_params.get(name) for name in case.expected_params} == case.expected_params
+ assert caller.location is not None
+ assert caller.location.model_dump(exclude_none=True) == {"input": case.input_name, "field": f"{case.input_name}[1]"}
+
+
[email protected](loop_scope="class")
+class TestInputNormalizerRefusalNaming:
+ @pytest.mark.parametrize(("_topic", "case"), InputRefusalNamingTestData.CASES)
+ async def test_a_refused_list_item_is_named_by_its_root_input_and_its_path(
+ self, mocker: MockerFixture, _topic: str, case: FileInputRefusalCase
+ ) -> None:
+ refusal = await _refusal_of_the_second_item(mocker=mocker, case=case)
+
+ _assert_named_by_root_and_path(refusal=refusal, case=case)
+
+ @pytest.mark.builds_problems_without_required_params(reason="an Image input holding a PDF is refused before any model reads it")
+ async def test_an_image_item_holding_a_pdf_is_named_by_its_root_input_and_its_path(self, mocker: MockerFixture) -> None:
+ refusal = await _refusal_of_the_second_item(mocker=mocker, case=InputRefusalNamingTestData.IMAGE_HOLDING_A_PDF)
+
+ _assert_named_by_root_and_path(refusal=refusal, case=InputRefusalNamingTestData.IMAGE_HOLDING_A_PDF)
diff --git a/tests/unit/pipelex/pipeline/test_inputs_template.py b/tests/unit/pipelex/pipeline/test_inputs_template.py
index 90df59698..87aa94c66 100644
--- a/tests/unit/pipelex/pipeline/test_inputs_template.py
+++ b/tests/unit/pipelex/pipeline/test_inputs_template.py
@@ -119,6 +119,10 @@ class TestBuildInputsForPipe:
assert str(bundle_path) in str(exc_info.value)
assert exc_info.value.to_problem(view=ProblemView.CALLER).code == CoreCode.REQUEST_PIPE_UNSPECIFIED
+ # The method declares no main pipe, so it has none to offer as a candidate.
+ caller_params = exc_info.value.to_problem(view=ProblemView.CALLER).params
+ assert caller_params is not None
+ assert caller_params.as_wire() == {"candidates": []}
def test_bundle_path_explicit_pipe_code_wins(self, ops_mocks: dict[str, Any], tmp_path: Path) -> None:
"""With a bundle path, an explicit pipe code overrides the bundle's main_pipe, and the result names it qualified."""
@@ -157,6 +161,10 @@ class TestBuildInputsForPipe:
asyncio.run(build_inputs_for_pipe())
assert exc_info.value.to_problem(view=ProblemView.CALLER).code == CoreCode.REQUEST_PIPE_UNSPECIFIED
+ # The method declares no main pipe, so it has none to offer as a candidate.
+ caller_params = exc_info.value.to_problem(view=ProblemView.CALLER).params
+ assert caller_params is not None
+ assert caller_params.as_wire() == {"candidates": []}
ops_mocks["get_required_entry_pipe"].assert_not_called()
diff --git a/tests/unit/pipelex/pipeline/test_method_entry.py b/tests/unit/pipelex/pipeline/test_method_entry.py
index 1277a0563..221e3cd52 100644
--- a/tests/unit/pipelex/pipeline/test_method_entry.py
+++ b/tests/unit/pipelex/pipeline/test_method_entry.py
@@ -86,7 +86,8 @@ class TestMethodEntry:
},
"none of its bundles declares a main_pipe ('a.mthds', 'b/b.mthds')",
CoreCode.REQUEST_PIPE_UNSPECIFIED,
- None,
+ # With no main pipe declared anywhere, every pipe the method declares is one to choose from.
+ {"candidates": ["entry_a.first", "entry_b.second"]},
),
(
{
@@ -107,7 +108,7 @@ class TestMethodEntry:
"Its bundles: 'a.mthds'."
),
CoreCode.REQUEST_PIPE_UNSPECIFIED,
- None,
+ {"candidates": ["entry_a.first"]},
),
(
{
@@ -116,7 +117,8 @@ class TestMethodEntry:
},
"declares the main_pipe 'missing', exported by 'entry_a', which none of its bundles defines in that domain: 'a.mthds'.",
CoreCode.METHOD_PIPE_UNRESOLVED,
- {"missing": "missing"},
+ # The declaration holding the reference stands for the pipe, and no declared pipe is near the one missing.
+ {"pipe": "main_pipe", "missing": "missing", "candidates": []},
),
(
{
@@ -156,7 +158,7 @@ class TestMethodEntry:
problem = exc_info.value.to_problem(view=ProblemView.CALLER)
assert problem.code == expected_code
assert problem.domain != ProblemDomain.OPERATOR
- # The refusal gives the parameters its sentences name: the pipes to choose from, the missing one, the ambiguous one.
+ # The refusal gives every parameter its code requires: the pipes to choose from, the missing one, the ambiguous one.
assert problem.to_wire().get("params") == expected_params
def test_a_manifest_that_does_not_validate_is_an_entry_refusal(self, tmp_path: Path) -> None:
diff --git a/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py b/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
index dc92ef4aa..3ccf3ae96 100644
--- a/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
+++ b/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
@@ -62,6 +62,9 @@ class TestRefusalVerdictArms:
assert problem_item.code == CoreCode.METHOD_SCHEMA_VIOLATION
assert "registry slot 7" not in str(problem.to_wire())
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds a refusal with no parameters, to check that its item is named by its code's title"
+ )
def test_an_input_refusal_with_no_parameters_is_named_by_its_title(self) -> None:
_, items = _verdict_items(_InternalInputRefusalError("internal detail: registry slot 7 is stale"))
@@ -145,6 +148,7 @@ class TestRefusalVerdictArms:
assert raised.value is wrapper
assert wrapper.resolve_error_code() == CoreCode.SECURITY_TEMPLATE_REFUSED
+ @pytest.mark.builds_problems_without_required_params(reason="builds dry-run failures in the test, without the parameters a sweep records")
def test_a_sweep_with_a_security_refusal_among_its_failures_is_no_verdict(self) -> None:
"""One method fault beside one security refusal: the sweep answers the refusal's code, never an invalid verdict."""
sweep = DryRunError(
diff --git a/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py b/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
index db642c6e3..915eec112 100644
--- a/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
+++ b/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
@@ -6,6 +6,7 @@ machine-mappable per-error diagnostics instead of only a single ``detail`` strin
``build_validation_error_items`` builds ride beside it, one per problem item.
"""
+import pytest
from mthds.protocol.problem.registry import CoreCode, ProblemDomain, RetryVerdict, StepKind
from pipelex.base_exceptions import ValidationErrorCategory
@@ -23,6 +24,8 @@ def _error_with_two_categories() -> ValidateBundleError:
PipelexBundleBlueprintValidationErrorData(
error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,
source="main.mthds",
+ # The offending code, which the blueprint categorizer recovers from the refusal.
+ pipe_code="Not A Pipe",
message="Invalid main pipe syntax 'Not A Pipe'",
),
],
@@ -67,6 +70,9 @@ class TestValidateBundleErrorProblem:
assert operator.diagnostics is not None
assert operator.diagnostics.error_class == "ValidateBundleError"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_message_only_error_surfaces_a_residual_item(self) -> None:
"""No categorized errors → a ``blueprint_validation`` residual still rides the verdict (the invariant is total).
diff --git a/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py b/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py
index 6ee6fa971..c889b4ff1 100644
--- a/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py
+++ b/tests/unit/pipelex/pipeline/test_validate_bundle_error_withholding.py
@@ -13,6 +13,7 @@ from pipelex.core.exceptions import (
PipesAndConceptValidationErrorData,
)
from pipelex.errors.problem import ProblemView, make_location, make_problem_item
+from pipelex.libraries.collision_messages import DeclarationKind, duplicate_ref_items
from pipelex.pipeline import validate_bundle_translation
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle_translation import HOST_LIBRARY_FILE_PLACEHOLDER, withholding_host_library_files
@@ -45,6 +46,9 @@ class TestValidateBundleErrorWithholding:
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"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds every channel's error data in the test, and a residual item names no declaration"
+ )
def test_every_channel_names_no_withheld_file(self) -> None:
verdict = ValidateBundleError(
message=_mentioning_the_host_file(label="raw"),
@@ -93,6 +97,9 @@ class TestValidateBundleErrorWithholding:
for view in (ProblemView.CALLER, ProblemView.OPERATOR):
assert _HOST_FILE not in str(withheld.to_problem(view=view).to_wire())
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_what_the_raise_site_chose_is_carried(self) -> None:
"""The code a raise site chose, and the parameters and items it gave, survive the withholding, withheld as the messages are."""
item = make_problem_item(
@@ -118,6 +125,31 @@ class TestValidateBundleErrorWithholding:
assert caller.code == CoreCode.REQUEST_INVALID
assert caller.detail == f"The request's field 'field in '{HOST_LIBRARY_FILE_PLACEHOLDER}'' does not match the route's schema."
+ def test_a_host_file_s_side_of_a_name_declared_twice_is_left_to_the_caller_s_side(self) -> None:
+ """A name the caller's content and a host file both declare is one item, the caller's, naming the host file by its placeholder."""
+ caller_side, host_side = duplicate_ref_items(
+ ref_kind=DeclarationKind.PIPE, ref="harbour_board.post_notice", existing_source=_HOST_FILE, incoming_source="api://bundle-0.mthds"
+ )
+ # A conflict declared in two host files keeps both items: no item of the caller's restates it.
+ host_pair = duplicate_ref_items(
+ ref_kind=DeclarationKind.PIPE, ref="harbour_board.pin", existing_source=_HOST_FILE, incoming_source=_HOST_FILE
+ )
+ verdict = ValidateBundleError(
+ message="Duplicate declarations", pipelex_bundle_blueprint_validation_errors=[caller_side, host_side, *host_pair]
+ )
+
+ withheld = verdict.withholding_files(withheld_files={_HOST_FILE}, placeholder=HOST_LIBRARY_FILE_PLACEHOLDER)
+
+ items = withheld.validation_error_items() or []
+ assert [(item.source, item.message) for item in items] == [
+ ("api://bundle-0.mthds", f"Pipe 'harbour_board.post_notice' is declared here and in '{HOST_LIBRARY_FILE_PLACEHOLDER}'."),
+ (None, "Pipe 'harbour_board.pin' is declared twice in this bundle."),
+ ]
+ assert [item.params for item in items] == [
+ {"name": "harbour_board.post_notice", "conflict": "duplicate_declaration"},
+ {"name": "harbour_board.pin", "conflict": "duplicate_declaration"},
+ ]
+
def test_an_item_taking_its_cause_s_parameters_names_no_withheld_file(self, tmp_path: Path) -> None:
"""An item no stage classified reads its cause's parameters, which the withholding reaches too, its sentence with them."""
host_library_file = tmp_path / "harbour_board.mthds"
diff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.py
index 42bc5d19b..f03bea377 100644
--- a/tests/unit/pipelex/pipeline/test_validation_errors.py
+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py
@@ -9,6 +9,7 @@ follow the builder's items one for one.
import json
+import pytest
from mthds.protocol.problem.registry import CoreCode
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
@@ -20,7 +21,8 @@ from pipelex.core.exceptions import (
)
from pipelex.errors.bundle_validation_failure import BundleValidationFailure
from pipelex.errors.problem import ProblemView
-from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.libraries.exceptions import LibraryLoadingError
+from pipelex.pipeline.exceptions import TreePythonSyntaxError, ValidateBundleError
from pipelex.pipeline.validation_errors import build_validation_error_items, warning_problem_items
from pipelex.suggested_fix import DeleteKeyOp, RenameTableKeyOp, SetKeyOp
from pipelex.validation_error_types import HintLintErrorType, PipeFactoryErrorType, PipeValidationErrorType, TemplateCheckErrorType
@@ -174,6 +176,7 @@ class TestBuildValidationErrorItems:
)
assert [item.category for item in items] == [ValidationErrorCategory.PIPE_FACTORY, ValidationErrorCategory.DRY_RUN]
+ @pytest.mark.builds_problems_without_required_params(reason="builds dry-run failures in the test, without the parameters a sweep records")
def test_a_verdict_projects_its_dry_run_failures(self) -> None:
"""A ``ValidateBundleError`` carrying dry-run failures lists one ``dry_run`` item per failure, and its problem one item each."""
exc = ValidateBundleError(
@@ -242,6 +245,9 @@ class TestBuildValidationErrorItems:
)
assert [item.category for item in items] == [ValidationErrorCategory.PIPE_FACTORY]
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a message-only verdict's residual item names no declaration, so it carries no field path"
+ )
def test_validation_items_are_total_for_message_only_error(self) -> None:
"""A bare-message ``ValidateBundleError`` still lists a non-empty set of items — the invariant is total.
@@ -440,6 +446,9 @@ class TestBuildValidationErrorItems:
# And the verdict lists it (it would be missing if the list were dropped).
assert [item.pipe_code for item in exc.validation_error_items()] == ["pipe_inst"]
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a warning no type classifies names no declaration, so its item carries no field path"
+ )
def test_warnings_become_problem_items_under_the_code_their_type_names(self) -> None:
"""A valid report's warnings, as a surface speaking problem items carries them: each type names its code, and a
warning no type classifies takes `method.schema_violation`, as an unclassified item of an invalid verdict does.
@@ -484,3 +493,45 @@ class TestBuildValidationErrorItems:
},
]
assert "emphasis" in items[0].detail
+
+ def test_a_pipe_refusal_s_own_facts_reach_its_problem_item(self) -> None:
+ """The facts the check that found the fault knows ride the item beside the pipe its locators give."""
+ verdict = ValidateBundleError(
+ message="validation failed",
+ pipe_validation_errors=[
+ PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_CONCEPT,
+ domain_code="testapp",
+ source="main.mthds",
+ pipe_code="summarize",
+ message="The output does not fit.",
+ field_path="summarize.output",
+ params={"declared": "testapp.Summary", "expected": ["native.Text", "native.Html"], "pipe_type": "PipeCompose"},
+ ),
+ ],
+ )
+
+ (item,) = verdict.problem_items() or []
+
+ assert item.code == CoreCode.METHOD_OUTPUT_CONCEPT_MISMATCH
+ assert item.params is not None
+ assert item.params.as_wire() == {
+ "pipe": "summarize",
+ "declared": "testapp.Summary",
+ "expected": ["native.Text", "native.Html"],
+ "pipe_type": "PipeCompose",
+ }
+
+ def test_an_unclassified_item_reads_through_the_verdict_s_umbrella_to_the_refusal_it_forwards(self) -> None:
+ """A library that could not load a bundle forwards the parser's refusal under `method.invalid`: the item takes the parser's code and facts."""
+ syntax_refusal = TreePythonSyntaxError("The file does not parse.").with_params(finding="invalid syntax at line 3")
+ umbrella = LibraryLoadingError("The library could not be loaded.")
+ umbrella.__cause__ = syntax_refusal
+ verdict = ValidateBundleError(message="The library could not be loaded.")
+ verdict.__cause__ = umbrella
+
+ (item,) = verdict.problem_items() or []
+
+ assert item.code == CoreCode.METHOD_SYNTAX
+ assert item.params is not None
+ assert item.params.as_wire() == {"finding": "invalid syntax at line 3"}
diff --git a/tests/unit/pipelex/pipeline/test_validation_render.py b/tests/unit/pipelex/pipeline/test_validation_render.py
index 6e49b6d6e..7d9b4936c 100644
--- a/tests/unit/pipelex/pipeline/test_validation_render.py
+++ b/tests/unit/pipelex/pipeline/test_validation_render.py
@@ -5,6 +5,7 @@ from __future__ import annotations
from pathlib import Path
from typing import Any
+import pytest
from mthds.protocol.problem.models import FixOp, ProblemItem, SetKeyOp
from mthds.protocol.problem.models import SuggestedFix as WireSuggestedFix
from mthds.protocol.problem.registry import CoreCode
@@ -126,6 +127,9 @@ class TestValidationRender:
assert "✅" not in markdown
assert "⚠️" not in markdown
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds the validation item in the test, without the multiplicities its raise site names"
+ )
def test_renders_an_invalid_verdict_from_its_problem_items(self):
"""The invalid-arm renderer presents the verdict's problem items, the `errors` a host answers: each numbered under
its code's title with its code, where it is, its sentence and its suggested fix, and never a validation item's own
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_clamp.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_clamp.py
index 1958c287c..88424ee9a 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_clamp.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_clamp.py
@@ -102,6 +102,9 @@ class TestAnthropicStructuredClamp:
assert "was lowered" not in exc_info.value.message
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
@pytest.mark.parametrize("is_wrapped", [True, False])
async def test_a_timeout_of_the_lowered_call_says_the_limit_was_lowered(self, mocker: MockerFixture, is_wrapped: bool) -> None:
"""The note is added to the error the call raises, whose class and retryable category stay as they were."""
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py
index 09dc51a50..7b26c47a6 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py
@@ -274,6 +274,9 @@ class TestAnthropicWorkerErrorHandling:
# ---- Problem integration ----
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_category(self, mocker: MockerFixture) -> None:
"""The category stays on the chain, and the problem takes the retry verdict of the code it gives."""
worker = _make_worker(mocker)
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py
index 478612466..87a902913 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py
@@ -283,6 +283,9 @@ class TestAnthropicWorkerObjectErrorHandling:
assert exc_info.value.user_action is not None
assert exc_info.value.user_action.kind is UserActionKind.CONTACT_SUPPORT
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_provider_facts_are_serialized_in_the_operator_problem(self, mocker: MockerFixture) -> None:
"""The operator's problem carries what the provider answered, and the error advises its local reader what to do."""
_patch_gen_object_dependencies(mocker)
diff --git a/tests/unit/pipelex/providers/azure_rest/test_azure_worker_error_handling.py b/tests/unit/pipelex/providers/azure_rest/test_azure_worker_error_handling.py
index 3c37c315d..0fc6218d3 100644
--- a/tests/unit/pipelex/providers/azure_rest/test_azure_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/azure_rest/test_azure_worker_error_handling.py
@@ -171,6 +171,9 @@ class TestAzureWorkerErrorHandling:
assert exc_info.value.user_action.kind is expected_user_action_kind
assert exc_info.value.__cause__ is sdk_exc
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_category(self, mocker: MockerFixture) -> None:
"""The category stays on the chain, and the problem takes the retry verdict of the code it gives."""
worker = _make_azure_img_gen_worker(mocker)
diff --git a/tests/unit/pipelex/providers/bedrock/test_bedrock_worker_error_handling.py b/tests/unit/pipelex/providers/bedrock/test_bedrock_worker_error_handling.py
index 445d902ff..4b3355cd3 100644
--- a/tests/unit/pipelex/providers/bedrock/test_bedrock_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/bedrock/test_bedrock_worker_error_handling.py
@@ -105,6 +105,9 @@ class TestBedrockWorkerErrorHandling:
# ---- Problem integration ----
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_transient_is_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a TRANSIENT Bedrock error invites a retry."""
worker = _make_bedrock_llm_worker(mocker)
@@ -127,6 +130,9 @@ class TestBedrockWorkerErrorHandling:
assert problem.is_retryable is True
assert _diagnostics_of(problem).error_class == "LLMCompletionError"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_capacity_not_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a CAPACITY Bedrock error invites no retry."""
worker = _make_bedrock_llm_worker(mocker)
@@ -148,6 +154,9 @@ class TestBedrockWorkerErrorHandling:
assert find_inference_error_category_in_chain(error) == "capacity"
assert problem.is_retryable is False
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_configuration_not_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a CONFIGURATION Bedrock error invites no retry."""
worker = _make_bedrock_llm_worker(mocker)
diff --git a/tests/unit/pipelex/providers/docling/test_docling_worker_error_handling.py b/tests/unit/pipelex/providers/docling/test_docling_worker_error_handling.py
index c707f8366..fc4245e7b 100644
--- a/tests/unit/pipelex/providers/docling/test_docling_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/docling/test_docling_worker_error_handling.py
@@ -75,6 +75,7 @@ class TestDoclingWorkerErrorHandling:
assert exc_info.value.user_action is not None
assert exc_info.value.user_action.kind is expected_user_action_kind
+ @pytest.mark.builds_problems_without_required_params(reason="an extract worker reads its source by URI and never learns the input it came from")
async def test_problem_for_file_not_found(self, mocker: MockerFixture) -> None:
"""A FileNotFoundError is a CONTENT failure, and its problem invites no retry."""
worker = _make_docling_extract_worker(mocker)
diff --git a/tests/unit/pipelex/providers/fal/test_fal_worker_error_handling.py b/tests/unit/pipelex/providers/fal/test_fal_worker_error_handling.py
index 54751cad4..fdcea5a09 100644
--- a/tests/unit/pipelex/providers/fal/test_fal_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/fal/test_fal_worker_error_handling.py
@@ -198,6 +198,9 @@ class TestFalWorkerErrorHandling:
assert exc_info.value.user_action.kind is expected_user_action_kind
assert exc_info.value.__cause__ is sdk_exc
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_category(self, mocker: MockerFixture) -> None:
"""The category stays on the chain, and the problem takes the retry verdict of the code it gives."""
worker = _make_fal_img_gen_worker(mocker)
diff --git a/tests/unit/pipelex/providers/google/test_google_img_gen_worker_error_handling.py b/tests/unit/pipelex/providers/google/test_google_img_gen_worker_error_handling.py
index 5a3bf55fe..1cd023445 100644
--- a/tests/unit/pipelex/providers/google/test_google_img_gen_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/google/test_google_img_gen_worker_error_handling.py
@@ -235,6 +235,9 @@ class TestGoogleImgGenWorkerErrorHandling:
assert exc_info.value.provider_metadata.sdk_exception_type == expected_sdk_type
assert exc_info.value.__cause__ is sdk_exc
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_the_operator_problem_carries_the_provider_facts(self, mocker: MockerFixture) -> None:
worker = _make_worker(mocker)
sdk_exc = _make_google_client_error(429, "Resource has been exhausted", status="RESOURCE_EXHAUSTED")
diff --git a/tests/unit/pipelex/providers/google/test_google_img_gen_worker_refusal.py b/tests/unit/pipelex/providers/google/test_google_img_gen_worker_refusal.py
index a9dc3b496..66f8105f9 100644
--- a/tests/unit/pipelex/providers/google/test_google_img_gen_worker_refusal.py
+++ b/tests/unit/pipelex/providers/google/test_google_img_gen_worker_refusal.py
@@ -124,6 +124,7 @@ class TestGoogleImgGenWorkerRefusal:
assert _MODEL_ID not in error.message
caller = error.to_problem(view=ProblemView.CALLER)
assert caller.code == CoreCode.MODEL_CONTENT_REFUSED
+ assert caller.to_wire()["params"] == {"model": _MODEL_HANDLE}
assert caller.domain == ProblemDomain.INPUT
assert error_code_spec(CoreCode.MODEL_CONTENT_REFUSED).status == 422
# The caller reads the code's sentence, never the provider's model id, and the reason rides the operator's view.
@@ -216,6 +217,9 @@ class TestGoogleImgGenWorkerRefusal:
fields={"model_handle": _MODEL_HANDLE, "finish_reason": "IMAGE_BRAND_NEW"},
)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the image worker sends no output limit and Gemini reports none, the max_tokens and output_tokens of model.output_truncated"
+ )
async def test_an_answer_cut_before_its_image_reads_output_truncated(self, mocker: MockerFixture) -> None:
"""A finish reason of MAX_TOKENS with no image is the cut it states, not an empty answer to rephrase."""
async with _answering(_finished_without_image("MAX_TOKENS")) as http_client:
diff --git a/tests/unit/pipelex/providers/google/test_google_worker_error_handling.py b/tests/unit/pipelex/providers/google/test_google_worker_error_handling.py
index 11ce54a1f..28bc45708 100644
--- a/tests/unit/pipelex/providers/google/test_google_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/google/test_google_worker_error_handling.py
@@ -247,6 +247,9 @@ class TestGoogleWorkerErrorHandling:
# ---- Problem integration ----
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_category_and_retryable(self, mocker: MockerFixture) -> None:
"""The category stays on the chain, and the problem takes the retry verdict of the code it gives."""
worker = _make_google_llm_worker(mocker)
@@ -262,6 +265,9 @@ class TestGoogleWorkerErrorHandling:
assert problem.is_retryable is True
assert _diagnostics_of(problem).error_class == "LLMCompletionError"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_capacity_not_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a CAPACITY error invites no retry."""
worker = _make_google_llm_worker(mocker)
diff --git a/tests/unit/pipelex/providers/huggingface/test_hf_worker_error_handling.py b/tests/unit/pipelex/providers/huggingface/test_hf_worker_error_handling.py
index fa1b9e50d..7abca70c2 100644
--- a/tests/unit/pipelex/providers/huggingface/test_hf_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/huggingface/test_hf_worker_error_handling.py
@@ -134,6 +134,9 @@ class TestHuggingFaceWorkerErrorHandling:
assert exc_info.value.user_action.kind is expected_user_action_kind
assert exc_info.value.__cause__ is sdk_exc
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_category(self, mocker: MockerFixture) -> None:
"""The category stays on the chain, and the problem takes the retry verdict of the code it gives."""
worker = _make_hf_img_gen_worker(mocker)
diff --git a/tests/unit/pipelex/providers/linkup/test_linkup_worker_error_handling.py b/tests/unit/pipelex/providers/linkup/test_linkup_worker_error_handling.py
index 93dd31e1b..5b3d604de 100644
--- a/tests/unit/pipelex/providers/linkup/test_linkup_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/linkup/test_linkup_worker_error_handling.py
@@ -177,6 +177,9 @@ class TestLinkupWorkerErrorHandling:
# ---- Problem tests ----
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_extract_problem_for_auth(self, mocker: MockerFixture) -> None:
"""An authentication error is a CONFIGURATION failure, and its problem invites no retry."""
worker = _make_linkup_extract_worker(mocker)
@@ -192,6 +195,9 @@ class TestLinkupWorkerErrorHandling:
assert problem.is_retryable is False
assert _diagnostics_of(problem).error_class == "ExtractJobFailureError"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_search_problem_for_rate_limit(self, mocker: MockerFixture) -> None:
"""A rate limit error is a TRANSIENT failure, and its problem invites a retry."""
worker = _make_linkup_search_worker(mocker)
@@ -206,6 +212,9 @@ class TestLinkupWorkerErrorHandling:
assert find_inference_error_category_in_chain(error) == "transient"
assert problem.is_retryable is True
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_search_problem_for_no_result(self, mocker: MockerFixture) -> None:
"""A no-result error is a CONTENT failure, and its problem invites no retry."""
worker = _make_linkup_search_worker(mocker)
@@ -220,6 +229,9 @@ class TestLinkupWorkerErrorHandling:
assert find_inference_error_category_in_chain(error) == "content"
assert problem.is_retryable is False
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_extract_problem_for_no_result(self, mocker: MockerFixture) -> None:
"""A no-result error is a CONTENT failure, and its problem invites no retry."""
worker = _make_linkup_extract_worker(mocker)
diff --git a/tests/unit/pipelex/providers/mistral/test_mistral_worker_error_handling.py b/tests/unit/pipelex/providers/mistral/test_mistral_worker_error_handling.py
index d78c40e1b..5485a9078 100644
--- a/tests/unit/pipelex/providers/mistral/test_mistral_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/mistral/test_mistral_worker_error_handling.py
@@ -253,6 +253,9 @@ class TestMistralWorkerErrorHandling:
# ---- Problem integration ----
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_llm_problem_transient_is_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a TRANSIENT LLM error invites a retry."""
worker = _make_mistral_llm_worker(mocker)
@@ -268,6 +271,9 @@ class TestMistralWorkerErrorHandling:
assert problem.is_retryable is True
assert _diagnostics_of(problem).error_class == "LLMCompletionError"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_llm_problem_capacity_not_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a CAPACITY LLM error invites no retry."""
worker = _make_mistral_llm_worker(mocker)
@@ -282,6 +288,9 @@ class TestMistralWorkerErrorHandling:
assert find_inference_error_category_in_chain(error) == "capacity"
assert problem.is_retryable is False
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_extract_problem_includes_category(self, mocker: MockerFixture) -> None:
"""An extract error keeps its category on the chain."""
worker = _make_mistral_extract_worker(mocker)
diff --git a/tests/unit/pipelex/providers/openai/test_openai_completions_retries_kept.py b/tests/unit/pipelex/providers/openai/test_openai_completions_retries_kept.py
index cb669e2a7..d6f51711f 100644
--- a/tests/unit/pipelex/providers/openai/test_openai_completions_retries_kept.py
+++ b/tests/unit/pipelex/providers/openai/test_openai_completions_retries_kept.py
@@ -68,6 +68,9 @@ class TestOpenAICompletionsRetriesKept:
assert create.await_count == 3
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_a_rate_limited_text_call_stays_retryable(self, mocker: MockerFixture) -> None:
"""A provider failure on the text path is classified as before, its retryable category untouched by the stop check."""
worker, create = make_worker(mocker, thinking_mode=ThinkingMode.NONE, response=text_completion())
diff --git a/tests/unit/pipelex/providers/openai/test_openai_img_gen_worker_error_handling.py b/tests/unit/pipelex/providers/openai/test_openai_img_gen_worker_error_handling.py
index 3e9da9af2..dd10b1e6a 100644
--- a/tests/unit/pipelex/providers/openai/test_openai_img_gen_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/openai/test_openai_img_gen_worker_error_handling.py
@@ -293,6 +293,9 @@ class TestOpenAIImgGenWorkerErrorHandling:
assert exc_info.value.provider_metadata.status_code == 404
assert exc_info.value.model_handle == "gpt-image-1"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_provider_metadata(self, mocker: MockerFixture) -> None:
worker = _make_openai_img_gen_worker(mocker)
sdk_exc = openai.RateLimitError(
diff --git a/tests/unit/pipelex/providers/openai/test_openai_worker_error_handling.py b/tests/unit/pipelex/providers/openai/test_openai_worker_error_handling.py
index 549de1d7c..50b2444f4 100644
--- a/tests/unit/pipelex/providers/openai/test_openai_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/openai/test_openai_worker_error_handling.py
@@ -387,6 +387,9 @@ class TestOpenAIWorkerErrorHandling:
# ---- Problem integration ----
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_includes_category_and_retryable(self, mocker: MockerFixture) -> None:
"""The category stays on the chain, and the problem takes the retry verdict of the code it gives."""
worker = _make_completions_llm_worker(mocker)
@@ -402,6 +405,9 @@ class TestOpenAIWorkerErrorHandling:
assert problem.is_retryable is True
assert _diagnostics_of(problem).error_class == "LLMCompletionError"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="calls the worker below its public method, whose enrichment names the model and the provider"
+ )
async def test_problem_capacity_not_retryable(self, mocker: MockerFixture) -> None:
"""The problem of a CAPACITY error invites no retry."""
worker = _make_completions_llm_worker(mocker)
diff --git a/tests/unit/pipelex/providers/pypdfium2/test_pypdfium2_worker_error_handling.py b/tests/unit/pipelex/providers/pypdfium2/test_pypdfium2_worker_error_handling.py
index 0bb541d7f..6ba740a72 100644
--- a/tests/unit/pipelex/providers/pypdfium2/test_pypdfium2_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/pypdfium2/test_pypdfium2_worker_error_handling.py
@@ -89,6 +89,7 @@ class TestPypdfium2WorkerErrorHandling:
assert exc_info.value.user_action is not None
assert exc_info.value.user_action.kind is expected_user_action_kind
+ @pytest.mark.builds_problems_without_required_params(reason="an extract worker reads its source by URI and never learns the input it came from")
async def test_problem_for_file_not_found(self, mocker: MockerFixture) -> None:
"""A FileNotFoundError is a CONTENT failure, and its problem invites no retry."""
worker = _make_pypdfium2_worker(mocker)
diff --git a/tests/unit/pipelex/providers/test_context_window_refusals.py b/tests/unit/pipelex/providers/test_context_window_refusals.py
index 1f449f86e..dde6a8615 100644
--- a/tests/unit/pipelex/providers/test_context_window_refusals.py
+++ b/tests/unit/pipelex/providers/test_context_window_refusals.py
@@ -450,6 +450,9 @@ class TestContextWindowRefusals:
assert rendered.user_action is not None
assert "context window" not in rendered.user_action.detail
+ @pytest.mark.builds_problems_without_required_params(
+ reason="a provider's context-window refusal carries neither the prompt's size nor the window's, the counts of model.context_exceeded"
+ )
@pytest.mark.asyncio
async def test_the_worker_reports_the_prompt_over_the_window_as_the_callers_input(self, mocker: MockerFixture) -> None:
"""End to end through a worker: the run report reads `model.context_exceeded`, the caller's to fix, answered 422."""
@@ -476,6 +479,8 @@ class TestContextWindowRefusals:
caller = exc_info.value.to_problem(view=ProblemView.CALLER)
assert caller.code == CoreCode.MODEL_CONTEXT_EXCEEDED
+ # The refusal names the bound the prompt passed and the model, never the counts the provider words alone.
+ assert caller.to_wire()["params"] == {"model": "gpt-4o", "limit": "context_window"}
assert caller.domain == ProblemDomain.INPUT
assert caller.retry == RetryVerdict.NO
assert error_code_spec(CoreCode.MODEL_CONTEXT_EXCEEDED).status == 422
diff --git a/tests/unit/pipelex/test_pipelex_error_message_init.py b/tests/unit/pipelex/test_pipelex_error_message_init.py
index 7da9066c6..b2e86473a 100644
--- a/tests/unit/pipelex/test_pipelex_error_message_init.py
+++ b/tests/unit/pipelex/test_pipelex_error_message_init.py
@@ -31,6 +31,7 @@ class TestPipelexErrorMessageInit:
offenders.append(f"{error_cls.__module__}.{error_cls.__name__} (lists {shadow_cls.__name__} before PipelexError)")
assert not offenders, "Exception classes shadow PipelexError.__init__ — `.message` will be unset:\n" + "\n".join(offenders)
+ @pytest.mark.builds_problems_without_required_params(reason="builds the error with a message alone, to check how its message is set")
@pytest.mark.parametrize("error_cls", [ConstructFieldBlueprintValueError, RoutingProfileBlueprintValueError])
def test_message_set_and_problem_succeeds(self, error_cls: type[PipelexError]) -> None:
"""A reordered ``(PipelexError, ValueError)`` mixin sets ``.message``, keeps its
diff --git a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_failure_text.py b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_failure_text.py
index 122cf783d..ee60ad66e 100644
--- a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_failure_text.py
+++ b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_failure_text.py
@@ -1,13 +1,14 @@
from __future__ import annotations
import json
-from typing import TYPE_CHECKING, Any
+from typing import Any
import pytest
+from mthds.protocol.problem.registry import CoreCode
from pydantic import BaseModel
+from pipelex.base_exceptions import PipelexError
from pipelex.errors.problem import ProblemView
-from pipelex.system.exceptions import ToolError
from pipelex.tools.jinja2.exceptions import (
Jinja2TemplateBudgetError,
Jinja2TemplateInvalidError,
@@ -15,14 +16,11 @@ from pipelex.tools.jinja2.exceptions import (
Jinja2TemplateSecurityError,
)
from pipelex.tools.jinja2.jinja2_render_budget import DEFAULT_RENDER_BUDGET_UNITS
-from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async, render_jinja2_sync
+from pipelex.tools.jinja2.jinja2_rendering import locating_template_refusal, render_jinja2_async, render_jinja2_sync
from pipelex.tools.jinja2.template_category import TemplateCategory
from pipelex.tools.jinja2.template_owner import TemplateOwner
from pipelex.tools.jinja2.template_surface import TemplateSurface
-if TYPE_CHECKING:
- from pipelex.base_exceptions import PipelexError
-
# A value of the run's data, which no message, parameter or diagnostic carries.
_PAYLOAD = "confidential-patient-diagnosis"
# The same value as an identifier, which a template can also write as plain text.
@@ -44,6 +42,11 @@ class _Chart:
return range(10**12)
+# A format string nesting replacement fields in their format specs far deeper than any formatter reads, which a template
+# writes in a `.format` call it never reaches.
+_DEEPLY_NESTED_FORMAT_FIELDS = "{0:" * 1100 + "x" + "}" * 1100
+
+
# How the budget words a refusal, up to the call it refused.
_BUDGET_REFUSAL_PREFIX = (
f"Jinja2 render — refused by the render budget: Rendering the template would spend more than its budget of {DEFAULT_RENDER_BUDGET_UNITS:,} "
@@ -54,10 +57,10 @@ _BUDGET_REFUSAL_PREFIX = (
async def _render_failure(*, template_source: str, context: dict[str, Any], is_async: bool) -> PipelexError:
"""The error rendering `template_source` raises, through the synchronous or the asynchronous render.
- A refusal of the sandbox is a `SecurityError`, every other render failure a `ToolError`.
+ A `ToolError`, or for a refusal of the sandbox `Jinja2TemplateSecurityError`, which is a `SecurityError`.
"""
if is_async:
- with pytest.raises((ToolError, Jinja2TemplateSecurityError)) as async_exc_info:
+ with pytest.raises(PipelexError) as async_exc_info:
await render_jinja2_async(
template_source=template_source,
template_category=TemplateCategory.BASIC,
@@ -65,7 +68,7 @@ async def _render_failure(*, template_source: str, context: dict[str, Any], is_a
template_owner=TemplateOwner.METHOD,
)
return async_exc_info.value
- with pytest.raises((ToolError, Jinja2TemplateSecurityError)) as sync_exc_info:
+ with pytest.raises(PipelexError) as sync_exc_info:
render_jinja2_sync(
template_source=template_source,
template_category=TemplateCategory.BASIC,
@@ -75,6 +78,7 @@ async def _render_failure(*, template_source: str, context: dict[str, Any], is_a
return sync_exc_info.value
[email protected]_problems_without_required_params(reason="renders outside any pipe, whose failure location names the pipe")
@pytest.mark.asyncio(loop_scope="class")
class TestJinja2RenderFailureText:
@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])
@@ -119,6 +123,20 @@ class TestJinja2RenderFailureText:
Jinja2TemplateSecurityError,
"Jinja2 render — refused by the template sandbox: A template may not read an unsafe name on a 'object' value.",
),
+ (
+ "a private name read by a key a string literal of the expressions also holds, which no access reads",
+ f"{{% if lookup == 'debug _{_PAYLOAD_IDENTIFIER}' %}}debug{{% endif %}}{{{{ record[lookup] }}}}",
+ {"record": object(), "lookup": f"_{_PAYLOAD_IDENTIFIER}"},
+ Jinja2TemplateSecurityError,
+ "Jinja2 render — refused by the template sandbox: A template may not read an unsafe name on a 'object' value.",
+ ),
+ (
+ "a private name read by a key of the data inside a format call's argument, which a literal the call does not format writes",
+ f"{{{{ 'x'.format(record[lookup]) }}}}{{{{ '_{_PAYLOAD_IDENTIFIER}' }}}}",
+ {"record": object(), "lookup": f"_{_PAYLOAD_IDENTIFIER}"},
+ Jinja2TemplateSecurityError,
+ "Jinja2 render — refused by the template sandbox: A template may not read an unsafe name on a 'object' value.",
+ ),
(
"a callable stored in a namespace under a key of the data",
"{% set ns = namespace({lookup: record.count}) %}{{ ns }}",
@@ -173,6 +191,13 @@ class TestJinja2RenderFailureText:
assert isinstance(error, expected_error), topic
assert str(error) == expected_message, topic
assert "confidential" not in json.dumps(error.to_problem(view=ProblemView.OPERATOR).to_wire()), topic
+ assert "confidential" not in json.dumps(error.to_problem(view=ProblemView.CALLER).to_wire()), topic
+ if isinstance(error, Jinja2TemplateSecurityError):
+ # The refused name is the data's, so the problem withholds it rather than pass it on as `name`.
+ assert error.refused_name is None, topic
+ caller = error.to_problem(view=ProblemView.CALLER)
+ assert caller.params is not None, topic
+ assert "name" not in caller.params.as_wire(), topic
@pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])
@pytest.mark.parametrize(
@@ -196,6 +221,18 @@ class TestJinja2RenderFailureText:
{"record": object()},
"Jinja2 render — refused by the template sandbox: A template may not read '_secret' on a 'object' value.",
),
+ (
+ "a private name a format string reads, the string a format call formats",
+ "{{ '{0._secret}'.format(record) }}",
+ {"record": object()},
+ "Jinja2 render — refused by the template sandbox: A template may not read '_secret' on a 'object' value.",
+ ),
+ (
+ "a private name a format string reads, the string a format_map call formats",
+ "{{ '{r._secret}'.format_map({'r': record}) }}",
+ {"record": object()},
+ "Jinja2 render — refused by the template sandbox: A template may not read '_secret' on a 'object' value.",
+ ),
(
"a callable stored in a namespace under a name the template spells",
"{% set ns = namespace(helper=record.count) %}{{ ns }}",
@@ -259,3 +296,54 @@ class TestJinja2RenderFailureText:
assert isinstance(error, Jinja2TemplateBudgetError)
assert str(error).startswith(f"{_BUDGET_REFUSAL_PREFIX}calling the method '{_PAYLOAD_IDENTIFIER}' of a '_Chart' value needs about ")
+
+ @pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])
+ @pytest.mark.parametrize(
+ ("topic", "template_source", "context", "expected_params"),
+ [
+ (
+ "a private name the template writes as a literal key, beside a format string nested too deep to read",
+ f"{{{{ record['_secret'] }}}}{{% if false %}}{{{{ '{_DEEPLY_NESTED_FORMAT_FIELDS}'.format(record) }}}}{{% endif %}}",
+ {"record": object()},
+ {"name": "_secret"},
+ ),
+ (
+ "a private name of the data, which only a format string nested too deep to read writes",
+ f"{{{{ record[lookup] }}}}{{% if false %}}{{{{ '{{0._secret:{_DEEPLY_NESTED_FORMAT_FIELDS}}}'.format(record) }}}}{{% endif %}}",
+ {"record": object(), "lookup": "_secret"},
+ {},
+ ),
+ ],
+ )
+ async def test_a_format_string_nested_too_deep_to_read_leaves_the_refusal_itself(
+ self, topic: str, template_source: str, context: dict[str, Any], expected_params: dict[str, Any], is_async: bool
+ ) -> None:
+ """Building the refusal reads the template's format strings, which a deeply nested one must not turn into another failure.
+
+ The scan stops past the depth any formatter reads and counts nothing from that literal, so a name only it writes
+ is withheld, and the sandbox's refusal comes out as itself, located on its template field.
+ """
+ if is_async:
+ with pytest.raises(Jinja2TemplateSecurityError) as async_exc_info, locating_template_refusal(template_field="template"):
+ await render_jinja2_async(
+ template_source=template_source,
+ template_category=TemplateCategory.BASIC,
+ templating_context=context,
+ template_owner=TemplateOwner.METHOD,
+ )
+ error = async_exc_info.value
+ else:
+ with pytest.raises(Jinja2TemplateSecurityError) as sync_exc_info, locating_template_refusal(template_field="template"):
+ render_jinja2_sync(
+ template_source=template_source,
+ template_category=TemplateCategory.BASIC,
+ templating_context=context,
+ template_owner=TemplateOwner.METHOD,
+ )
+ error = sync_exc_info.value
+
+ caller = error.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED, topic
+ assert caller.location is not None, topic
+ assert caller.location.as_wire() == {"field": "template"}, topic
+ assert (caller.params.as_wire() if caller.params is not None else {}) == expected_params, topic
diff --git a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py
index f22114057..86df362e4 100644
--- a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py
+++ b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py
@@ -3,10 +3,10 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
import pytest
-from mthds.protocol.problem.registry import CoreCode, ProblemDomain
+from mthds.protocol.problem.registry import CoreCode, MethodNameConflictConflict, ProblemDomain
from pipelex.base_exceptions import PipelexError
-from pipelex.errors.problem import ProblemView
+from pipelex.errors.problem import UNDECLARED_PARAM_MESSAGE, ProblemView
from pipelex.tools.jinja2.exceptions import (
Jinja2StuffError,
Jinja2TemplateBudgetError,
@@ -57,6 +57,9 @@ async def _render_failure(
class TestJinja2RenderOwner:
+ @pytest.mark.builds_problems_without_required_params(
+ reason="renders outside any pipe, whose failure location names the pipe; the render does not know which field of the pipe the template is"
+ )
@pytest.mark.parametrize(
("template_source", "fault"),
[
@@ -99,6 +102,10 @@ class TestJinja2RenderOwner:
assert operator.diagnostics is not None
assert "frob_the_lane" in operator.diagnostics.message
+ @pytest.mark.builds_problems_without_required_params(
+ reason="renders outside any pipe, whose failure location names the pipe; the render knows neither the template's field nor the budget "
+ "operation's kind nor the input a Pipelex template displays"
+ )
@pytest.mark.parametrize(
("topic", "template_source", "context", "is_undefined_strict", "error_class", "method_code", "pipelex_code"),
[
@@ -194,6 +201,31 @@ class TestJinja2RenderOwner:
assert error.to_problem(view=ProblemView.CALLER).code == expected_code, f"{topic} on a {template_owner} template"
assert template_source not in error.message, f"{topic} on a {template_owner} template"
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_a_method_variable_named_like_a_reserved_key_is_a_name_conflict_naming_it(self) -> None:
+ error = await _render_failure(
+ "{{ lane }}", template_owner=TemplateOwner.METHOD, context={"lane": "express", Jinja2ContextKey.TAG_STYLE: "taken"}
+ )
+
+ caller = error.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.METHOD_NAME_CONFLICT
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"name": Jinja2ContextKey.TAG_STYLE, "conflict": MethodNameConflictConflict.DUPLICATE_DECLARATION}
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_a_reserved_key_on_a_pipelex_template_gives_no_parameter_its_code_lacks(self, caplog: pytest.LogCaptureFixture) -> None:
+ error = await _render_failure(
+ "{{ lane }}", template_owner=TemplateOwner.PIPELEX, context={"lane": "express", Jinja2ContextKey.TAG_STYLE: "taken"}
+ )
+
+ operator = error.to_problem(view=ProblemView.OPERATOR)
+
+ assert operator.code == CoreCode.RUNTIME_UNEXPECTED
+ assert [record for record in caplog.records if record.getMessage() == UNDECLARED_PARAM_MESSAGE] == []
+
+ @pytest.mark.builds_problems_without_required_params(
+ reason="renders outside any pipe, whose failure location names the pipe; the render does not know which field of the pipe the template is"
+ )
def test_the_sync_render_is_coded_alike(self) -> None:
with pytest.raises(Jinja2TemplateInvalidError) as exc_info:
render_jinja2_sync(
diff --git a/tests/unit/pipelex/tools/misc/test_close_matches.py b/tests/unit/pipelex/tools/misc/test_close_matches.py
new file mode 100644
index 000000000..85ee9cbc2
--- /dev/null
+++ b/tests/unit/pipelex/tools/misc/test_close_matches.py
@@ -0,0 +1,20 @@
+import pytest
+
+from pipelex.tools.misc.string_utils import close_matches
+
+
+class TestCloseMatches:
+ @pytest.mark.parametrize(
+ ("cutoff", "max_matches", "expected"),
+ [
+ pytest.param(0.6, 5, ["summarize_text", "summarize_texts"], id="a_lenient_cutoff_offers_both_near_names"),
+ pytest.param(0.99, 5, [], id="a_strict_cutoff_offers_none"),
+ pytest.param(0.6, 1, ["summarize_text"], id="the_count_keeps_the_nearest"),
+ ],
+ )
+ def test_the_cutoff_and_the_count_decide_what_is_offered(self, cutoff: float, max_matches: int, expected: list[str]) -> None:
+ offered = close_matches(
+ name="sumarize_text", candidates=("summarize_text", "summarize_texts", "translate"), cutoff=cutoff, max_matches=max_matches
+ )
+
+ assert offered == expected
diff --git a/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py b/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py
index 9a8ea6626..d6bf157de 100644
--- a/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py
+++ b/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py
@@ -30,11 +30,14 @@ class TestFetchFileFromUrl:
raw_bytes = await fetch_file_from_url_httpx(url=URL, transport=_transport_answering(200, b"%PDF-1.4"))
assert raw_bytes == b"%PDF-1.4"
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the URL fetch knows neither the input the URL came from nor the kind of file its caller wants"
+ )
@pytest.mark.parametrize(
("status_code", "expected_code", "expected_params"),
[
- (404, CoreCode.INPUT_FILE_UNREADABLE, {}),
- (403, CoreCode.INPUT_FILE_UNREADABLE, {}),
+ (404, CoreCode.INPUT_FILE_UNREADABLE, {"reason": "the server answered HTTP 404"}),
+ (403, CoreCode.INPUT_FILE_UNREADABLE, {"reason": "the server answered HTTP 403"}),
(429, CoreCode.INPUT_URL_UNREACHABLE, {"host": "example.com"}),
(500, CoreCode.INPUT_URL_UNREACHABLE, {"host": "example.com"}),
(503, CoreCode.INPUT_URL_UNREACHABLE, {"host": "example.com"}),
@@ -43,8 +46,9 @@ class TestFetchFileFromUrl:
async def test_error_status_raises_an_input_error(self, status_code: int, expected_code: CoreCode, expected_params: dict[str, str]) -> None:
"""A 4xx/5xx becomes an input error, whose message names the status and never the URL, the run's data.
- A server that will not serve the file is ``input.file_unreadable``; one that cannot answer now, a 5xx or a
- 429, is ``input.url_unreachable``, which a retry may get past and which takes the URL's host as its parameter.
+ A server that will not serve the file is ``input.file_unreadable``, which takes what the server answered as its
+ ``reason``; one that cannot answer now, a 5xx or a 429, is ``input.url_unreachable``, which a retry may get past
+ and which takes the URL's host as its parameter.
"""
with pytest.raises(RemoteFileFetchError) as exc_info:
await fetch_file_from_url_httpx(url=URL, transport=_transport_answering(status_code))
@@ -54,6 +58,9 @@ class TestFetchFileFromUrl:
assert caller.code == expected_code
assert caller.domain == ProblemDomain.INPUT
assert caller.is_retryable is error_code_spec(expected_code).invites_retry
+ # The fetch names what it knows, the URL's host or why the file could not be read; its caller knows the input.
+ assert caller.params is not None
+ assert caller.params.as_wire() == expected_params
operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)
assert operator.diagnostics is not None
assert f"HTTP {status_code}" in operator.diagnostics.message
@@ -73,6 +80,9 @@ class TestFetchFileFromUrl:
await fetch_file_from_url_httpx(url=URL, transport=_transport_raising(exc))
assert exc_info.value.resolve_error_code() == expected_code
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the URL fetch knows neither the input the URL came from nor the kind of file its caller wants"
+ )
async def test_a_url_that_does_not_parse_is_refused_without_quoting_it(self) -> None:
"""Httpx refuses the URL while it builds the request, with a text quoting the part it refused, the run's data."""
unparsable_url = "https://example.com:confidential-patient-diagnosis/report.pdf"
@@ -82,8 +92,14 @@ class TestFetchFileFromUrl:
assert exc_info.value.resolve_error_code() == CoreCode.INPUT_FILE_UNREADABLE
assert "confidential" not in exc_info.value.message
- assert "confidential" not in json.dumps(exc_info.value.to_problem(view=ProblemView.OPERATOR).to_wire())
+ operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)
+ assert "confidential" not in json.dumps(operator.to_wire())
+ assert operator.params is not None
+ assert operator.params.as_wire() == {"reason": "the URL does not parse"}
+ @pytest.mark.builds_problems_without_required_params(
+ reason="re-codes a fetch failure by hand, without the provider and the defect a provider's catch site names"
+ )
async def test_the_host_reaches_only_a_code_that_declares_it(self, caplog: pytest.LogCaptureFixture) -> None:
"""A catch site that re-codes the failure, as a provider's file does, gives its code no parameter it would refuse.
@@ -98,9 +114,76 @@ class TestFetchFileFromUrl:
operator = recoded.to_problem(view=ProblemView.OPERATOR)
assert operator.code == CoreCode.PROVIDER_RESPONSE_INVALID
- assert operator.params is None
+ assert (operator.params.as_wire() if operator.params is not None else {}) == {}
assert [record.getMessage() for record in caplog.records if "does not declare" in record.getMessage()] == []
+ @pytest.mark.builds_problems_without_required_params(
+ reason="the URL fetch knows neither the input the URL came from nor the kind of file its caller wants"
+ )
+ @pytest.mark.parametrize(
+ ("transport", "expected_code", "expected_message", "expected_params"),
+ [
+ pytest.param(
+ _transport_answering(404),
+ CoreCode.INPUT_FILE_UNREADABLE,
+ "Could not fetch a remote file: the server answered HTTP 404",
+ {"reason": "the server answered HTTP 404"},
+ id="status",
+ ),
+ pytest.param(
+ _transport_answering(503),
+ CoreCode.INPUT_URL_UNREACHABLE,
+ "Could not fetch a remote file: the server answered HTTP 503",
+ {"host": "files.example.com"},
+ id="transient-status",
+ ),
+ pytest.param(
+ _transport_raising(httpx.ConnectError("boom")),
+ CoreCode.INPUT_URL_UNREACHABLE,
+ "Could not fetch a remote file: the host could not be reached",
+ {"host": "files.example.com"},
+ id="connect",
+ ),
+ pytest.param(
+ _transport_raising(httpx.ReadTimeout("slow")),
+ CoreCode.INPUT_URL_UNREACHABLE,
+ "Could not fetch a remote file: the request timed out",
+ {"host": "files.example.com"},
+ id="timeout",
+ ),
+ pytest.param(
+ _transport_raising(httpx.RemoteProtocolError("bad")),
+ CoreCode.INPUT_FILE_UNREADABLE,
+ "Could not fetch a remote file: the request failed (RemoteProtocolError)",
+ {"reason": "the request failed (RemoteProtocolError)"},
+ id="protocol",
+ ),
+ ],
+ )
+ async def test_no_message_names_the_url_and_the_facts_ride_as_parameters(
+ self, transport: httpx.MockTransport, expected_code: CoreCode, expected_message: str, expected_params: dict[str, str]
+ ) -> None:
+ """Every failure's message says what the server or the network answered and never the URL, a signed link's token included.
+
+ The host and the reason are facts the error holds, each given as a parameter to the code that declares it.
+ """
+ signed_url = "https://files.example.com/reports/confidential-patient-diagnosis.pdf?token=secret-token-4471"
+
+ with pytest.raises(RemoteFileFetchError) as exc_info:
+ await fetch_file_from_url_httpx(url=signed_url, transport=transport)
+
+ error = exc_info.value
+ assert error.resolve_error_code() == expected_code
+ assert error.message == expected_message
+ operator = error.to_problem(view=ProblemView.OPERATOR)
+ caller = error.to_problem(view=ProblemView.CALLER)
+ for wire in (json.dumps(operator.to_wire()), json.dumps(caller.to_wire())):
+ assert "confidential" not in wire
+ assert "secret-token" not in wire
+ assert "/reports/" not in wire
+ assert caller.params is not None
+ assert caller.params.as_wire() == expected_params
+
async def test_the_input_a_catch_site_names_completes_the_sentence(self) -> None:
"""`input.url_unreachable` names the input and the host, which its detail and its steps read."""
with pytest.raises(RemoteFileFetchError) as exc_info:
diff --git a/tests/unit/pipelex/tools/network/test_ssrf_guard.py b/tests/unit/pipelex/tools/network/test_ssrf_guard.py
index 9e0f94e49..bfc9e1047 100644
--- a/tests/unit/pipelex/tools/network/test_ssrf_guard.py
+++ b/tests/unit/pipelex/tools/network/test_ssrf_guard.py
@@ -42,10 +42,10 @@ class TestSsrfGuard:
mocker.patch("socket.getaddrinfo", side_effect=fake)
with pytest.raises(SsrfBlockedError) as exc_info:
await resolve_to_allowed_ips("attacker.example", port=80)
- # The host is part of a URL the runtime did not choose, a run's input or a caller's callback: no message names it.
- assert "attacker.example" not in str(exc_info.value)
- # The refusal states the class of what the name resolved to, for its security event, and its message never names the address.
+ # The refusal states the class of what the name resolved to, for its security event. The host is part of a URL the
+ # runtime did not choose, a run's input or a caller's callback, so no message names it, nor the address.
assert exc_info.value.security_target_class == SecurityTargetClass.METADATA
+ assert "attacker.example" not in str(exc_info.value)
assert "169.254.169.254" not in str(exc_info.value)
@pytest.mark.parametrize(
@@ -59,7 +59,8 @@ class TestSsrfGuard:
],
)
async def test_resolve_blocks_literal_private_host(self, host: str, target_class: SecurityTargetClass) -> None:
- # A literal private IP never needs resolution — blocked by the cheap rule, and classified for the security event.
+ # A literal private IP never needs resolution — blocked by the cheap rule, classified for the security event, and
+ # never named by the refusal's message.
with pytest.raises(SsrfBlockedError) as exc_info:
await resolve_to_allowed_ips(host, port=80)
assert exc_info.value.security_target_class == target_class
diff --git a/tests/unit/pipelex/tools/storage/test_gcp_storage_provider.py b/tests/unit/pipelex/tools/storage/test_gcp_storage_provider.py
index c91e3f9e9..7dcd65a6a 100644
--- a/tests/unit/pipelex/tools/storage/test_gcp_storage_provider.py
+++ b/tests/unit/pipelex/tools/storage/test_gcp_storage_provider.py
@@ -5,6 +5,7 @@ from typing import Any
import pytest
from pytest_mock import MockerFixture
+from pipelex.errors.problem import ProblemView
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.tools.storage.exceptions import (
StorageFileNotFoundError,
@@ -166,6 +167,10 @@ class TestGcpStorageProvider:
await gcp_provider_no_signed_urls.load(uri=nonexistent_uri)
assert "nonexistent/file.bin" in str(exc_info.value)
+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert problem.code == PipelexErrorCode.STORAGE_NOT_FOUND
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"scheme": "gcs"}
@pytest.mark.parametrize(
("failure_name", "expected_code"),
diff --git a/tests/unit/pipelex/tools/storage/test_s3_storage_provider.py b/tests/unit/pipelex/tools/storage/test_s3_storage_provider.py
index 497e7fe25..ad226c813 100644
--- a/tests/unit/pipelex/tools/storage/test_s3_storage_provider.py
+++ b/tests/unit/pipelex/tools/storage/test_s3_storage_provider.py
@@ -6,6 +6,7 @@ import pytest
from botocore.exceptions import BotoCoreError, ClientError, EndpointConnectionError, NoCredentialsError, ReadTimeoutError
from pytest_mock import MockerFixture
+from pipelex.errors.problem import ProblemView
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.tools.storage.exceptions import StorageFileNotFoundError, StorageInvalidKeyError, StorageS3Error
from pipelex.tools.storage.s3_storage_provider import CONDITIONAL_CONFLICT_RETRY_DELAYS_SECONDS, S3StorageProvider, checksum_sha256_header_value
@@ -148,6 +149,10 @@ class TestS3StorageProvider:
await s3_provider_no_signed_urls.load(uri=nonexistent_uri)
assert "nonexistent/file.bin" in str(exc_info.value)
+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert problem.code == PipelexErrorCode.STORAGE_NOT_FOUND
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"scheme": "s3"}
async def test_store_raises_if_key_has_scheme_prefix(
self,
diff --git a/tests/unit/pipelex/tools/storage/test_storage_load_size.py b/tests/unit/pipelex/tools/storage/test_storage_load_size.py
index b6dcf5f77..c7af6a120 100644
--- a/tests/unit/pipelex/tools/storage/test_storage_load_size.py
+++ b/tests/unit/pipelex/tools/storage/test_storage_load_size.py
@@ -10,6 +10,8 @@ import pytest
from pytest_mock import MockerFixture
from typing_extensions import override
+from pipelex.errors.problem import ProblemView
+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.tools.storage.exceptions import StorageFileNotFoundError, StorageLocalError
from pipelex.tools.storage.in_memory_storage_provider import InMemoryStorageProvider
from pipelex.tools.storage.local_storage_provider import LocalStorageProvider
@@ -53,6 +55,20 @@ class TestStorageLoadSize:
with pytest.raises(StorageFileNotFoundError):
await provider.load_size(uri=f"{PIPELEX_STORAGE_SCHEME}missing/file.pdf")
+ async def test_a_missing_object_names_the_kind_of_storage_that_lost_it(self, tmp_path: Path) -> None:
+ """The refusal of a provider Pipelex ships names its kind, the `scheme` of `pipelex.storage.not_found`."""
+ for provider, expected_kind in [(InMemoryStorageProvider(), "memory"), (LocalStorageProvider(root_path=tmp_path), "local")]:
+ for read in (
+ provider.load(uri=f"{PIPELEX_STORAGE_SCHEME}missing/file.pdf"),
+ provider.load_size(uri=f"{PIPELEX_STORAGE_SCHEME}missing/file.pdf"),
+ ):
+ with pytest.raises(StorageFileNotFoundError) as raised:
+ await read
+ problem = raised.value.to_problem(view=ProblemView.CALLER)
+ assert problem.code == PipelexErrorCode.STORAGE_NOT_FOUND
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"scheme": expected_kind}
+
async def test_the_local_size_is_read_without_opening_the_file(self, tmp_path: Path, mocker: MockerFixture) -> None:
provider = LocalStorageProvider(root_path=tmp_path)
uri = await provider.store(data=PAYLOAD, key="size/file.pdf")
diff --git a/tests/unit/pipelex/tools/test_jinja2_render_budget.py b/tests/unit/pipelex/tools/test_jinja2_render_budget.py
index c0ede6d6b..5c3e3d6d4 100644
--- a/tests/unit/pipelex/tools/test_jinja2_render_budget.py
+++ b/tests/unit/pipelex/tools/test_jinja2_render_budget.py
@@ -602,6 +602,10 @@ class TestRenderBudget:
text = "word " * 2400
assert _render("{{ doc | striptags }}", doc=_text_content(text)) == _render("{{ text | striptags }}", text=text)
+ @pytest.mark.builds_problems_without_required_params(
+ reason="renders outside any pipe, whose failure location names the pipe; the render knows neither the budget operation's kind nor the input "
+ "a Pipelex template displays"
+ )
def test_budget_error_is_the_method_s_or_the_input_s(self) -> None:
"""A method's template past its budget is the method's to fix; a Pipelex template's, the caller's input."""
method_fault = Jinja2TemplateBudgetError("refused by the render budget").to_problem(view=ProblemView.CALLER)
diff --git a/tests/unit/pipelex/tools/test_jinja2_sandbox.py b/tests/unit/pipelex/tools/test_jinja2_sandbox.py
index 36b32516b..40daf8014 100644
--- a/tests/unit/pipelex/tools/test_jinja2_sandbox.py
+++ b/tests/unit/pipelex/tools/test_jinja2_sandbox.py
@@ -9,6 +9,7 @@ from enum import StrEnum
from typing import Any
import pytest
+from mthds.protocol.problem.registry import CoreCode
from pipelex.base_exceptions import SecurityError
from pipelex.core.concepts.concept_factory import ConceptFactory
@@ -27,6 +28,7 @@ from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async, render_jinja2_sync
from pipelex.tools.jinja2.template_category import TemplateCategory
+from pipelex.tools.jinja2.template_owner import TemplateOwner
from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
from pipelex.tools.templating.text_format import TextFormat
@@ -186,6 +188,94 @@ class TestTemplateSandbox:
with pytest.raises(Jinja2TemplateSecurityError, match=r"may not call the method 'model_copy' of a 'ImageContent' value"):
await _render("{{ photos[0].model_copy() }}")
+ @pytest.mark.builds_problems_without_required_params(reason="renders outside any pipe, whose failure location names the pipe")
+ @pytest.mark.parametrize(
+ ("_topic", "template_source", "refused_name"),
+ [
+ ("private_attribute", "{{ note._stuff }}", "_stuff"),
+ ("pydantic_method", "{{ photos[0].model_copy() }}", "model_copy"),
+ ("mutating_method", "{{ tags.intersection_update(['a']) }}", "intersection_update"),
+ ("callable_in_a_namespace", "{% set ns = namespace(hook=spy) %}", "spy"),
+ ],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_refusal_gives_the_refused_name_to_its_problem(self, _topic: str, template_source: str, refused_name: str) -> None:
+ """The caller reads what a method's template reached for as the `name` of `security.template_refused`, never the template."""
+ with pytest.raises(Jinja2TemplateSecurityError) as exc_info:
+ await render_jinja2_async(
+ template_source=template_source,
+ template_category=TemplateCategory.LLM_PROMPT,
+ templating_context=_make_context(),
+ templating_style=_TEMPLATING_STYLE,
+ template_owner=TemplateOwner.METHOD,
+ )
+
+ assert exc_info.value.refused_name == refused_name
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"name": refused_name}
+
+ @pytest.mark.parametrize(
+ ("_topic", "template_source", "data_value"),
+ [
+ ("private_attribute_by_key", "{{ note[note.text] }}", "_quokka_marmalade_4471"),
+ ("method_by_attr_filter", "{{ (photos[0] | attr(note.text))() }}", "model_copy"),
+ ("callable_in_a_namespace_by_key", "{% set ns = namespace({note.text: spy}) %}", "quokka_marmalade_4471"),
+ ],
+ )
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_a_refused_name_the_run_s_data_gave_reaches_no_reader(self, _topic: str, template_source: str, data_value: str) -> None:
+ """A template that looks the refused name up from the run's data gives no `name`, so the run's input reaches no view.
+
+ Its message, its problem in either view and the problem's sentences say what happened without the name: the
+ template looked a name up from the run's data, and the sandbox refused it.
+ """
+ context = _make_context()
+ context["note"] = _make_artefact(content=TextContent(text=data_value), name="note", concept_code=NativeConceptCode.TEXT)
+ with pytest.raises(Jinja2TemplateSecurityError) as exc_info:
+ await render_jinja2_async(
+ template_source=template_source,
+ template_category=TemplateCategory.LLM_PROMPT,
+ templating_context=context,
+ templating_style=_TEMPLATING_STYLE,
+ template_owner=TemplateOwner.METHOD,
+ )
+
+ error = exc_info.value.with_params(pipe="say")
+ assert error.refused_name is None
+ assert data_value not in error.message
+ operator = error.to_problem(view=ProblemView.OPERATOR)
+ caller = error.to_problem(view=ProblemView.CALLER)
+ for problem in (operator, caller):
+ assert problem.code == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert data_value not in str(problem.to_wire())
+ assert problem.params is not None
+ assert problem.params.as_wire() == {"pipe": "say"}
+ assert problem.detail == "A template of pipe 'say' looked a name up from the run's data, and the template sandbox refused that name."
+ assert caller.next_step.detail == (
+ "Change the templates of pipe 'say' so that the run's data no longer chooses the names they look up, then run the method again."
+ )
+
+ @pytest.mark.asyncio(loop_scope="class")
+ async def test_a_refused_name_the_template_spells_is_named_by_its_sentences(self) -> None:
+ """A name the template's own source writes is passed on as `name`, which the code's own sentences quote."""
+ with pytest.raises(Jinja2TemplateSecurityError) as exc_info:
+ await render_jinja2_async(
+ template_source="{{ note['_stuff'] }}",
+ template_category=TemplateCategory.LLM_PROMPT,
+ templating_context=_make_context(),
+ templating_style=_TEMPLATING_STYLE,
+ template_owner=TemplateOwner.METHOD,
+ )
+
+ caller = exc_info.value.with_params(pipe="say").to_problem(view=ProblemView.CALLER)
+
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"pipe": "say", "name": "_stuff"}
+ assert caller.detail == "A template of pipe 'say' reached for '_stuff', which the template sandbox forbids."
+ assert caller.next_step.detail == "Remove '_stuff' from the templates of pipe 'say', then run the method again."
+
@pytest.mark.asyncio(loop_scope="class")
async def test_refused_mutation_leaves_the_value_unchanged(self) -> None:
context = _make_context()
diff --git a/tests/unit/pipelex/tools/uri/test_uri_read_scope.py b/tests/unit/pipelex/tools/uri/test_uri_read_scope.py
index 3485d6fee..f4891bd62 100644
--- a/tests/unit/pipelex/tools/uri/test_uri_read_scope.py
+++ b/tests/unit/pipelex/tools/uri/test_uri_read_scope.py
@@ -139,9 +139,11 @@ class TestAuthorizeUriRead:
def test_the_refusal_is_an_input_error_answered_as_a_422_quoting_no_uri(self) -> None:
with pytest.raises(UriReadRefusedError) as exc_info:
- authorize_uri_read(uri="/etc/passwd", read_scope=READ_SCOPE, position="the input 'photo'")
+ authorize_uri_read(uri="/etc/passwd", read_scope=READ_SCOPE, position="the input 'photo'", input_name="photo")
caller = exc_info.value.to_problem(view=ProblemView.CALLER)
assert caller.code == CoreCode.SECURITY_INPUT_URL_REFUSED
+ assert caller.params is not None
+ assert caller.params.as_wire()["input"] == "photo"
assert caller.domain == ProblemDomain.INPUT
assert error_code_spec(CoreCode.SECURITY_INPUT_URL_REFUSED).status == 422
assert "/etc/passwd" not in str(caller.to_wire())
diff --git a/tests/unit/pipelex/tracing/test_assembler_equivalence.py b/tests/unit/pipelex/tracing/test_assembler_equivalence.py
index 187cb845a..b975567a3 100644
--- a/tests/unit/pipelex/tracing/test_assembler_equivalence.py
+++ b/tests/unit/pipelex/tracing/test_assembler_equivalence.py
@@ -754,6 +754,9 @@ def _scenario_dry_condition_merge(tracer: GraphTracer, context: TraceContext) ->
class TestAssemblerEquivalence:
"""Equivalence tests comparing GraphTracer teardown with GraphSpecAssembler."""
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
@pytest.mark.parametrize(
"scenario_fn",
[
diff --git a/tests/unit/pipelex/tracing/test_graphspec_assembler.py b/tests/unit/pipelex/tracing/test_graphspec_assembler.py
index 78f62b160..8017f57d0 100644
--- a/tests/unit/pipelex/tracing/test_graphspec_assembler.py
+++ b/tests/unit/pipelex/tracing/test_graphspec_assembler.py
@@ -716,6 +716,9 @@ class TestGraphSpecAssembler:
assert [node.node_id for node in result.nodes] == [outcome]
assert [edge for edge in result.edges if edge.kind == EdgeKind.SELECTED_OUTCOME] == []
+ @pytest.mark.builds_problems_without_required_params(
+ reason="builds an inference failure by hand, below the worker that names its model and provider"
+ )
def test_partial_failure(self) -> None:
"""Child fails with error, parent has no end event → FAILED + CANCELED."""
parent = _node_id(_WF_A, 0)