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/Raise-sites-without-content · L-261015-e9b07a (#1452)
Louis Choquela081134ae6eb
diff --git a/.drift/acks/logging-docs.toml b/.drift/acks/logging-docs.tomlindex e848a962f..d0252ecb4 100644--- a/.drift/acks/logging-docs.toml+++ b/.drift/acks/logging-docs.toml@@ -1,9 +1,10 @@contract = "logging-docs"-digest = "sha256:d9ec388a1a3a14e1cf3fa4316211776c0a55a6a33d646202bd93c5aa3e5265b0"-reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-10T12:37:22Z"-rationale = "real-catch: The contract now lists docs/under-the-hood/log-sink-plugins.md as a review target, since its table of built-in sinks and its explanation of why console is the default both describe what the console renders, which console_fields.py decides; no trigger file changed since the last ack. Reviewed that page against console_fields.py, console_log_sink.py and console_prefix.py: the console row named an emoji formatter that no longer exists, the handler now taking the stdlib's plain logging.Formatter, and the default's rationale promised emoji and clickable paths, while the path column is off unless is_show_path turns it on. Both passages now state what the console renders: the fields after the message coloured by name per FIELD_STYLES, the advice line from advice_segments, the dimmed package name before another library's line, and the layouts. The rest of the page, the sink contract, what a sink reads off a record and the reserved keys, states nothing console_fields.py or error_fields.py decides. logging.md was reviewed at the previous ack against the same trigger blobs; its console sections were re-read and still hold."+digest = "sha256:f07cb29a7da0c4d4f3b462d3cc7879db0de8a1991455e000de153d036e487b4f"+reviewed_by = "Louis Choquel"+reviewed_at = "2026-10-17T06:50:19Z"+rationale = "real-catch: the contract now triggers on pydantic_utils.py, where error_fields writes a ValidationError: its locations, reasons and the new is_authored_input option live there. logging.md now names the TypeAdapter form of validated_type and is_authored_input, the secondary-failure lines logged by class and code, and the instructor records no sink writes; log-sink-plugins.md said a redaction failure was the one case a sink misses an accepted record, and now names the instructor filter as the other."[trigger_files]"pipelex/tools/log/console_fields.py" = "blob:10c4516405dfdfe889590ef0d8e1914f56600a2f"-"pipelex/tools/log/error_fields.py" = "blob:515b7649ddd22dceb192faa21713732ec61cd6e0"+"pipelex/tools/log/error_fields.py" = "blob:e58e2a88ebc48c08fdfe1c7d173c9a719346cac0"+"pipelex/tools/typing/pydantic_utils.py" = "blob:6c469e95f53135d426c00e7b4cfc8711004f518b"diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex 91d85dacf..5f496f0ff 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:16fabe1ce1d3ef30ab6c155bf87f87acc09b63d9b5443256570c3b38a49af871"+digest = "sha256:21a9e03e80e78e4fd5f4f99418986cf26be098028e711c01acc0e4489cfff2d5"reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-17T00:39:22Z"-rationale = "clean-pass: the served-model check now gives its refusal the model handle and the capability as params; pipelex-kernel.md stays accurate and now names both params."+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."[trigger_files]"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"@@ -23,7 +23,7 @@ rationale = "clean-pass: the served-model check now gives its refusal the model"pipelex/kernel/llm_results.py" = "blob:6e3b8a2878b5bb284ece5fac10262fb59ac2029d""pipelex/kernel/memory_ops.py" = "blob:7fbbfaaec99f9712d8e215520cb02e26aad3fb40""pipelex/kernel/pipelex_kernel.py" = "blob:c7d40db1572aaca00d1c04a1039f5e3e564d6f87"-"pipelex/kernel/prompt_assembly.py" = "blob:47ed529296780eb21f3956849081f3108e18ffa4"+"pipelex/kernel/prompt_assembly.py" = "blob:8eb3f12c8c908dea5bc97579587578632a6d8431""pipelex/kernel/prompt_references.py" = "blob:a4a8c5535c7e51a16ac6c8d1296439b331192a7f""pipelex/kernel/search_ops.py" = "blob:30d2af78f0ef00c4d8b3647f52cc7cb4a01bf236""pipelex/kernel/search_results.py" = "blob:101b70dc96cc5ee1721c9f6b1cb725a5ca78ff70"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 325db720a..e8fc825ad 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@- **Every error carries its registry code**: every `PipelexError` subclass declares in `error_code` the code it raises, a code of the MTHDS core registry or of the Pipelex error registry, or else an `ErrorCodeSet` its raise sites choose from with `with_error_code()`, its cause's code (`InheritsCause`, with a fallback), or `ABSTRACT_ERROR` for a base never raised itself. `resolve_error_code()` gives the code an error reports, the first one named along its cause chain, and `runtime.unexpected` when none is; `pipelex.errors.error_codes` reads any code's title, domain, retry verdict, status and steps (`error_code_spec`, `parse_error_code`).- **`PipelexError.with_items()`**: a raise site that finds several faults of one kind gives one problem item per fault, so a `PipeParallel` whose branches give several results of a multiplicity their fields do not declare names each one in its `pipe.output_multiplicity` problem's `errors`, beside the first in its sentence.- **`PluginRegistrar.declare_error_codes`**: a plugin, a closed one included, declares the public codes it raises while it registers, and a code neither the MTHDS core nor the Pipelex registry defines refuses the boot with `PluginErrorCodeNotRegisteredError` (`pipelex.plugin.broken`), naming the plugin and the code.+- **`InputFreeValueError` and the input-free rendering of a refusal**: a pydantic validator raising `InputFreeValueError` (`pipelex.tools.typing.validation_exceptions`) declares that its message names nothing of the value it refused, which keeps its sentence wherever a refusal of a run's data is written, and `format_validation_error_without_input()` and `describe_exception_without_input()` (`pipelex.tools.typing.pydantic_utils`) write a `ValidationError` as its locations and reasons, never the values it refused.- **`PipelexRequestError`**: the runtime's own refusal of a request it cannot serve is a `PipelineRequestError` of the mthds package carrying the core code `request.invalid` (or `request.unsupported`) and its problem document, so a client reads the same refusal whether the runtime or the standard's client raised it.- **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`), the run, the request and each of the run's extras as `run.extras.<key>`, 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 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 is `request.invalid` and logs none), 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()`.@@ -33,6 +34,7 @@- **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.- **A truncated completion says which limit cut it**: `LLMCompletionTruncatedError` carries `model.output_truncated` when the method's `max_tokens` cut the answer and `model.context_exceeded` when the context window did, both the method's to change.- **`ModelDeckPresetValidationError` is spelt right (Breaking)**: the error a model deck preset that fails validation raises was `ModelDeckPresetValidatonError`, and its reports carried that `error_type`; a consumer that branched on the old name branches on the new one, or on its code, `pipelex.config.invalid`.+- **A pipe's failure line carries its code, not its text**: `The execution of a pipe failed` carries the problem's `error.code` beside `error.type` and no longer `error.message`, so a log query selects failed pipes by code, and the line holds neither the caller's own text, a function's message or a template's source, nor a refused host.- **`pipelex-agent` reads `retryable` from the code (Breaking)**: the agent CLI's error envelope takes `retryable` from the error's code, and its table of retryable error types is gone, as are the domain-table entries of classes that now carry a code. The envelope names that code as `error_code`, the member a hosted refusal already carried, so an agent branches on the code whichever runner failed, and its `hint`, when the error's chain advises nothing and the table names no hint for its class, is its code's next step as the operator reads it.- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its class name, which the operator reads as `diagnostics.error_class`, and its code, `security.template_refused` on a method's template, are unchanged.- **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.@@ -50,7 +52,7 @@- **A prompt over the model's context window reads `model.context_exceeded`**: a provider 400, or another 4xx such as the 422 or 413 a gateway may answer, saying the inputs are over what the model can read, by OpenAI's `context_length_exceeded` code or by the wording OpenAI, Anthropic, Mistral, Bedrock and Gemini give it, in the error's message or its body, is the caller's `model.context_exceeded`, answered 422, where it read `runtime.unexpected`, or `input.too_large` on a 413. A language model's window holds the prompt and the output requested with `max_tokens` together, and a 400 the `max_tokens` sent caused reads the same, so its next step is to shorten the input or lower `max_tokens`, or choose a model with a larger context window; an image, extraction, search or judgment model's next step names what it reads instead. A 400 about a malformed request still reads `runtime.unexpected`.- **A structured output cut at `max_tokens` reads `model.output_truncated`**: the Anthropic, OpenAI Chat Completions and Mistral workers turn instructor's `IncompleteOutputException`, raised for a structured answer cut at its output limit, into `LLMCompletionTruncatedError`, naming a structured output, the stop value, the output tokens and the `max_tokens` sent, where it escaped unclassified as `runtime.unexpected`. `LLMCompletionTruncatedError` takes an `output_kind`, a text or a structured output. When the Anthropic structured-output timeout lowered the limit that cut it, the error says so and advises a lower reasoning effort or a smaller output, never a higher `max_tokens`.- **A Gemini image a safety filter blocked reads `model.content_refused`**: the Google image worker reads the answer's finish reason, or the prompt's block reason when no candidate came back, and raises `ImgGenGenerationError` with `model.content_refused`, answered 422 with a next step to revise the prompt or its images, where an `IMAGE_SAFETY` or `PROHIBITED_CONTENT` answer read as an empty one, `provider.response_invalid`. The message names the reason Gemini gave and what it says, so an image stopped for recitation or for an unsupported language reads the same code without being called a safety block. An answer the model's output token limit stopped before it held an image (`MAX_TOKENS`) raises the new `ImgGenOutputTruncatedError`, `model.output_truncated`, answered 422 with a next step to simplify the prompt or choose another image model, where it read `provider.response_invalid`.-- **A file-type refusal no longer quotes the file**: `FileTypeError`'s message gives the number of bytes it read, where it quoted up to 300 bytes of the file's content.+- **No error message carries a run's data**: an error's message, which reaches the operator's diagnostics, the error tracker and the log lines, no longer quotes an input's value, a stuff's content, a model's answer or a value a pipe built: a refused input is described by its kind and size, a list item by its index and type, a URL by its scheme when it is one Pipelex reads, a date or a time by the form it expected, a pydantic refusal of a run's data, a provider's metadata included, by its locations and reasons, a stuff by its code and concept, and a file of unknown type by the number of bytes read. A `PipeFunc` whose function raised names the class of what it raised and never its text, as does any other failure of its executor, by its class and its code; a template that fails to render is described by the class Jinja2 raised and the template's line, never by Jinja2's text, which quotes a key of the data the template reached for, nor by its source, a name it reached for, the sandbox's refusals and the render budget's refusal of a call included, being named only when the parsed template spells it, a syntax error by its kind and line rather than the token Jinja2 quotes, and Pipelex's filters never quoting the argument they refuse; a structured generation `instructor` gave up on is described by the refused answer's reasons, located by the class it asked for, by the class of any other failure to parse the answer, a model's refusal included, or by the class of what ended its loop; an exception that is not a Pipelex error stands in a problem's diagnostics as its class alone, a run's and the API server's catch-all's alike; and no message names a refused or unreachable host, which `input.url_unreachable` takes as its `host` parameter, alongside the input the URL came from, which an extract worker, a prompt's image or document and a document's page views name, while a provider's file that could not be fetched is given no parameter its code does not declare. A failure following a pipe's own, a delivery's or the graph tracer's, is logged by its class and code, a webhook's transport failure is named by its class, a trace event log's refusal and the tracing assembly's errors are written by their reasons, and no sink writes `instructor`'s log records, which quote the model's answers. A location never quotes a key of the value's own: a key of a dict, or one the model does not declare, is written `<key>` (`entries.<key>.score`), only what the validated type's schema names is written as it is, and a refusal whose model is not known is written by its reasons alone; every site that validates an input into its concept's class, an explicit envelope and a transported stuff included, locates its refusal by that class, an explicit envelope's naming the input and the field as `input.invalid`'s parameters, and a refusal of a method author's own document is located as pydantic gives it (`is_authored_input`). A CSV input's refusal names the file by the input it was given as, never by its path, and quotes no cell nor a column the concept does not declare; its problem takes the input as its `input` parameter.- **Pre-release documentation is published**: a push to a `pre-release/` branch deploys its documentation under the `pre-release` alias of docs.pipelex.com, where the deploy workflow called a make target with no recipe and published nothing.### Removeddiff --git a/api/pipelex_api/exception_handlers.py b/api/pipelex_api/exception_handlers.pyindex f76e9eb7c..5f29b3517 100644--- a/api/pipelex_api/exception_handlers.py+++ b/api/pipelex_api/exception_handlers.py@@ -394,7 +394,8 @@ async def handle_unexpected_error(request: Request, exc: Exception) -> Response:`PipelexUnexpectedError` (`make_unexpected_failure`) and answered as itsproblem, `runtime.unexpected`, through the same rendering as every otherfailure: the caller reads the code's own sentences and never the exception's- text, and the operator reads its class and message in `diagnostics`. A+ text, and the operator reads its class in `diagnostics`, never its text either,+ which can carry anything of a run's data. Atraceback reaches no response — it goes to the operator log, correlated byrequest id.diff --git a/api/tests/unit/test_exception_handlers.py b/api/tests/unit/test_exception_handlers.pyindex 6db20d4b6..12946425f 100644--- a/api/tests/unit/test_exception_handlers.py+++ b/api/tests/unit/test_exception_handlers.py@@ -556,7 +556,8 @@ class TestExceptionHandlers:assert "error_type" not in bodyif as_operator:assert body["diagnostics"]["error_class"] == "PipelexUnexpectedError"- assert body["diagnostics"]["message"] == f"RuntimeError: {_UNEXPECTED_MESSAGE}"+ # The operator reads the class alone: a foreign exception's text can carry anything of the run's data.+ assert body["diagnostics"]["message"] == "RuntimeError"assert body["diagnostics"]["causes"] == [{"error_class": "RuntimeError"}]else:assert "diagnostics" not in body@@ -609,12 +610,12 @@ class TestExceptionHandlers:def test_unmapped_transport_error_falls_back_to_catch_all_500(self):# Without the orchestrator plugin's mapper (the agnostic base), the same bare transport error has no dedicated# handler and collapses to the catch-all `runtime.unexpected` — whose diagnostics still tell the operator which- # transport class failed and why.+ # transport class failed, and never its text, which can carry anything.response = _build_client(raise_server_exceptions=False, as_operator=True).get("/synthetic-transport-error")assert response.status_code == 500body = response.json()assert body["code"] == CoreCode.RUNTIME_UNEXPECTED- assert body["diagnostics"]["message"] == f"_SyntheticTransportError: {_TRANSPORT_MESSAGE}"+ assert body["diagnostics"]["message"] == "_SyntheticTransportError"def test_handler_of_handlers_catches_a_corrupt_problem(self):# When building the problem itself raises, the failure escapes the PipelexError handler; ServerErrorMiddleware@@ -624,7 +625,7 @@ class TestExceptionHandlers:assert response.status_code == 500body = response.json()assert body["code"] == CoreCode.RUNTIME_UNEXPECTED- assert body["diagnostics"]["message"] == "RuntimeError: problem_facts is deliberately broken"+ assert body["diagnostics"]["message"] == "RuntimeError"@pytest.mark.parametrize(("method", "path", "json_body", "expected_status"),diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.mdindex 5ca6b3154..99beab76b 100644--- a/docs/api-server/error-responses.md+++ b/docs/api-server/error-responses.md@@ -101,7 +101,7 @@ A failure the runtime raised is one problem seen through a view, and the identitEvery text in a problem that the runtime did not write itself, a message, a provider's answer or a parameter, is cut to a bounded length, keeping its head and ending with ` […]`.-The catch-all, a failure no more specific handler matched, answers `runtime.unexpected` with a **500** in both views: the caller reads that code's sentences, and the operator reads the exception's class and message in `diagnostics`. A traceback never reaches a response in either view.+The catch-all, a failure no more specific handler matched, answers `runtime.unexpected` with a **500** in both views: the caller reads that code's sentences, and the operator reads the exception's class in `diagnostics`, never its text, which can carry anything of a run's data, a pydantic refusal adding its reasons without the values it refused. A traceback never reaches a response in either view.The server's own record of a failure the runtime raised is built from the operator view, whichever view the response carries, so it names the error's class, its code and what the inference provider answered (see [Logging](logging.md)).diff --git a/docs/configuration/config-technical/network-config.md b/docs/configuration/config-technical/network-config.mdindex 7510d9fd3..60ce2dbed 100644--- a/docs/configuration/config-technical/network-config.md+++ b/docs/configuration/config-technical/network-config.md@@ -21,7 +21,7 @@ The value above is the default.With `is_fetch_ssrf_guard_enabled = true`, every download of a value's URL is checked when the connection opens, on the first request and on every redirect hop to a new host. The host is resolved, and the connection is refused when the name is `localhost` or a cloud metadata alias, or when any address it resolves to is not globally routable: private networks (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback, link-local (including the `169.254.169.254` metadata endpoint), carrier-grade NAT, multicast, reserved and unspecified addresses, in IPv4 and IPv6. Pipelex then connects to the address it checked, so a DNS record that changes between the check and the connection cannot slip through.-A refusal raises `SsrfBlockedError`, with the code `security.input_url_refused`, and fails the pipe that needed the bytes. It is not treated as a failed download: where Pipelex would otherwise keep a generated image's remote URL after a download error, a refused URL fails the pipe instead. The error message names the host that was requested and never the address it resolved to.+A refusal raises `SsrfBlockedError`, with the code `security.input_url_refused`, and fails the pipe that needed the bytes. It is not treated as a failed download: where Pipelex would otherwise keep a generated image's remote URL after a download error, a refused URL fails the pipe instead. The error message names neither the host that was requested, which is part of the run's data or of the caller's callback URL, nor the address it resolved to.A URL passed to a provider as a URL, for a model that fetches images itself, is not downloaded by Pipelex and is not checked by this guard.diff --git a/docs/tools/logging.md b/docs/tools/logging.mdindex e45911458..a9379c585 100644--- a/docs/tools/logging.md+++ b/docs/tools/logging.md@@ -204,6 +204,8 @@ httpx = "WARNING"The record's `pathname`, `lineno` and `funcName` point at the calling line, which is what the `console` sink's path column shows when `is_show_path` is on and what the caller-info templates render when `is_caller_info_enabled` is on; all of it comes from that same frame, with no source file read.+One library's records never reach a sink, whatever level `package_log_levels` gives its logger: `instructor`'s, which quote the run's data by design, each refused answer the model gave and the requests it sends with their prompts. Every sink's handler drops a record whose logger is `instructor` or one below it (`PayloadLoggerFilter` in `pipelex/tools/log/log_sink.py`, which reads `PAYLOAD_LOGGER_PACKAGES`), and Pipelex reports what `instructor` does through its own lines and errors, which hold none of it.+A filter attached to `logging.getLogger("pipelex")` never sees these records: the stdlib runs a logger's filters only for records emitted on that very logger, and a record is emitted on the module-named one. Attach the filter to the handler instead, which the stdlib runs for every record it handles, or, to reach whichever sink is installed, append a processor to the sink's `processors` list, as described in [Log Sink Plugins](../under-the-hood/log-sink-plugins.md#logsink).## Before configuration@@ -476,7 +478,7 @@ log.warning(### Values in fields-What varies goes in `fields`, named by the [naming convention](#naming-convention), and one concept has one name across the codebase, so that a query written for one line finds every line about the same thing. Pipelex's own concepts take the names in the table below. A concept the OpenTelemetry semantic conventions define takes their key verbatim: `file.path` for a path on disk and `file.name` for a file's name alone, `url.full` for a URL and `url.path` for the path of a request's URL, `server.address` for the host a request is sent to, `http.response.status_code` for the status of an HTTP response, `user.id` for the authenticated caller, never an identity the server refused, `error.type` for the class of an error, and the `gen_ai.*` keys for inference, such as `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.request.temperature`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. A `gen_ai.*` key means on a log line what it means on Pipelex's LLM span: `gen_ai.request.model` is the model's handle and `gen_ai.response.model` the provider's id the model deck pins for that handle, the one the call is made with, whichever model the provider says answered. `gen_ai.operation.name` is the one exception for now, as [the inference call end](#the-inference-call-end) explains. A line about an inference call carries them beside `model_handle`, `backend_name` and `sdk`, so it joins its span in a log store, while `model_handle` names the handle on every line about a model, inference or not. An OpenTelemetry key that more than one call site uses is spelled through a constant, so a misspelt one is an error the type checker reports rather than a field no query finds: `OTelLogAttr` in `pipelex/system/telemetry/otel_constants.py` holds those keys, `GenAISpanAttr` beside it the `gen_ai.*` ones, and `pipelex.tools.log.error_fields` the two error keys. A count is named `<what>_count` (`concept_count`) and a duration `duration_ms`, in milliseconds. A path is named `<what>_path`, a list of paths `<what>_paths`, a directory `<what>_dir` and a file as a declaration names it `<what>_file`, with their plurals, beside `file.path`: the console takes a field for a path by that ending and cuts its value at its start, keeping the file's name (see [Fields after the message](#fields-after-the-message)), so a field holding no path takes none of these endings. A field carries one JSON type on every line that has it, `null` aside, so a query compares it one way: where the value would be an integer on some lines and a word on others, `unbounded` for instance, the field is left out of the lines the word would name, and the table says so.+What varies goes in `fields`, named by the [naming convention](#naming-convention), and one concept has one name across the codebase, so that a query written for one line finds every line about the same thing. Pipelex's own concepts take the names in the table below. A concept the OpenTelemetry semantic conventions define takes their key verbatim: `file.path` for a path on disk and `file.name` for a file's name alone, `url.full` for a URL and `url.path` for the path of a request's URL, `server.address` for the host a request is sent to, `http.response.status_code` for the status of an HTTP response, `user.id` for the authenticated caller, never an identity the server refused, `error.type` for the class of an error, and the `gen_ai.*` keys for inference, such as `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.request.temperature`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. A `gen_ai.*` key means on a log line what it means on Pipelex's LLM span: `gen_ai.request.model` is the model's handle and `gen_ai.response.model` the provider's id the model deck pins for that handle, the one the call is made with, whichever model the provider says answered. `gen_ai.operation.name` is the one exception for now, as [the inference call end](#the-inference-call-end) explains. A line about an inference call carries them beside `model_handle`, `backend_name` and `sdk`, so it joins its span in a log store, while `model_handle` names the handle on every line about a model, inference or not. An OpenTelemetry key that more than one call site uses is spelled through a constant, so a misspelt one is an error the type checker reports rather than a field no query finds: `OTelLogAttr` in `pipelex/system/telemetry/otel_constants.py` holds those keys, `GenAISpanAttr` beside it the `gen_ai.*` ones, and `pipelex.tools.log.error_fields` the error keys. A count is named `<what>_count` (`concept_count`) and a duration `duration_ms`, in milliseconds. A path is named `<what>_path`, a list of paths `<what>_paths`, a directory `<what>_dir` and a file as a declaration names it `<what>_file`, with their plurals, beside `file.path`: the console takes a field for a path by that ending and cuts its value at its start, keeping the file's name (see [Fields after the message](#fields-after-the-message)), so a field holding no path takes none of these endings. A field carries one JSON type on every line that has it, `null` aside, so a query compares it one way: where the value would be an integer on some lines and a word on others, `unbounded` for instance, the field is left out of the lines the word would name, and the table says so.| Field | Type | What it names || --- | --- | --- |@@ -564,6 +566,7 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventio| `auth_refusal_reason` | string | Why the API server refused a caller's own credentials: `missing_bearer_token`, `expired_token`, `invalid_token` or `api_key_mismatch` || `claim_type` | string | The type a token's claim was decoded as, by its Python name, where the claim is refused and its value is not logged: `str`, `int`, `dict` || `error.type`, `error.message` | string | A handled exception's class name and its text, as [Exceptions](#exceptions) describes |+| `error.code` | string | The registry code of a failure's problem, which the line about a pipe's failure carries in place of its text || `error_domain` | string | Who fixes a failure: `input`, `config`, `runtime`, read from the domain of the failure's code || `error_category` | string | An inference failure's Pipelex classification, as its error carries it || `retryable` | boolean | Whether retrying the failed call as it was can help, as the failure's code says |@@ -580,10 +583,11 @@ An exception rides the record, never the message, at every level, DEBUG and VERB- **At ERROR and CRITICAL**, inside the `except` block, pass `include_exception=True`: the record carries the exception, and each sink writes its type and its traceback its own way. That is for an exception the code handles where it logs it, whose traceback nobody else will see, and above all for the catcher of an unexpected failure, the root of a CLI command or the API server's error handler, which logs it there and prints no traceback of its own: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it to the log store, which a traceback printed on the console alone never reaches. A CLI command's root also names the exception's type and message in its own output, which is not a log record, so the terminal says why the command failed whatever the sink and the level, under a `json` sink writing to a file as under a level above ERROR.- **An exception logged and then re-raised carries no traceback, at ERROR too**: it rides as `error_fields`, since whoever catches it owns its traceback, and a line that carried it as well would print it a second time, ahead of the catcher's own report.-- **A secondary failure carries no traceback either**: a cleanup that fails while another exception propagates, a tracer that will not close, a library that will not tear down, a delivery that fails after the run did, rides as `error_fields`, at ERROR too. Python chains the propagating exception onto it as its context, so its traceback would print the primary's text, a `ValidationError`'s refused input included, under a line that is not about it, while the primary's own catcher reports it. A cleanup that runs either way, a plugin's teardown callback, follows the same rule.+- **A pipe's failure carries no text at all**: `The execution of a pipe failed` names the pipe, `error.code`, the code of the problem the failure reports, and `error.type`, the exception's class, and never `error.message`. A run's failure can hold the caller's own text, a method function's message or a template's source, and a refused host, which no log line carries, while the caller's own problem holds them where the code declares a parameter for them, and the catcher's report gives the operator the rest.+- **A secondary failure carries no traceback either**: a cleanup that fails while another exception propagates, a tracer that will not close, a library that will not tear down, a delivery that fails after the run did, rides as fields, at ERROR too, and a failure that follows a pipe's own, the delivery's or the graph tracer's, rides as its class and, for a Pipelex error, its code, never its text, which names the caller's webhook URL or the trace's file, as the line about the pipe's own failure does. Python chains the propagating exception onto it as its context, so its traceback would print the primary's text, a `ValidationError`'s refused input included, under a line that is not about it, while the primary's own catcher reports it. A cleanup that runs either way, a plugin's teardown callback, follows the same rule.- **A `ValidationError` the code swallows carries no traceback**, at any level: its traceback ends in its own text, which quotes every value it refused, so it rides as `error_fields`, which writes it as below.- **At WARNING and below**, an exception the code expected and handled rides as two fields, `error.type`, its class's name, and `error.message`, its text, with no traceback, through `error_fields` (`pipelex.tools.log.error_fields`): `fields={"package_address": address, **error_fields(exc=exc)}`. A warning promises a degradation that was handled, and a traceback of Pipelex's own frames repeated on every emission of an expected failure says nothing a reader can act on; the facade's `warning` takes no `include_exception` for that reason. Where the diagnosis is the cause chain rather than the exception's own text, as when a fetch fails in git underneath, `error_fields(exc=exc, text=...)` carries the chain instead. The console cuts `error.message` only past 2000 characters, where a field with no length of its own is cut at 80 ([Fields after the message](#fields-after-the-message) names the fields that have one), so the chain reaches the terminal whole without a dependency's raw output flooding it.-- **A pydantic `ValidationError` never reaches a field as its own text**, which quotes every value it refused, a run's input or a model's response among them: `error_fields` writes it as its locations and reasons alone, `limits.burst: Input should be a valid integer`, whichever line logs it. A reason is pydantic's own message, kept only when nothing in it came from the input: the error is one of pydantic's built-in types, its message is the one pydantic renders, and its context is empty or holds only values the schema gives, a bound such as `max_length`, the values or tags it expects, a discriminator's name, a pattern, a class. Any other error is written as its location and its type alone, `date: value_error`: a custom validator's message, a `value_error`, an `assertion_error` or a `PydanticCustomError`'s, is the validator's text, which can quote the very value it rejected, and several of pydantic's own templates quote the input as well, the unknown tag of a discriminated union (`item: union_tag_invalid`), the character a UUID could not parse, a parser's own complaint. An `extra_forbidden` error is located at its parent, `limits: Extra inputs are not permitted`, or carries no location at the root, since the last part of its location is the key the caller sent. A `text=` given in its place is carried as given.+- **A pydantic `ValidationError` never reaches a field as its own text**, which quotes every value it refused, a run's input or a model's response among them: `error_fields` writes it as its locations and reasons alone, `retries: Input should be a valid integer`, whichever line logs it. A reason is pydantic's own message, kept only when nothing in it came from the input: the error is one of pydantic's built-in types, its message is the one pydantic renders, and its context is empty or holds only values the schema gives, a bound such as `max_length`, the values or tags it expects, a discriminator's name, a pattern, a class. Any other error is written as its location and its type alone, `date: value_error`: a custom validator's message, a `value_error`, an `assertion_error` or a `PydanticCustomError`'s, is the validator's text, which can quote the very value it rejected, unless the validator raised `InputFreeValueError` (`pipelex.tools.typing.validation_exceptions`), which declares its sentence names nothing of the value and keeps it, as the native contents' validators do, and several of pydantic's own templates quote the input as well, the unknown tag of a discriminated union (`item: union_tag_invalid`), the character a UUID could not parse, a parser's own complaint. A location quotes the keys of a dict the value holds, and a key the model does not declare, which are input by definition, so it is written only as far as the schema of the validated model names it, every other part as `<key>`: a refused value under a dict's key reads `limits.<key>: Input should be a valid integer`, and a key a nested model forbids `limits.<key>: Extra inputs are not permitted`. A line that knows that model passes it as `error_fields(exc=..., validated_type=...)`, a model or a `TypeAdapter`; without it, each error is written by its reason alone. A line about a method author's own document, or a value Pipelex built for itself such as a dry run's mock, holds no run's data and says so with `error_fields(exc=..., is_authored_input=True)`, which writes the locations as pydantic gives them. A `text=` given in its place is carried as given.`error.type` is the OpenTelemetry key for the class of error an operation ended with. `error.message` is the key OpenTelemetry gave an error's text before deprecating that general attribute in favour of domain-specific ones; Pipelex keeps it as `error.type`'s companion because the `exception.*` keys belong to the sinks, which write them for a record that carries the exception itself and prefix a field spelling one.diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex ad3a6c135..caab6f3f0 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -91,7 +91,21 @@ A third, narrower projection, `problem_metadata()`, gives a `ProblemMetadata`: w### Sentences come from the code, never from the message-What a caller reads is written in the registry, not at the raise site. `detail` and the step's `detail` are rendered from the code's templates with the problem's parameters, and an error's own message, which its raise site writes for whoever debugs the runtime, rides only the operator view's `diagnostics.message`. A raise site can therefore put in its message anything that helps an operator, such as a path on the host, a configuration value, a foreign exception's text or a model's output, and no caller reads it; what a caller needs in order to act is given as parameters.+What a caller reads is written in the registry, not at the raise site. `detail` and the step's `detail` are rendered from the code's templates with the problem's parameters, and an error's own message, which its raise site writes for whoever debugs the runtime, rides only the operator view's `diagnostics.message`. A raise site can therefore put in its message what helps an operator, such as a path on the host, a configuration value or a foreign exception's text, and no caller reads it; what a caller needs in order to act is given as parameters.++### What a message may carry++A message reaches the operator's diagnostics, the error tracker and every log line about the failure, so it carries no run's data: never an input's value, a stuff's content, a value a pipe built or a model's answer. A raise site refusing a run's data names it by identifiers, the input, the field, the index of a list item, the concept and the kind and size of the value (`a string of 24 character(s)`, `an object of 3 key(s)`), and gives the facts its code declares as parameters; a fact its code declares no parameter for is left out. It never names the caller's own text either, a method's template source or a function's own exception text, which only a parameter its code declares as `caller_text` may carry, capped.++- **A pydantic refusal of a run's data** is written by `format_validation_error_without_input()` (`pipelex/tools/typing/pydantic_utils.py`): each error's location and reason, the reason being pydantic's own message when nothing in it came from the input, or else the error's type, such as `count: int_parsing`, each located reason written once, in the order it first comes. A `ValidationError`'s own text quotes every value it refused, and so does the readable analysis `format_pydantic_validation_error()` gives, which is kept for the documents whose author reads them, a method or a configuration. `describe_exception_without_input()` writes any exception's text the same way, a `ValidationError`'s by its locations and reasons; a caller describing a foreign exception, whose text can carry anything, names it by its class instead.+- **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 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 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.Rendering never fails. A template naming a parameter the problem does not hold makes `detail` fall back to the code's title, and the step to the generic sentence of its kind, such as `Correct the method as the problem describes, then validate it again.` The fallback is logged as a warning, `A problem's sentence could not be rendered from its template`, with the code and the reason as fields, so a raise site that forgot a parameter is found in the logs while the reader still reads a sentence.@@ -291,7 +305,7 @@ raise (A pipe checking that its required inputs are present tells the two cases apart by its stack: at the entry pipe, a missing input is one the request left out, `input.missing` with its `input` parameter; below it, it is one an earlier step of the method did not produce, `pipe.input_unresolved` with its `variable` parameter. The message, which also lists the inputs that may be omitted, is the operator's diagnostics; the caller reads `The request does not give the input 'name', which the method requires.` and the step `Add the input 'name' to the request, then send it again.`-Because no caller reads a message, no raise site has to vouch for one: a model output that does not fit its structure, a `PipeFunc` crash, an input resource named by its path on the host and a template that fails to render all keep their whole text for the operator, while their caller reads the code's sentences. A raise site's only duty toward the caller is its parameters, which the caller view shows: it gives only the caller's own names and values (pipe codes, concept codes, variable names, the model as the method wrote it), and a fact only an operator may read is a parameter the registry marks `operator_only`.+Because no caller reads a message, a raise site vouches for its message only toward the operator, and it carries no run's data even there ([What a message may carry](#what-a-message-may-carry)): a model output that does not fit its structure is named by its fields and the reasons it was refused, a `PipeFunc` crash by the class of what the function raised, a template that fails to render by a fixed sentence naming the class Jinja2 raised and its line, and an input resource by the input it was given as, while their caller reads the code's sentences. A raise site's only duty toward the caller is its parameters, which the caller view shows: it gives only the caller's own names and values (pipe codes, concept codes, variable names, the model as the method wrote it), and a fact only an operator may read is a parameter the registry marks `operator_only`.---@@ -367,7 +381,7 @@ One refusal outside any service's own namespace is classified by the runtime its### The `instructor` Unwrap-On structured-generation paths, `instructor` raises an `InstructorRetryException` from the exception that ended its retry loop. The loop re-asks only a response that fails the schema, so that exception is either the raw SDK exception of a call that failed in transport, or, once the re-ask budget is spent, the last parse failure. `extract_underlying_sdk_exception()` recovers it from the wrapper's cause, not from `failed_attempts`, which lists only parse failures and would name an earlier one when a re-ask then fails in transport. The recovered exception routes through the same per-provider categorization as the plain-text path. Once the re-ask budget is spent, the recovered exception is the last `pydantic.ValidationError`, which `_STATUSLESS_BY_TYPE_NAME` classifies as `CONTENT` / `CHANGE_INPUT` with `model.output_schema_mismatch`, a `runtime` code whose verdict invites a retry and which answers its registry status, 502. A recovered exception the classifier does not recognize lands in `UNKNOWN`.+On structured-generation paths, `instructor` raises an `InstructorRetryException` from the exception that ended its retry loop. The loop re-asks only a response that fails the schema, so that exception is either the raw SDK exception of a call that failed in transport, or, once the re-ask budget is spent, the last parse failure. `extract_underlying_sdk_exception()` recovers it from the wrapper's cause, not from `failed_attempts`, which lists only parse failures and would name an earlier one when a re-ask then fails in transport. The recovered exception routes through the same per-provider categorization as the plain-text path. Once the re-ask budget is spent, the recovered exception is the last `pydantic.ValidationError`, whose text quotes the model's answer, so its metadata's `message` is written without it, by its reasons, located by the class the generation asked for, which each worker passes as `validated_type` (`describe_exception_without_input()`). The loop can also end at once on a failure to parse the answer that it does not re-ask, such as the `AssertionError` that `instructor`'s OpenAI parser raises with the model's refusal in its text. Each worker therefore passes its SDK's own error classes as `sdk_error_types`, the ones it catches on its plain path: a recovered exception of one of them keeps its text, which is the provider's and which the classification reads, and any other is written by its class alone. A fallback that recovers no exception names the wrapper's own cause by its class alone (`describe_instructor_failure()`). `_STATUSLESS_BY_TYPE_NAME` classifies the `ValidationError` as `CONTENT` / `CHANGE_INPUT` with `model.output_schema_mismatch`, a `runtime` code whose verdict invites a retry and which answers its registry status, 502. A recovered exception the classifier does not recognize lands in `UNKNOWN`.One exception escapes the loop unwrapped. `instructor` reads the stop value of every structured answer it parses, and raises its `IncompleteOutputException` for one cut at the request's output limit: an OpenAI-shaped completion, Mistral's included, whose first choice finished on `length`, or an Anthropic message that stopped on `max_tokens`. It never re-asks such an answer, and it raises the exception as it is, carrying the cut answer as its `last_completion`, never inside an `InstructorRetryException`. The workers whose structuring mode can raise it, the Anthropic, OpenAI Chat Completions and Mistral workers, catch it and raise `LLMCompletionTruncatedError` from it through `LLMWorkerAbstract._incomplete_output_error`, which reads the answer's stop value and output tokens with `read_incomplete_output` (in `pipelex/cogt/llm/completion_stop.py`). A structured output cut at its limit therefore reads `model.output_truncated`, as a text cut at the same limit does, and names the same stop value, output tokens and `max_tokens`, the error's `output_kind` saying a structured output was cut rather than a text. When the Anthropic worker's structured-output timeout lowered the limit, the worker passes a `MaxTokensCeiling` naming the limit it was given and the timeout, and the error says the limit was lowered and to what, then gives as its next step, in its message and its `user_action`, a lower reasoning effort or a smaller output, since a higher `max_tokens` would be lowered the same way. The Gemini and Responses API structuring modes never raise it.@@ -405,7 +419,7 @@ The advice an error carries, its `user_action`, is not a fact of its problem: thWhen a pipe fails during a run, the error a surface receives sits under several wrappers: the pipe router's `PipeRouterError`, maybe a runtime bridge's `PipelexBridgeDispatchError`, and the runner's `PipelineExecutionError`. None of them is what went wrong, and a problem built from `PipelineExecutionError` with a bridge's sentence for a message would tell the reader nothing. So the two located wrappers, `PipeRouterError` and `PipelineExecutionError`, which take their cause's code, answer the problem of the **root fault** and only add where it happened (`pipelex/pipe_run/located_failure.py`). The root fault is the error whose code the failure resolves to: the first `PipelexError` down the cause chain that carries a code of its own, the walk `resolve_error_code()` makes, so a wrapper that adds the fact deciding the code (a PipeFunc's `pipe.function_raised` over a coded error its function raised) is the root fault over its cause; when none carries one, the deepest error implying a code, else the innermost `PipelexError`. The walk stops at the first exception that is not a `PipelexError`, whose stand-in is then the fault.-**Locating.** `PipeRouterProtocol.run()` catches every failure of the pipe it runs and re-raises it as a `PipeRouterError` chained to it, with the pipe's code and a snapshot of its stack taken where it failed. A failure that already carries a `PipeRouterError` rises untouched through the routers of the controllers above, so the innermost location is the one reported. An exception that is not a `PipelexError` first becomes a `PipelexUnexpectedError` whose message names its class (`KeyError: 'boom'`), which only an operator reads, and a dry run that sorts its own failures from programming bugs (the bundle validator's sweep, the validate surfaces' graph step) finds the foreign exception behind it with `find_foreign_fault()` and lets it propagate rather than report it as the bundle's failure. A host router whose transport raises its own failures overrides the `_as_pipelex_failure()` hook, and returns `None` for a control-flow exception such as a cancellation, which then propagates as it is. For a transport failure carrying a recovered problem, the far side packs the root fault's own problem, never a located one: when it packs that problem alone, the hook returns a `PipelexError` carrying it and the router locates it at the pipe it ran; when it packs the location it found as well, the hook returns a `PipeRouterError` rebuilt over that problem with `make_located()`, which the router raises untouched, so the problem reads exactly as the local run's. The runner wraps any failure of the run into a `PipelineExecutionError` with `make_for_run_failure()`, which takes the location from the innermost `PipeRouterError` on the chain (`find_failure_location()`), never from the live stack, which has unwound by then.+**Locating.** `PipeRouterProtocol.run()` catches every failure of the pipe it runs and re-raises it as a `PipeRouterError` chained to it, with the pipe's code and a snapshot of its stack taken where it failed. A failure that already carries a `PipeRouterError` rises untouched through the routers of the controllers above, so the innermost location is the one reported. An exception that is not a `PipelexError` first becomes a `PipelexUnexpectedError` whose message is its class (`KeyError`), which only an operator reads, and a dry run that sorts its own failures from programming bugs (the bundle validator's sweep, the validate surfaces' graph step) finds the foreign exception behind it with `find_foreign_fault()` and lets it propagate rather than report it as the bundle's failure. A host router whose transport raises its own failures overrides the `_as_pipelex_failure()` hook, and returns `None` for a control-flow exception such as a cancellation, which then propagates as it is. For a transport failure carrying a recovered problem, the far side packs the root fault's own problem, never a located one: when it packs that problem alone, the hook returns a `PipelexError` carrying it and the router locates it at the pipe it ran; when it packs the location it found as well, the hook returns a `PipeRouterError` rebuilt over that problem with `make_located()`, which the router raises untouched, so the problem reads exactly as the local run's. The runner wraps any failure of the run into a `PipelineExecutionError` with `make_for_run_failure()`, which takes the location from the innermost `PipeRouterError` on the chain (`find_failure_location()`), never from the live stack, which has unwound by then.**The problem.** Both wrappers answer the same problem, the root fault's own (`located_root_fault()`), built as the wrapper reports it (`located_problem()`, over `PipelexError.problem_reported_by()`) with the location they hold:diff --git a/docs/under-the-hood/log-sink-plugins.md b/docs/under-the-hood/log-sink-plugins.mdindex baf4a430e..6025faf6a 100644--- a/docs/under-the-hood/log-sink-plugins.md+++ b/docs/under-the-hood/log-sink-plugins.md@@ -96,7 +96,7 @@ class LogSink(ABC):```- **`make_handler`** builds the stdlib handler the sink installs on the root logger, and is where a heavy import belongs. It is called once per install, so selecting a sink is what pays for its dependency and a sink whose package is missing fails there, at boot, with `MissingDependencyError` naming the extra. A sink object installed again after a `reset` builds a second handler rather than being handed the first one back, because the teardown closed it — and a close is terminal for a sink that really releases what it writes to, so a reused handler would accept every record and drop the lot with nothing raised to say so. **Open the target in `make_handler`, not in `__init__`**, or the second install writes to something already closed. A sink that cannot, because it is handed its target already built, refuses a second handler from `make_handler` instead of building one on the closed target: the built-in `otlp` sink is constructed around its processor and shuts it down with its provider at close, and the built-in `gcp` sink around the client library's transport, whose worker thread its close stops for good, so installing the same `OtlpLogSink` or `GcpLogSink` object again raises, and each factory builds a new one at every boot.-- **`processors`** is the slot a cross-cutting transformation hooks into. A processor is a callable that edits a record in place, `Callable[[logging.LogRecord], None]`, and the base runs every processor over each record before the handler formats it, through a filter on the sink's own handler. Each one is guarded on its own: the stdlib runs a handler's filters outside any `try`, so a processor that raised would raise out of the `log.<level>(...)` call that emitted the record, and instead what it raises is reported on stderr by its type and the processor's name — never its text or its traceback, since a processor fails on the record's own values and its exception is where those end up — guarded in its turn since a closed stderr makes the reporter raise, the processors after it still run, and the record is handed on. A failing processor costs that record its processing, never the call and never the line; the redaction processor, which must not hand on what it failed to scrub, strips the record down to a `[REDACTION FAILED: <exception type>]` notice before it raises, and where even that stripping could not complete it leaves a mark that has the record dropped rather than emitted — the one case in which a sink does not see a record its logger accepted. **Redaction is the first processor, and the base is not what appends it**: `log.install_sink` puts it in front of the sink's own list, so every sink gets it, built-in, out-of-tree or the doctor's fallback, with none of them knowing about it — see [Redaction](../tools/logging.md#redaction) for why it edits the record every root handler shares instead of a copy.+- **`processors`** is the slot a cross-cutting transformation hooks into. A processor is a callable that edits a record in place, `Callable[[logging.LogRecord], None]`, and the base runs every processor over each record before the handler formats it, through a filter on the sink's own handler. Each one is guarded on its own: the stdlib runs a handler's filters outside any `try`, so a processor that raised would raise out of the `log.<level>(...)` call that emitted the record, and instead what it raises is reported on stderr by its type and the processor's name — never its text or its traceback, since a processor fails on the record's own values and its exception is where those end up — guarded in its turn since a closed stderr makes the reporter raise, the processors after it still run, and the record is handed on. A failing processor costs that record its processing, never the call and never the line; the redaction processor, which must not hand on what it failed to scrub, strips the record down to a `[REDACTION FAILED: <exception type>]` notice before it raises, and where even that stripping could not complete it leaves a mark that has the record dropped rather than emitted. That is one of the two cases in which a sink does not see a record its logger accepted; the other is a record of a library that writes a run's data into its lines, `instructor`'s, which the base's handler drops before any processor runs (`PayloadLoggerFilter`, see [Logger names and levels](../tools/logging.md#logger-names-and-levels)). **Redaction is the first processor, and the base is not what appends it**: `log.install_sink` puts it in front of the sink's own list, so every sink gets it, built-in, out-of-tree or the doctor's fallback, with none of them knowing about it — see [Redaction](../tools/logging.md#redaction) for why it edits the record every root handler shares instead of a copy.- **`redirect_to_stderr`** exists for the agent CLI, whose stdout is reserved for its structured envelope: a sink that writes to a process stream moves it to stderr, and one that writes to a collector ignores the call.### What a sink reads off a recorddiff --git a/docs/under-the-hood/pipelex-kernel.md b/docs/under-the-hood/pipelex-kernel.mdindex a4e12c436..0ee6917ea 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. `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. `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.mdindex 8a727a822..ca722ab1f 100644--- a/docs/under-the-hood/template-sandbox.md+++ b/docs/under-the-hood/template-sandbox.md@@ -42,11 +42,11 @@ A method template renders without a template loader, so `{% include %}`, `{% extMany 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 refused attribute or callable and the type it was reached on. 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 }}`. 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. `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.-A render that would overdraw its budget raises `Jinja2TemplateBudgetError`, with the code `pipe.template_budget_exceeded`, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A template whose macros or includes nest deeper than Python allows raises the same error. It is a `ToolError`, not a `SecurityError`: a budget is a limit on what a render may spend rather than a policy refusal, so it is handled by its code like any other fault of the method.+A render that would overdraw its budget raises `Jinja2TemplateBudgetError`, with the code `pipe.template_budget_exceeded`, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A refused call names the method it called only when the template spells that name, as in `{{ note.center(width) }}`; a method the template reaches by a value, as in `{{ (note | attr(key))(width) }}`, is described without its name, *calling a method of a 'str' value*. A template whose macros or includes nest deeper than Python allows raises the same error. It is a `ToolError`, not a `SecurityError`: a budget is a limit on what a render may spend rather than a policy refusal, so it is handled by its code like any other fault of the method.A template that names a filter or a test Jinja2 does not know inside a conditional branch compiles, and only the render of that branch finds the name. The render raises `Jinja2TemplateInvalidError`, with the code `method.template_invalid`, whose message names the unknown name and never quotes the template. A `PipeCondition` expression and a `PipeLLM` prompt answer it as a fault of the method, located on the pipe and the field, with the code's step for the method's author, which the caller view carries as well.diff --git a/drift.toml b/drift.tomlindex ccf7233cb..38f150e91 100644--- a/drift.toml+++ b/drift.toml@@ -141,12 +141,16 @@ review = [verify_commands = [][contracts.logging-docs]-description = "The logging doc restates the console's field rules and the handled-exception fields, the log-sink page summarises what the console renders, and both must track the two modules that decide them."-# The page restates, rule by rule, what the two modules decide: the style map (`FIELD_STYLES`) and+description = "The logging doc restates the console's field rules and the handled-exception fields, the log-sink page summarises what the console renders, and both must track the modules that decide them."+# The page restates, rule by rule, what the modules decide: the style map (`FIELD_STYLES`) and# the fields it colours, the cut lengths (`FIELD_VALUE_MAX_LENGTH` and the generous ones in# `FIELD_MAX_LENGTHS`), the field names whose value is cut at its start (`LEFT_CUT_FIELD_SUFFIXES`,-# `LEFT_CUT_FIELDS`), when a pydantic message is kept rather than its error type-# (`SCHEMA_CONTEXT_KEYS`), and where an `extra_forbidden` error is located. A name added to one of+# `LEFT_CUT_FIELDS`), in `console_fields.py`; the handled-exception fields and their arguments, in+# `error_fields.py`; and, in `pydantic_utils.py`, where `error_fields` writes a `ValidationError`+# through `describe_exception_without_input`, when a pydantic message is kept rather than its error+# type (`SCHEMA_CONTEXT_KEYS`, `refusal_reason_without_input`) and how a location is written+# (`located_validation_errors`: what the schema names, `<key>` for the rest, an authored document's+# as pydantic gives it). A name added to one of# those sets, or a length moved, silently falsifies a sentence quantifying over it, which is the# staleness this contract exists to catch. The log-sink plugins page describes the `console` sink# in its table of built-in sinks and again where it explains why that sink is the default, and@@ -160,6 +164,7 @@ description = "The logging doc restates the console's field rules and the handletriggers = ["pipelex/tools/log/console_fields.py","pipelex/tools/log/error_fields.py",+ "pipelex/tools/typing/pydantic_utils.py",]review = ["docs/tools/logging.md",diff --git a/pipelex/cogt/content_generation/assignment_models.py b/pipelex/cogt/content_generation/assignment_models.pyindex 1a67a25c5..44647032a 100644--- a/pipelex/cogt/content_generation/assignment_models.py+++ b/pipelex/cogt/content_generation/assignment_models.py@@ -154,10 +154,16 @@ class ExtractAssignment(BaseModel):class RenderPageViewsAssignment(BaseModel):+ """Serializable unit for rendering a document's pages as images.++ ``input_name`` is the input the document came from, as a caller writes it, which a failed fetch of its URL names.+ """+job_metadata: JobMetadatacogt_run_params: CogtRunParamsdocument_uri: strpage_views_dpi: int+ input_name: str | None = Nonedef referenced_uris(self) -> list[UriReference]:"""The URL the leaf reads for this assignment: the document whose pages it renders."""diff --git a/pipelex/cogt/content_generation/content_generator.py b/pipelex/cogt/content_generation/content_generator.pyindex 3fb6896c7..893d30646 100644--- a/pipelex/cogt/content_generation/content_generator.py+++ b/pipelex/cogt/content_generation/content_generator.py@@ -228,6 +228,7 @@ class ContentGenerator(ContentGeneratorProtocol):cogt_run_params=cogt_run_params,document_uri=extract_input.document_uri,page_views_dpi=page_views_dpi,+ input_name=extract_input.input_name,)return await render_page_views_and_store(render_assignment=render_assignment,diff --git a/pipelex/cogt/content_generation/llm_generate.py b/pipelex/cogt/content_generation/llm_generate.pyindex 8d96a1712..1fca18696 100644--- a/pipelex/cogt/content_generation/llm_generate.py+++ b/pipelex/cogt/content_generation/llm_generate.py@@ -1,6 +1,6 @@from typing import cast-from pydantic import BaseModel+from pydantic import BaseModel, ConfigDictfrom pipelex.cogt.content_generation.assignment_models import LLMAssignment, ObjectAssignmentfrom pipelex.cogt.content_generation.dry_mock import (@@ -57,6 +57,28 @@ async def llm_gen_object(object_assignment: ObjectAssignment, *, object_class: treturn generated_object+def make_object_list_schema(*, item_class: type[BaseModel], item_class_name: str) -> type[BaseModel]:+ """The model a list of objects is generated as, ``ListOf<item>``, whose ``items`` are the objects.++ Its title is its name from the start, not only its ``__name__``: ``instructor`` validates the model's answer with a+ subclass named after the wrapper, and a refusal of that answer is located by this class's schema only when both+ validators carry the same title (``pipelex.tools.typing.pydantic_utils.located_validation_errors``).+ """+ list_schema_name = f"ListOf{item_class_name}"++ class ListSchema(BaseModel):+ model_config = ConfigDict(title=list_schema_name)++ items: list[item_class] # type: ignore[valid-type] # pyright: ignore[reportInvalidTypeForm]++ ListSchema.__name__ = list_schema_name+ if item_class.__doc__:+ ListSchema.__doc__ = f"List wrapper for {item_class_name}.\n\nItem description:\n{item_class.__doc__}"+ else:+ ListSchema.__doc__ = f"A list of {item_class_name}."+ return ListSchema++async def llm_gen_object_list(object_assignment: ObjectAssignment, *, object_class: type[BaseModel] | None = None) -> list[BaseModel]:"""Generate a list of structured objects. ``object_class`` is the caller's live item class when there is one.@@ -75,22 +97,14 @@ async def llm_gen_object_list(object_assignment: ObjectAssignment, *, object_cla)item_class_name = object_assignment.object_class_nameitem_class = resolve_object_class(object_assignment=object_assignment, object_class=object_class)-- class ListSchema(BaseModel):- items: list[item_class] # type: ignore[valid-type] # pyright: ignore[reportInvalidTypeForm]-- ListSchema.__name__ = f"ListOf{item_class_name}"-- if item_class.__doc__:- ListSchema.__doc__ = f"List wrapper for {item_class_name}.\n\nItem description:\n{item_class.__doc__}"- else:- ListSchema.__doc__ = f"A list of {item_class_name}."+ list_schema = make_object_list_schema(item_class=item_class, item_class_name=item_class_name)dump_prompt(llm_prompt=llm_job.llm_prompt)- wrapped_list: ListSchema = await llm_worker.gen_object(+ wrapped_list = await llm_worker.gen_object(llm_job=llm_job,- schema=ListSchema,+ schema=list_schema,)dump_response_from_text_gen(response=wrapped_list)- generated_list: list[BaseModel] = cast("list[BaseModel]", wrapped_list.items) # pyright: ignore[reportUnknownMemberType]+ # The wrapper's one field, which `make_object_list_schema` declares.+ generated_list: list[BaseModel] = cast("list[BaseModel]", wrapped_list.items) # type: ignore[attr-defined] # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType]return generated_listdiff --git a/pipelex/cogt/content_generation/render_generate.py b/pipelex/cogt/content_generation/render_generate.pyindex 6be57d6b2..31bd2f913 100644--- a/pipelex/cogt/content_generation/render_generate.py+++ b/pipelex/cogt/content_generation/render_generate.py@@ -12,6 +12,7 @@ from pipelex.cogt.content_generation.generated_content_factory import GeneratedCfrom pipelex.cogt.content_generation.read_authorization import authorize_assignment_readsfrom pipelex.cogt.image.generated_image import GeneratedImageRawDetailsfrom pipelex.core.stuffs.image_content import ImageContent+from pipelex.tools.misc.file_fetch_utils import fetching_for_inputfrom pipelex.tools.misc.image_utils import ImageFormat@@ -32,10 +33,11 @@ async def render_page_views_and_store(# Deferred import: avoid pulling the pdf rendering SDK at module-load timefrom pipelex.tools.pdf.pypdfium2_renderer import pypdfium2_renderer # ruff: ignore[import-outside-top-level]- page_view_images = await pypdfium2_renderer.render_pdf_pages_from_uri(- pdf_uri=render_assignment.document_uri,- dpi=render_assignment.page_views_dpi,- )+ with fetching_for_input(input_name=render_assignment.input_name):+ page_view_images = await pypdfium2_renderer.render_pdf_pages_from_uri(+ pdf_uri=render_assignment.document_uri,+ dpi=render_assignment.page_views_dpi,+ )image_contents: list[ImageContent] = []for page_view_image in page_view_images:raw_details = GeneratedImageRawDetails.make_from_pil_image(diff --git a/pipelex/cogt/document/prompt_document.py b/pipelex/cogt/document/prompt_document.pyindex 3ad3beca2..62ff3789d 100644--- a/pipelex/cogt/document/prompt_document.py+++ b/pipelex/cogt/document/prompt_document.py@@ -29,11 +29,17 @@ from pipelex.tools.uri.uri_resolver import resolve_uriclass PromptDocumentUri(BaseModel):- """A prompt document specified by URI (path, URL, storage URI, or data URL)."""+ """A prompt document specified by URI (path, URL, storage URI, or data URL).++ ``input_name`` is the input the document came from, as a caller writes it (``photos[2]``), when the prompt reads it+ from one: a fetch of its URL that fails names that input, since the failure never names the URL, which is the+ run's data.+ """kind: Literal["uri"] = "uri"uri: strmime_type: str | None = None+ input_name: str | None = None@field_validator("uri", mode="before")@classmethoddiff --git a/pipelex/cogt/document/prompt_document_factory.py b/pipelex/cogt/document/prompt_document_factory.pyindex d619c49a1..dea318010 100644--- a/pipelex/cogt/document/prompt_document_factory.py+++ b/pipelex/cogt/document/prompt_document_factory.py@@ -16,7 +16,13 @@ from pipelex.tools.misc.base64_utils import (class PromptDocumentFactory:@classmethoddef make_prompt_document(- cls, *, uri: str | None = None, base64_data: str | None = None, raw_bytes: bytes | None = None, mime_type: str | None = None+ cls,+ *,+ uri: str | None = None,+ base64_data: str | None = None,+ raw_bytes: bytes | None = None,+ mime_type: str | None = None,+ input_name: str | None = None,) -> PromptDocument:"""Create a PromptDocument from the provided input.@@ -27,6 +33,8 @@ class PromptDocumentFactory:mime_type: The document's MIME type, as run setup established it or the caller declared it.For inline bytes it refines what the bytes alone identify; a data URL's own type isthe fallback.+ input_name: The input the document came from, as a caller writes it, which a failed fetch of its URL+ names (only used with a uri other than a data URL, which nothing fetches)Returns:A PromptDocument instance (PromptDocumentUri, PromptDocumentBase64, or PromptDocumentBinary)@@ -45,6 +53,6 @@ class PromptDocumentFactory:if extracted is not None:extracted_base64_data, data_url_mime_type = extractedreturn PromptDocumentBase64(base64_data=extracted_base64_data, mime_type=mime_type or data_url_mime_type)- return PromptDocumentUri(uri=uri, mime_type=mime_type)+ return PromptDocumentUri(uri=uri, mime_type=mime_type, input_name=input_name)msg = "PromptDocumentFactory requires one of: uri, base64_data, or raw_bytes"raise PromptDocumentFactoryError(msg)diff --git a/pipelex/cogt/document/prompt_document_utils.py b/pipelex/cogt/document/prompt_document_utils.pyindex cc1b476be..ca3209cc3 100644--- a/pipelex/cogt/document/prompt_document_utils.py+++ b/pipelex/cogt/document/prompt_document_utils.py@@ -15,7 +15,7 @@ from pipelex.cogt.document.prompt_document import (PromptDocumentUri,)from pipelex.runtime_hub import get_storage_provider-from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx+from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx, fetching_for_inputfrom pipelex.tools.misc.file_utils import load_binary_asyncfrom pipelex.tools.misc.filetype_utils import detect_file_type_from_base64, detect_file_type_from_bytesfrom pipelex.tools.uri.prepared_file import PreparedFile, PreparedFileBase64, PreparedFileHttpUrl@@ -62,7 +62,8 @@ async def prepare_prompt_document(if is_http_url_enabled:prepared = PreparedFileHttpUrl(url=prompt_document.resolved.url)else:- raw_bytes = await fetch_file_from_url_httpx(url=prompt_document.resolved.url)+ with fetching_for_input(input_name=prompt_document.input_name):+ raw_bytes = await fetch_file_from_url_httpx(url=prompt_document.resolved.url)prepared = PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),@@ -140,7 +141,8 @@ async def prepare_prompt_document_as_base64(prompt_document: PromptDocument) ->case PromptDocumentUri():match prompt_document.resolved:case ResolvedHttpUrl():- raw_bytes = await fetch_file_from_url_httpx(url=prompt_document.resolved.url)+ with fetching_for_input(input_name=prompt_document.input_name):+ raw_bytes = await fetch_file_from_url_httpx(url=prompt_document.resolved.url)return PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),diff --git a/pipelex/cogt/extract/extract_worker_abstract.py b/pipelex/cogt/extract/extract_worker_abstract.pyindex f62153c82..fc99e62f2 100644--- a/pipelex/cogt/extract/extract_worker_abstract.py+++ b/pipelex/cogt/extract/extract_worker_abstract.py@@ -14,6 +14,7 @@ from pipelex.cogt.usage.pricing_unit import PricingUnitfrom pipelex.cogt.usage.usage_cost import record_unit_priced_usagefrom pipelex.reporting.reporting_protocol import ReportingProtocolfrom pipelex.system.job_metadata import UnitJobId+from pipelex.tools.misc.exceptions import RemoteFileFetchErrorfrom pipelex.tools.misc.filetype_utils import IMAGE_FORMAT_KEY, describe_file_format, describe_format_keys, format_key_from_mime_typefrom pipelex.tools.uri.resolved_uri import ResolvedHttpUrlfrom pipelex.tools.uri.uri_resolver import resolve_uri@@ -144,6 +145,12 @@ class ExtractWorkerAbstract(InferenceWorkerAbstract):except CogtError as exc:exc.fill_model_and_provider(model_handle=self.inference_model.name, backend_name=self.inference_model.backend_name)raise+ except RemoteFileFetchError as exc:+ # The file to extract could not be fetched. The fetch knows the URL alone; the input it came from is+ # known here, and its code's sentences name it.+ if (input_name := extract_job.extract_input.input_name) is not None:+ exc.with_input(input_name=input_name)+ raisecall_summary.count_pages_extracted(count=len(result.pages))diff --git a/pipelex/cogt/image/prompt_image.py b/pipelex/cogt/image/prompt_image.pyindex 7f13ff412..03b5bf0ef 100644--- a/pipelex/cogt/image/prompt_image.py+++ b/pipelex/cogt/image/prompt_image.py@@ -38,11 +38,17 @@ class PromptImageDetail(StrEnum):class PromptImageUri(BaseModel):- """A prompt image specified by URI (path, URL, storage URI, or data URL)."""+ """A prompt image specified by URI (path, URL, storage URI, or data URL).++ ``input_name`` is the input the image came from, as a caller writes it (``photos[2]``), when the prompt reads it+ from one: a fetch of its URL that fails names that input, since the failure never names the URL, which is the+ run's data.+ """kind: Literal["uri"] = "uri"uri: strmime_type: str | None = None+ input_name: str | None = None@field_validator("uri", mode="before")@classmethoddiff --git a/pipelex/cogt/image/prompt_image_factory.py b/pipelex/cogt/image/prompt_image_factory.pyindex 9eec1e279..685e32833 100644--- a/pipelex/cogt/image/prompt_image_factory.py+++ b/pipelex/cogt/image/prompt_image_factory.py@@ -16,7 +16,13 @@ from pipelex.tools.misc.base64_utils import (class PromptImageFactory:@classmethoddef make_prompt_image(- cls, *, uri: str | None = None, base64_data: str | None = None, raw_bytes: bytes | None = None, mime_type: str | None = None+ cls,+ *,+ uri: str | None = None,+ base64_data: str | None = None,+ raw_bytes: bytes | None = None,+ mime_type: str | None = None,+ input_name: str | None = None,) -> PromptImage:"""Create a PromptImage from the provided input.@@ -26,6 +32,8 @@ class PromptImageFactory:raw_bytes: Raw binary image datamime_type: The image's MIME type when it is known (only used with a uri other than a data URL,whose bytes carry their own type)+ input_name: The input the image came from, as a caller writes it, which a failed fetch of its URL names+ (only used with a uri other than a data URL, which nothing fetches)Returns:A PromptImage instance (PromptImageUri, PromptImageBase64, or PromptImageBinary)@@ -44,6 +52,6 @@ class PromptImageFactory:if extracted is not None:extracted_base64_data, _mime_type = extractedreturn PromptImageBase64(base64_data=extracted_base64_data)- return PromptImageUri(uri=uri, mime_type=mime_type)+ return PromptImageUri(uri=uri, mime_type=mime_type, input_name=input_name)msg = "PromptImageFactory requires one of: uri, base64_data, or raw_bytes"raise PromptImageFactoryError(msg)diff --git a/pipelex/cogt/image/prompt_image_utils.py b/pipelex/cogt/image/prompt_image_utils.pyindex 45753f7a6..a54cebd40 100644--- a/pipelex/cogt/image/prompt_image_utils.py+++ b/pipelex/cogt/image/prompt_image_utils.py@@ -15,7 +15,7 @@ from pipelex.cogt.image.prompt_image import (PromptImageUri,)from pipelex.runtime_hub import get_storage_provider-from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx+from pipelex.tools.misc.file_fetch_utils import fetch_file_from_url_httpx, fetching_for_inputfrom pipelex.tools.misc.file_utils import load_binary_asyncfrom pipelex.tools.misc.filetype_utils import detect_file_type_from_base64, detect_file_type_from_bytesfrom pipelex.tools.uri.prepared_file import PreparedFile, PreparedFileBase64, PreparedFileHttpUrl@@ -62,7 +62,8 @@ async def prepare_prompt_image(if is_http_url_enabled:prepared = PreparedFileHttpUrl(url=prompt_image.resolved.url)else:- raw_bytes = await fetch_file_from_url_httpx(url=prompt_image.resolved.url)+ with fetching_for_input(input_name=prompt_image.input_name):+ raw_bytes = await fetch_file_from_url_httpx(url=prompt_image.resolved.url)prepared = PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),@@ -141,7 +142,8 @@ async def prepare_prompt_image_as_base64(prompt_image: PromptImage) -> PreparedFcase PromptImageUri():match prompt_image.resolved:case ResolvedHttpUrl():- raw_bytes = await fetch_file_from_url_httpx(url=prompt_image.resolved.url)+ with fetching_for_input(input_name=prompt_image.input_name):+ raw_bytes = await fetch_file_from_url_httpx(url=prompt_image.resolved.url)return PreparedFileBase64(base64_data=base64.b64encode(raw_bytes).decode("ascii"),file_type=detect_file_type_from_bytes(raw_bytes),diff --git a/pipelex/cogt/inference/error_classification.py b/pipelex/cogt/inference/error_classification.pyindex e1dba9ed1..e842d041c 100644--- a/pipelex/cogt/inference/error_classification.py+++ b/pipelex/cogt/inference/error_classification.py@@ -15,9 +15,10 @@ from http import HTTPStatusfrom typing import Any, TypeAlias, castimport httpx-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, ValidationErrorfrom pipelex.cogt.inference.provider_name import ProviderName+from pipelex.tools.typing.pydantic_utils import ValidatedType, describe_exception_without_input# SDK exception class-name substrings that identify a network/transport failure# (no HTTP status reached us). Matched case-insensitively against@@ -92,7 +93,11 @@ class ProviderErrorMetadata(BaseModel):sdk_exception_type: str# Human-readable error text from the SDK exception (``str(exc)``). Both the# Classify step (quota / content-policy discrimination) and the Render step- # (message composition) read it, so the Extract step must capture it.+ # (message composition) read it, so the Extract step must capture it. A+ # pydantic ``ValidationError``, which ends instructor's re-asks, is written by+ # its locations and reasons alone: its own text quotes the model's answer. Any+ # other failure to parse that answer, such as instructor's assertion carrying a+ # model's refusal, is written by its class alone.message: str = ""status_code: int | None = Nonerequest_id: str | None = None@@ -438,6 +443,44 @@ def extract_underlying_sdk_exception(instructor_exc: Any) -> BaseException | Nonreturn None+def describe_instructor_failure(*, instructor_exc: BaseException) -> str:+ """Why instructor's structured generation failed, when :func:`extract_underlying_sdk_exception` recovered nothing.++ The worker calls it with the result of that extraction already known to be ``None``: the wrapper's cause is then+ either nothing or a retry error whose last attempt holds no exception, such as tenacity's ``RetryError``, whose text+ is a ``Future``'s representation, a memory address included. Neither ``instructor``'s own text, which is the last+ exception's and quotes the model's answer, nor the cause's is used: the failure is named by the class of the cause,+ or of the wrapper itself when there is none.++ Args:+ instructor_exc: The ``InstructorRetryException`` instructor raised.++ Returns:+ The reason, such as ``RetryError``.+ """+ cause = instructor_exc.__cause__+ return type(cause).__name__ if cause is not None else type(instructor_exc).__name__+++# The exception classes a provider's SDK raises as its own, as a worker catches them.+SdkErrorTypes: TypeAlias = tuple[type[BaseException], ...]+++def _describe_provider_exception(*, exc: BaseException, validated_type: ValidatedType | None, sdk_error_types: SdkErrorTypes | None) -> str:+ """The text a provider's metadata carries for ``exc``, which never quotes the model's answer.++ ``sdk_error_types`` is ``None`` when the worker caught ``exc`` as its SDK's own error: its text is the provider's,+ which the Classify step reads, quota against rate limiting or a content policy, and is kept. A tuple says ``exc``+ was recovered from ``instructor``'s loop, which ends either on the SDK's own error, an instance of one of these+ types, or on a failure to parse the model's answer, whose text can quote that answer: a ``ValidationError`` is+ written by its locations and reasons, located by ``validated_type``, and any other parsing failure by its class+ alone, such as the ``AssertionError`` that ``instructor``'s OpenAI parser raises with the model's refusal in its text.+ """+ if sdk_error_types is not None and not isinstance(exc, (ValidationError, *sdk_error_types)):+ return type(exc).__name__+ return describe_exception_without_input(exc=exc, validated_type=validated_type)++def parse_retry_after_seconds(value: Any) -> float | None:"""Parse a ``Retry-After`` header value into a delay in seconds.@@ -483,9 +526,17 @@ def _provider_error_code_from_body(body: Any) -> str | None:return None-def extract_openai_metadata(exc: BaseException) -> ProviderErrorMetadata:+def extract_openai_metadata(+ exc: BaseException, *, validated_type: ValidatedType | None = None, sdk_error_types: SdkErrorTypes | None = None+) -> ProviderErrorMetadata:"""Distill an OpenAI SDK exception into a ``ProviderErrorMetadata``.+ ``exc`` can also be the exception that ended instructor's re-asks, recovered from its wrapper, for which the worker+ passes its SDK's own error classes as ``sdk_error_types``: an exception of none of them failed to parse the model's+ answer, and its text can quote that answer. The most common, the ``ValidationError`` of the model's last answer, is+ written by its reasons, located by the schema of ``validated_type``, the class the structured generation asked for,+ never by the answer's values, and any other parsing failure by its class alone.+Tolerates the SDK's two exception shapes:- ``APIStatusError`` subclasses (``BadRequestError``, ``RateLimitError``,@@ -521,7 +572,7 @@ def extract_openai_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.OPENAI,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=_describe_provider_exception(exc=exc, validated_type=validated_type, sdk_error_types=sdk_error_types),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -530,9 +581,17 @@ def extract_openai_metadata(exc: BaseException) -> ProviderErrorMetadata:)-def extract_anthropic_metadata(exc: BaseException) -> ProviderErrorMetadata:+def extract_anthropic_metadata(+ exc: BaseException, *, validated_type: ValidatedType | None = None, sdk_error_types: SdkErrorTypes | None = None+) -> ProviderErrorMetadata:"""Distill an Anthropic SDK exception into a ``ProviderErrorMetadata``.+ ``exc`` can also be the exception that ended instructor's re-asks, recovered from its wrapper, for which the worker+ passes its SDK's own error classes as ``sdk_error_types``: an exception of none of them failed to parse the model's+ answer, and its text can quote that answer. The most common, the ``ValidationError`` of the model's last answer, is+ written by its reasons, located by the schema of ``validated_type``, the class the structured generation asked for,+ never by the answer's values, and any other parsing failure by its class alone.+Tolerates the two exception shapes in the Anthropic SDK:- ``APIStatusError`` subclasses expose ``status_code``, ``request_id``,@@ -556,7 +615,7 @@ def extract_anthropic_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.ANTHROPIC,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=_describe_provider_exception(exc=exc, validated_type=validated_type, sdk_error_types=sdk_error_types),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -672,9 +731,17 @@ def _google_provider_error_code_from_details(details: Any) -> str | None:return None-def extract_google_metadata(exc: BaseException) -> ProviderErrorMetadata:+def extract_google_metadata(+ exc: BaseException, *, validated_type: ValidatedType | None = None, sdk_error_types: SdkErrorTypes | None = None+) -> ProviderErrorMetadata:"""Distill a Google GenAI SDK exception into a ``ProviderErrorMetadata``.+ ``exc`` can also be the exception that ended instructor's re-asks, recovered from its wrapper, for which the worker+ passes its SDK's own error classes as ``sdk_error_types``: an exception of none of them failed to parse the model's+ answer, and its text can quote that answer. The most common, the ``ValidationError`` of the model's last answer, is+ written by its reasons, located by the schema of ``validated_type``, the class the structured generation asked for,+ never by the answer's values, and any other parsing failure by its class alone.+Google's exception shape differs from OpenAI/Anthropic:- ``APIError`` (and subclasses ``ClientError`` / ``ServerError``) expose@@ -700,7 +767,7 @@ def extract_google_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.GOOGLE,sdk_exception_type=_resolve_sdk_exception_type(exc, status_code=status_code),- message=str(exc),+ message=_describe_provider_exception(exc=exc, validated_type=validated_type, sdk_error_types=sdk_error_types),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -721,7 +788,7 @@ def extract_azure_metadata(exc: BaseException) -> ProviderErrorMetadata:return _build_azure_metadata(response=getattr(exc, "response", None),sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),)@@ -792,7 +859,7 @@ def extract_fal_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.FAL,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -825,7 +892,7 @@ def extract_huggingface_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.HUGGINGFACE,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -880,7 +947,7 @@ def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.GATEWAY,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -889,9 +956,17 @@ def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata:)-def extract_mistral_metadata(exc: BaseException) -> ProviderErrorMetadata:+def extract_mistral_metadata(+ exc: BaseException, *, validated_type: ValidatedType | None = None, sdk_error_types: SdkErrorTypes | None = None+) -> ProviderErrorMetadata:"""Distill a Mistral SDK exception into a ``ProviderErrorMetadata``.+ ``exc`` can also be the exception that ended instructor's re-asks, recovered from its wrapper, for which the worker+ passes its SDK's own error classes as ``sdk_error_types``: an exception of none of them failed to parse the model's+ answer, and its text can quote that answer. The most common, the ``ValidationError`` of the model's last answer, is+ written by its reasons, located by the schema of ``validated_type``, the class the structured generation asked for,+ never by the answer's values, and any other parsing failure by its class alone.+Tolerates the two shapes the Mistral SDK raises:- ``MistralError`` (and subclasses like ``SDKError``) carry ``status_code``,@@ -928,7 +1003,7 @@ def extract_mistral_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.MISTRAL,sdk_exception_type=_resolve_sdk_exception_type(exc, status_code=status_code),- message=str(exc),+ message=_describe_provider_exception(exc=exc, validated_type=validated_type, sdk_error_types=sdk_error_types),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -994,7 +1069,7 @@ def extract_bedrock_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.BEDROCK,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=status_code,request_id=request_id,retry_after_seconds=retry_after_seconds,@@ -1018,7 +1093,7 @@ def extract_linkup_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.LINKUP,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=None,request_id=None,retry_after_seconds=None,@@ -1088,7 +1163,7 @@ def extract_typesafe_metadata(exc: BaseException) -> ProviderErrorMetadata:return ProviderErrorMetadata(provider=ProviderName.TYPESAFE,sdk_exception_type=type(exc).__name__,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=status_code,request_id=request_id if isinstance(request_id, str) else None,retry_after_seconds=retry_after_seconds,@@ -1130,7 +1205,7 @@ def extract_local_extract_metadata(exc: BaseException, *, provider: ProviderNamereturn ProviderErrorMetadata(provider=provider,sdk_exception_type=normalized_type_name,- message=str(exc),+ message=describe_exception_without_input(exc=exc),status_code=None,request_id=None,retry_after_seconds=None,diff --git a/pipelex/cogt/llm/llm_worker_abstract.py b/pipelex/cogt/llm/llm_worker_abstract.pyindex af4c19dab..1ea5158fd 100644--- a/pipelex/cogt/llm/llm_worker_abstract.py+++ b/pipelex/cogt/llm/llm_worker_abstract.py@@ -14,11 +14,14 @@ from pipelex.cogt.exceptions import (CogtError,CompletionOutputKind,CompletionTruncationLimit,+ InferenceErrorCategory,LLMCapabilityError,+ LLMCompletionError,LLMCompletionRefusedError,LLMCompletionTruncatedError,MaxTokensCeiling,)+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind, describe_instructor_failurefrom pipelex.cogt.inference.inference_call_summary import InferenceCallSummary, InferenceOperationfrom pipelex.cogt.inference.inference_constants import InferenceOutputTypefrom pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract@@ -519,6 +522,36 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):output_tokens=output_tokens,)+ def _make_structured_generation_failure(self, *, api_name: str, schema: type[BaseModel], instructor_exc: BaseException) -> LLMCompletionError:+ """The error of a structured generation `instructor` gave up on, when no exception could be recovered from it.++ Every worker generating objects through `instructor` raises it in that case, `from` the wrapper. Its message names+ the class of the wrapper's cause (`describe_instructor_failure`), never `instructor`'s own text, which is the+ last validation error's and quotes the model's answer, the run's data. The common case, the re-asks ending on a+ refused answer, recovers that `ValidationError` and is classified from it, located by the same schema.++ Args:+ api_name: The provider's API, as the message names it, such as `Anthropic`.+ schema: The class the generation was asked for.+ instructor_exc: The `InstructorRetryException` that ended the generation.++ Returns:+ The error, `runtime.unexpected`, for the worker to raise.+ """+ reason = describe_instructor_failure(instructor_exc=instructor_exc)+ msg = (+ f"{api_name} structured generation via 'instructor' failed with model '{self.inference_model.desc}' "+ f"trying to generate schema '{schema.__name__}': {reason}"+ )+ return LLMCompletionError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CONTACT_SUPPORT,+ detail="Structured generation failed for an unrecognized reason — retry, and report this if it persists",+ ),+ ).with_error_code(CoreCode.RUNTIME_UNEXPECTED)+def _incomplete_output_error(self,*,diff --git a/pipelex/core/memory/input_shaper.py b/pipelex/core/memory/input_shaper.pyindex a4d469526..1093454d5 100644--- a/pipelex/core/memory/input_shaper.py+++ b/pipelex/core/memory/input_shaper.py@@ -55,6 +55,7 @@ from pipelex.core.stuffs.stuff import DictStuff, Stufffrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.stuff_content_factory import StuffContentFactoryfrom pipelex.core.stuffs.stuff_factory import StuffFactory+from pipelex.tools.typing.pydantic_utils import describe_exception_without_input, validation_error_locationsfrom pipelex.tools.uri.uri_resolver import resolve_local_path_reference@@ -127,12 +128,14 @@ class InputKind(StrEnum):return False-def _first_refused_field(*, validation_error: ValidationError) -> str | None:- """The dotted path, inside the value, of the first field a structure's validation refused; ``None`` when it names none."""- errors = validation_error.errors(include_url=False, include_input=False)- if not errors or not errors[0]["loc"]:- return None- return ".".join(str(segment) for segment in errors[0]["loc"])+def _first_refused_field(*, validation_error: ValidationError, structure_class: type[StuffContent]) -> str | None:+ """The dotted path, inside the value, of the first field a structure's validation refused; ``None`` when it names none.++ The path names what the structure's schema names, a key of the value's own written as the placeholder, since such a+ key is the caller's data (see ``validation_error_locations``).+ """+ locations = validation_error_locations(validation_error=validation_error, validated_type=structure_class)+ return locations[0] if locations else Noneclass InputShaper:@@ -812,18 +815,18 @@ class InputShaper:declared class is not a malformed *value*, and reporting it as one pointed the author attheir input instead of at the concept."""+ structure_class = concept_provider.get_structure_class(concept=concept)try:- return StuffContentFactory.make_content_from_value(- stuff_content_subclass=concept_provider.get_structure_class(concept=concept),- value=value,- )+ return StuffContentFactory.make_content_from_value(stuff_content_subclass=structure_class, value=value)except (ValidationError, StuffContentFactoryError) as exc:+ # A ValidationError's own text quotes the value it refused, the run's input: the reason names its fields and+ # reasons alone, and the fields only as far as the structure's schema names them.raise StructureValidationError.make(variable_name=variable_name,declared_concept_ref=stuff_spec.concept.concept_ref,- reason=str(exc),+ reason=describe_exception_without_input(exc=exc, validated_type=structure_class),expected_shape=cls._render_expected_shape(concept_provider=concept_provider, stuff_spec=stuff_spec),- field=_first_refused_field(validation_error=exc) if isinstance(exc, ValidationError) else None,+ field=_first_refused_field(validation_error=exc, structure_class=structure_class) if isinstance(exc, ValidationError) else None,) from exc@classmethod@@ -1157,21 +1160,24 @@ class InputShaper:@classmethoddef _describe_value(cls, value: Any) -> str:- """A short human description of a provided value, for error messages."""+ """A short human description of a provided value, for error messages: its kind and its size, never the value.++ The value is the run's input, which no message carries, since a message reaches the operator's diagnostics and+ the log lines. An object's keys are the caller's text too, so it is described by how many it holds.+ """# bool before int: bool is a subclass of int.if value is None:return "null"if isinstance(value, bool):- return f"a boolean ({str(value).lower()})"+ return "a boolean"if isinstance(value, float) and not math.isfinite(value):- return f"a number JSON cannot hold ({value})"+ return "a number JSON cannot hold, NaN or an infinity"if isinstance(value, str):- return f'a string ("{value[:40]}")'+ return f"a string of {len(value)} character(s)"if isinstance(value, (int, float)):- return f"a number ({value})"+ return "a number"if isinstance(value, list):return f"a list of {len(cast('list[Any]', value))} item(s)"if isinstance(value, dict):- keys = sorted(str(key) for key in cast("dict[Any, Any]", value))- return f"an object with keys [{', '.join(keys)}]"+ return f"an object of {len(cast('dict[Any, Any]', value))} key(s)"return f"a value of type {type(value).__name__}"diff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.pyindex 70d00128f..fb6408231 100644--- a/pipelex/core/memory/working_memory_factory.py+++ b/pipelex/core/memory/working_memory_factory.py@@ -32,7 +32,8 @@ class WorkingMemoryFactory(BaseModel):@classmethoddef make_from_single_stuff(cls, stuff: Stuff) -> WorkingMemory:if not stuff.stuff_name:- msg = f"Cannot make_from_single_stuff because stuff has no name: {stuff}"+ # A stuff's own text carries its content, the run's data: the message names it by its header, its code and concept.+ msg = f"Cannot make_from_single_stuff because stuff has no name: {stuff.header}"raise WorkingMemoryFactoryError(msg)stuff_dict: StuffDict = {stuff.stuff_name: stuff}return WorkingMemory(root=stuff_dict, aliases={MAIN_STUFF_NAME: stuff.stuff_name})@@ -51,7 +52,8 @@ class WorkingMemoryFactory(BaseModel):if not name:if is_ignore_unnamed:continue- msg = f"Stuff {stuff} has no name"+ # A stuff's own text carries its content, the run's data: the message names it by its header, its code and concept.+ msg = f"Stuff {stuff.header} has no name"raise WorkingMemoryFactoryError(msg)stuff_dict[name] = stuffaliases: dict[str, str] = {}@@ -172,13 +174,14 @@ class WorkingMemoryFactory(BaseModel):needed_inputs_for_factory.append(text_typed_named_stuff_spec)except ValidationError as exc:- # Fallback to TextContent when the typed stuff spec fails pydantic validation+ # Fallback to TextContent when the typed stuff spec fails pydantic validation. The spec is the method's+ # own document, no run's data, so its refusal is located as pydantic gives it.log.warning("An input whose concept's structure class could not be used was mocked as text",fields={"stuff_name": named_stuff_spec.variable_name,"concept_ref": named_stuff_spec.concept.concept_ref,- **error_fields(exc=exc),+ **error_fields(exc=exc, is_authored_input=True),},)text_typed_named_stuff_spec = TypedNamedStuffSpec.make_from_named(@@ -281,13 +284,14 @@ class WorkingMemoryFactory(BaseModel):working_memory.add_new_stuff(name=typed_named_stuff_spec.variable_name, stuff=mock_stuff)except (FactoryException, ValidationError) as exc:# Mock build (polyfactory) or content validation (pydantic) failed for this dynamic- # class — fall back to text content. Unexpected errors propagate.+ # class — fall back to text content. Unexpected errors propagate. The refused value is a mock Pipelex+ # built, no run's data, so its refusal is located as pydantic gives it.log.warning("A text stand-in was used for a mock input its structure could not build",fields={"stuff_name": typed_named_stuff_spec.variable_name,"concept_ref": typed_named_stuff_spec.concept.concept_ref,- **error_fields(exc=exc),+ **error_fields(exc=exc, is_authored_input=True),},)# Create fallback text contentdiff --git a/pipelex/core/stuffs/date_content.py b/pipelex/core/stuffs/date_content.pyindex 053ee7620..2659e39e6 100644--- a/pipelex/core/stuffs/date_content.py+++ b/pipelex/core/stuffs/date_content.py@@ -10,6 +10,7 @@ from pipelex.core.stuffs.iso_temporal import parse_iso_date, parse_iso_timefrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.tools.misc.pretty import require_rich_for_renderingfrom pipelex.tools.misc.string_utils import is_numeric_string+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorif TYPE_CHECKING:from pipelex.tools.misc.pretty import PrettyPrintable@@ -48,10 +49,10 @@ class DateContent(StuffContent):# UTC offset — exactly the fidelity loss DT3 forbids ("no silent midnight").if isinstance(value, datetime.datetime):msg = "A Date takes a calendar date and a separate time of day, not a datetime; put the date in `date` and the time and offset in `time`."- raise ValueError(msg) # ruff: ignore[type-check-without-type-error] — must be ValueError so pydantic wraps it into a ValidationError+ raise InputFreeValueError(msg)if isinstance(value, (int, float)) or (isinstance(value, str) and is_numeric_string(value)): # bool is an int subclassmsg = "A Date's date/time must be an ISO 8601 string or a date/time object, never a number (no epoch-seconds)."- raise ValueError(msg)+ raise InputFreeValueError(msg)# A datetime-shaped STRING on the `date` field would be truncated to the calendar date (silently# so at midnight), dropping the stated time and offset — the same DT3 loss as a datetime object.# The `time` field legitimately carries ':' (e.g. "15:40:00"), so this narrows to `date`.@@ -60,7 +61,7 @@ class DateContent(StuffContent):"A Date's `date` field takes a calendar date alone; a string carrying a time ""(e.g. '2026-07-07T00:00:00') would drop it — put the time and offset in `time` instead.")- raise ValueError(msg)+ raise InputFreeValueError(msg)# Parsing the ISO string here — rather than leaving it to the field's own validation — is what# keeps this model usable under the strict validation instructor applies to every LLM response:# a mode="before" validator forfeits pydantic's strict-JSON acceptance of ISO strings, becausediff --git a/pipelex/core/stuffs/image_content.py b/pipelex/core/stuffs/image_content.pyindex be5c7a805..bc51055a2 100644--- a/pipelex/core/stuffs/image_content.py+++ b/pipelex/core/stuffs/image_content.py@@ -10,6 +10,7 @@ from pipelex.tools.jinja2.template_category import TemplateCategoryfrom pipelex.tools.misc.http_utils import validate_url_resource_existsfrom pipelex.tools.misc.pretty import require_rich_for_renderingfrom pipelex.tools.templating.text_format import TextFormat+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorfrom pipelex.tools.uri.uri_resolver import describe_uri, extract_filename_from_uriif TYPE_CHECKING:@@ -35,7 +36,7 @@ class ImageContent(StuffContent):"""Pixel dimensions come from measuring the image, which yields both — a lone one is a bug."""if (self.width is None) != (self.height is None):msg = "An Image carries both width and height, or neither — a lone pixel dimension is not a valid state."- raise ValueError(msg)+ raise InputFreeValueError(msg)return self@model_validator(mode="after")diff --git a/pipelex/core/stuffs/iso_temporal.py b/pipelex/core/stuffs/iso_temporal.pyindex a95692ae4..7774b9aec 100644--- a/pipelex/core/stuffs/iso_temporal.py+++ b/pipelex/core/stuffs/iso_temporal.py@@ -1,6 +1,8 @@import datetimeimport re+from pipelex.tools.typing.validation_exceptions import InputFreeValueError+# The temporal natives accept EXTENDED ISO 8601 only. `date.fromisoformat` / `time.fromisoformat`# (3.11+) additionally accept the basic forms ("20260707", "154000") and the week / ordinal calendars# ("2026-W27-2", "2026-189"): all of those restate the value in a calendar the source did not use, and@@ -12,6 +14,7 @@ import re# The offset's minutes are range-checked here because nothing downstream does it: they are summed into# a timedelta, so `+02:60` would arrive as a silent `+03:00` (an out-of-range offset HOUR does raise,# and the time's own minute/second components are range-checked by `fromisoformat`).+# A refusal names the form it expected and never the value it refused, which is a run's input or a model's answer._EXTENDED_DATE_PATTERN = re.compile(r"\d{4}-\d{2}-\d{2}")_EXTENDED_TIME_PATTERN = re.compile(r"(?P<hour>\d{2}):\d{2}(:\d{2}([.,]\d+)?)?([Zz]|[+-]\d{2}(:[0-5]\d)?)?")@@ -26,18 +29,19 @@ def parse_iso_date(text: str) -> datetime.date:datetime.date: The parsed calendar date.Raises:- ValueError: When the string is not an extended ISO 8601 calendar date. Callers in a pydantic- validator rely on this staying a ValueError, which pydantic wraps into a ValidationError.+ InputFreeValueError: When the string is not an extended ISO 8601 calendar date. Callers in a pydantic+ validator rely on this staying a ValueError, which pydantic wraps into a ValidationError, and its message+ names the form expected, never the value."""if not _EXTENDED_DATE_PATTERN.fullmatch(text):- msg = f"'{text}' is not an extended ISO 8601 calendar date (e.g. '2026-07-07')."- raise ValueError(msg)+ msg = "The value is not an extended ISO 8601 calendar date (e.g. '2026-07-07')."+ raise InputFreeValueError(msg)try:return datetime.date.fromisoformat(text)except ValueError as exc:- msg = f"'{text}' is not a valid ISO 8601 calendar date (e.g. '2026-07-07')."- raise ValueError(msg) from exc+ msg = "The value is not a valid ISO 8601 calendar date (e.g. '2026-07-07')."+ raise InputFreeValueError(msg) from excdef parse_iso_time(text: str) -> datetime.time:@@ -50,22 +54,22 @@ def parse_iso_time(text: str) -> datetime.time:datetime.time: The parsed time of day, carrying the UTC offset when the string states one.Raises:- ValueError: When the string is not an extended ISO 8601 time of day, or uses the end-of-day+ InputFreeValueError: When the string is not an extended ISO 8601 time of day, or uses the end-of-day``24:00`` form. Callers in a pydantic validator rely on this staying a ValueError, which- pydantic wraps into a ValidationError.+ pydantic wraps into a ValidationError, and its message names the form expected, never the value."""match = _EXTENDED_TIME_PATTERN.fullmatch(text)if not match:- msg = f"'{text}' is not an extended ISO 8601 time of day (e.g. '15:40:00' or '15:40:00+02:00')."- raise ValueError(msg)+ msg = "The value is not an extended ISO 8601 time of day (e.g. '15:40:00' or '15:40:00+02:00')."+ raise InputFreeValueError(msg)# ISO 8601's end-of-day 24:00 names the NEXT day's midnight, which a time of day alone cannot# carry. It must be rejected explicitly rather than left to the parser: Python 3.14 silently# returns 00:00 for it (3.11-3.13 raise), so accepting it would move the value back a full day —# and only on some of the interpreters we support.if match.group("hour") == "24":- msg = f"'{text}' uses the ISO 8601 end-of-day form 24:00, which names the next day's midnight; state that day with '00:00:00' instead."- raise ValueError(msg)+ msg = "The value uses the ISO 8601 end-of-day form 24:00, which names the next day's midnight; state that day with '00:00:00' instead."+ raise InputFreeValueError(msg)# `fromisoformat` takes only the upper-case UTC designator, while RFC 3339 states the two spellings# are equivalent and pydantic accepted both before this parser existed. Case-folding the designator# is not normalization of the value — it names the same offset — so admit it rather than refuse a@@ -74,5 +78,5 @@ def parse_iso_time(text: str) -> datetime.time:try:return datetime.time.fromisoformat(parsable)except ValueError as exc:- msg = f"'{text}' is not a valid ISO 8601 time of day (e.g. '15:40:00' or '15:40:00+02:00')."- raise ValueError(msg) from exc+ msg = "The value is not a valid ISO 8601 time of day (e.g. '15:40:00' or '15:40:00+02:00')."+ raise InputFreeValueError(msg) from excdiff --git a/pipelex/core/stuffs/json_content.py b/pipelex/core/stuffs/json_content.pyindex fd2a7bb12..f2a9841f5 100644--- a/pipelex/core/stuffs/json_content.py+++ b/pipelex/core/stuffs/json_content.py@@ -8,6 +8,7 @@ from typing_extensions import overridefrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.tools.misc.markdown_utils import convert_to_markdownfrom pipelex.tools.misc.pretty import require_rich_for_rendering+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorif TYPE_CHECKING:from pipelex.tools.misc.pretty import PrettyPrintable@@ -23,11 +24,12 @@ class JSONContent(StuffContent):# A ValueError, never a TypeError: pydantic turns only the former into a ValidationError, so a# dict holding a value that is not JSON is reported like any other invalid content. NaN and the# infinities are refused too, since JSON cannot hold them and serialization would turn them into null.+ # The encoder's complaint names a type, a circular reference or an out-of-range float, never the value.try:json.dumps(value, allow_nan=False)except (TypeError, ValueError) as exc:msg = f"json_obj is not valid JSON: {exc}"- raise ValueError(msg) from exc+ raise InputFreeValueError(msg) from excreturn value@overridediff --git a/pipelex/core/stuffs/number_content.py b/pipelex/core/stuffs/number_content.pyindex 35fbdbb48..45edabf87 100644--- a/pipelex/core/stuffs/number_content.py+++ b/pipelex/core/stuffs/number_content.py@@ -5,6 +5,7 @@ from pydantic import Field, field_validatorfrom typing_extensions import overridefrom pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorclass NumberContent(StuffContent):@@ -17,8 +18,8 @@ class NumberContent(StuffContent):def check_finite(cls, value: float) -> int | float:# NaN and the infinities are not JSON numbers: serialization would turn them into null.if isinstance(value, float) and not math.isfinite(value):- msg = f"number must be finite, got {value}"- raise ValueError(msg)+ msg = "number must be finite, never NaN or an infinity"+ raise InputFreeValueError(msg)return value@propertydiff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.pyindex ad392ce8c..64b1f8ab8 100644--- a/pipelex/core/stuffs/stuff.py+++ b/pipelex/core/stuffs/stuff.py@@ -27,7 +27,7 @@ from pipelex.core.stuffs.text_content import TextContentfrom pipelex.core.stuffs.yes_no_content import YesNoContentfrom pipelex.tools.misc.pretty import PrettyRenderablefrom pipelex.tools.misc.string_utils import pascal_case_to_snake_case-from pipelex.tools.typing.pydantic_utils import CustomBaseModel, format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import CustomBaseModel, format_validation_error_without_inputif TYPE_CHECKING:from pipelex.tools.misc.pretty import PrettyPrintable@@ -149,7 +149,8 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffContelog.verbose(f"A {type(content).__name__} content was validated and converted to {content_type.__name__}")return validated_contentexcept ValidationError as exc:- formatted_error = format_pydantic_validation_error(exc)+ # The content is the run's data: the refusal names its fields and reasons, never its values.+ formatted_error = format_validation_error_without_input(validation_error=exc, validated_type=content_type)raise StuffContentValidationError(original_type=type(content).__name__,target_type=content_type.__name__,diff --git a/pipelex/core/stuffs/stuff_content_factory.py b/pipelex/core/stuffs/stuff_content_factory.pyindex aadb07314..1d56405fe 100644--- a/pipelex/core/stuffs/stuff_content_factory.py+++ b/pipelex/core/stuffs/stuff_content_factory.py@@ -56,15 +56,16 @@ class StuffContentFactory:# down to the basic spellings and the end-of-day 24:00 form. Splitting rather than calling# datetime.fromisoformat is what makes the time half reachable by that parser at all.match = re.fullmatch(r"(?P<date>\d{4}-\d{2}-\d{2})(?:[Tt ](?P<time>.+))?", value)+ # A refusal names the form it expected, never the value, which is the run's input.if not match:- msg = f"Date input '{value}' is not an extended ISO 8601 date or datetime (e.g. '2026-07-07' or '2026-07-07T15:40:00+02:00')."+ msg = "A Date input is not an extended ISO 8601 date or datetime (e.g. '2026-07-07' or '2026-07-07T15:40:00+02:00')."raise StuffContentFactoryError(msg)time_text = match.group("time")try:the_date = parse_iso_date(match.group("date"))the_time = parse_iso_time(time_text) if time_text is not None else Noneexcept ValueError as exc:- msg = f"Date input '{value}' is not an extended ISO 8601 date or datetime (e.g. '2026-07-07' or '2026-07-07T15:40:00+02:00'): {exc}"+ msg = f"A Date input is not an extended ISO 8601 date or datetime (e.g. '2026-07-07' or '2026-07-07T15:40:00+02:00'): {exc}"raise StuffContentFactoryError(msg) from excreturn the_date, the_time@@ -79,7 +80,7 @@ class StuffContentFactory:try:parsed = parse_iso_time(value)except ValueError as exc:- msg = f"Time input '{value}' is not an extended ISO 8601 time of day (e.g. '15:40:00' or '15:40:00+02:00'): {exc}"+ msg = f"A Time input is not an extended ISO 8601 time of day (e.g. '15:40:00' or '15:40:00+02:00'): {exc}"raise StuffContentFactoryError(msg) from excreturn time_subclass(time=parsed)diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.pyindex 11197cf92..3008f0fc5 100644--- a/pipelex/core/stuffs/stuff_factory.py+++ b/pipelex/core/stuffs/stuff_factory.py@@ -1,7 +1,7 @@import datetimefrom pathlib import Pathfrom typing import Any, cast-from urllib.parse import urlsplit, urlunsplit+from urllib.parse import urlsplitimport shortuuidfrom mthds.protocol.pipeline_inputs import StuffContentOrData@@ -20,14 +20,21 @@ from pipelex.core.stuffs.stuff import DictStuff, Stufffrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.core.stuffs.stuff_content_factory import StuffContentFactoryfrom pipelex.core.stuffs.text_content import TextContent+from pipelex.errors.error_codes import error_code_specfrom pipelex.runtime_hub import get_class_registry+from pipelex.tools.storage.storage_provider_abstract import PIPELEX_STORAGE_SCHEMEfrom pipelex.tools.tabular.csv_codec import is_tabular_path, list_content_from_csvfrom pipelex.tools.tabular.exceptions import CsvError-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_input, validation_error_locationsfrom pipelex.tools.uri.resolved_uri import ResolvedLocalPathfrom pipelex.tools.uri.uri_read_scope import authorize_uri_readfrom pipelex.tools.uri.uri_resolver import resolve_uri+# The schemes of the remote locations Pipelex itself reads, which a refusal of a table given at one names. Any other+# scheme is the caller's own text, as free as a url's host or path, since `urlsplit` takes whatever precedes the first+# colon when letters, digits, `+`, `-` and `.` make it up: such a refusal names none.+_NAMED_REMOTE_SCHEMES: frozenset[str] = frozenset({"http", "https", "s3", "gs", PIPELEX_STORAGE_SCHEME.removesuffix("://")})+class StuffBlueprint(BaseModel):stuff_name: str@@ -141,7 +148,11 @@ class StuffFactory:try:the_stuff_content = the_subclass.model_validate(obj=stuff_contents)except ValidationError as exc:- msg = f"Error combining stuffs for concept {concept.code}, stuff named `{name}`: {format_pydantic_validation_error(exc=exc)}"+ # The branches' outputs are the run's data: the refusal names the fields and reasons, never the values.+ msg = (+ f"Error combining stuffs for concept {concept.code}, stuff named `{name}`: "+ f"{format_validation_error_without_input(validation_error=exc, validated_type=the_subclass)}"+ )raise StuffFactoryError(msg).with_error_code(CoreCode.PIPE_OUTPUT_INVALID) from excreturn cls.make_stuff(concept=concept,@@ -150,6 +161,29 @@ class StuffFactory:code=code,)+ @classmethod+ def _make_content_refusal(+ cls, *, name: str | None, concept_ref: str, content_class: type[StuffContent], validation_error: ValidationError, what: str+ ) -> StuffFactoryError:+ """The refusal of an input's content that its concept's class does not validate, ``input.invalid``.++ The content is the run's data: the message names each refused field as far as the class's schema names it, and+ its reason, never the value, and the first refused field is the problem's ``field``.+ """+ reasons = format_validation_error_without_input(validation_error=validation_error, validated_type=content_class)+ msg = (+ f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a dict that should represent a StuffContentOrData "+ f"but {what} does not fit the concept '{concept_ref}': {reasons}"+ )+ locations = validation_error_locations(validation_error=validation_error, validated_type=content_class)+ refused_field = next((location for location in locations if location is not None), None)+ params: dict[str, str] = {}+ if name is not None:+ params["input"] = name+ if refused_field is not None:+ params["field"] = refused_field+ return StuffFactoryError(msg).with_params(**params)+@classmethoddef _try_make_csv_list_stuff(cls,@@ -235,23 +269,13 @@ class StuffFactory:# base64/pipelex-storage url is a non-local ResolvedUri; an `s3://`/`gs://`-style scheme slips# through as a ResolvedLocalPath but keeps `://` in its path, so reject those too.if not isinstance(resolved, ResolvedLocalPath) or "://" in resolved.path:- # Strip query/fragment/userinfo before echoing the url: the message reaches the operator's- # diagnostics and every log line, so a signed/token-bearing url (e.g. an S3 presigned link)- # must not leak its credentials into it. Keep scheme/host/path to identify it.- safe_netloc = url_parts.hostname or ""- try:- safe_port = url_parts.port- except ValueError:- # A malformed/out-of-range port makes the `.port` property raise; don't let that- # ValueError escape (it would bypass this redaction and surface the raw url in a- # traceback). Drop the port from the sanitized display instead.- safe_port = None- if safe_port is not None:- safe_netloc = f"{safe_netloc}:{safe_port}"- safe_url = urlunsplit((url_parts.scheme, safe_netloc, url_parts.path, "", ""))+ # The url is the input's value, which no message carries: it can be a signed link whose query holds a+ # credential, and its host and path are the caller's data. The input's name identifies it, and so does its+ # scheme when it is one Pipelex reads: any other scheme is the caller's own text too.+ in_scheme = f", in the scheme '{url_parts.scheme}'" if url_parts.scheme in _NAMED_REMOTE_SCHEMES else ""msg = (f"CSV input supports local file paths only in v1, but stuff '{name}' for concept "- f"'{concept.concept_ref}' points at a remote/non-local url: {safe_url!r}. "+ 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)@@ -268,7 +292,13 @@ class StuffFactory:read_scope=read_scope,position=f"the table given for input '{name}'" if name is not None else "a table given as an input",)- return list_content_from_csv(Path(resolved.path), row_model=row_model)+ 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)+ raise@classmethoddef _resolve_entry_concept(@@ -362,11 +392,12 @@ class StuffFactory:raise StuffFactoryError(msg)# Check all items are of the same type- for item in list_content.items:+ for item_index, item in enumerate(list_content.items):if not isinstance(item, type(first_item)):+ # The item is the run's data: the message names its position and its type, never its value.msg = (f"Trying to create a Stuff '{name}' from a ListContent of '{type(first_item).__name__}' "- f"but the items are not of the same type. Especially, items {item} is of type {type(item).__name__}. "+ f"but the items are not of the same type: the item at index {item_index} is of type {type(item).__name__}. ""Every items of the list should be an identical type.")raise StuffFactoryError(msg)@@ -431,10 +462,11 @@ class StuffFactory:# Case 1.2: list[str] → ListContent[TextContent] with Text conceptif isinstance(first_item, str):- for item in stuff_content_or_data:+ for item_index, item in enumerate(stuff_content_or_data):if not isinstance(item, str):msg = (- f"Trying to create a Stuff '{name}' from a list of strings but the item {item} is not a string. "+ f"Trying to create a Stuff '{name}' from a list of strings but the item at index {item_index}, "+ f"of type {type(item).__name__}, is not a string. ""Every items of the list should be a identical type. If its a string, everything should be a string.")raise StuffFactoryError(msg)@@ -453,11 +485,11 @@ class StuffFactory:content_class_name = type(first_item).__name__# Check all items are of the same type- for item in stuff_content_or_data:+ for item_index, item in enumerate(stuff_content_or_data):if not isinstance(item, type(first_item)):msg = (f"Trying to create a Stuff '{name}' from a list of '{type(first_item).__name__}' "- f"but the items are not of the same type. Especially, items {item} is of type {type(item).__name__}. "+ f"but the items are not of the same type: the item at index {item_index} is of type {type(item).__name__}. ""Every items of the list should be a identical type. If its a string, everything should be a string.")raise StuffFactoryError(msg)@@ -643,11 +675,17 @@ class StuffFactory:)raise StuffFactoryError(msg).with_error_code(CoreCode.INPUT_WRONG_CONCEPT)+ try:+ dict_content = the_class.model_validate(obj=content)+ except ValidationError as exc:+ raise cls._make_content_refusal(+ name=name, concept_ref=concept.concept_ref, content_class=the_class, validation_error=exc, what="its content"+ ) from excreturn cls.make_stuff(name=name,code=code,concept=concept,- content=the_class.model_validate(obj=content),+ content=dict_content,)# Case 2.2/2.2b/2.4/2.5/2.6: content is a list@@ -673,11 +711,12 @@ class StuffFactory:# Case 2.2/2.2b: list[str]if isinstance(first_item, str):- for item in list_content_2:+ for item_index, item in enumerate(list_content_2):if not isinstance(item, str):msg = (- f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a list of strings but the item {item} "- "is not a string. Every items of the list should be a identical type. If its a string, everything should be a string."+ f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a list of strings but the item at index "+ f"{item_index}, of type {type(item).__name__}, is not a string. "+ "Every items of the list should be a identical type. If its a string, everything should be a string.")raise StuffFactoryError(msg)@@ -714,22 +753,32 @@ class StuffFactory:# Case 2.6: list[dict]if isinstance(first_item, dict):- for item_dict in list_content_2:+ for item_index, item_dict in enumerate(list_content_2):if not isinstance(item_dict, dict):msg = (f"Trying to create a Stuff '{name}' in the inputs of your pipe, from a list of dicts but "- f"the item {item_dict} is not a dict. Every items of the list should be a identical type. "- "If its a dict, everything should be a dict."+ f"the item at index {item_index}, of type {type(item_dict).__name__}, is not a dict. "+ "Every items of the list should be a identical type. If its a dict, everything should be a dict.")raise StuffFactoryError(msg)- # Create StuffContent objects from dicts+ # Create StuffContent objects from dicts, with the class the factory validates each one into+ item_class = get_class_registry().get_class(name=concept.structure_class_name) or TextContentstuff_items: list[StuffContent] = []- for item_dict in list_content_2:- stuff_content = StuffContentFactory.make_stuff_content_from_concept_with_fallback(- concept=concept,- value=item_dict,- )+ for item_index, item_dict in enumerate(list_content_2):+ try:+ stuff_content = StuffContentFactory.make_stuff_content_from_concept_with_fallback(+ concept=concept,+ value=item_dict,+ )+ except ValidationError as exc:+ raise cls._make_content_refusal(+ name=name,+ concept_ref=concept.concept_ref,+ content_class=item_class,+ validation_error=exc,+ what=f"the item at index {item_index} of its content",+ ) from excstuff_items.append(stuff_content)return cls.make_stuff(diff --git a/pipelex/core/stuffs/time_content.py b/pipelex/core/stuffs/time_content.pyindex aa86d1caa..92838596e 100644--- a/pipelex/core/stuffs/time_content.py+++ b/pipelex/core/stuffs/time_content.py@@ -9,6 +9,7 @@ from pipelex.core.stuffs.iso_temporal import parse_iso_timefrom pipelex.core.stuffs.stuff_content import StuffContentfrom pipelex.tools.misc.pretty import require_rich_for_renderingfrom pipelex.tools.misc.string_utils import is_numeric_string+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorif TYPE_CHECKING:from pipelex.tools.misc.pretty import PrettyPrintable@@ -36,10 +37,10 @@ class TimeContent(StuffContent):# accurate "no seconds-since-midnight" wording in place of a generic malformed-ISO one.if isinstance(value, (int, float)) or (isinstance(value, str) and is_numeric_string(value)): # bool is an int subclassmsg = "A Time must be an ISO 8601 string or a time object, never a number (no seconds-since-midnight)."- raise ValueError(msg)+ raise InputFreeValueError(msg)if isinstance(value, datetime.datetime):msg = "A Time takes a time of day alone, not a datetime; use Date for a date with a time."- raise ValueError(msg) # ruff: ignore[type-check-without-type-error] — must be ValueError so pydantic wraps it into a ValidationError+ raise InputFreeValueError(msg)# Parsing the ISO string here — rather than leaving it to the field's own validation — is what# keeps this model usable under the strict validation instructor applies to every LLM response:# a mode="before" validator forfeits pydantic's strict-JSON acceptance of ISO strings, becausediff --git a/pipelex/errors/foreign_raises.py b/pipelex/errors/foreign_raises.pyindex 1194e9567..68606a19b 100644--- a/pipelex/errors/foreign_raises.py+++ b/pipelex/errors/foreign_raises.py@@ -45,8 +45,9 @@ VALIDATOR_DECORATOR_NAMES: frozenset[str] = frozenset()"""Pydantic's decorators, inside which a builtin raise is wrapped by pydantic into its own error."""-VALIDATOR_EXCEPTION_NAMES: frozenset[str] = frozenset({"ValueError", "TypeError", "AssertionError", "PydanticCustomError"})-"""The exceptions pydantic turns into a validation error when a validator raises them."""+VALIDATOR_EXCEPTION_NAMES: frozenset[str] = frozenset({"ValueError", "TypeError", "AssertionError", "PydanticCustomError", "InputFreeValueError"})+"""The exceptions pydantic turns into a validation error when a validator raises them, ``InputFreeValueError`` being the+``ValueError`` whose message holds nothing of the value refused."""DATA_MODEL_DUNDER_NAMES: frozenset[str] = frozenset({@@ -80,12 +81,14 @@ FRAMEWORK_CARRIER_NAMES: frozenset[str] = frozenset("StopIteration","StopAsyncIteration","GeneratorExit",- # Temporal's failure carrier, Jinja's template refusals inside the render budget and the sandbox,+ # Temporal's failure carrier, Jinja's template refusals inside the render budget and the sandbox (the sandbox's+ # own `SandboxRefusalError` being Jinja's `SecurityError` worded twice),# httpcore's refused connection inside the SSRF guard's transport, google-auth's refresh refusal,# kajson's decoder refusal inside the payload decoder, and the print protocol's end of stream."ApplicationError","TemplateError","JinjaSecurityError",+ "SandboxRefusalError","ConnectError","RefreshError","KajsonDecoderError",diff --git a/pipelex/kernel/prompt_assembly.py b/pipelex/kernel/prompt_assembly.pyindex 47ed52929..8eb3f12c8 100644--- a/pipelex/kernel/prompt_assembly.py+++ b/pipelex/kernel/prompt_assembly.py@@ -228,9 +228,17 @@ class PromptFiles:def prompt_images(self) -> list[PromptImage]:"""Every registered image in registry order, each keeping the format its preparation established.- Carrying the MIME type lets the worker check the format instead of guessing it again.+ Carrying the MIME type lets the worker check the format instead of guessing it again, and carrying the input an+ image came from, the first path that registered it, lets a failed fetch of its URL name that input. An image a+ filter registered while the template rendered came from no path the prompt names, and carries none."""- return [PromptImageFactory.make_prompt_image(uri=image.url, mime_type=image.mime_type) for image in self._image_registry.images]+ input_names: dict[int, str] = {}+ for image_path, registry_index in self._image_registry_indices.items():+ input_names.setdefault(registry_index, image_path)+ return [+ PromptImageFactory.make_prompt_image(uri=image.url, mime_type=image.mime_type, input_name=input_names.get(registry_index))+ for registry_index, image in enumerate(self._image_registry.images)+ ]def prompt_documents(self) -> list[PromptDocument]:"""Every referenced document in the order its token numbers it."""@@ -290,6 +298,7 @@ class PromptFiles:self._documents[document_reference.variable_path] = PromptDocumentFactory.make_prompt_document(uri=document_content.url,mime_type=document_content.mime_type,+ input_name=document_reference.variable_path,)def _register_direct_list_documents(self, *, document_reference: DocumentReference, context_provider: ContextProviderAbstract) -> None:@@ -312,9 +321,11 @@ class PromptFiles:if not isinstance(document_item, DocumentContent):msg = f"Item of '{document_reference.variable_path}' is of type '{type(document_item).__name__}', expected DocumentContent"raise PromptContentError(msg).with_error_code(CoreCode.METHOD_WIRING_INVALID)- self._documents[f"{document_reference.variable_path}[{list_position}]"] = PromptDocumentFactory.make_prompt_document(+ document_path = f"{document_reference.variable_path}[{list_position}]"+ self._documents[document_path] = PromptDocumentFactory.make_prompt_document(uri=document_item.url,mime_type=document_item.mime_type,+ input_name=document_path,)diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex 5c773384c..868a13a1c 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -1762,9 +1762,11 @@ class LibraryManager(LibraryManagerAbstract):pipe.validate_once_built()child_library.pipe_library.add_new_pipe(pipe=pipe)except ValidationError as exc:+ # The pipe's blueprint is the dependency author's own document, no run's data: its refusal is+ # located as pydantic gives it.log.warning("A pipe of a dependency could not be loaded",- fields={"dependency_alias": alias, "pipe_code": pipe_code, **error_fields(exc=exc)},+ fields={"dependency_alias": alias, "pipe_code": pipe_code, **error_fields(exc=exc, is_authored_input=True)},)unbuilt_pipe_reasons[pipe_ref] = "; ".join(str(error["msg"]) for error in exc.errors()) or str(exc)except PipeValidationError as exc:diff --git a/pipelex/pipe_operators/compose/structured_content_composer.py b/pipelex/pipe_operators/compose/structured_content_composer.pyindex a9cb72df2..1a9ea95ce 100644--- a/pipelex/pipe_operators/compose/structured_content_composer.py+++ b/pipelex/pipe_operators/compose/structured_content_composer.py@@ -27,7 +27,7 @@ from pipelex.tools.misc.string_utils import find_private_path_segmentfrom pipelex.tools.templating.templating_style import TemplatingStylefrom pipelex.tools.typing.annotation_utils import unwrap_optionalfrom pipelex.tools.typing.class_utils import are_classes_equivalent-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputNativeScalarValue: TypeAlias = str | float | int | bool | datetime.date | datetime.time"""The native Python scalar types a content wrapper can be unwrapped into."""@@ -95,7 +95,8 @@ class StructuredContentComposer:try:return self.output_class.model_validate(field_values)except ValidationError as exc:- formatted_error = format_pydantic_validation_error(exc)+ # The composed values are the run's data: the refusal names the fields, their reasons and their types, never the values.+ formatted_error = format_validation_error_without_input(validation_error=exc, validated_type=self.output_class)field_type_summary = self._build_field_type_summary(field_values)msg = f"Cannot validate {self.output_class.__name__}: {formatted_error}\n{field_type_summary}"raise StructuredContentComposerValidationError(msg) from exc@@ -440,8 +441,9 @@ class StructuredContentComposer:elif isinstance(stuff_content, DateContent):if expected_type is datetime.date:if stuff_content.time is not None:+ # The date is the run's data, so the message says what it carries, never its value.msg = (- f"Cannot copy a Date carrying a time of day ({stuff_content.rendered_plain()}) into a bare `date` field: "+ "Cannot copy a Date carrying a time of day into a bare `date` field: ""it would silently drop the time and its UTC offset. Target a Date-typed field to keep the time.")raise StructuredContentComposerTypeError(msg)@@ -551,7 +553,7 @@ class StructuredContentComposer:content_dict = stuff_content.model_dump(exclude_none=False, serialize_as_any=True)return expected_type.model_validate(content_dict)except ValidationError as exc:- formatted_error = format_pydantic_validation_error(exc)+ formatted_error = format_validation_error_without_input(validation_error=exc, validated_type=expected_type)msg = f"Cannot convert {actual_type.__name__} to {expected_type.__name__}: classes are not compatible. {formatted_error}"raise StructuredContentComposerTypeError(msg) from exc@@ -728,7 +730,7 @@ class StructuredContentComposer:try:expected_type.model_validate(item_dict)except ValidationError as exc:- formatted_error = format_pydantic_validation_error(exc)+ formatted_error = format_validation_error_without_input(validation_error=exc, validated_type=expected_type)msg = f"Cannot convert item[{idx}] from {actual_type.__name__} to {expected_type_name}: {formatted_error}"raise StructuredContentComposerTypeError(msg) from excdiff --git a/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py b/pipelex/pipe_operators/doc_gen/doc_gen_rendering.pyindex 4e8b4b834..6547add83 100644--- a/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py+++ b/pipelex/pipe_operators/doc_gen/doc_gen_rendering.py@@ -6,28 +6,19 @@ print stage renders an HTML template file, which it reads through the method filBoth raise the same errors, worded the same way."""-import refrom typing import Anyfrom jinja2.exceptions import UndefinedErrorfrom mthds.protocol.problem.registry import CoreCode+from pipelex.cogt.templating.template_preprocessor import rewrite_template_sigilsfrom pipelex.cogt.templating.template_rendering import render_templatefrom pipelex.pipe_operators.doc_gen.exceptions import PipeDocGenRunError, PipeDocGenUndefinedValueErrorfrom pipelex.tools.jinja2.exceptions import Jinja2TemplateInvalidError, Jinja2TemplateRenderError+from pipelex.tools.jinja2.jinja2_rendering import template_line_of, undefined_variable_namefrom pipelex.tools.jinja2.template_category import TemplateCategoryfrom pipelex.tools.templating.templating_style import TemplatingStyle-# The name a strict undefined's message says is missing: Jinja2 words it "'name' is undefined", "... has no attribute-# 'name'" or "... has no element 'name'", where what comes before the name can quote an object's class, never a caller's.-_UNDEFINED_NAME_PATTERN = re.compile(r"(?:has no (?:attribute|element) |^)'([^']+)'(?: is undefined)?$")---def undefined_name(*, undefined_error: UndefinedError) -> str | None:- """The name a strict undefined's error says is missing, or ``None`` when its message is not one Jinja2 words."""- match = _UNDEFINED_NAME_PATTERN.search(undefined_error.message or "")- return match.group(1) if match else None-async def render_doc_gen_template(*,@@ -64,15 +55,19 @@ async def render_doc_gen_template(except Jinja2TemplateRenderError as exc:undefined_error = exc.__cause__if isinstance(undefined_error, UndefinedError):- # Raised from Jinja's own error rather than from the tools-layer wrapper, whose message quotes the- # template, so that this is the root fault a verdict or a run's problem names.+ # Raised from Jinja's own error, so that this is the root fault a verdict or a run's problem names. Its text+ # can quote a key of the run's data the template reached for, so the name is given only when the template+ # itself spells it, read off the source Jinja2 compiled, its sigils rewritten, and the line Jinja2 failed at+ # says where.+ variable_name = undefined_variable_name(undefined_error=undefined_error, template_source=rewrite_template_sigils(template))+ what = f"it reads '{variable_name}', which is not defined" if variable_name else "it reads a value that is not defined"+ template_line = template_line_of(render_error=undefined_error)+ where = f" (line {template_line})" if template_line is not None else ""msg = (- f"PipeDocGen '{pipe_code}' could not render its {label}: {undefined_error.message}. "+ f"PipeDocGen '{pipe_code}' could not render its {label}: {what}{where}. ""Every value a document's template reads must exist: check the name against the input's concept, ""or test an optional value first with {% if ... %}.")- raise PipeDocGenUndefinedValueError(msg).with_params(- pipe=pipe_code, variable=undefined_name(undefined_error=undefined_error)- ) from undefined_error+ raise PipeDocGenUndefinedValueError(msg).with_params(pipe=pipe_code, variable=variable_name) from undefined_errormsg = f"PipeDocGen '{pipe_code}' could not render its {label}: {exc}"raise PipeDocGenRunError(msg) from excdiff --git a/pipelex/pipe_operators/func/direct_pipe_func_executor.py b/pipelex/pipe_operators/func/direct_pipe_func_executor.pyindex 6d2706e4f..e311b8b69 100644--- a/pipelex/pipe_operators/func/direct_pipe_func_executor.py+++ b/pipelex/pipe_operators/func/direct_pipe_func_executor.py@@ -86,7 +86,9 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):except Exception as exc:# Case (2), unbounded code: the function is arbitrary user code whose exception surface cannot be# enumerated. Whatever it raised is its failure, a coded Pipelex error a helper raised inside it included.- msg = f"{type(exc).__name__}: {exc}"+ # The message names the exception's class alone: its text is the function's own, which can quote the+ # run's inputs, and `pipe.function_raised` declares no parameter to carry it.+ msg = f"The function raised {type(exc).__name__}"raise PipeFuncRaisedError(msg).with_params(function=function_name) from exc# Outside the function's failure: the kernel's coercion refusing what the function returned is the step's# output failing, `FuncOutputTypeError` with `pipe.output_invalid`, whatever shape it refused.diff --git a/pipelex/pipe_operators/func/exceptions.py b/pipelex/pipe_operators/func/exceptions.pyindex 4f1807440..55617c9f7 100644--- a/pipelex/pipe_operators/func/exceptions.py+++ b/pipelex/pipe_operators/func/exceptions.py@@ -32,9 +32,9 @@ class PipeFuncRaisedError(PipelexError):Raised by the in-process executor from whatever the function's own code raised, so that the step tells a failureof its function from a failure of the seam that runs it: it is ``pipe.function_raised`` whatever the function- raised, a coded Pipelex error included, which rides as its cause. Its message gives the type and the text of the- function's exception, which can carry whatever the process holds, so it reaches the operator alone, as every- message does, and no parameter of its code repeats it.+ raised, a coded Pipelex error included, which rides as its cause. Its message names the class of the function's+ exception and never its text, which is the function's own and can quote the run's inputs or whatever the process+ holds: a message reaches the operator's diagnostics and the logs, and the code declares no parameter for it."""error_code = CoreCode.PIPE_FUNCTION_RAISEDdiff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.pyindex dfd7d88db..f9652ad5a 100644--- a/pipelex/pipe_operators/func/pipe_func.py+++ b/pipelex/pipe_operators/func/pipe_func.py@@ -10,6 +10,7 @@ from pydantic import PrivateAttr, field_validatorfrom typing_extensions import overridefrom pipelex import log+from pipelex.base_exceptions import PipelexErrorfrom pipelex.config import is_pipe_func_sandbox_hostedfrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.memory.working_memory import WorkingMemory@@ -49,6 +50,24 @@ from pipelex.validation_error_types import PipeValidationErrorType_PROCESS_HOLDER = "process"+def _describe_executor_failure(*, exc: BaseException) -> str:+ """What the executor's failure was, named by classes and a code, never by a text.++ What the function raised is named by its class, which the in-process executor marks by raising `PipeFuncRaisedError`+ from it. Any other failure is named by its class, and a Pipelex error by its code as well: an out-of-process+ executor reports a coded Pipelex error whose message can hold the function's own text, and a foreign exception, a+ transport's, can quote it too. The text of either can quote the run's inputs, and no message carries those.+ """+ if isinstance(exc, PipeFuncRaisedError):+ function_exc = exc.__cause__+ if function_exc is None:+ return "The function raised an exception"+ return f"The function raised {type(function_exc).__name__}"+ if isinstance(exc, PipelexError):+ return f"{type(exc).__name__} ({exc.resolve_error_code()})"+ return type(exc).__name__++class PipeFuncOutput(PipeOutput):pass@@ -356,13 +375,12 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):# The message names the step's inputs, never their values: those are this run's content.inputs_desc = ", ".join(self.inputs.root) or "none"output_desc = self.output.to_bundle_representation()- # The function's own exception, which the in-process executor marks as raised by the function.- error_desc = exc.message if isinstance(exc, PipeFuncRaisedError) else f"{type(exc).__name__}: {exc}"+ error_desc = _describe_executor_failure(exc=exc)msg = (f"PipeFunc '{self.code}' failed during execution.\n Expected output: {output_desc}\n Inputs: {inputs_desc}\n\n Error: {error_desc}")- # No parameter carries the function's own exception text, which can carry whatever the- # process holds (a path, a setting, a secret): it rides the operator's diagnostics alone.+ # Neither the message nor a parameter carries the function's own exception text, which can+ # quote the run's inputs or whatever the process holds (a path, a setting, a secret).# The wrapper takes its cause's code. What the function raised reads# `pipe.function_raised` only because an executor marked it so: the in-process executor# raises it as `PipeFuncRaisedError`, and an out-of-process one must report a coded Pipelexdiff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.pyindex cf9cd4dad..47b524eb4 100644--- a/pipelex/pipe_operators/llm/pipe_llm.py+++ b/pipelex/pipe_operators/llm/pipe_llm.py@@ -1,4 +1,4 @@-from typing import TYPE_CHECKING, Any, Literal+from typing import TYPE_CHECKING, Any, Literal, TypeAliasfrom mthds.protocol.problem.registry import CoreCodefrom pydantic import ValidationError@@ -46,7 +46,7 @@ from pipelex.tools.jinja2.exceptions import Jinja2TemplateInvalidErrorfrom pipelex.tools.jinja2.jinja2_unknown_names import find_unknown_filters_and_testsfrom pipelex.tools.misc.string_utils import get_root_from_dotted_pathfrom pipelex.tools.templating.templating_style import TemplatingStyle-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputfrom pipelex.validation_error_types import PipeValidationErrorTypeif TYPE_CHECKING:@@ -54,6 +54,10 @@ if TYPE_CHECKING:from pipelex.kernel.llm_results import StructuringPath+#: A content class, named here because a pipe's `type` field shadows the builtin in its class body.+StuffContentClass: TypeAlias = type[StuffContent]++class PipeLLMOutput(PipeOutput):pass@@ -340,15 +344,16 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):raise self._make_invalid_prompt_error(invalid_template_error=exc, pipe_run_params=pipe_run_params) from excexcept LLMCompletionError as exc:location = self._format_error_location(pipe_run_params=pipe_run_params)- error_details = self._format_llm_error(exc=exc, settings=[llm_setting_main])+ error_details = self._format_llm_error(exc=exc, settings=[llm_setting_main], output_class=output_class)msg = f"Error generating text with LLM {location}: {error_details}"raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from excexcept ValidationError as exc:# Not classified as the caller's fault, here or on the object path below, where an# output the model could not fit to the structure surfaces as `LLMCompletionError`:# whether a model's output fits depends on what the model produced this time.+ # The refused value is the model's answer, the run's data: the message names its fields and reasons alone.location = self._format_error_location(pipe_run_params=pipe_run_params)- error_details = format_pydantic_validation_error(exc)+ error_details = format_validation_error_without_input(validation_error=exc, validated_type=output_class)msg = f"Error generating text content in PipeLLM {location}: {error_details}"raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code).with_error_code(CoreCode.MODEL_OUTPUT_SCHEMA_MISMATCH@@ -381,7 +386,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):raise self._make_invalid_prompt_error(invalid_template_error=exc, pipe_run_params=pipe_run_params) from excexcept LLMCompletionError as exc:location = self._format_error_location(pipe_run_params=pipe_run_params)- error_details = self._format_llm_error(exc=exc, settings=[llm_setting_for_object])+ error_details = self._format_llm_error(exc=exc, settings=[llm_setting_for_object], output_class=output_class)what_failed = "list of objects" if is_multiple_output else "single object"msg = f"Error generating {what_failed} with direct method {location}: {error_details}"raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code) from exc@@ -442,12 +447,15 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):def _format_error_location(self, pipe_run_params: PipeRunParams) -> str:return f"in pipe '{pipe_run_params.pipe_stack_str}'"- def _format_llm_error(self, exc: LLMCompletionError, *, settings: list[LLMSetting]) -> str:- """Format an LLMCompletionError, extracting and formatting any ValidationError in the chain."""+ def _format_llm_error(self, exc: LLMCompletionError, *, settings: list[LLMSetting], output_class: StuffContentClass) -> str:+ """Format an LLMCompletionError, with any ValidationError in its chain written without the model's answer it refused.++ Its locations name what the output's class names, when it is the class the error came from.+ """error_details = str(exc)for current_exc in iter_cause_chain(exc):if isinstance(current_exc, ValidationError):- error_details += f"\n{format_pydantic_validation_error(current_exc)}"+ error_details += f"\n{format_validation_error_without_input(validation_error=current_exc, validated_type=output_class)}"breakreturn f"{error_details}\nLLM settings: {settings}"diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.pyindex 86f162316..b5e3f104e 100644--- a/pipelex/pipe_run/delivery_executor.py+++ b/pipelex/pipe_run/delivery_executor.py@@ -241,7 +241,7 @@ class DeliveryExecutor:# error rides as its fields, never its text or traceback, which quote the values the record held.log.error("The absence record of the main output is malformed",- fields=error_fields(exc=validation_error),+ fields=error_fields(exc=validation_error, validated_type=AbsenceRecord),)return None@@ -314,6 +314,8 @@ class DeliveryExecutor:raw-dict render. A warning is emitted on the fallback path so silent regressionson built-in hydration surface in logs."""+ # The class the content validates into, whose schema names a refusal's locations in the warning.+ structure_class: type[StuffContent] | None = Nonetry:concept_ref = stuff_raw["concept"]if not isinstance(concept_ref, str):@@ -335,6 +337,7 @@ class DeliveryExecutor:fields={"concept_ref": concept_ref, "structure_class_name": concept.structure_class_name},)return None+ structure_class = item_classcontent = hydrate_content(concept=concept, raw_content=stuff_raw["content"])return Stuff(stuff_code=stuff_raw["stuff_code"],@@ -345,7 +348,7 @@ class DeliveryExecutor:except (PipeJobError, ValidationError, KajsonException, KeyError, TypeError) as exc:log.warning("A delivered result could not be hydrated and was rendered raw",- fields=error_fields(exc=exc),+ fields=error_fields(exc=exc, validated_type=structure_class),)return None@@ -527,5 +530,6 @@ class DeliveryExecutor:msg = f"Webhook delivery failed for pipeline_run_id={pipeline_run_id}: HTTP {exc.response.status_code}"raise WebhookDeliveryError(msg) from excexcept httpx.RequestError as exc:- msg = f"Webhook delivery failed for pipeline_run_id={pipeline_run_id}: {exc}"+ # By the failure's class, never its text, which can quote the caller's webhook URL.+ msg = f"Webhook delivery failed for pipeline_run_id={pipeline_run_id}: {type(exc).__name__}"raise WebhookDeliveryError(msg) from excdiff --git a/pipelex/pipe_run/located_failure.py b/pipelex/pipe_run/located_failure.pyindex 1349e92c6..32702001b 100644--- a/pipelex/pipe_run/located_failure.py+++ b/pipelex/pipe_run/located_failure.py@@ -27,7 +27,7 @@ from pydantic import ValidationErrorfrom pipelex.base_exceptions import PipelexError, PipelexUnexpectedError, iter_cause_chainfrom pipelex.errors.problem import PipelexProblem, ProblemView, make_location-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_input# Joins the pipe codes of a failure's path from the entry pipe down to the pipe that failed.PIPE_PATH_SEPARATOR = " → "@@ -111,12 +111,17 @@ def make_unexpected_failure(*, error: Exception) -> PipelexUnexpectedError:"""Stand a `PipelexUnexpectedError` in for an exception that is not a `PipelexError`.Its message names the original class, and it is chained to the original so its traceback- survives. Its message only ever reaches an operator, since a foreign exception's text can carry- anything, a server path or a secret included. A pydantic `ValidationError` keeps the readable- rendering the runner gives one.+ survives. The message becomes the run's `diagnostics.message`, which an operator's webhook+ receives, so it never holds the foreign exception's text, which can carry anything: a key of the+ run's data (`KeyError('[email protected]')`), a value a function was handed, a server path or a+ secret. A pydantic `ValidationError` adds its reasons, which hold none of the values it refused,+ and no location, since the model it came from is not known here."""- detail = format_pydantic_validation_error(error) if isinstance(error, ValidationError) else (str(error) or repr(error))- unexpected_error = PipelexUnexpectedError(f"{type(error).__name__}: {detail}")+ if isinstance(error, ValidationError):+ message = f"{type(error).__name__}: {format_validation_error_without_input(validation_error=error)}"+ else:+ message = type(error).__name__+ unexpected_error = PipelexUnexpectedError(message)unexpected_error.__cause__ = errorunexpected_error.__suppress_context__ = Truereturn unexpected_errordiff --git a/pipelex/pipe_run/pipe_run.py b/pipelex/pipe_run/pipe_run.pyindex ed8037846..a90131388 100644--- a/pipelex/pipe_run/pipe_run.py+++ b/pipelex/pipe_run/pipe_run.py@@ -15,7 +15,7 @@ from pipelex.interpreter_hub import get_concept_library, get_own_pipesfrom pipelex.pipe_run.delivery_assignment import DeliveryAssignment, DeliveryStatusfrom pipelex.pipe_run.delivery_executor import DeliveryExecutorfrom pipelex.pipe_run.exceptions import DeliveryError-from pipelex.pipe_run.located_failure import make_unexpected_failure+from pipelex.pipe_run.located_failure import find_root_fault, make_unexpected_failurefrom pipelex.pipe_run.pipe_run_protocol import PipeRunProtocolfrom pipelex.pipe_run.tracing_assembly import RunTraceEvents, assemble_tracing_on_output, read_run_trace_eventsfrom pipelex.pipeline.build_pipe_io_artifacts import build_pipe_io_artifacts@@ -23,7 +23,7 @@ from pipelex.pipeline.usage_stats_reporting import RunUsageFacts, input_kinds_offrom pipelex.system.usage_stats.usage_stats_client import usage_stats_are_enabledfrom pipelex.system.usage_stats.usage_stats_contract import UsageStatsOutcomefrom pipelex.system.usage_stats.usage_stats_runs import RunInferenceTally, tallying_inference_calls-from pipelex.tools.log.error_fields import error_fields+from pipelex.tools.log.error_fields import ERROR_CODE_FIELD, ERROR_TYPE_FIELD, error_fieldsif TYPE_CHECKING:from pipelex.core.pipes.pipe_output import PipeOutput@@ -32,6 +32,35 @@ if TYPE_CHECKING:from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocol+def _secondary_failure_fields(*, exc: Exception) -> dict[str, str]:+ """The fields of a failure that followed the pipe's own, by its class and, for a Pipelex error, its code.++ Like the line about the pipe's failure, a line about what failed after it never carries the exception's text: a+ delivery's names the caller's webhook URL or the place it stored to, and an ``OSError``'s the file it could not+ close, each the run's data.+ """+ fields = {ERROR_TYPE_FIELD: type(exc).__name__}+ if isinstance(exc, PipelexError):+ fields[ERROR_CODE_FIELD] = str(exc.resolve_error_code())+ return fields+++def _failure_code(*, error: Exception) -> str:+ """The registry code a run's failure reports, read without building its problem, which only a webhook needs.++ A bare exception stands as a fault of ours, ``runtime.unexpected``. A Pipelex error reports the code its cause chain+ resolves to, or, when its root fault carries a problem recovered across a transport boundary, that problem's code,+ as the problem the caller receives does.+ """+ if not isinstance(error, PipelexError):+ return CoreCode.RUNTIME_UNEXPECTED+ root_fault = find_root_fault(error=error)+ recovered = root_fault.recovered_problem() if root_fault is not None else None+ if recovered is not None:+ return recovered.code+ return str(error.resolve_error_code())++WEBHOOK_PROBLEM_FAULT_MESSAGE = "The problem of a failed run could not be built for its webhooks""""The error logged when a failed run's problem raises while it is built for the run's webhooks."""@@ -129,12 +158,21 @@ class PipeRun(PipeRunProtocol):pipeline_run_id=pipeline_run_id,request_id=pipe_job.job_metadata.run_metadata.request_id,)- # The error rides as fields and no traceback: the exception is re-raised below, and its traceback- # belongs to whoever catches it, the CLI or the API's handler, which would otherwise print it twice.+ # The error rides as identifiers and no traceback: the exception is re-raised below, and its traceback+ # belongs to whoever catches it, the CLI or the API's handler, which would otherwise print it twice. The+ # line carries the failure's code and the exception's class, never its text: the text can hold the+ # caller's own words, a function's message or a template's source, and a refused host, which no log line+ # carries, while the problem the caller receives holds them where the code declares them. The code is read+ # without building the problem, which a run with no webhook never builds.# `pipe_code` is the bare code `Pipe run starts` carries for the same pipe, so one query finds both lines.log.error("The execution of a pipe failed",- fields={"pipe_code": pipe_job.pipe.code, "pipe_ref": pipe_job.pipe.pipe_ref, **error_fields(exc=exc)},+ fields={+ "pipe_code": pipe_job.pipe.code,+ "pipe_ref": pipe_job.pipe.pipe_ref,+ ERROR_CODE_FIELD: _failure_code(error=exc),+ ERROR_TYPE_FIELD: type(exc).__name__,+ },)# A security refusal also logs its security event, once, naming the run and never what it refused.emit_security_event_for_run(error=exc, run_metadata=pipe_job.job_metadata.run_metadata)@@ -147,10 +185,11 @@ class PipeRun(PipeRunProtocol):if execution_error is None:raise# A secondary failure rides as fields with no traceback: the execution error is chained onto it, so- # its traceback would print the execution error's text, which can quote the run's inputs.+ # its traceback would print the execution error's text, which can quote the run's inputs. Its own+ # text is not written either: an OSError's names the file of the run's trace.log.error("The graph tracer could not be closed after the pipe execution failed",- fields=error_fields(exc=close_error),+ fields=_secondary_failure_fields(exc=close_error),)# Assemble graph and/or usage onto pipe_output from the single trace-event read. The two@@ -215,9 +254,10 @@ class PipeRun(PipeRunProtocol):if execution_error is None:raise# As fields with no traceback, for the same reason as the tracer's: the execution error is chained onto it.+ # By its code and class, never its text, which names the caller's webhook URL or the store it wrote to.log.error("The delivery also failed after the pipe execution failed",- fields=error_fields(exc=delivery_error),+ fields=_secondary_failure_fields(exc=delivery_error),)if execution_error is not None:diff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.pyindex d29855830..eeaaea07d 100644--- a/pipelex/pipe_run/tracing_assembly.py+++ b/pipelex/pipe_run/tracing_assembly.py@@ -25,6 +25,7 @@ from pipelex.runtime_hub import get_event_log_overridefrom pipelex.system.exceptions import MissingDependencyErrorfrom pipelex.system.job_metadata import RunMetadatafrom pipelex.tools.log.error_fields import error_fields+from pipelex.tools.typing.pydantic_utils import describe_exception_without_inputfrom pipelex.tracing.event_log_factory import make_event_logfrom pipelex.tracing.exceptions import EventLogError, TraceEventModeErrorfrom pipelex.tracing.graphspec_assembler import GraphSpecAssembler@@ -122,9 +123,11 @@ def read_run_trace_events(*, pipeline_run_id: str) -> RunTraceEvents:event_log.close()except (OSError, json.JSONDecodeError, ValidationError, PipelexConfigError, MissingDependencyError, EventLogError) as read_error:log.warning("The trace events of a run could not be read for its tracing assembly", fields=error_fields(exc=read_error))+ # A ValidationError is written by its reasons, never the traced values it quotes, which are the run's data.+ read_failure = describe_exception_without_input(exc=read_error)return RunTraceEvents(events=None,- read_error=f"Tracing assembly failed to read events for pipeline_run_id={pipeline_run_id}: {read_error}",+ read_error=f"Tracing assembly failed to read events for pipeline_run_id={pipeline_run_id}: {read_failure}",)return RunTraceEvents(events=events, read_error=None)@@ -231,7 +234,11 @@ def _assemble_tracing_events(log.debug("Assembled the graph from the trace events", fields={"event_count": len(events)})except (ValidationError, TraceEventModeError) as assembly_error:log.warning("The graph could not be assembled from the trace events", fields=error_fields(exc=assembly_error))- result.graph_assembly_error = f"Graph assembly failed for pipeline_run_id={pipeline_run_id}: {assembly_error}"+ # The error travels on the run's output: a ValidationError is written by its reasons, never the traced values it+ # quotes, which are the run's data.+ result.graph_assembly_error = (+ f"Graph assembly failed for pipeline_run_id={pipeline_run_id}: {describe_exception_without_input(exc=assembly_error)}"+ )return resultdiff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.pyindex 95104ab6d..c821aed1c 100644--- a/pipelex/pipeline/runner.py+++ b/pipelex/pipeline/runner.py@@ -40,7 +40,7 @@ from pipelex.system.storage_scope import LOCAL_STORAGE_SCOPE, LOCAL_USER_IDfrom pipelex.system.telemetry.events import EventName, EventProperty, Outcomefrom pipelex.system.usage_stats.usage_stats_contract import UsageStatsMethodSourcefrom pipelex.system.usage_stats.usage_stats_runs import method_source_scope-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputif TYPE_CHECKING:import asyncio@@ -406,7 +406,11 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):output_name=pipe_job.output_name,) from excexcept ValidationError as exc:- formatted_error = format_pydantic_validation_error(exc)+ # The run's inputs are the caller's data: the message names why they failed, never their values. Each site+ # that validates an input into a known class refuses it there, located by that class's schema; a refusal+ # that reaches this arm came from a model this frame does not know, and a location read without its schema+ # could quote a key of the data, so it is named by its model and its reasons alone.+ formatted_error = format_validation_error_without_input(validation_error=exc)model_name = exc.titlemsg = f"Input validation failed for '{model_name}': {formatted_error}"raise PipeExecutionError(message=msg).with_error_code(CoreCode.INPUT_INVALID) from excdiff --git a/pipelex/providers/anthropic/anthropic_llm_worker.py b/pipelex/providers/anthropic/anthropic_llm_worker.pyindex 4cdddbce1..636de7297 100644--- a/pipelex/providers/anthropic/anthropic_llm_worker.py+++ b/pipelex/providers/anthropic/anthropic_llm_worker.py@@ -53,6 +53,11 @@ if TYPE_CHECKING:from anthropic.types import Message+# The Anthropic SDK's own errors, a call the API refused or that failed in transport: caught as they are,+# and told apart from a failure to parse the model's answer when one of them ends instructor's loop.+_SDK_ERRORS = (APIStatusError, APIConnectionError)++@pydantic_dataclassclass _ThinkingParams:"""Container for thinking-related SDK parameters."""@@ -370,7 +375,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):**self._request_extras_kwargs(llm_job=llm_job, output_desc=InferenceOutputType.TEXT),) as stream:final_message: Message = await stream.get_final_message()- except (APIStatusError, APIConnectionError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_anthropic_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(@@ -518,7 +523,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):# one so transient/capacity/auth errors aren't all flattened to UNKNOWN.underlying_exc = extract_underlying_sdk_exception(instructor_exc=instructor_exc)if underlying_exc is not None:- metadata = extract_anthropic_metadata(underlying_exc)+ metadata = extract_anthropic_metadata(underlying_exc, validated_type=schema, sdk_error_types=_SDK_ERRORS)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)rendered_error = render_inference_error(metadata=metadata,@@ -528,18 +533,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):model_handle=self.inference_model.name,)raise self._with_note(error=rendered_error, note=lowered_max_tokens_note, failure=underlying_exc) from instructor_exc- msg = (- f"Anthropic structured generation via 'instructor' failed with model: {self.inference_model.desc} "- f"trying to generate schema: {schema} with error: {instructor_exc}"- )- fallback_error = LLMCompletionError(- msg,- error_category=InferenceErrorCategory.UNKNOWN,- user_action=UserAction(- kind=UserActionKind.CONTACT_SUPPORT,- detail="Structured generation failed for an unrecognized reason — retry, and report this if it persists",- ),- ).with_error_code(CoreCode.RUNTIME_UNEXPECTED)+ fallback_error = self._make_structured_generation_failure(api_name="Anthropic", schema=schema, instructor_exc=instructor_exc)raise self._with_note(error=fallback_error, note=lowered_max_tokens_note, failure=None) from instructor_excexcept IncompleteOutputException as incomplete_exc:# instructor found the answer stopped at `max_tokens`. When the timeout lowered that limit, a higher one is@@ -556,7 +550,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):max_tokens=effective_max_tokens,max_tokens_ceiling=max_tokens_ceiling,) from incomplete_exc- except (APIStatusError, APIConnectionError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_anthropic_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)rendered_error = render_inference_error(diff --git a/pipelex/providers/fal/fal_factory.py b/pipelex/providers/fal/fal_factory.pyindex 3c2753207..be8b0dcf8 100644--- a/pipelex/providers/fal/fal_factory.py+++ b/pipelex/providers/fal/fal_factory.py@@ -7,6 +7,7 @@ from pipelex.cogt.exceptions import ImgGenGenerationError, InferenceErrorCategorfrom pipelex.cogt.image.generated_image import GeneratedImageRawDetailsfrom pipelex.cogt.image.image_size import ImageSizefrom pipelex.cogt.inference.error_classification import UserAction, UserActionKind+from pipelex.tools.typing.pydantic_utils import describe_exception_without_inputclass FalFactory:@@ -51,7 +52,8 @@ class FalFactory:)generated_image_list.append(generated_image)except (KeyError, TypeError, ValidationError) as exc:- msg = f"Failed to parse image data from fal response: {exc}"+ # The response is the provider's answer, the run's data: a ValidationError is written without its values.+ msg = f"Failed to parse image data from fal response: {describe_exception_without_input(exc=exc)}"raise ImgGenGenerationError(msg,error_category=InferenceErrorCategory.UNKNOWN,diff --git a/pipelex/providers/google/google_llm_worker.py b/pipelex/providers/google/google_llm_worker.pyindex 1e9ea70d0..9b16677ea 100644--- a/pipelex/providers/google/google_llm_worker.py+++ b/pipelex/providers/google/google_llm_worker.py@@ -5,14 +5,11 @@ import httpxfrom google.genai import errors as genai_errorsfrom google.genai import types as genai_typesfrom google.genai.client import Client as GoogleGenAiClient-from mthds.protocol.problem.registry import CoreCodefrom typing_extensions import overridefrom pipelex import log-from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCapabilityError, LLMCompletionError+from pipelex.cogt.exceptions import LLMCapabilityErrorfrom pipelex.cogt.inference.error_classification import (- UserAction,- UserActionKind,extract_google_metadata,extract_underlying_sdk_exception,)@@ -40,6 +37,11 @@ if TYPE_CHECKING:from openai.types.chat import ChatCompletionMessageParam+# The Google GenAI SDK's own errors, a call the API refused or that failed in transport: caught as they are,+# and told apart from a failure to parse the model's answer when one of them ends instructor's loop.+_SDK_ERRORS = (genai_errors.ServerError, genai_errors.ClientError, httpx.TransportError)++class GoogleLLMWorker(LLMWorkerAbstract):# Key into inference.llm.effort_to_budget_maps for manual-thinking budget resolutionreasoning_budget_family: ClassVar[str] = "gemini"@@ -251,7 +253,7 @@ class GoogleLLMWorker(LLMWorkerAbstract):contents=contents,config=generation_config,)- except (genai_errors.ServerError, genai_errors.ClientError, httpx.TransportError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_google_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(@@ -345,7 +347,7 @@ class GoogleLLMWorker(LLMWorkerAbstract):# one so transient/capacity/auth errors aren't all flattened to UNKNOWN.underlying_exc = extract_underlying_sdk_exception(instructor_exc=instructor_exc)if underlying_exc is not None:- metadata = extract_google_metadata(underlying_exc)+ metadata = extract_google_metadata(underlying_exc, validated_type=schema, sdk_error_types=_SDK_ERRORS)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(metadata=metadata,@@ -354,16 +356,8 @@ class GoogleLLMWorker(LLMWorkerAbstract):model_desc=self.inference_model.desc,model_handle=self.inference_model.name,) from instructor_exc- msg = f"Google structured generation failed after retries for model '{self.inference_model.desc}': {instructor_exc}"- raise LLMCompletionError(- msg,- error_category=InferenceErrorCategory.UNKNOWN,- user_action=UserAction(- kind=UserActionKind.CONTACT_SUPPORT,- detail="Structured generation failed for an unrecognized reason — retry, and report this if it persists",- ),- ).with_error_code(CoreCode.RUNTIME_UNEXPECTED) from instructor_exc- except (genai_errors.ServerError, genai_errors.ClientError, httpx.TransportError) as sdk_exc:+ raise self._make_structured_generation_failure(api_name="Google", schema=schema, instructor_exc=instructor_exc) from instructor_exc+ except _SDK_ERRORS as sdk_exc:metadata = extract_google_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(@@ -375,7 +369,7 @@ class GoogleLLMWorker(LLMWorkerAbstract):) from sdk_excif not isinstance(result_object, schema):- msg = f"Google Gemini API returned an object that is not of type {schema}: {result_object}"+ msg = f"Google Gemini API returned an object that is not of type {schema}: a {type(result_object).__name__}"raise GoogleLLMWorkerError(msg)# Track token usage if available from completiondiff --git a/pipelex/providers/mistral/mistral_llm_worker.py b/pipelex/providers/mistral/mistral_llm_worker.pyindex c5e7fb08f..d12b9afc2 100644--- a/pipelex/providers/mistral/mistral_llm_worker.py+++ b/pipelex/providers/mistral/mistral_llm_worker.py@@ -36,6 +36,11 @@ if TYPE_CHECKING:from mistralai.client.types import OptionalNullable+# The Mistral SDK's own errors, a call the API refused or that failed in transport: caught as they are,+# and told apart from a failure to parse the model's answer when one of them ends instructor's loop.+_SDK_ERRORS = (MistralError, httpx.TransportError)++class MistralLLMWorker(LLMWorkerAbstract):def __init__(self,@@ -156,7 +161,7 @@ class MistralLLMWorker(LLMWorkerAbstract):max_tokens=max_tokens,reasoning_effort=reasoning_effort,)- except (MistralError, httpx.TransportError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_mistral_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(@@ -285,7 +290,7 @@ class MistralLLMWorker(LLMWorkerAbstract):# one so transient/capacity/auth errors aren't all flattened to UNKNOWN.underlying_exc = extract_underlying_sdk_exception(instructor_exc=instructor_exc)if underlying_exc is not None:- metadata = extract_mistral_metadata(underlying_exc)+ metadata = extract_mistral_metadata(underlying_exc, validated_type=schema, sdk_error_types=_SDK_ERRORS)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(metadata=metadata,@@ -294,21 +299,13 @@ class MistralLLMWorker(LLMWorkerAbstract):model_desc=self.inference_model.desc,model_handle=self.inference_model.name,) from instructor_exc- msg = f"Mistral structured generation failed after retries for model '{self.inference_model.desc}': {instructor_exc}"- raise LLMCompletionError(- msg,- error_category=InferenceErrorCategory.UNKNOWN,- user_action=UserAction(- kind=UserActionKind.CONTACT_SUPPORT,- detail="Structured generation failed for an unrecognized reason — retry, and report this if it persists",- ),- ).with_error_code(CoreCode.RUNTIME_UNEXPECTED) from instructor_exc+ raise self._make_structured_generation_failure(api_name="Mistral", schema=schema, instructor_exc=instructor_exc) from instructor_excexcept IncompleteOutputException as incomplete_exc:# instructor found the answer's first choice finished on `length`raise self._incomplete_output_error(llm_job=llm_job, last_completion=incomplete_exc.last_completion, max_tokens=max_tokens) from incomplete_exc- except (MistralError, httpx.TransportError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_mistral_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(diff --git a/pipelex/providers/openai/openai_completions_llm_worker.py b/pipelex/providers/openai/openai_completions_llm_worker.pyindex 122502bb7..5b108c9eb 100644--- a/pipelex/providers/openai/openai_completions_llm_worker.py+++ b/pipelex/providers/openai/openai_completions_llm_worker.py@@ -35,6 +35,11 @@ if TYPE_CHECKING:from openai.types.chat import ChatCompletionMessage+# The OpenAI SDK's own errors, a call the API refused or that failed in transport: caught as they are,+# and told apart from a failure to parse the model's answer when one of them ends instructor's loop.+_SDK_ERRORS = (openai.APIStatusError, openai.APIConnectionError)++class OpenAICompletionsLLMWorker(LLMWorkerAbstract):def __init__(self,@@ -154,7 +159,7 @@ class OpenAICompletionsLLMWorker(LLMWorkerAbstract):extra_headers=extra_headers,extra_body=extra_body,)- except (openai.APIStatusError, openai.APIConnectionError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_openai_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(@@ -187,7 +192,8 @@ class OpenAICompletionsLLMWorker(LLMWorkerAbstract):openai_message: ChatCompletionMessage = response.choices[0].messageresponse_text = openai_message.contentif response_text is None:- msg = f"OpenAI response message content is None: {response}\nmodel: {self.inference_model.desc}"+ # The response is the model's answer, the run's data: the message names the model and the finish reason alone.+ msg = f"OpenAI response message content is None (finish reason: {response.choices[0].finish_reason})\nmodel: {self.inference_model.desc}"raise LLMCompletionError(msg,error_category=InferenceErrorCategory.CONTENT,@@ -239,7 +245,7 @@ class OpenAICompletionsLLMWorker(LLMWorkerAbstract):# one so transient/capacity/auth errors aren't all flattened to UNKNOWN.underlying_exc = extract_underlying_sdk_exception(instructor_exc=instructor_exc)if underlying_exc is not None:- metadata = extract_openai_metadata(underlying_exc)+ metadata = extract_openai_metadata(underlying_exc, validated_type=schema, sdk_error_types=_SDK_ERRORS)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(metadata=metadata,@@ -248,19 +254,13 @@ class OpenAICompletionsLLMWorker(LLMWorkerAbstract):model_desc=self.inference_model.desc,model_handle=self.inference_model.name,) from instructor_exc- msg = (- f"OpenAI structured generation via 'instructor' failed with model: {self.inference_model.desc} "- f"trying to generate schema: {schema} with error: {instructor_exc}"- )- raise LLMCompletionError(msg, error_category=InferenceErrorCategory.UNKNOWN).with_error_code(- CoreCode.RUNTIME_UNEXPECTED- ) from instructor_exc+ raise self._make_structured_generation_failure(api_name="OpenAI", schema=schema, instructor_exc=instructor_exc) from instructor_excexcept IncompleteOutputException as incomplete_exc:# instructor found the answer's first choice finished on `length`raise self._incomplete_output_error(llm_job=llm_job, last_completion=incomplete_exc.last_completion, max_tokens=job_params.max_tokens) from incomplete_exc- except (openai.APIStatusError, openai.APIConnectionError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_openai_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(diff --git a/pipelex/providers/openai/openai_responses_llm_worker.py b/pipelex/providers/openai/openai_responses_llm_worker.pyindex f8f22ff34..f9c2e4a4b 100644--- a/pipelex/providers/openai/openai_responses_llm_worker.py+++ b/pipelex/providers/openai/openai_responses_llm_worker.py@@ -46,6 +46,11 @@ if TYPE_CHECKING:from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar+# The OpenAI SDK's own errors, a call the API refused or that failed in transport: caught as they are,+# and told apart from a failure to parse the model's answer when one of them ends instructor's loop.+_SDK_ERRORS = (openai.APIStatusError, openai.APIConnectionError)++class OpenAIResponsesLLMWorker(LLMWorkerAbstract):def __init__(self,@@ -164,7 +169,7 @@ class OpenAIResponsesLLMWorker(LLMWorkerAbstract):extra_headers=extra_headers,extra_body=extra_body,)- except (openai.APIStatusError, openai.APIConnectionError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_openai_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(@@ -189,7 +194,8 @@ class OpenAIResponsesLLMWorker(LLMWorkerAbstract):)if not response.output_text:- msg = f"OpenAI Responses message content is empty: {response}\nmodel: {self.inference_model.desc}"+ # The response is the model's answer, the run's data: the message names the model and the status alone.+ msg = f"OpenAI Responses message content is empty (status: {response.status})\nmodel: {self.inference_model.desc}"raise LLMCompletionError(msg,error_category=InferenceErrorCategory.CONTENT,@@ -258,7 +264,7 @@ class OpenAIResponsesLLMWorker(LLMWorkerAbstract):# one so transient/capacity/auth/not-found errors aren't flattened to UNKNOWN.underlying_exc = extract_underlying_sdk_exception(instructor_exc=instructor_exc)if underlying_exc is not None:- metadata = extract_openai_metadata(underlying_exc)+ metadata = extract_openai_metadata(underlying_exc, validated_type=schema, sdk_error_types=_SDK_ERRORS)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(metadata=metadata,@@ -267,14 +273,10 @@ class OpenAIResponsesLLMWorker(LLMWorkerAbstract):model_desc=self.inference_model.desc,model_handle=self.inference_model.name,) from instructor_exc- msg = (- f"OpenAI structured generation via 'instructor' failed with model: {self.inference_model.desc} "- f"trying to generate schema: {schema} with error: {instructor_exc}"- )- raise LLMCompletionError(msg, error_category=InferenceErrorCategory.UNKNOWN).with_error_code(- CoreCode.RUNTIME_UNEXPECTED+ raise self._make_structured_generation_failure(+ api_name="OpenAI Responses", schema=schema, instructor_exc=instructor_exc) from instructor_exc- except (openai.APIStatusError, openai.APIConnectionError) as sdk_exc:+ except _SDK_ERRORS as sdk_exc:metadata = extract_openai_metadata(sdk_exc)classification = classify_inference_error(metadata, family=InferenceErrorFamily.LLM)raise render_inference_error(diff --git a/pipelex/runtime_bridge/primitives/hydration.py b/pipelex/runtime_bridge/primitives/hydration.pyindex 1f8c7d446..72daec285 100644--- a/pipelex/runtime_bridge/primitives/hydration.py+++ b/pipelex/runtime_bridge/primitives/hydration.py@@ -23,6 +23,7 @@ from pipelex.libraries.concept.exceptions import ConceptLibraryErrorfrom pipelex.libraries.exceptions import LibraryErrorfrom pipelex.pipe_run.exceptions import PipeJobErrorfrom pipelex.runtime_hub import get_class_registry+from pipelex.tools.typing.pydantic_utils import describe_exception_without_inputdef _validate_as_known_class(*, item_class: type[StuffContent], raw_item: StuffContent | dict[str, Any]) -> StuffContent:@@ -245,8 +246,13 @@ def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory:raw_root = working_memory_raw.get("root", {})for stuff_name, stuff_dict in raw_root.items():+ # The class the content is validated into, once its concept is known, whose schema locates a refusal.+ structure_class: type[StuffContent] | None = Nonetry:concept = resolve_stuff_concept(concept_ref=stuff_dict["concept"], stuff_name=stuff_name, concept_provider=concept_provider)+ registered_class = get_class_registry().get_class(name=concept.structure_class_name)+ if registered_class is not None and issubclass(registered_class, StuffContent):+ structure_class = registered_classcontent = hydrate_content(concept=concept, raw_content=stuff_dict["content"])stuff = Stuff(stuff_code=stuff_dict["stuff_code"],@@ -258,7 +264,9 @@ def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory:msg = f"Failed to hydrate stuff '{stuff_name}': missing key {exc} in raw dict"raise PipeJobError(msg) from excexcept (ValidationError, KajsonException) as exc:- msg = f"Failed to hydrate stuff '{stuff_name}': {exc}"+ # The content is the run's data: a ValidationError is written by its reasons, never its values, each located+ # as far as the schema of the class the content is validated into names it.+ msg = f"Failed to hydrate stuff '{stuff_name}': {describe_exception_without_input(exc=exc, validated_type=structure_class)}"raise PipeJobError(msg) from excworking_memory.root[stuff_name] = stuff@@ -269,7 +277,7 @@ def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory:try:working_memory.absences[absence_name] = AbsenceRecord.model_validate(absence_raw)except ValidationError as exc:- msg = f"Failed to hydrate absence record '{absence_name}': {exc}"+ msg = f"Failed to hydrate absence record '{absence_name}': {describe_exception_without_input(exc=exc, validated_type=AbsenceRecord)}"raise PipeJobError(msg) from excreturn working_memorydiff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.pyindex c0d102e68..9aee49ac1 100644--- a/pipelex/tools/jinja2/exceptions.py+++ b/pipelex/tools/jinja2/exceptions.py@@ -1,3 +1,4 @@+from jinja2.exceptions import SecurityError as JinjaSecurityErrorfrom mthds.protocol.problem.registry import CoreCodefrom pipelex.base_exceptions import SecurityError@@ -54,9 +55,10 @@ class Jinja2TemplateInvalidError(Jinja2TemplateRenderError):class Jinja2TemplateSecurityError(SecurityError):"""A template reached for something the sandbox policy refuses (`jinja2_sandbox.py`).- That is an undeclared private name, or a call that is not a method of a plain value. Its message names the- attribute or the callable and the type it was reached on, and never quotes the template source, since the same- render serves Pipelex's own templates. On a method's template it is `security.template_refused`, the default; on+ That is an undeclared private name, or a call that is not a method of a plain value. Its message names the type+ the refused name was reached on, and the attribute or the callable only when the parsed template spells it, since+ a name reached by a value is the run's data; it never quotes the template source, since the same render serves+ Pipelex's own templates. On a method's template it is `security.template_refused`, the default; onPipelex's own, our template tripping our sandbox is our bug, `runtime.unexpected`.A `SecurityError`, not a `ToolError`, in the family of `UriReadRefusedError`, `SsrfBlockedError` and@@ -109,3 +111,20 @@ class Jinja2DetectVariablesError(ToolError):"""A template whose variables cannot be read because it does not parse; its callers report the method's syntax."""error_code = CoreCode.METHOD_SYNTAX+++class SandboxRefusalError(JinjaSecurityError):+ """A refusal of the template sandbox (`jinja2_sandbox.py`), worded with the names it quotes and without them.++ It is Jinja2's ``SecurityError``, the carrier Jinja2 expects a refusal by, raised at the point of access. Its message+ names what the template reached for: an attribute it read, the name it stored a callable under in a namespace, the+ 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`).+ """++ def __init__(self, message: str, *, named: tuple[str, ...], anonymous_message: str):+ super().__init__(message)+ self.named = named+ self.anonymous_message = anonymous_messagediff --git a/pipelex/tools/jinja2/jinja2_filters.py b/pipelex/tools/jinja2/jinja2_filters.pyindex f0a3c1167..822104ef5 100644--- a/pipelex/tools/jinja2/jinja2_filters.py+++ b/pipelex/tools/jinja2/jinja2_filters.py@@ -60,11 +60,14 @@ async def text_format(context: Context, value: Any, text_format: TextFormat | stif text_format:# A template can name its own format — `{{ x | format("markdown") }}` — and Jinja2 hands the# argument over as a raw string, so both that and a `TextFormat` member normalise here. An- # unknown name is a template error, reported as one rather than as a bare `ValueError`.+ # unknown name is a template error, reported as one rather than as a bare `ValueError`. The+ # message lists the formats the filter knows, never the name it was handed, which a template+ # can take from the run's data (`{{ x | format(chosen) }}`).try:named_text_format = TextFormat(text_format)except ValueError as exc:- msg = f"Invalid text format: '{text_format}'"+ known_formats = ", ".join(f"'{known_format}'" for known_format in TextFormat)+ msg = f"Invalid text format: the format filter takes one of {known_formats}"raise Jinja2ContextError(msg).with_error_code(CoreCode.METHOD_TEMPLATE_INVALID) from excelse:named_text_format = None@@ -116,9 +119,8 @@ async def tag(context: Context, value: Any, tag_name: str | None = None) -> str:Jinja2ContextError: If value is undefined."""if isinstance(value, Undefined):+ # The tag name is not written: a template can take it from the run's data (`{{ x | tag(label) }}`).msg = "Cannot use tag filter on undefined value"- if tag_name:- msg = f"Cannot use tag filter on undefined value with tag_name '{tag_name}'"raise Jinja2ContextError(msg)# Protocol-based rendering, licensed by the value's type (see renderable_dispatch.py)diff --git a/pipelex/tools/jinja2/jinja2_render_budget.py b/pipelex/tools/jinja2/jinja2_render_budget.pyindex d18b604de..44d6bc98c 100644--- a/pipelex/tools/jinja2/jinja2_render_budget.py+++ b/pipelex/tools/jinja2/jinja2_render_budget.py@@ -34,7 +34,7 @@ import sysfrom collections.abc import AsyncIterator, Iterator, Sizedfrom contextlib import contextmanagerfrom contextvars import ContextVar-from typing import TYPE_CHECKING, Any, Final, Generic, TypeVar, cast+from typing import TYPE_CHECKING, Any, Final, Generic, NamedTuple, TypeVar, castfrom jinja2.exceptions import TemplateErrorfrom jinja2.runtime import LoopContext, Undefined@@ -105,7 +105,41 @@ class RenderBudgetExceededError(TemplateError):Raised from the hook that caught the overdraft, and turned into `Jinja2TemplateBudgetError` by therender functions. It derives from nothing a filter or Jinja's runtime catches on the way.++ Its message names the refused operation, and a call by the method it called, which a template reaching it by+ `obj[key]` or `obj | attr(key)` names by a value of the run's data: `named` holds the names the message quotes and+ `anonymous_message` words it without them, and the render reporting the overdraft keeps the message only when the+ template's own source spells every name, as it does for the sandbox's `SandboxRefusalError`.+ """++ def __init__(self, message: str, *, named: tuple[str, ...] = (), anonymous_message: str | None = None) -> None:+ super().__init__(message)+ self.named = named+ self.anonymous_message = anonymous_message or message+++class DescribedOperation(NamedTuple):+ """An operation the budget may refuse, described with the names it quotes, `text`, and without them, `anonymous_text`.++ A call is described by the callable it calls, whose name is the template's own when it reads it with a dot, but a+ value of the run's data when it reads it by `obj[key]` or `obj | attr(key)`: `named` holds the names `text` quotes.+ """++ text: str+ anonymous_text: str+ named: tuple[str, ...]+++def describe_operation(*, operation: str | Callable[[], str | DescribedOperation]) -> DescribedOperation:+ """The operation a hook charges, its description built only now if the hook gave a function building it.++ A fixed description, such as `the operator '*'` or `the filter 'join'`, quotes no name a value supplied, so it reads+ the same with and without its names."""+ described = operation() if callable(operation) else operation+ if isinstance(described, DescribedOperation):+ return described+ return DescribedOperation(text=described, anonymous_text=described, named=())class RenderBudget:@@ -117,24 +151,24 @@ class RenderBudget:self.total = totalself.remaining = total- def charge(self, *, units: int, operation: str | Callable[[], str]) -> None:+ def charge(self, *, units: int, operation: str | Callable[[], str | DescribedOperation]) -> None:"""Spend `units`, or refuse the operation if they are more than what is left."""if units > self.remaining:self._refuse(units=units, operation=operation)self.remaining -= units- def afford(self, *, units: int, operation: str | Callable[[], str]) -> None:+ def afford(self, *, units: int, operation: str | Callable[[], str | DescribedOperation]) -> None:"""Refuse the operation if its estimate is more than what is left, without spending anything."""if units > self.remaining:self._refuse(units=units, operation=operation)- def _refuse(self, *, units: int, operation: str | Callable[[], str]) -> None:- described = operation() if callable(operation) else operation- msg = (- f"Rendering the template would spend more than its budget of {self.total:,} work units: "- f"{described} needs about {units:,}, and {self.remaining:,} are left."- )- raise RenderBudgetExceededError(msg)+ def _refuse(self, *, units: int, operation: str | Callable[[], str | DescribedOperation]) -> None:+ described = describe_operation(operation=operation)+ preamble = f"Rendering the template would spend more than its budget of {self.total:,} work units"+ overdraft = f"needs about {units:,}, and {self.remaining:,} are left."+ msg = f"{preamble}: {described.text} {overdraft}"+ anonymous_msg = f"{preamble}: {described.anonymous_text} {overdraft}"+ raise RenderBudgetExceededError(msg, named=described.named, anonymous_message=anonymous_msg)_ACTIVE_RENDER_BUDGET: Final[ContextVar[RenderBudget | None]] = ContextVar("pipelex_active_render_budget", default=None)diff --git a/pipelex/tools/jinja2/jinja2_render_charging.py b/pipelex/tools/jinja2/jinja2_render_charging.pyindex f14284953..e7e022bf2 100644--- a/pipelex/tools/jinja2/jinja2_render_charging.py+++ b/pipelex/tools/jinja2/jinja2_render_charging.py@@ -39,11 +39,13 @@ from pipelex.tools.jinja2.jinja2_render_budget import (EAGER_TYPES,ESCAPE_FACTOR,STEP_UNITS,+ DescribedOperation,RenderBudget,charged_if_lazy,charged_iterable,check_int_result,compare_weight,+ describe_operation,is_data_object,produced_size,refuse_int_result,@@ -147,19 +149,22 @@ def _inputs_units(*, values: tuple[Any, ...], keywords: dict[str, Any], step: inreturn units-def _charge_result(*, budget: RenderBudget, result: Any, operation: str | Callable[[], str], produces_int: bool) -> Any:+def _charge_result(*, budget: RenderBudget, result: Any, operation: str | Callable[[], str | DescribedOperation], produces_int: bool) -> Any:if produces_int and type(result) is int:- check_int_result(value=result, operation=operation() if callable(operation) else operation)+ # Only an operator or a filter produces an integer it checks, and neither quotes a name a value supplied.+ check_int_result(value=result, operation=describe_operation(operation=operation).anonymous_text)budget.charge(units=produced_size(result), operation=operation)return result-async def _charge_awaited(*, budget: RenderBudget, pending: Awaitable[Any], operation: str | Callable[[], str], produces_int: bool) -> Any:+async def _charge_awaited(+ *, budget: RenderBudget, pending: Awaitable[Any], operation: str | Callable[[], str | DescribedOperation], produces_int: bool+) -> Any:result = await pendingreturn _charge_result(budget=budget, result=result, operation=operation, produces_int=produces_int)-def _finish(*, budget: RenderBudget, result: Any, operation: str | Callable[[], str], produces_int: bool = False) -> Any:+def _finish(*, budget: RenderBudget, result: Any, operation: str | Callable[[], str | DescribedOperation], produces_int: bool = False) -> Any:"""Charge an operation's result, once awaited when the operation is async."""if type(result) not in EAGER_TYPES and inspect.isawaitable(result):return _charge_awaited(budget=budget, pending=result, operation=operation, produces_int=produces_int)@@ -265,8 +270,12 @@ def _call_inputs_units(*, obj: Any, plain_method: tuple[Any, OperationCost] | Noreturn _inputs_units(values=args, keywords=kwargs, step=CALL_UNITS)-def charged_call(*, context: Context, obj: Any, args: tuple[Any, ...], kwargs: dict[str, Any], operation: Callable[[], str]) -> Any:- """Make a call the sandbox has allowed, charging it to the render's budget."""+def charged_call(*, context: Context, obj: Any, args: tuple[Any, ...], kwargs: dict[str, Any], operation: Callable[[], DescribedOperation]) -> Any:+ """Make a call the sandbox has allowed, charging it to the render's budget.++ `operation` describes the call with the callable's name and without it, since a template reading the callable by+ `obj[key]` or `obj | attr(key)` names it by a value of the run's data; it runs only when the budget refuses.+ """budget = render_budget_of(context)plain_method = _plain_method_cost(obj=obj)bound_value: Any = plain_method[0] if plain_method is not None else Nonediff --git a/pipelex/tools/jinja2/jinja2_rendering.py b/pipelex/tools/jinja2/jinja2_rendering.pyindex 9f0a3edda..06fa3f21d 100644--- a/pipelex/tools/jinja2/jinja2_rendering.py+++ b/pipelex/tools/jinja2/jinja2_rendering.py@@ -1,9 +1,12 @@+import refrom collections.abc import Awaitable, Callable-from typing import Any, Protocol, TypeVar+from typing import Any, NamedTuple, Protocol, TypeVar+from jinja2 import nodesfrom jinja2.exceptions import (FilterArgumentError,SecurityError,+ TemplateAssertionError,TemplateError,TemplateNotFound,TemplateRuntimeError,@@ -21,6 +24,7 @@ from pipelex.tools.jinja2.exceptions import (Jinja2TemplateInvalidError,Jinja2TemplateRenderError,Jinja2TemplateSecurityError,+ SandboxRefusalError,)from pipelex.tools.jinja2.jinja2_environment import (make_jinja2_env_from_registry,@@ -95,7 +99,7 @@ def _compile_jinja2_template(except TemplateSyntaxError as exc:# A filter or test the environment does not define, outside any branch, is a `TemplateAssertionError`# that compiling finds; a method's template is only parsed at load, so this is where it surfaces.- raise _make_invalid_template_error(template_error=exc, template_owner=template_owner) from exc+ raise _make_invalid_template_error(template_error=exc, template_source=template_source, template_owner=template_owner) from excdef _prepare_templating_context(@@ -122,19 +126,130 @@ def _prepare_templating_context(return prepared_templating_context-def _make_type_error_msg(template_source: str, *, templating_context: dict[str, Any], type_error: TypeError) -> str:- context_vars = ", ".join(f"'{key}'" for key in templating_context)- return (- f"Jinja2 render — type error: '{type_error}'. "- f"This often happens when trying to iterate over a method or accessing an attribute incorrectly. "- f"Template source:\n{template_source}\n"- f"Available context variables: {context_vars}"- )+#: The file name Jinja2 gives a template compiled from a string, in the frames it rewrites into a render's traceback.+_TEMPLATE_FRAME_FILENAME = "<template>"++# The name a strict undefined's message says is missing: Jinja2 words it "'name' is undefined", "... has no attribute+# 'name'" or "... has no element 'name'", where what comes before the name can quote an object's class.+_UNDEFINED_NAME_PATTERN = re.compile(r"(?:has no (?:attribute|element) |^)'([^']+)'(?: is undefined)?$")+++def template_line_of(*, render_error: BaseException) -> int | None:+ """The line of the template a render failed at, read off the frame Jinja2 writes for the template in its traceback.++ The innermost such frame is the one that raised. ``None`` when the traceback holds none, such as for a failure+ raised before the render ran.+ """+ template_line: int | None = None+ traceback = render_error.__traceback__+ while traceback is not None:+ if traceback.tb_frame.f_code.co_filename == _TEMPLATE_FRAME_FILENAME:+ template_line = traceback.tb_lineno+ traceback = traceback.tb_next+ return template_line+++class SpelledNames(NamedTuple):+ """The names a template's own source spells, read off the template Jinja2 parses, never off its text.++ ``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``+ 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.+ """++ references: frozenset[str]+ filters_and_tests: frozenset[str]+++def template_spelled_names(*, template_source: str) -> SpelledNames:+ """The names ``template_source`` spells (see ``SpelledNames``), none when it does not parse.++ ``template_source`` is the source Jinja2 compiles, after Pipelex's sigils are rewritten into Jinja2's syntax. Parsing+ runs none of the template.+ """+ jinja2_env = make_jinja2_env_without_loader(template_category=TemplateCategory.BASIC, enable_async=False)+ try:+ parsed_template = jinja2_env.parse(template_source)+ except TemplateSyntaxError:+ 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)+ for node in parsed_template.find_all(spelling_nodes):+ match node:+ 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):+ references.add(attribute)+ case nodes.Keyword(key=str() as key):+ references.add(key)+ case nodes.Getitem(arg=nodes.Const(value=str() as key)) | nodes.Pair(key=nodes.Const(value=str() as key)):+ references.add(key)+ case nodes.Filter(name=str() as filter_name):+ filters_and_tests.add(filter_name)+ # `attr('name')` reaches the attribute a literal names.+ if filter_name == "attr" and node.args and isinstance(node.args[0], nodes.Const) and isinstance(node.args[0].value, str):+ references.add(node.args[0].value)+ case nodes.Test(name=str() as test_name):+ filters_and_tests.add(test_name)+ case _:+ pass+ return SpelledNames(references=frozenset(references), filters_and_tests=frozenset(filters_and_tests))+++def undefined_variable_name(*, undefined_error: UndefinedError, template_source: str) -> str | None:+ """The name an undefined's error says is missing, when the template itself spells it, else ``None``.++ Jinja2 names what a template reached for, which is the template's own name for ``{{ invoice.total }}``, but the+ run's value for ``{{ notes[patient_id] }}``, a key of the data: a name is given only when the parsed template spells+ it as a variable or an attribute (see ``template_spelled_names``), so a key drawn from the data, which no message+ carries, never is, even when the same word appears elsewhere in the template's text. ``template_source`` is the+ source Jinja2 compiled, after Pipelex's sigils are rewritten.+ """+ match = _UNDEFINED_NAME_PATTERN.search(undefined_error.message or "")+ if match is None:+ return None+ name = match.group(1)+ return name if name in template_spelled_names(template_source=template_source).references else None-def _make_security_error_msg(*, security_error: SecurityError) -> str:- # The template source is left out on purpose: the same render serves Pipelex's own templates.- return f"Jinja2 render — refused by the template sandbox: {security_error}"+def _describe_render_error(*, description: str, render_error: BaseException) -> str:+ """A fixed description of a render's failure, with the class Jinja2 or Python raised and the template's line.++ Neither the exception's own text nor the template source is written: Jinja2's and Python's texts can quote a value+ the template reached, which is the run's data, or a name drawn from it, and the source is the method's own text, or+ for Pipelex's own templates the run's data they render.+ """+ template_line = template_line_of(render_error=render_error)+ where = f", at line {template_line} of the template" if template_line is not None else ""+ return f"{description} ({type(render_error).__name__}{where})"+++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``)."""+ 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.++ 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.+ """+ 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+ 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}"# A template nesting macro calls or recursive loops deep enough reaches Python's recursion limit before@@ -142,32 +257,74 @@ def _make_security_error_msg(*, security_error: SecurityError) -> str:_RECURSION_MSG = "Jinja2 render — refused by the render budget: the template nests calls deeper than Python allows."-def _make_budget_error_msg(*, budget_error: RenderBudgetExceededError) -> str:- # Like a refusal, the message names the operation and its size, never the template source or a value.- return f"Jinja2 render — refused by the render budget: {budget_error}"+def _make_budget_error_msg(*, budget_error: RenderBudgetExceededError, template_source: str) -> str:+ """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``).+ """+ 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+ return f"Jinja2 render — refused by the render budget: {refusal}"+++def _make_own_error_msg(*, error_label: str, error: Jinja2StuffError | Jinja2ContextError) -> str:+ # A refusal of Pipelex's own filters, whose message, like every raise site's of Pipelex, holds no run's data: no+ # argument the template handed the filter, which can be a value of the run's, and no value it refused.+ return f"Jinja2 render — {error_label}: '{error}'"+++def _make_undefined_error_msg(*, undefined_error: UndefinedError, template_source: str) -> str:+ variable_name = undefined_variable_name(undefined_error=undefined_error, template_source=template_source)+ description = f"the template reads '{variable_name}', which is not defined" if variable_name else "the template reads a value that is not defined"+ return f"Jinja2 render — undefined error: {_describe_render_error(description=description, render_error=undefined_error)}"+++# How Jinja2 words a filter or a test its environment does not define: "No filter named 'frob'." when it compiles the+# template, "No filter named 'frob' found." when it renders a branch that applies it.+_UNKNOWN_FILTER_OR_TEST_PATTERN = re.compile(r"^No (?P<kind>filter|test) named '(?P<name>[^']+)'")-def _make_non_type_error_msg(- template_source: str,- *,- error_label: str,- error: Jinja2StuffError | UndefinedError | Jinja2ContextError | FilterArgumentError | ArithmeticError,-) -> str:- return f"Jinja2 render — {error_label}: '{error}', template_source:\n{template_source}"+def _describe_template_fault(*, template_error: TemplateError, template_source: str) -> str:+ """What Jinja2 refused in a template, as a fixed description and the template's line, never Jinja2's own text.-def _make_invalid_template_error(*, template_error: TemplateError, template_owner: TemplateOwner) -> Jinja2TemplateInvalidError:+ A syntax error's text quotes the token Jinja2 stopped at (``expected token 'end of print statement', got 'x'``),+ which is the template's text, and the template can be the run's data, as Pipelex's own templates render it: the+ description names the kind of fault and where it is. A filter or a test the environment does not define is named,+ as the author reads it best, when the parsed template applies it by that name.+ """+ unknown = _UNKNOWN_FILTER_OR_TEST_PATTERN.match(template_error.message or "")+ if unknown is not None:+ kind = unknown["kind"]+ if unknown["name"] in template_spelled_names(template_source=template_source).filters_and_tests:+ description = f"No {kind} named '{unknown['name']}'"+ else:+ description = f"the template applies a {kind} its environment does not define"+ elif isinstance(template_error, TemplateAssertionError):+ description = "the template uses a construct Jinja2 refuses where it stands"+ elif isinstance(template_error, TemplateSyntaxError):+ description = "syntax error"+ else:+ description = "the template uses a construct Jinja2 cannot render"+ template_line = template_error.lineno if isinstance(template_error, TemplateSyntaxError) else template_line_of(render_error=template_error)+ where = f" at line {template_line}" if template_line else ""+ return f"{description}{where}."+++def _make_invalid_template_error(*, template_error: TemplateError, template_source: str, template_owner: TemplateOwner) -> Jinja2TemplateInvalidError:"""The error of a template that cannot render as written, coded by its owner.- Its message gives Jinja2's own finding (`TemplateError.message`, which names the filter, test or template the- template reached for), never the template source nor the line Jinja2 would quote with it, so on a method's- template it can be the ``finding`` parameter its problem shows the caller.+ Its message gives what Jinja2 refused as a fixed description and the template's line (see+ ``_describe_template_fault``), never Jinja2's own text, the template source nor the line Jinja2 would quote with+ it, so on a method's template it can be the ``finding`` parameter its problem shows the caller."""if isinstance(template_error, TemplateNotFound):- # A template without a loader (every method template) has nothing to include or extend.- fault = f"template not found: '{template_error.name}'."+ # A template without a loader (every method template) has nothing to include or extend. The name is left out:+ # an include can name its template by a value of the run's data.+ fault = "template not found: the template includes, imports or extends a template it cannot reach."else:- fault = template_error.message or type(template_error).__name__+ fault = _describe_template_fault(template_error=template_error, template_source=template_source)msg = f"Jinja2 render — the template cannot render as written: {fault}"invalid_error = _coded_by_owner(error=Jinja2TemplateInvalidError(msg, fault=fault, template_owner=template_owner), template_owner=template_owner)if template_owner.is_method:@@ -209,7 +366,7 @@ _RENDER_FAILURES: tuple[type[BaseException], ...] = (def _make_render_failure(- *, template_source: str, render_error: BaseException, templating_context: dict[str, Any], template_owner: TemplateOwner+ *, render_error: BaseException, template_source: str, template_owner: TemplateOwner) -> ToolError | Jinja2TemplateSecurityError:"""Translate what a render raised into the error the render reports, coded by the template's owner.@@ -217,12 +374,20 @@ def _make_render_failure(`TemplateRuntimeError`s too, and only what is left of that family, the plain `TemplateRuntimeError` Jinja2 raisesfor the template's own constructs, such as a filter or a test inside a branch that the environment does not define,is the template's fault on any input.++ What Jinja2 or Python raised while rendering is written as a fixed description, its class and the template's line,+ never its own text, which can quote a value the template reached, such as a key of the run's data+ (``'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)+ 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)if isinstance(render_error, (RenderBudgetExceededError, RecursionError)):- budget_msg = _make_budget_error_msg(budget_error=render_error) if isinstance(render_error, RenderBudgetExceededError) else _RECURSION_MSG+ budget_msg = (+ _make_budget_error_msg(budget_error=render_error, template_source=template_source)+ if isinstance(render_error, RenderBudgetExceededError)+ else _RECURSION_MSG+ )match template_owner:case TemplateOwner.METHOD:return Jinja2TemplateBudgetError(budget_msg)@@ -230,53 +395,53 @@ def _make_render_failure(# Pipelex's own template only overspends on data too large to display.return Jinja2TemplateBudgetError(budget_msg).with_error_code(CoreCode.INPUT_TOO_LARGE)if isinstance(render_error, Jinja2ContextError):- msg = _make_non_type_error_msg(template_source=template_source, error_label="context error", error=render_error)+ msg = _make_own_error_msg(error_label="context error", error=render_error)return _make_context_render_error(msg=msg, context_error=render_error, template_owner=template_owner)if isinstance(render_error, Jinja2StuffError):- msg = _make_non_type_error_msg(template_source=template_source, error_label="stuff error", error=render_error)+ msg = _make_own_error_msg(error_label="stuff error", error=render_error)return _make_data_render_error(msg=msg, template_owner=template_owner)if isinstance(render_error, UndefinedError):- msg = _make_non_type_error_msg(template_source=template_source, error_label="undefined error", error=render_error)+ msg = _make_undefined_error_msg(undefined_error=render_error, template_source=template_source)return _make_data_render_error(msg=msg, template_owner=template_owner)if isinstance(render_error, FilterArgumentError):# A filter refusing its argument may be refusing this run's value (`reverse` on a value that is not iterable)# as well as the template's own literal, which nothing here tells apart, so it is not the template's alone.- msg = _make_non_type_error_msg(template_source=template_source, error_label="filter argument error", error=render_error)+ description = "a filter refused its argument"+ msg = f"Jinja2 render — filter argument error: {_describe_render_error(description=description, render_error=render_error)}"return _make_data_render_error(msg=msg, template_owner=template_owner)if isinstance(render_error, (TemplateSyntaxError, TemplateNotFound, TemplateRuntimeError)):- return _make_invalid_template_error(template_error=render_error, template_owner=template_owner)+ return _make_invalid_template_error(template_error=render_error, template_source=template_source, template_owner=template_owner)if isinstance(render_error, ArithmeticError):# The template's own arithmetic, the sandbox's range cap included: `range` raises OverflowError past it.- msg = _make_non_type_error_msg(template_source=template_source, error_label="arithmetic error", error=render_error)+ description = "the template's arithmetic failed, or a range overran the sandbox's limit"+ msg = f"Jinja2 render — arithmetic error: {_describe_render_error(description=description, render_error=render_error)}"return _make_data_render_error(msg=msg, template_owner=template_owner)if isinstance(render_error, TypeError):- msg = _make_type_error_msg(template_source=template_source, templating_context=templating_context, type_error=render_error)+ # Often an iteration over a method, or an attribute reached the wrong way.+ description = "the template applied an operation to a value of a type that does not support it"+ msg = f"Jinja2 render — type error: {_describe_render_error(description=description, render_error=render_error)}"return _make_data_render_error(msg=msg, template_owner=template_owner)msg = f"Jinja2 render — {type(render_error).__name__} is not a failure the render translates"raise PipelexUnexpectedError(msg) from render_errordef _render_template_sync(- template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any], template_owner: TemplateOwner+ *, template: _Jinja2Template, template_source: str, templating_context: dict[str, Any], template_owner: TemplateOwner) -> str:try:generated_text: str = template.render(**templating_context)except _RENDER_FAILURES as exc:- raise _make_render_failure(- template_source=template_source, render_error=exc, templating_context=templating_context, template_owner=template_owner- ) from exc+ raise _make_render_failure(render_error=exc, template_source=template_source, template_owner=template_owner) from excreturn generated_textasync def _render_template_async(- template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any], template_owner: TemplateOwner+ *, template: _Jinja2Template, template_source: str, templating_context: dict[str, Any], template_owner: TemplateOwner) -> str:try:generated_text: str = await template.render_async(**templating_context)except _RENDER_FAILURES as exc:- raise _make_render_failure(- template_source=template_source, render_error=exc, templating_context=templating_context, template_owner=template_owner- ) from exc+ raise _make_render_failure(render_error=exc, template_source=template_source, template_owner=template_owner) from excreturn generated_text@@ -303,8 +468,8 @@ def render_jinja2_sync(template_owner=template_owner,)return _render_template_sync(- template_source=template_source,template=template,+ template_source=template_source,templating_context=prepared_templating_context,template_owner=template_owner,)@@ -339,8 +504,8 @@ async def render_jinja2_async(template_owner=template_owner,)return await _render_template_async(- template_source=template_source,template=template,+ template_source=template_source,templating_context=prepared_templating_context,template_owner=template_owner,)diff --git a/pipelex/tools/jinja2/jinja2_required_variables.py b/pipelex/tools/jinja2/jinja2_required_variables.pyindex 96497e2cf..d24c5b8fd 100644--- a/pipelex/tools/jinja2/jinja2_required_variables.py+++ b/pipelex/tools/jinja2/jinja2_required_variables.py@@ -37,6 +37,27 @@ class VariableReference:filters: list[str] = field(default_factory=list[str])+def _make_detect_variables_error(+ *, parse_error: Jinja2StuffError | TemplateSyntaxError | UndefinedError, template_category: TemplateCategory+) -> Jinja2DetectVariablesError:+ """The error of a template that could not be parsed to find its variables, naming the kind of fault and where.++ Neither the template source, the line of it Jinja2 quotes, nor Jinja2's own message is written: a syntax error's+ message quotes the token Jinja2 stopped at (``expected token 'end of print statement', got 'x'``) and its text ends+ with the line, both the template's text, which is the method's own, or for Pipelex's own templates the run's data+ they render.+ """+ if isinstance(parse_error, TemplateSyntaxError):+ where = f" at line {parse_error.lineno}" if parse_error.lineno else ""+ finding = f"syntax error{where} ({type(parse_error).__name__})"+ elif isinstance(parse_error, UndefinedError):+ finding = f"undefined error ({type(parse_error).__name__})"+ else:+ finding = f"stuff error: '{parse_error}'"+ msg = f"Jinja2 detect variables — {finding}, template_category: {template_category}"+ return Jinja2DetectVariablesError(msg)++def detect_jinja2_required_variables(*,template_category: TemplateCategory,@@ -62,17 +83,8 @@ def detect_jinja2_required_variables(try:parsed_ast = jinja2_env.parse(template_source)- except Jinja2StuffError as stuff_error:- msg = f"Jinja2 detect variables — stuff error: '{stuff_error}', template_category: {template_category}, template_source:\n{template_source}"- raise Jinja2DetectVariablesError(msg) from stuff_error- except TemplateSyntaxError as syntax_error:- msg = f"Jinja2 detect variables — syntax error: '{syntax_error}', template_category: {template_category}, template_source:\n{template_source}"- raise Jinja2DetectVariablesError(msg) from syntax_error- except UndefinedError as undef_error:- msg = (- f"Jinja2 detect variables — undefined error: '{undef_error}', template_category: {template_category}, template_source:\n{template_source}"- )- raise Jinja2DetectVariablesError(msg) from undef_error+ except (Jinja2StuffError, TemplateSyntaxError, UndefinedError) as parse_error:+ raise _make_detect_variables_error(parse_error=parse_error, template_category=template_category) from parse_errorpaths: set[str] = set()@@ -140,17 +152,8 @@ def detect_jinja2_variable_references(try:parsed_ast = jinja2_env.parse(template_source)- except Jinja2StuffError as stuff_error:- msg = f"Jinja2 detect variables — stuff error: '{stuff_error}', template_category: {template_category}, template_source:\n{template_source}"- raise Jinja2DetectVariablesError(msg) from stuff_error- except TemplateSyntaxError as syntax_error:- msg = f"Jinja2 detect variables — syntax error: '{syntax_error}', template_category: {template_category}, template_source:\n{template_source}"- raise Jinja2DetectVariablesError(msg) from syntax_error- except UndefinedError as undef_error:- msg = (- f"Jinja2 detect variables — undefined error: '{undef_error}', template_category: {template_category}, template_source:\n{template_source}"- )- raise Jinja2DetectVariablesError(msg) from undef_error+ except (Jinja2StuffError, TemplateSyntaxError, UndefinedError) as parse_error:+ raise _make_detect_variables_error(parse_error=parse_error, template_category=template_category) from parse_errorreferences: dict[str, VariableReference] = {}diff --git a/pipelex/tools/jinja2/jinja2_sandbox.py b/pipelex/tools/jinja2/jinja2_sandbox.pyindex e2ca68f6c..6165c7e2c 100644--- a/pipelex/tools/jinja2/jinja2_sandbox.py+++ b/pipelex/tools/jinja2/jinja2_sandbox.py@@ -22,10 +22,11 @@ forge content, such as an image pointing at another organisation's storage key.formatter, and the methods a type declares in its template surface. Everything else is refused:pydantic methods, `Stuff` and content methods, classes, free functions and class methods, everymethod 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, which the- render functions turn into `Jinja2TemplateSecurityError`, a Pipelex `SecurityError` like the runtime's- other policy refusals. Jinja's stock sandbox returns an undefined value that prints as nothing, which- would send a prompt with a hole in it.+- **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.- **Spending.** What a template may reach says nothing about what it may spend, so every render alsospends from one budget (`jinja2_render_budget.py`), charged by the hooks of this class, by wrappersaround every filter and test, and by a rewrite of the parsed template for what no hook reaches@@ -54,16 +55,16 @@ import inspectimport typesfrom datetime import date, datetime, time, timedeltafrom decimal import Decimal-from typing import TYPE_CHECKING, Any, NoReturn, cast+from typing import TYPE_CHECKING, Any, NamedTuple, NoReturn, cast-from jinja2.exceptions import SecurityError as JinjaSecurityErrorfrom jinja2.runtime import BlockReference, Context, LoopContext, Macro, Undefinedfrom jinja2.sandbox import ImmutableSandboxedEnvironment, safe_rangefrom jinja2.utils import Cycler, Joiner, Namespace, generate_lorem_ipsumfrom markupsafe import Markupfrom typing_extensions import override-from pipelex.tools.jinja2.jinja2_render_budget import DEFAULT_RENDER_BUDGET_UNITS, active_render_budget, compare_weight+from pipelex.tools.jinja2.exceptions import SandboxRefusalError+from pipelex.tools.jinja2.jinja2_render_budget import DEFAULT_RENDER_BUDGET_UNITS, DescribedOperation, active_render_budget, compare_weightfrom pipelex.tools.jinja2.jinja2_render_charging import (INTERNAL_FILTERS,BudgetedContext,@@ -106,8 +107,11 @@ _PLAIN_VALUE_TYPES: tuple[type, ...] = (def _refuse_callable_in_namespace(*, name: str, value: object) -> None:# An undefined value is callable only so that calling it fails as an undefined value: storing it is harmless.if callable(value) and not isinstance(value, Undefined):- msg = f"A template may not store {_describe_callable(obj=value)} in a namespace, as '{name}': a namespace holds data only."- raise JinjaSecurityError(msg)+ # The name a template stores under can be a value of the run's data (`namespace({key: value})`).+ 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)class DataNamespace(Namespace):@@ -206,23 +210,55 @@ def _is_declared_template_method(*, obj: object) -> bool:return inspect.getattr_static(type(bound_to), obj.__name__, _MISSING) is obj.__func__-def _describe_callable(*, obj: object) -> str:+class _CallableDescription(NamedTuple):+ """A refused callable described with its name, ``text``, and without it, ``anonymous_text``.++ The name is the one a template reached it by when it read it with a dot, but one read by ``obj[key]`` or+ ``obj | attr(key)`` is reached by a value of the run's data: ``named`` holds the names ``text`` quotes. The class a+ value is of is named in both, a name of code.+ """++ text: str+ anonymous_text: str+ named: tuple[str, ...]+++def _describe_callable(*, obj: object) -> _CallableDescription:"""Name a refused callable by what it is and what it was reached on, never by its value's repr."""if isinstance(obj, (types.BuiltinMethodType, types.MethodType)):name = obj.__name__bound_to: object = getattr(obj, "__self__", None)if isinstance(bound_to, type):- return f"the method '{name}' of the class '{bound_to.__name__}'"+ return _CallableDescription(+ text=f"the method '{name}' of the class '{bound_to.__name__}'",+ anonymous_text=f"a method of the class '{bound_to.__name__}'",+ named=(name,),+ )if bound_to is None or isinstance(bound_to, types.ModuleType):- return f"the function '{name}'"- return f"the method '{name}' of a '{type(bound_to).__name__}' value"+ return _CallableDescription(text=f"the function '{name}'", anonymous_text="a function", named=(name,))+ return _CallableDescription(+ text=f"the method '{name}' of a '{type(bound_to).__name__}' value",+ anonymous_text=f"a method of a '{type(bound_to).__name__}' value",+ named=(name,),+ )if isinstance(obj, Macro):- return f"the macro '{obj.name}'"+ return _CallableDescription(text=f"the macro '{obj.name}'", anonymous_text="a macro", named=(obj.name,))if isinstance(obj, type):- return f"the class '{obj.__name__}'"+ return _CallableDescription(text=f"the class '{obj.__name__}'", anonymous_text="a class", named=(obj.__name__,))if isinstance(obj, types.FunctionType):- return f"the function '{obj.__name__}'"- return f"a '{type(obj).__name__}' value"+ return _CallableDescription(text=f"the function '{obj.__name__}'", anonymous_text="a function", named=(obj.__name__,))+ value_description = f"a '{type(obj).__name__}' value"+ return _CallableDescription(text=value_description, anonymous_text=value_description, named=())+++def _describe_call(*, obj: object) -> DescribedOperation:+ """A call the render budget refused, described with the callable's name and without it (see `_describe_callable`)."""+ callable_description = _describe_callable(obj=obj)+ return DescribedOperation(+ text=f"calling {callable_description.text}",+ anonymous_text=f"calling {callable_description.anonymous_text}",+ named=callable_description.named,+ )class PipelexTemplateEnvironment(ImmutableSandboxedEnvironment):@@ -308,8 +344,12 @@ class PipelexTemplateEnvironment(ImmutableSandboxedEnvironment):@overridedef unsafe_undefined(self, obj: Any, attribute: str) -> NoReturn:- msg = f"A template may not read '{attribute}' on a '{type(obj).__name__}' value."- raise JinjaSecurityError(msg)+ # The attribute is the template's own name for `.name`, but a value of the run's data for `obj[key]` or+ # `obj | attr(key)`.+ 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)@overridedef wrap_str_format(self, value: Any) -> Callable[..., str] | None:@@ -323,9 +363,16 @@ class PipelexTemplateEnvironment(ImmutableSandboxedEnvironment):@overridedef call(self, context: Context, obj: Any, /, *args: Any, **kwargs: Any) -> Any:if not self.is_safe_callable(obj):- msg = f"A template may not call {_describe_callable(obj=obj)}: templates read data and call methods of plain values only."- raise JinjaSecurityError(msg)- return charged_call(context=context, obj=obj, args=args, kwargs=kwargs, operation=lambda: f"calling {_describe_callable(obj=obj)}")+ callable_description = _describe_callable(obj=obj)+ msg = f"A template may not call {callable_description.text}: templates read data and call methods of plain values only."+ 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)+ # 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.+ return charged_call(context=context, obj=obj, args=args, kwargs=kwargs, operation=lambda: _describe_call(obj=obj))@overridedef call_binop(self, context: Context, operator: str, left: Any, right: Any) -> Any:diff --git a/pipelex/tools/log/error_fields.py b/pipelex/tools/log/error_fields.pyindex 515b7649d..e58e2a88e 100644--- a/pipelex/tools/log/error_fields.py+++ b/pipelex/tools/log/error_fields.py@@ -6,14 +6,20 @@ say what went wrong this time and get the redaction's field treatment, control ctraceback rides along: at WARNING and below a handled, expected failure is not a bug in Pipelex's frames, and at ERRORan exception that is re-raised has its traceback written by whoever catches it.-A pydantic ``ValidationError`` is written as its locations and reasons only: its own text quotes every value it-refused, which is payload, a run's inputs or a model's response, and no log line carries payload. A reason is pydantic's-own message, kept only when nothing in it came from the input: pydantic wrote all of it, and every value its template-fills in comes from the schema, a bound, the expected values or a discriminator's name. Otherwise the error is written as-its location and its error type, ``date: value_error``: a custom validator's message is the validator's text, which can-quote the value it rejected, and several of pydantic's own templates quote the input too, an unknown tag of a-discriminated union, the character a UUID could not parse, a parser's own complaint. An ``extra_forbidden`` error's last-location component is the key the caller sent, which is input by definition, so its location stops at its parent.+A pydantic ``ValidationError`` is written as its locations and reasons only, by ``format_validation_error_without_input``+(``pipelex.tools.typing.pydantic_utils``), which a raise site refusing a run's data writes its message with as well: its+own text quotes every value it refused, which is payload, a run's inputs or a model's response, and no log line carries+payload. A reason is pydantic's own message, kept only when nothing in it came from the input: pydantic wrote all of it,+and every value its template fills in comes from the schema, a bound, the expected values or a discriminator's name.+Otherwise the error is written as+its error type, ``value_error``: a custom validator's message is the validator's text, which can quote the value it+rejected, and several of pydantic's own templates quote the input too, an unknown tag of a discriminated union, the+character a UUID could not parse, a parser's own complaint. A location quotes the keys of a dict the input holds, and a+key the model does not declare, which are input by definition, so a location is written only as far as the schema of the+validated model names it, every other component as ``<key>``; a line that does not know that model, given as+``validated_type``, writes each error by its reason alone. A line about a method author's own document, or a value+Pipelex built for itself such as a dry run's mock, says so with ``is_authored_input`` and writes its locations as+pydantic gives them, since no key of it is a run's data.``error.type`` is the OpenTelemetry semantic-convention key for the class of error an operation ended with.``error.message`` is the key the conventions gave an error's text before deprecating the general attribute in favour@@ -21,11 +27,7 @@ of domain-specific ones; it is kept here as ``error.type``'s companion because tsinks, which write them for a record that carries the exception itself and prefix a field spelling one."""-from typing import cast, get_args--from pydantic import ValidationError-from pydantic_core import ErrorDetails, PydanticKnownError-from pydantic_core.core_schema import ErrorType+from pipelex.tools.typing.pydantic_utils import ValidatedType, describe_exception_without_input#: The class of the handled exception, by its name.ERROR_TYPE_FIELD = "error.type"@@ -33,106 +35,29 @@ ERROR_TYPE_FIELD = "error.type"#: The handled exception's text.ERROR_MESSAGE_FIELD = "error.message"--#: The keys of a pydantic error's context whose values come from the schema, never from the input: the bounds a field-#: declares, the values, tags, schemes or version it expects, a discriminator's name, a pattern, and the class or the kind-#: of collection it validates into. A context holding any other key, the input's own tag, its length, or a parser's or-#: a validator's ``error`` text, which can quote the input, keeps its message off the line.-SCHEMA_CONTEXT_KEYS = frozenset(- {- "gt",- "ge",- "lt",- "le",- "multiple_of",- "min_length",- "max_length",- "max_digits",- "decimal_places",- "whole_digits",- "expected",- "expected_tags",- "expected_schemes",- "expected_version",- "discriminator",- "pattern",- "class_name",- "class",- "field_type",- "method_name",- "tz_expected",- "encoding",- }-)--#: The error type of a key the model forbids, whose last location component is that key, as the caller sent it.-EXTRA_FORBIDDEN_ERROR_TYPE = "extra_forbidden"--#: Every error type pydantic itself knows how to word.-_PYDANTIC_ERROR_TYPES: frozenset[str] = frozenset(get_args(ErrorType))---def _pydantic_own_reason(*, error: ErrorDetails) -> str | None:- """The error's message when nothing in it came from the input, or ``None`` when any of it may have.-- A type pydantic does not know is a ``PydanticCustomError``'s, whose message the validator wrote. A known type is- kept only when every key of its context is in ``SCHEMA_CONTEXT_KEYS``, so that its template is filled from the- schema alone, and when its message is exactly the one pydantic renders for it, which a ``PydanticCustomError``- reusing a built-in type's name with a message of its own is not.- """- error_type = error["type"]- if error_type not in _PYDANTIC_ERROR_TYPES:- # A type pydantic does not know, and so a `PydanticCustomError`'s, worded by the validator.- return None- context = error.get("ctx")- if context is not None and not SCHEMA_CONTEXT_KEYS.issuperset(context):- # A value of the context may come from the input, or be a validator's or a parser's own text.- return None- try:- own_message = PydanticKnownError(cast("ErrorType", error_type), context).message()- except (KeyError, TypeError, ValueError):- # Not with the context its template needs: the message is not pydantic's.- return None- if own_message != error["msg"]:- return None- return own_message---def _validation_error_text(*, validation_error: ValidationError) -> str:- """Each error of a ``ValidationError`` as its location and its reason, never the input it refused.-- The reason is pydantic's own message, or the error's type where the message may hold something of the input, since- a validator's text, or one of pydantic's templates, can quote the very value it rejected. A forbidden key's location- stops at its parent, the key being the caller's own text.- """- located_reasons: list[str] = []- for error in validation_error.errors(include_url=False, include_input=False):- location_parts = error["loc"][:-1] if error["type"] == EXTRA_FORBIDDEN_ERROR_TYPE else error["loc"]- location = ".".join(str(part) for part in location_parts)- reason = _pydantic_own_reason(error=error) or error["type"]- located_reasons.append(f"{location}: {reason}" if location else reason)- return "; ".join(located_reasons) or validation_error.title---def _exception_text(*, exc: BaseException) -> str:- """The text a handled exception is logged with: its own, except a ``ValidationError``'s, which quotes payload."""- if isinstance(exc, ValidationError):- return _validation_error_text(validation_error=exc)- return str(exc)+#: The registry code a failure's problem carries, which a line about a run's failure gives in place of its text.+ERROR_CODE_FIELD = "error.code"-def error_fields(*, exc: BaseException, text: str | None = None) -> dict[str, str]:+def error_fields(+ *, exc: BaseException, text: str | None = None, validated_type: ValidatedType | None = None, is_authored_input: bool = False+) -> dict[str, str]:"""The ``error.type`` and ``error.message`` fields of a handled exception, to spread into a call's ``fields``.Args:exc: The exception the line is about.text: The text to carry instead of the exception's own, for a line whose diagnosis is the exception's causechain rather than its own text.+ validated_type: The model whose validation raised ``exc``, when it is a ``ValidationError`` and the line knows+ it, which lets its locations be written.+ is_authored_input: Whether the input ``exc`` refused is a method author's own document or a value Pipelex+ built for itself, never a run's data, so that its locations are written as pydantic gives them.Returns:``{"error.type": <the exception's class name>, "error.message": <its text>}``, the text of a pydantic- ``ValidationError`` being its locations and reasons, without the values it refused, without a forbidden key's- name, and without any message that may quote the input, a custom validator's or one of pydantic's own, which- is written as its error type.+ ``ValidationError`` being its reasons, each located as far as the validated model's schema names it, without+ the values it refused, without a key of the input's own, and without any message that may quote the input, a+ custom validator's or one of pydantic's own, which is written as its error type."""- return {ERROR_TYPE_FIELD: type(exc).__name__, ERROR_MESSAGE_FIELD: _exception_text(exc=exc) if text is None else text}+ message = describe_exception_without_input(exc=exc, validated_type=validated_type, is_authored_input=is_authored_input) if text is None else text+ return {ERROR_TYPE_FIELD: type(exc).__name__, ERROR_MESSAGE_FIELD: message}diff --git a/pipelex/tools/log/log_sink.py b/pipelex/tools/log/log_sink.pyindex c50c9ab9d..7a214731f 100644--- a/pipelex/tools/log/log_sink.py+++ b/pipelex/tools/log/log_sink.py@@ -90,6 +90,21 @@ class ProcessorFilter(logging.Filter):return UNSCRUBBED_MARK not in record.__dict__+#: The loggers of libraries whose records quote a run's data by design, by their top-level package name: `instructor`+#: logs each attempt's validation error, which quotes the model's answer, and the requests it sends, with the prompt.+#: Pipelex reports what such a library does through its own lines and errors, so no sink writes their records, at any+#: level a configuration gives the logger.+PAYLOAD_LOGGER_PACKAGES: frozenset[str] = frozenset({"instructor"})+++class PayloadLoggerFilter(logging.Filter):+ """Drops a record of a library that writes a run's data into its log lines (``PAYLOAD_LOGGER_PACKAGES``)."""++ @override+ def filter(self, record: logging.LogRecord) -> bool:+ return record.name.split(".", 1)[0] not in PAYLOAD_LOGGER_PACKAGES++def _report_processor_failure(*, processor: LogRecordProcessor, exc: Exception) -> None:"""Write the stdlib's logging-error banner with the processor and the exception type, when the stdlib would have reported at all."""if not logging.raiseExceptions or not sys.stderr:@@ -119,9 +134,13 @@ class LogSink(ABC):@propertydef handler(self) -> logging.Handler:- """The sink's handler, built on first read with the processors wired in front of it."""+ """The sink's handler, built on first read with the processors wired in front of it.++ A record of a library that quotes a run's data in its lines is dropped first (``PayloadLoggerFilter``).+ """if self._handler is None:handler = self.make_handler()+ handler.addFilter(PayloadLoggerFilter())handler.addFilter(ProcessorFilter(processors=self.processors))self._handler = handlerreturn self._handlerdiff --git a/pipelex/tools/misc/exceptions.py b/pipelex/tools/misc/exceptions.pyindex 676fb0399..87cc40196 100644--- a/pipelex/tools/misc/exceptions.py+++ b/pipelex/tools/misc/exceptions.py@@ -78,15 +78,21 @@ class RemoteFileFetchError(ToolError):"""A remote file an input or a pipe referenced could not be fetched.Raised where the fetch happens — inside the operator that consumes the resource, the- one honest test that a URL serves what it claims to. The message names the URL and what- the server or the network said (an HTTP status, a refused connection, a timeout), and never- a resolved address; it reaches the operator's diagnostics, the caller reading the sentence- its code renders.+ one honest test that a URL serves what it claims to. The message names what the server or+ the network said (an HTTP status, a refused connection, a timeout), and never the URL, which+ is the run's data, nor a resolved address; it reaches the operator's diagnostics, the caller+ reading the sentence its code renders.A server that answered but would not serve the file is ``input.file_unreadable`` (thedefault); a timeout or a refused connection, which a retry may get past, is``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+ extract worker, names it with :meth:`with_input`."""error_code = ErrorCodeSet(@@ -98,6 +104,26 @@ 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):+ 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+ # 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++ def with_input(self, *, input_name: str) -> Self:+ """Name, where it is caught, the input whose URL could not be fetched.++ Returns:+ This error, so that the catch site can re-raise it.+ """+ self.input_name = input_name+ return self++ @override+ def problem_params(self) -> dict[str, Any]:+ return {"host": self.host, "input": self.input_name}+class SemVerError(ToolError):"""Raised when a version or a version constraint a method package declares does not parse."""diff --git a/pipelex/tools/misc/file_fetch_utils.py b/pipelex/tools/misc/file_fetch_utils.pyindex 03c1b30c9..79a9b78e8 100644--- a/pipelex/tools/misc/file_fetch_utils.py+++ b/pipelex/tools/misc/file_fetch_utils.py@@ -1,3 +1,6 @@+from collections.abc import Generator+from contextlib import contextmanager+import httpxfrom httpx import USE_CLIENT_DEFAULT, Response, Timeoutfrom mthds.protocol.problem.registry import CoreCode@@ -12,6 +15,14 @@ _TRANSIENT_HTTP_STATUSES = frozenset({408, 425, 429})_HTTP_SERVER_ERROR_FLOOR = 500+def _host_of(*, url: str) -> str | None:+ """The host the URL names, or ``None`` when it names none or does not parse, which the request then reports."""+ try:+ return httpx.URL(url).host or None+ except httpx.InvalidURL:+ return None++async def fetch_file_and_content_type_from_url_httpx(url: str,*,@@ -44,7 +55,7 @@ async def fetch_file_and_content_type_from_url_httpx(Raises:RemoteFileFetchError: The server answered with an error status, refused the- connection, or did not answer in time.+ connection, or did not answer in time, or the URL does not parse.SsrfBlockedError: The destination, or a redirect hop's, is not a globally routableaddress. It is a security error and deliberately not a ``RemoteFileFetchError``,so no caller's fallback for a failed download absorbs it.@@ -57,6 +68,11 @@ async def fetch_file_and_content_type_from_url_httpx(# bare `None` this signature defaults to left a hanging server able to block a# caller forever, and the `TimeoutException` branch below unreachable.timeout = Timeout(request_timeout) if request_timeout is not None else USE_CLIENT_DEFAULT+ # No message names the URL, which is the value an input or a pipe carried, a signed link's credential included: it+ # says what the server or the network answered. The URL's host is a fact the error holds, read once here, so that+ # the code that invites a retry, `input.url_unreachable`, takes it as its declared `host` parameter, and a code a+ # catch site chooses instead, which does not declare it, is given nothing it would refuse.+ host = _host_of(url=url)try:async with httpx.AsyncClient(headers={"User-Agent": user_agent}, transport=transport) as client:response: Response = await client.get(@@ -67,19 +83,24 @@ 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 '{url}': the server answered HTTP {status_code}"+ msg = f"Could not fetch a remote file: the server answered HTTP {status_code}"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).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from exc- raise RemoteFileFetchError(msg) from exc+ raise RemoteFileFetchError(msg, host=host).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from exc+ raise RemoteFileFetchError(msg, host=host) from excexcept httpx.TimeoutException as exc:- msg = f"Could not fetch '{url}': the request timed out"- raise RemoteFileFetchError(msg).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from 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 excexcept httpx.ConnectError as exc:- msg = f"Could not fetch '{url}': the host could not be reached"- raise RemoteFileFetchError(msg).with_error_code(CoreCode.INPUT_URL_UNREACHABLE) from exc+ 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 excexcept httpx.RequestError as exc:- msg = f"Could not fetch '{url}': the request failed ({type(exc).__name__})"+ msg = f"Could not fetch a remote file: the request failed ({type(exc).__name__})"+ raise RemoteFileFetchError(msg, host=host) 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 excdeclared_content_type: str | None = response.headers.get("content-type")@@ -112,3 +133,22 @@ async def fetch_file_from_url_httpx(transport=transport,)return raw_bytes+++@contextmanager+def fetching_for_input(*, input_name: str | None) -> Generator[None]:+ """Name ``input_name`` on a :class:`RemoteFileFetchError` the block raises, the input whose URL it fetched.++ A fetch knows the URL alone, which no message names, being the run's data; the caller that knows which input the URL+ belongs to wraps the fetch, so that a pipe reading several files says which one failed. An error that already names+ an input keeps it, and ``None``, a URL no input gave, names nothing.++ Raises:+ RemoteFileFetchError: What the block raised, naming the input.+ """+ try:+ yield+ except RemoteFileFetchError as exc:+ if input_name is not None and exc.input_name is None:+ exc.with_input(input_name=input_name)+ raisediff --git a/pipelex/tools/misc/http_utils.py b/pipelex/tools/misc/http_utils.pyindex ba546c724..17f031baf 100644--- a/pipelex/tools/misc/http_utils.py+++ b/pipelex/tools/misc/http_utils.py@@ -22,8 +22,11 @@ def validate_http_url_syntax(*, url: str) -> None:try:_HTTP_URL_ADAPTER.validate_python(url)except ValidationError as exc:- first_error = exc.errors()[0]["msg"] if exc.errors() else "not a valid http(s) URL"- msg = f"URL '{url}' is not a valid http(s) URL: {first_error}"+ # The URL is an input's value, possibly a signed link: the message names the URL parser's reason, a fixed+ # sentence such as "empty host", and never the URL.+ errors = exc.errors(include_url=False, include_input=False)+ first_error = errors[0]["msg"] if errors else "not a valid http(s) URL"+ msg = f"The URL is not a valid http(s) URL: {first_error}"raise UrlSyntaxError(msg) from excdiff --git a/pipelex/tools/network/exceptions.py b/pipelex/tools/network/exceptions.pyindex 566b88eb5..18e701ef3 100644--- a/pipelex/tools/network/exceptions.py+++ b/pipelex/tools/network/exceptions.py@@ -29,10 +29,10 @@ class SsrfBlockedError(SecurityError):and the caller fixes it by providing a public URL. A raise or catch site thatknows the method named the URL chooses ``security.method_url_refused``, and onethat knows a provider's answer named it ``security.provider_url_refused``.- The message deliberately names only the requested hostname, never the- resolved private IP, so it never reveals an internal address. That a name- resolves to a private address at all stays observable, since the refusal is- told apart from a host that cannot be reached.+ The message names neither the requested host, which is part of a URL the+ caller or the run supplied, nor the resolved private IP, so it never reveals+ an internal address. That a name resolves to a private address at all stays+ observable, since the refusal is told apart from a host that cannot be reached."""error_code = ErrorCodeSet(diff --git a/pipelex/tools/network/ssrf_guard.py b/pipelex/tools/network/ssrf_guard.pyindex 88f4ef5e6..1f26c6014 100644--- a/pipelex/tools/network/ssrf_guard.py+++ b/pipelex/tools/network/ssrf_guard.py@@ -56,8 +56,10 @@ async def resolve_to_allowed_ips(covering DNS too — stock httpcore resolves inside the same deadline, but hereresolution happens in a separate step."""+ # No message names the host: it is part of a URL the runtime did not choose, a run's input or a callback the caller+ # gave, and a message reaches the operator's diagnostics and the logs. The refusal's code says what was refused.if is_disallowed_host(host):- msg = f"Refusing to connect to {host!r}: destination is a disallowed (private/loopback/metadata) address."+ msg = "Refusing to connect: the destination is a disallowed (private/loopback/metadata) address."raise SsrfBlockedError(msg).with_security_target_class(classify_disallowed_host(host))loop = asyncio.get_running_loop()getaddrinfo_coro = loop.getaddrinfo(host, port, type=socket.SOCK_STREAM)@@ -67,21 +69,21 @@ async def resolve_to_allowed_ips(else:addr_infos = await asyncio.wait_for(getaddrinfo_coro, timeout=timeout)except socket.gaierror as exc:- msg = f"Could not resolve host {host!r}."+ msg = "Could not resolve the destination host."raise httpcore.ConnectError(msg) from excexcept TimeoutError as exc:- msg = f"Timed out resolving host {host!r}."+ msg = "Timed out resolving the destination host."raise httpcore.ConnectTimeout(msg) from excresolved_ips = [str(addr_info[4][0]) for addr_info in addr_infos]# Fail closed: if resolution yielded no address to vet, refuse rather than# fall through. getaddrinfo raises on failure today, but the guard's contract# is "return vetted IPs or raise" — never return an unvetted destination.if not resolved_ips:- msg = f"Refusing to connect to {host!r}: name resolved to no addresses."+ msg = "Refusing to connect: the destination host resolved to no addresses."raise SsrfBlockedError(msg)disallowed_ips = [resolved_ip for resolved_ip in resolved_ips if is_disallowed_ip(resolved_ip)]if disallowed_ips:- msg = f"Refusing to connect to {host!r}: it resolved to a disallowed (private/loopback/metadata) address."+ msg = "Refusing to connect: the destination host resolved to a disallowed (private/loopback/metadata) address."# The first disallowed address classifies the refusal for its security event, which never names the address.raise SsrfBlockedError(msg).with_security_target_class(classify_disallowed_host(disallowed_ips[0]))return resolved_ipsdiff --git a/pipelex/tools/tabular/csv_codec.py b/pipelex/tools/tabular/csv_codec.pyindex cae7df839..4ed3a7464 100644--- a/pipelex/tools/tabular/csv_codec.py+++ b/pipelex/tools/tabular/csv_codec.py@@ -18,7 +18,7 @@ import typesfrom datetime import date, datetimefrom enum import Enumfrom pathlib import Path-from typing import TYPE_CHECKING, Any, Literal, Union, get_args, get_origin+from typing import Any, Literal, Union, get_args, get_originfrom mthds.protocol.problem.registry import CoreCodefrom pydantic import ValidationError@@ -33,9 +33,7 @@ from pipelex.tools.tabular.exceptions import (CsvReadError,)from pipelex.tools.typing.annotation_utils import annotation_admits_none--if TYPE_CHECKING:- from pydantic_core import ErrorDetails+from pipelex.tools.typing.pydantic_utils import located_validation_errors, refusal_reason_without_input# v1 dialect defaults. Configurable via codec params, never auto-guessed (design §9).# The user-facing config surface (toml default / --delimiter / --encoding flags) is a@@ -133,26 +131,34 @@ def _assert_single_char_delimiter(delimiter: str) -> None:raise CsvError(msg).with_error_code(CoreCode.RUNTIME_UNEXPECTED)-def _validate_header(header: list[str], *, path: Path) -> None:- """Reject an empty header, or a header with a blank or duplicate column."""+def _csv_subject(*, input_name: str | None) -> str:+ """How a message names the file it refuses: by the input it was given as, never by its path, which is the caller's."""+ return f"the CSV file given for input '{input_name}'" if input_name is not None else "the CSV file"+++def _validate_header(header: list[str], *, subject: str) -> None:+ """Reject an empty header, or a header with a blank or duplicate column.++ A header cell is the file's own text, which no message quotes: a column is named by its 1-based position.+ """if not header:# An empty first row (a leading blank line, or a file that is just a newline) names no# columns; treat it as a malformed header rather than letting it surface as a confusing# "row wider than header" / missing-required error downstream.- msg = f"CSV file {path} has an empty header row; a header naming the columns is required."+ msg = f"Found an empty header row in {subject}; a header naming the columns is required."raise CsvColumnError(msg)seen: set[str] = set()- for column in header:+ for column_number, column in enumerate(header, start=1):if not column.strip():- msg = f"CSV file {path} has a blank header cell; every column needs a non-empty name."+ msg = f"Found a blank header cell in column {column_number} of {subject}; every column needs a non-empty name."raise CsvColumnError(msg)if column in seen:- msg = f"CSV file {path} has a duplicate header column {column!r}; column names must be unique."+ msg = f"Column {column_number} of {subject} repeats the name of an earlier column; column names must be unique."raise CsvColumnError(msg)seen.add(column)-def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str], list[tuple[int, list[str]]]]:+def _read_table(path: Path, *, delimiter: str, encoding: str, subject: str) -> tuple[list[str], list[tuple[int, list[str]]]]:"""Read a CSV file into a validated header row + the (1-based-line-numbered) data rows.The shared reader behind ``read_rows`` and ``list_content_from_csv`` — keeps the@@ -165,6 +171,10 @@ def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str]quoting (e.g. an unterminated quoted field) raises ``csv.Error`` at the boundary rather thansilently merging the following lines into one cell. Wraps every raw``OSError``/``UnicodeDecodeError``/``LookupError``/``csv.Error`` as ``CsvReadError``.++ No message names the file's path, which the caller gave, nor quotes its content: a decoding error's own text+ quotes the byte it refused, and an ``OSError``'s the path, so each is written by its reason alone. ``subject``+ names the file as the input it was given as, when that is known."""_assert_single_char_delimiter(delimiter)# Capture each record's physical line number from ``reader.line_num`` (the count of physical lines@@ -177,24 +187,25 @@ def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str]for row in reader:numbered_rows.append((reader.line_num, row))except UnicodeDecodeError as exc:- msg = f"Could not decode CSV file {path} as {encoding}: {exc}"+ msg = f"Could not decode {subject} as {encoding}: {exc.reason}"raise CsvReadError(msg) from excexcept LookupError as exc:- msg = f"Unknown encoding {encoding!r} for CSV file {path}: {exc}"+ msg = f"Unknown encoding {encoding!r} for {subject}"raise CsvReadError(msg) from excexcept csv.Error as exc:- msg = f"Malformed CSV file {path}: {exc}"+ # The csv module's own wording, which names the dialect's characters and never a cell.+ msg = f"Malformed CSV in {subject}: {exc}"raise CsvReadError(msg) from excexcept OSError as exc:- msg = f"Could not read CSV file {path}: {exc}"+ msg = f"Could not read {subject}: {exc.strerror or type(exc).__name__}"raise CsvReadError(msg) from excif not numbered_rows:- msg = f"CSV file {path} is empty; a header row is required."+ msg = f"Found nothing in {subject}; a header row is required."raise CsvReadError(msg)header = numbered_rows[0][1]- _validate_header(header, path=path)+ _validate_header(header, subject=subject)data_rows: list[tuple[int, list[str]]] = []for line_number, row in numbered_rows[1:]:@@ -203,7 +214,7 @@ def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str]continueif len(row) > len(header):msg = (- f"CSV file {path} row {line_number} has {len(row)} fields but the header declares "+ f"Row {line_number} of {subject} has {len(row)} fields but the header declares "f"{len(header)} column(s); the surplus cells map to no column.")raise CsvColumnError(msg)@@ -223,7 +234,7 @@ def read_rows(path: Path, *, delimiter: str = DEFAULT_DELIMITER, encoding: str =missing/unreadable file, an unknown/wrong encoding, or malformed quoting; raises``CsvColumnError`` for a duplicate/blank header cell or a data row wider than the header."""- header, data_rows = _read_table(path, delimiter=delimiter, encoding=encoding)+ header, data_rows = _read_table(path, delimiter=delimiter, encoding=encoding, subject=_csv_subject(input_name=None))return [_row_to_dict(row, header=header) for _, row in data_rows]@@ -248,14 +259,16 @@ def write_rows(writer.writerow(headers)for row in rows:writer.writerow([row.get(column, "") for column in headers])+ # The path is the one the caller asked to write; the rows are the run's output, so no message quotes a cell, which+ # an encoding error's own text does, nor repeats the path, which an `OSError`'s does.except LookupError as exc:- msg = f"Unknown encoding {encoding!r} for CSV file {path}: {exc}"+ msg = f"Unknown encoding {encoding!r} for CSV file {path}"raise CsvError(msg).with_error_code(CoreCode.REQUEST_INVALID) from excexcept UnicodeEncodeError as exc:- msg = f"Could not encode CSV file {path} as {encoding}: {exc}"+ msg = f"Could not encode CSV file {path} as {encoding}: a cell holds a character {encoding} cannot write ({exc.reason})"raise CsvError(msg).with_error_code(CoreCode.REQUEST_INVALID) from excexcept OSError as exc:- msg = f"Could not write CSV file {path}: {exc}"+ msg = f"Could not write CSV file {path}: {exc.strerror or type(exc).__name__}"raise CsvError(msg).with_error_code(CoreCode.REQUEST_INVALID) from exc@@ -289,13 +302,14 @@ def assert_supported_table_suffix(path: Path) -> None:suffix = path.suffix.lower()if suffix == ".csv":return+ # The file's name is the caller's own text, which no message carries: its suffix names the format.if suffix == ".xlsx":msg = (- f"Reading/writing Excel files ({path.name}) requires the optional 'pipelex[tabular]' extra, "- f"which is not part of v1. Convert to .csv, or install 'pipelex[tabular]' once it ships."+ "Reading/writing Excel files (.xlsx) requires the optional 'pipelex[tabular]' extra, "+ "which is not part of v1. Convert to .csv, or install 'pipelex[tabular]' once it ships.")raise CsvError(msg)- msg = f"Unsupported table file format for {path.name!r}: only .csv is supported (got suffix {path.suffix!r})."+ msg = f"Unsupported table file format: only .csv is supported (got suffix {path.suffix!r})."raise CsvError(msg)@@ -310,6 +324,7 @@ def list_content_from_csv(row_model: type[StuffContentType],delimiter: str = DEFAULT_DELIMITER,encoding: str = DEFAULT_READ_ENCODING,+ input_name: str | None = None,) -> ListContent[StuffContentType]:"""Read a CSV file into a ``ListContent`` of ``row_model`` instances (one row → one item).@@ -320,28 +335,34 @@ def list_content_from_csv(optional fields), but are left out for a defaulted field that refuses ``None``, which thentakes its default; remaining strings are coerced viapydantic's lax validation. A coercion failure raises ``CsvCoercionError`` naming the- 1-based row/column and field. ``row_model`` must be CSV-flat (see ``flat_field_names``).+ 1-based row and the field. ``row_model`` must be CSV-flat (see ``flat_field_names``).++ The file is the caller's input: no message names its path, quotes a cell, or names a column the concept does not+ declare, which is the file's own text: a message names the file by ``input_name``, the input it was given as, when+ the caller knows it."""assert_supported_table_suffix(path)field_names = flat_field_names(row_model)field_name_set = set(field_names)required_fields = {name for name, field_info in row_model.model_fields.items() if field_info.is_required()}- header, data_rows = _read_table(path, delimiter=delimiter, encoding=encoding)+ subject = _csv_subject(input_name=input_name)+ header, data_rows = _read_table(path, delimiter=delimiter, encoding=encoding, subject=subject)header_set = set(header)- extra_columns = header_set - field_name_set- if extra_columns:+ extra_column_numbers = [column_number for column_number, column in enumerate(header, start=1) if column not in field_name_set]+ if extra_column_numbers:msg = (- f"CSV file {path} has column(s) {sorted(extra_columns)} not declared on concept {row_model.__name__!r}. "- f"Remove them or project to a matching flat concept."+ f"Column(s) {', '.join(str(column_number) for column_number in extra_column_numbers)} of {subject} are not declared "+ f"on concept {row_model.__name__!r}, whose columns are {', '.join(field_names)}. "+ "Remove them or project to a matching flat concept.")raise CsvColumnError(msg)- missing_required = required_fields - header_set+ missing_required = sorted(required_fields - header_set)if missing_required:- msg = f"CSV file {path} is missing required column(s) {sorted(missing_required)} for concept {row_model.__name__!r}."- raise CsvColumnError(msg)+ msg = f"Required column(s) {missing_required} of concept {row_model.__name__!r} are missing from {subject}."+ raise CsvColumnError(msg).with_params(field=missing_required[0])# A CSV that omits a *nullable* column means "no value" for every row → None (CT2), regardless of# the row model's own default. Carrying these as explicit None keeps the contract from silently@@ -372,14 +393,20 @@ def list_content_from_csv(try:item = row_model.model_validate(row_data)except ValidationError as exc:- error_fields = sorted({_validation_error_label(error) for error in exc.errors()})+ # A row's key the model does not declare is the file's own text: the locations name what the row model's+ # schema names, and a model-level failure, which has none, is named by its error type. The errors are read+ # once, with their locations.+ located_errors = located_validation_errors(validation_error=exc, validated_type=row_model)+ error_fields = sorted({located_error.location or located_error.error["type"] for located_error in located_errors})fields_label = ", ".join(error_fields) or "?"- # Use pydantic's per-error `msg` (e.g. "Input should be a valid integer"), NOT str(exc):- # str(exc) appends `input_value=<raw cell>`, which would put the cell content, a run's input, into- # the operator's diagnostics and every log line carrying the message. Row/field identifiers suffice.- reasons = "; ".join(sorted({str(error.get("msg", "")) for error in exc.errors()})) or "invalid value"- msg = f"Could not coerce CSV row {row_number} of {path} for concept {row_model.__name__!r}: field(s) {fields_label} — {reasons}"- raise CsvCoercionError(msg) from exc+ # Each error's reason without the cell, NOT str(exc): str(exc) appends `input_value=<raw cell>`, and a+ # validator's message can quote the cell too, which would put the cell content, a run's input, into the+ # operator's diagnostics and every log line carrying the message. Row/field identifiers suffice.+ reasons = (+ "; ".join(sorted({refusal_reason_without_input(error=located_error.error) for located_error in located_errors})) or "invalid value"+ )+ msg = f"Could not coerce row {row_number} of {subject} for concept {row_model.__name__!r}: field(s) {fields_label} — {reasons}"+ raise CsvCoercionError(msg).with_params(field=located_errors[0].location if located_errors else None) from excitems.append(item)return ListContent(items=items)@@ -413,18 +440,6 @@ def csv_from_list_content(write_rows(path=path, headers=headers, rows=rows, delimiter=delimiter, encoding=encoding)-def _validation_error_label(error: "ErrorDetails") -> str:- """Best field label for one pydantic error: the dotted ``loc``, else the error type.-- A model-level failure (e.g. a ``model_validator``) has an empty ``loc``; falling back to- the error type keeps the coercion message from naming an unhelpful ``field(s) ?``.- """- loc = error.get("loc") or ()- if loc:- return ".".join(str(part) for part in loc)- return str(error.get("type", "model"))--def _to_cell(value: Any) -> str:"""Serialize one ``model_dump(mode="json")`` scalar to a CSV cell.diff --git a/pipelex/tools/typing/pydantic_utils.py b/pipelex/tools/typing/pydantic_utils.pyindex 1d13db247..6c469e95f 100644--- a/pipelex/tools/typing/pydantic_utils.py+++ b/pipelex/tools/typing/pydantic_utils.py@@ -1,16 +1,21 @@from __future__ import annotationsfrom enum import StrEnum-from typing import TYPE_CHECKING, Any, TypeVar, cast+from typing import TYPE_CHECKING, Any, NamedTuple, TypeAlias, TypeVar, cast, get_args+from weakref import WeakKeyDictionary-from pydantic import BaseModel, ValidationError+from pydantic import BaseModel, TypeAdapter, ValidationError+from pydantic_core import PydanticKnownError, SchemaError, SchemaValidator+from pydantic_core.core_schema import CoreSchema, ErrorTypefrom typing_extensions import overridefrom pipelex.tools.misc.attribute_utils import AttributePolisher+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorif TYPE_CHECKING:from collections.abc import Callable, Sequence+ from pydantic_core import ErrorDetailsfrom rich.repr import Result as RichReprResultBaseModelTypeVar = TypeVar("BaseModelTypeVar", bound=BaseModel)@@ -163,6 +168,11 @@ def analyze_pydantic_validation_error(exc: ValidationError) -> PydanticValidatiodef format_pydantic_validation_error(exc: ValidationError) -> str:"""Format a Pydantic ValidationError into a readable string with detailed error information.+ The text quotes the values pydantic refused, an invalid enum value or a literal it did not expect, so it is for a+ document whose author reads it: the caller's own method or the operator's configuration. A run's data, its inputs,+ a model's answer or a value a pipe built, is never refused through it: `format_validation_error_without_input`+ renders that refusal without the data.+Args:exc: The Pydantic ValidationError exception@@ -173,6 +183,424 @@ def format_pydantic_validation_error(exc: ValidationError) -> str:return analyze_pydantic_validation_error(exc).error_msg+#: The keys of a pydantic error's context whose values come from the schema, never from the input: the bounds a field+#: declares, the values, tags, schemes or version it expects, a discriminator's name, a pattern, and the class or the kind+#: of collection it validates into. A context holding any other key, the input's own tag, its length, or a parser's or+#: a validator's ``error`` text, which can quote the input, keeps its message out of the rendering.+SCHEMA_CONTEXT_KEYS = frozenset(+ {+ "gt",+ "ge",+ "lt",+ "le",+ "multiple_of",+ "min_length",+ "max_length",+ "max_digits",+ "decimal_places",+ "whole_digits",+ "expected",+ "expected_tags",+ "expected_schemes",+ "expected_version",+ "discriminator",+ "pattern",+ "class_name",+ "class",+ "field_type",+ "method_name",+ "tz_expected",+ "encoding",+ }+)++#: The error type of a key the model forbids, whose last location component is that key, as the caller sent it.+EXTRA_FORBIDDEN_ERROR_TYPE = "extra_forbidden"++#: The error type pydantic gives a validator's ``ValueError``, whose message is the validator's own text.+VALUE_ERROR_TYPE = "value_error"++#: Every error type pydantic itself knows how to word.+_PYDANTIC_ERROR_TYPES: frozenset[str] = frozenset(get_args(ErrorType))+++def _pydantic_own_reason(*, error: ErrorDetails) -> str | None:+ """The error's message when nothing in it came from the input, or ``None`` when any of it may have.++ A validator's ``InputFreeValueError`` keeps its message, which declares it holds nothing of the value. Any other+ type pydantic does not know is a ``PydanticCustomError``'s, whose message the validator wrote. A known type is+ kept only when every key of its context is in ``SCHEMA_CONTEXT_KEYS``, so that its template is filled from the+ schema alone, and when its message is exactly the one pydantic renders for it, which a ``PydanticCustomError``+ reusing a built-in type's name with a message of its own is not.+ """+ error_type = error["type"]+ context = error.get("ctx")+ if error_type == VALUE_ERROR_TYPE and context is not None and isinstance(context.get("error"), InputFreeValueError):+ # A validator's refusal that declares its message holds nothing of the value: pydantic's "Value error, " prefix+ # and the validator's own sentence.+ return error["msg"]+ if error_type not in _PYDANTIC_ERROR_TYPES:+ # A type pydantic does not know, and so a `PydanticCustomError`'s, worded by the validator.+ return None+ if context is not None and not SCHEMA_CONTEXT_KEYS.issuperset(context):+ # A value of the context may come from the input, or be a validator's or a parser's own text.+ return None+ try:+ own_message = PydanticKnownError(cast("ErrorType", error_type), context).message()+ except (KeyError, TypeError, ValueError):+ # Not with the context its template needs: the message is not pydantic's.+ return None+ if own_message != error["msg"]:+ return None+ return own_message+++def refusal_reason_without_input(*, error: ErrorDetails) -> str:+ """One error's reason, never anything of the input it refused: pydantic's own message, or else the error's type."""+ return _pydantic_own_reason(error=error) or error["type"]+++#: What a location writes in place of a component the schema does not name: a key of a dict, a key the model does not+#: declare, or anything below a point the schema no longer describes. Such a key is the caller's own text, the run's data.+PAYLOAD_KEY_PLACEHOLDER = "<key>"++#: The component pydantic appends to a dict key's location when it refuses the key itself, rather than its value.+_DICT_KEY_MARKER = "[key]"++#: The schemas that wrap one inner schema without adding a component to a location.+_WRAPPING_SCHEMA_TYPES = frozenset({"default", "nullable", "function-after", "function-before", "function-wrap", "json", "model", "dataclass"})++#: The schemas whose components are positions, which say where an item is and nothing of what it holds.+_SEQUENCE_SCHEMA_TYPES = frozenset({"list", "set", "frozenset", "generator"})++#: The schemas whose components are the names of their fields.+_FIELDS_SCHEMA_TYPES = frozenset({"model-fields", "typed-dict"})++#: What a tagged union's walk finds when no tag of the schema is the location's component.+_NO_TAG = object()+++def _schema_node(*, value: object) -> dict[str, Any] | None:+ """A core schema node, or ``None`` when ``value`` is not one, which leaves the walk where the schema stops."""+ if isinstance(value, dict):+ return cast("dict[str, Any]", value)+ return None+++def _schema_nodes(*, value: object) -> list[dict[str, Any]]:+ """The schema nodes a list holds, every other item left out."""+ if not isinstance(value, list):+ return []+ nodes: list[dict[str, Any]] = []+ for item in cast("list[object]", value):+ if (node := _schema_node(value=item)) is not None:+ nodes.append(node)+ return nodes+++#: The labels pydantic gives the union choices of a validated type's schema, by the identity of each choice's node. A+#: label is read off a validator built for the choice, which compiles the choice and every definition the schema holds,+#: so it is built once per node: the nodes belong to the validated type's schema, which lives as long as the type, and+#: an entry goes with the type.+_UNION_CHOICE_LABELS: WeakKeyDictionary[object, dict[int, str | None]] = WeakKeyDictionary()+++def _union_choice(+ *, choice: object, definitions: dict[str, dict[str, Any]], choice_labels: dict[int, str | None]+) -> tuple[dict[str, Any] | None, str | None]:+ """A union's choice and the label pydantic gives it in a location, read off the validator it builds for it.++ A choice is a schema, or a schema and its own label. The label is ``None`` when no validator can be built for the+ choice alone, so no location component is taken for it. A label found once is kept in ``choice_labels``, by the+ choice node's identity, so it is not compiled again.+ """+ if isinstance(choice, tuple):+ choice_schema, choice_label = cast("tuple[object, object]", choice)+ return _schema_node(value=choice_schema), choice_label if isinstance(choice_label, str) else None+ node = _schema_node(value=choice)+ if node is None:+ return None, None+ node_id = id(node)+ if node_id in choice_labels:+ return node, choice_labels[node_id]+ label: str | None+ try:+ validator = SchemaValidator(cast("CoreSchema", {"type": "definitions", "schema": node, "definitions": list(definitions.values())}))+ except SchemaError:+ label = None+ else:+ label = validator.title+ choice_labels[node_id] = label+ return node, label+++def _unwrapped_schema(*, schema: dict[str, Any] | None, definitions: dict[str, dict[str, Any]]) -> dict[str, Any] | None:+ """The schema that names the next component of a location, through every schema that adds none.++ It follows a definition reference, and collects the definitions a ``definitions`` schema holds, into+ ``definitions``. ``None`` when the schema is unknown, a reference to no definition, or a schema that can hold+ another under no name of its own, such as a chain of validators.+ """+ current = schema+ while current is not None:+ schema_type = current.get("type")+ if schema_type == "definitions":+ for definition in _schema_nodes(value=current.get("definitions")):+ if isinstance(ref := definition.get("ref"), str):+ definitions[ref] = definition+ current = _schema_node(value=current.get("schema"))+ elif schema_type == "definition-ref":+ schema_ref = current.get("schema_ref")+ current = definitions.get(schema_ref) if isinstance(schema_ref, str) else None+ elif schema_type == "lax-or-strict":+ current = _schema_node(value=current.get("lax_schema"))+ elif schema_type == "json-or-python":+ current = _schema_node(value=current.get("python_schema"))+ elif schema_type in _WRAPPING_SCHEMA_TYPES and "schema" in current:+ current = _schema_node(value=current["schema"])+ else:+ return current+ return None+++def _field_paths(*, fields: object) -> list[tuple[tuple[str | int, ...], dict[str, Any] | None]]:+ """Each field's location paths, its name and its validation aliases, with the schema of its value."""+ named_fields: list[tuple[str, dict[str, Any]]] = []+ if isinstance(fields, dict):+ for name, field in cast("dict[str, object]", fields).items():+ if (field_node := _schema_node(value=field)) is not None:+ named_fields.append((name, field_node))+ else:+ for field_node in _schema_nodes(value=fields):+ if isinstance(field_name := field_node.get("name"), str):+ named_fields.append((field_name, field_node))+ paths: list[tuple[tuple[str | int, ...], dict[str, Any] | None]] = []+ for name, field_node in named_fields:+ value_schema = _schema_node(value=field_node.get("schema"))+ paths.append(((name,), value_schema))+ alias: object = field_node.get("validation_alias")+ if isinstance(alias, str):+ paths.append(((alias,), value_schema))+ elif isinstance(alias, list):+ alias_parts = cast("list[object]", alias)+ # An `AliasChoices` is a list of paths, an `AliasPath` a single one.+ alias_paths = alias_parts if alias_parts and all(isinstance(alias_part, list) for alias_part in alias_parts) else [alias_parts]+ for alias_path in alias_paths:+ path_components = [component for component in cast("list[object]", alias_path) if isinstance(component, (str, int))]+ paths.append((tuple(path_components), value_schema))+ return paths+++def _schema_location_parts(*, schema: dict[str, Any], location: Sequence[str | int], choice_labels: dict[int, str | None]) -> list[str]:+ """The components of a location, each one the schema names written as it is and every other one as the placeholder.++ The walk follows the schema the location descends through: a field's name or alias, a position in a sequence, a+ union's choice and a tagged union's tag are the schema's own and are kept. A dict's key, and a key a model does not+ declare, are the caller's and are replaced; so is every component below a point the walk cannot follow, since it+ cannot tell what that component is. ``choice_labels`` holds the labels of the schema's union choices found so far.+ """+ definitions: dict[str, dict[str, Any]] = {}+ parts: list[str] = []+ current: dict[str, Any] | None = schema+ index = 0+ while index < len(location):+ component = location[index]+ current = _unwrapped_schema(schema=current, definitions=definitions)+ schema_type = current.get("type") if current is not None else None+ if current is not None and (schema_type in _FIELDS_SCHEMA_TYPES or schema_type == "dataclass-args"):+ remaining = tuple(location[index:])+ matches = [+ (path, value_schema) for path, value_schema in _field_paths(fields=current.get("fields")) if path and remaining[: len(path)] == path+ ]+ if matches:+ path, value_schema = max(matches, key=lambda match: len(match[0]))+ parts.extend(str(path_component) for path_component in path)+ current = value_schema+ index += len(path)+ continue+ # A key the model does not declare: the caller's own text.+ parts.append(PAYLOAD_KEY_PLACEHOLDER)+ current = _schema_node(value=current.get("extras_schema"))+ elif current is not None and schema_type in _SEQUENCE_SCHEMA_TYPES and isinstance(component, int):+ parts.append(str(component))+ current = _schema_node(value=current.get("items_schema"))+ elif current is not None and schema_type == "tuple" and isinstance(component, int):+ items_schema = _schema_nodes(value=current.get("items_schema"))+ variadic_index = current.get("variadic_item_index")+ parts.append(str(component))+ item_index = variadic_index if isinstance(variadic_index, int) and component >= variadic_index else component+ current = items_schema[item_index] if item_index < len(items_schema) else None+ elif current is not None and schema_type == "dict":+ # A dict's key is the caller's own text; a refusal of the key itself is marked after it.+ parts.append(PAYLOAD_KEY_PLACEHOLDER)+ if index + 1 < len(location) and location[index + 1] == _DICT_KEY_MARKER:+ parts.append(_DICT_KEY_MARKER)+ current = _schema_node(value=current.get("keys_schema"))+ index += 1+ else:+ current = _schema_node(value=current.get("values_schema"))+ elif current is not None and schema_type == "union":+ raw_choices = current.get("choices")+ choices = cast("list[object]", raw_choices) if isinstance(raw_choices, list) else []+ matched_choice: dict[str, Any] | None = None+ is_matched = False+ for choice in choices:+ choice_node, choice_label = _union_choice(choice=choice, definitions=definitions, choice_labels=choice_labels)+ if choice_label is not None and choice_label == component:+ matched_choice = choice_node+ is_matched = True+ break+ parts.append(str(component) if is_matched else PAYLOAD_KEY_PLACEHOLDER)+ current = matched_choice+ elif current is not None and schema_type == "tagged-union":+ raw_tagged_choices = current.get("choices")+ tagged_choices = cast("dict[object, object]", raw_tagged_choices) if isinstance(raw_tagged_choices, dict) else {}+ matched_tag: object = next((choice_tag for choice_tag in tagged_choices if str(choice_tag) == str(component)), _NO_TAG)+ if matched_tag is _NO_TAG:+ parts.append(PAYLOAD_KEY_PLACEHOLDER)+ current = None+ else:+ parts.append(str(component))+ current = _schema_node(value=tagged_choices[matched_tag])+ else:+ # A point the schema does not describe: nothing below it can be told apart from the caller's own text.+ parts.append(PAYLOAD_KEY_PLACEHOLDER)+ current = None+ index += 1+ return parts+++#: What validated an input, and so whose schema names a refusal's locations: a model, or a ``TypeAdapter`` over a type+#: that is not one, such as a union of models.+ValidatedType: TypeAlias = type[BaseModel] | TypeAdapter[Any]+++class LocatedValidationError(NamedTuple):+ """One error of a ``ValidationError``, read without its input, and its location as far as it may be written."""++ error: ErrorDetails+ location: str | None+++def _validator_title_and_schema(*, validated_type: ValidatedType) -> tuple[str | None, dict[str, Any]]:+ """The title the validator of ``validated_type`` gives its errors, and the core schema it validates with."""+ if isinstance(validated_type, TypeAdapter):+ return getattr(validated_type.validator, "title", None), cast("dict[str, Any]", validated_type.core_schema)+ return getattr(validated_type.__pydantic_validator__, "title", None), cast("dict[str, Any]", validated_type.__pydantic_core_schema__)+++def located_validation_errors(+ *, validation_error: ValidationError, validated_type: ValidatedType | None, is_authored_input: bool = False+) -> list[LocatedValidationError]:+ """Each error of a ``ValidationError``, without its input, with its dotted location as far as it may be written.++ A location quotes the keys the input holds where it is a dict, or where it adds a key the model does not declare, and+ those keys are the run's data: a dict's key, ``entries.confidential-diagnosis.score``, is written+ ``entries.<key>.score``. Only the components the schema names are written as they are (see+ ``_schema_location_parts``), so a location needs the type the error came from. Without it, or when the error's+ title is not the type's, so that it came from another model, no location is given. An input that is no run's data,+ a method author's own document or a value Pipelex built for itself such as a dry run's mock, is located as pydantic+ gives it, whatever validated it. Every formatter of a location reads it here, and the errors are read once.++ Args:+ validation_error: The error whose errors are wanted.+ validated_type: The model, or the ``TypeAdapter``, whose validation raised it, or ``None`` when it is not known.+ is_authored_input: Whether the validated input is a method author's own document or a value Pipelex built for+ itself, never a run's data, so that its keys are the author's or Pipelex's own and are written.++ Returns:+ One entry per error, in the order of its errors, its location ``None`` for an error at the root or when the type+ is not known.+ """+ errors = validation_error.errors(include_url=False, include_input=False)+ if is_authored_input:+ return [LocatedValidationError(error=error, location=".".join(str(part) for part in error["loc"]) or None) for error in errors]+ if validated_type is None:+ return [LocatedValidationError(error=error, location=None) for error in errors]+ validator_title, schema = _validator_title_and_schema(validated_type=validated_type)+ if validator_title != validation_error.title:+ return [LocatedValidationError(error=error, location=None) for error in errors]+ choice_labels = _UNION_CHOICE_LABELS.setdefault(validated_type, {})+ return [+ LocatedValidationError(+ error=error, location=".".join(_schema_location_parts(schema=schema, location=error["loc"], choice_labels=choice_labels)) or None+ )+ for error in errors+ ]+++def validation_error_locations(+ *, validation_error: ValidationError, validated_type: ValidatedType | None, is_authored_input: bool = False+) -> list[str | None]:+ """Each error's dotted location, in the order of its errors, as far as it may be written (see ``located_validation_errors``).++ Args:+ validation_error: The error whose locations are wanted.+ validated_type: The model, or the ``TypeAdapter``, whose validation raised it, or ``None`` when it is not known.+ is_authored_input: Whether the validated input is a method author's own document or a value Pipelex built for+ itself, whose locations are written as pydantic gives them.++ Returns:+ One location per error, ``None`` for an error at the root or when the type is not known.+ """+ located_errors = located_validation_errors(validation_error=validation_error, validated_type=validated_type, is_authored_input=is_authored_input)+ return [located_error.location for located_error in located_errors]+++def format_validation_error_without_input(+ *, validation_error: ValidationError, validated_type: ValidatedType | None = None, is_authored_input: bool = False+) -> str:+ """Each error of a ``ValidationError`` as its location and its reason, never the input it refused.++ A ``ValidationError``'s own text, and the analysis `format_pydantic_validation_error` gives, quote the values pydantic+ refused, which on a run's data are its inputs, a model's answer or a value a pipe built, and no message, log line or+ view carries those. The reason is pydantic's own message, or the error's type where the message may hold something+ of the input, since a validator's text, or one of pydantic's templates, can quote the very value it rejected; a+ validator that raises ``InputFreeValueError`` declares its text holds none of it, and keeps it. The location names+ only what the validated type's schema names (see ``located_validation_errors``), so a caller that knows the type+ passes it, and without it each error is given by its reason alone; a caller refusing an author's own document, or a+ value Pipelex built for itself, says so and has its locations written as they are.++ Args:+ validation_error: The error to write.+ validated_type: The model, or the ``TypeAdapter``, whose validation raised it, when the caller knows it.+ is_authored_input: Whether the validated input is a method author's own document or a value Pipelex built for+ itself, never a run's data.++ Returns:+ The errors, ``; ``-separated in the order they come, each written once, or the error's title when it holds none.+ """+ located_errors = located_validation_errors(validation_error=validation_error, validated_type=validated_type, is_authored_input=is_authored_input)+ # A dict preserves the order of first appearance, and finds a repeat in constant time: a refused list of many items+ # gives many errors of the same location and reason.+ located_reasons: dict[str, None] = {}+ for located_error in located_errors:+ reason = refusal_reason_without_input(error=located_error.error)+ located_reasons.setdefault(f"{located_error.location}: {reason}" if located_error.location else reason, None)+ return "; ".join(located_reasons) or validation_error.title+++def describe_exception_without_input(*, exc: BaseException, validated_type: ValidatedType | None = None, is_authored_input: bool = False) -> str:+ """The text of an exception, a ``ValidationError``'s written without the input it refused.++ Every other exception's text is kept as it is: a raise site of Pipelex writes no run's data into its message. A+ caller describing a foreign exception, whose text can carry anything, names it by its class instead.++ Args:+ exc: The exception to describe.+ validated_type: The model, or the ``TypeAdapter``, whose validation raised it, when it is a ``ValidationError``+ and the caller knows it, which lets its locations be written (see ``format_validation_error_without_input``).+ is_authored_input: Whether the validated input is a method author's own document or a value Pipelex built for+ itself, never a run's data, whose locations are written as they are.++ Returns:+ The exception's text.+ """+ if isinstance(exc, ValidationError):+ return format_validation_error_without_input(validation_error=exc, validated_type=validated_type, is_authored_input=is_authored_input)+ return str(exc)++def convert_strenum_to_str(obj: dict[str, Any] | list[Any] | StrEnum | Any,) -> dict[str, Any] | list[Any] | str | Any:diff --git a/pipelex/tools/typing/validation_exceptions.py b/pipelex/tools/typing/validation_exceptions.pynew file mode 100644index 000000000..27345a879--- /dev/null+++ b/pipelex/tools/typing/validation_exceptions.py@@ -0,0 +1,14 @@+"""The refusal a pydantic validator raises when its message holds nothing of the value it refused.++Its own module, importing nothing, because ``pydantic_utils`` reads it and ``pipelex.base_exceptions``, which the+package's ``exceptions.py`` imports, already imports ``pydantic_utils``.+"""+++class InputFreeValueError(ValueError):+ """A validator's refusal whose message names what was expected and never the value it refused.++ Pydantic wraps it into a ``value_error`` like any ``ValueError``. Where a ``ValidationError`` over a run's data is+ written without its input, by ``format_validation_error_without_input``, a ``value_error`` keeps its message only+ when the validator raised this class, since any other validator's text may quote the value it rejected.+ """diff --git a/pipelex/tracing/dynamodb_event_log.py b/pipelex/tracing/dynamodb_event_log.pyindex 4df718636..9b4dcc77f 100644--- a/pipelex/tracing/dynamodb_event_log.py+++ b/pipelex/tracing/dynamodb_event_log.py@@ -33,7 +33,7 @@ from pipelex import logfrom pipelex.system.exceptions import MissingDependencyErrorfrom pipelex.system.execution_chain import execution_chain_digestfrom pipelex.tools.log.error_fields import error_fields-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputfrom pipelex.tracing.event_log_protocol import EventLogProtocol, deduplicate_and_order_eventsfrom pipelex.tracing.exceptions import EventLogReadError, EventLogSchemaMismatchError, EventLogSetupErrorfrom pipelex.tracing.trace_events import AnyTraceEvent, TraceEvent, json_invalid_message@@ -223,7 +223,10 @@ class DynamoDBEventLog(EventLogProtocol):continuerefused_count += 1if first_refusal is None:- first_refusal = f"PK={item.get('PK')} SK={item.get('SK')}: {format_pydantic_validation_error(exc)}"+ # The refusal is written by its reasons, located by the event models' schema, never the traced+ # values it quotes, which are the run's data.+ refusal = format_validation_error_without_input(validation_error=exc, validated_type=_any_trace_event_adapter)+ first_refusal = f"PK={item.get('PK')} SK={item.get('SK')}: {refusal}"continueevents.append(event)diff --git a/pipelex/tracing/ndjson_event_log.py b/pipelex/tracing/ndjson_event_log.pyindex 1318e8106..1ceaac84a 100644--- a/pipelex/tracing/ndjson_event_log.py+++ b/pipelex/tracing/ndjson_event_log.py@@ -21,7 +21,7 @@ from pipelex import logfrom pipelex.system.execution_chain import execution_chain_digestfrom pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.log.error_fields import error_fields-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputfrom pipelex.tracing.event_log_protocol import EventLogProtocol, deduplicate_and_order_eventsfrom pipelex.tracing.exceptions import EventLogSchemaMismatchErrorfrom pipelex.tracing.trace_events import AnyTraceEvent, TraceEvent, json_invalid_message@@ -192,7 +192,10 @@ class NdjsonEventLog(EventLogProtocol):continuerefused_count += 1if first_refusal is None:- first_refusal = f"{ndjson_path}:{line_number} — {format_pydantic_validation_error(validation_error)}"+ first_refusal = (+ f"{ndjson_path}:{line_number} — "+ f"{format_validation_error_without_input(validation_error=validation_error, validated_type=_any_trace_event_adapter)}"+ )continueevents.append(event)diff --git a/subject_grants.toml b/subject_grants.tomlindex d744fd1d3..cdbc37dbc 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -5672,26 +5672,10 @@ rationale = "Transforms the templating_context; single operand."param = "template_source"rationale = "Jinja op on the template_source; single operand (context keyword-only)."-["pipelex/tools/jinja2/jinja2_rendering.py::_make_non_type_error_msg"]-param = "template_source"-rationale = "Factory from source: builds the result from the template_source; single operand."--["pipelex/tools/jinja2/jinja2_rendering.py::_make_type_error_msg"]-param = "template_source"-rationale = "Factory from source: builds the result from the template_source; single operand."-["pipelex/tools/jinja2/jinja2_rendering.py::_prepare_templating_context"]param = "templating_context"rationale = "Jinja op on the templating_context; single operand (context keyword-only)."-["pipelex/tools/jinja2/jinja2_rendering.py::_render_template_async"]-param = "template_source"-rationale = "Jinja op on the template_source; single operand (context keyword-only)."--["pipelex/tools/jinja2/jinja2_rendering.py::_render_template_sync"]-param = "template_source"-rationale = "Jinja op on the template_source; single operand (context keyword-only)."-["pipelex/tools/jinja2/jinja2_rendering.py::render_jinja2_async"]param = "template_source"rationale = "Jinja op on the template_source; single operand (context keyword-only)."@@ -6596,10 +6580,6 @@ rationale = "Transforms the value; single operand."param = "header"rationale = "Validates/checks the header; single operand."-["pipelex/tools/tabular/csv_codec.py::_validation_error_label"]-param = "error"-rationale = "Validates/checks the error; single operand."-["pipelex/tools/tabular/csv_codec.py::assert_supported_table_suffix"]param = "path"rationale = "File/path op on the path; single operand."diff --git a/tests/data/errors/foreign_raises.txt b/tests/data/errors/foreign_raises.txtindex d106ba666..97841d271 100644--- a/tests/data/errors/foreign_raises.txt+++ b/tests/data/errors/foreign_raises.txt@@ -48,11 +48,11 @@ pipelex/core/method_trees/method_file_store.py | LocalMethodFileStore.hold_treepipelex/core/method_trees/tree_bundle.py | TreeBundle.location | ValueError | invariantpipelex/core/method_trees/tree_python.py | TreeModuleGuard.find_spec | TreeModuleExcludedError | carrierpipelex/core/pipes/inputs/input_stuff_specs.py | InputStuffSpecs.get_single_stuff_spec | ValueError | invariant-pipelex/core/stuffs/iso_temporal.py | parse_iso_date | ValueError | validator-pipelex/core/stuffs/iso_temporal.py | parse_iso_date | ValueError | validator-pipelex/core/stuffs/iso_temporal.py | parse_iso_time | ValueError | validator-pipelex/core/stuffs/iso_temporal.py | parse_iso_time | ValueError | validator-pipelex/core/stuffs/iso_temporal.py | parse_iso_time | ValueError | validator+pipelex/core/stuffs/iso_temporal.py | parse_iso_date | InputFreeValueError | validator+pipelex/core/stuffs/iso_temporal.py | parse_iso_date | InputFreeValueError | validator+pipelex/core/stuffs/iso_temporal.py | parse_iso_time | InputFreeValueError | validator+pipelex/core/stuffs/iso_temporal.py | parse_iso_time | InputFreeValueError | validator+pipelex/core/stuffs/iso_temporal.py | parse_iso_time | InputFreeValueError | validatorpipelex/core/stuffs/non_null_any.py | _refuse_none | PydanticCustomError | validatorpipelex/core/stuffs/stuff_artefact.py | _get_content_html | AttributeError | carrierpipelex/core/stuffs/stuff_artefact.py | _get_template_value | KeyError | carrierdiff --git a/tests/e2e/pipelex/cli/test_csv_run.py b/tests/e2e/pipelex/cli/test_csv_run.pyindex 6594c7705..e6d081f7b 100644--- a/tests/e2e/pipelex/cli/test_csv_run.py+++ b/tests/e2e/pipelex/cli/test_csv_run.py@@ -173,4 +173,6 @@ class TestCsvRun:combined = result.stdout + result.stderrassert result.returncode != 0, f"a missing input .csv must fail.\n{combined!r}"assert "Traceback (most recent call last)" not in combined, f"error must be clean, not a raw traceback: {combined!r}"- assert "nope.csv" in combined, f"the error should name the offending CSV file: {combined!r}"+ # The file's path is the caller's input, which no message carries: the error names the input it was given as.+ assert "the CSV file given for input 'people'" in combined, f"the error should name the offending input: {combined!r}"+ assert "nope.csv" not in combined, f"the error should not quote the path: {combined!r}"diff --git a/tests/integration/pipelex/csv/test_csv_input_detection.py b/tests/integration/pipelex/csv/test_csv_input_detection.pyindex 67532e418..a83ac4aea 100644--- a/tests/integration/pipelex/csv/test_csv_input_detection.py+++ b/tests/integration/pipelex/csv/test_csv_input_detection.py@@ -63,12 +63,13 @@ class TestCsvInputDetection:WorkingMemoryFactory.make_from_pipeline_inputs(inputs, concept_provider=get_concept_library(), read_scope=None)message = str(exc_info.value)assert "local" in message.lower()- # The path is preserved so the user can identify the offending input...- assert "people.csv" in message- # ...but the signed query string / fragment (which can carry credentials) must be stripped:- # CsvError is caller-facing and survives STRICT disclosure, so it must not leak the token.- for secret in ("token=abc", "X-Amz-Signature=deadbeef", "frag"):- assert secret not in message+ # The input is named, with the url's scheme...+ assert "stuff 'people'" in message+ assert f"scheme '{remote_url.split(':', 1)[0]}'" in message+ # ...and the url itself, the input's value, is not: neither its host, its path, nor a signed query string or a+ # fragment, which can carry credentials.+ for url_part in ("example.com", "bucket", "people.csv", "token=abc", "X-Amz-Signature=deadbeef", "frag"):+ assert url_part not in messagedef test_remote_csv_url_rejected_through_cli_inputs_resolution(self, load_test_library: Callable[[list[Path]], None]) -> None:load_test_library([BUNDLE_DIR])diff --git a/tests/integration/pipelex/pipeline/test_data.py b/tests/integration/pipelex/pipeline/test_data.pyindex 43bc8132e..e2bd068ef 100644--- a/tests/integration/pipelex/pipeline/test_data.py+++ b/tests/integration/pipelex/pipeline/test_data.py@@ -700,6 +700,76 @@ 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."""diff --git a/tests/integration/pipelex/pipeline/test_located_run_failure.py b/tests/integration/pipelex/pipeline/test_located_run_failure.pyindex eb9212005..5287e6745 100644--- a/tests/integration/pipelex/pipeline/test_located_run_failure.py+++ b/tests/integration/pipelex/pipeline/test_located_run_failure.py@@ -225,12 +225,14 @@ class TestLocatedRunFailure:assert error.pipe_code == "flow"assert error.pipe_stack == ["flow"]- assert error.message == "Pipe 'flow' failed: KeyError: 'boom from a pipe'"+ # Named by its class alone: a foreign exception's text can carry a key of the run's data.+ assert error.message == "Pipe 'flow' failed: KeyError"operator = error.to_problem(view=ProblemView.OPERATOR)assert operator.code == CoreCode.RUNTIME_UNEXPECTEDassert operator.diagnostics is not Noneassert operator.diagnostics.error_class == "PipelexUnexpectedError"- assert "boom from a pipe" in operator.diagnostics.message+ assert operator.diagnostics.message == "KeyError"+ assert "boom from a pipe" not in str(operator.to_wire())caller = error.to_problem(view=ProblemView.CALLER)assert caller.code == CoreCode.RUNTIME_UNEXPECTEDassert "boom from a pipe" not in str(caller.to_wire())diff --git a/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py b/tests/integration/pipelex/pipeline/test_render_time_template_refusals.pyindex c6c5aea88..fa046a9f2 100644--- a/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py+++ b/tests/integration/pipelex/pipeline/test_render_time_template_refusals.py@@ -27,7 +27,8 @@ from tests.integration.pipelex.pipeline.test_data import RenderTimeTemplateTestDif TYPE_CHECKING:from pytest_mock import MockerFixture-_UNKNOWN_FILTER_FAULT = f"No filter named '{RenderTimeTemplateTestData.UNKNOWN_FILTER}' found."+# The filter is named, since the template applies it by that name, with the template's line, never Jinja2's own text.+_UNKNOWN_FILTER_FAULT = f"No filter named '{RenderTimeTemplateTestData.UNKNOWN_FILTER}' at line 1."def _llm_bundle(*, prompt_field: str) -> str:diff --git a/tests/integration/pipelex/pipeline/test_run_content_stays_out_of_sinks.py b/tests/integration/pipelex/pipeline/test_run_content_stays_out_of_sinks.pynew file mode 100644index 000000000..e56c05dcc--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_run_content_stays_out_of_sinks.py@@ -0,0 +1,171 @@+import io+import json+import logging+from collections.abc import Generator+from contextlib import contextmanager+from typing import Any++import pytest+from mthds.protocol.problem.registry import CoreCode+from pytest_mock import MockerFixture+from typing_extensions import override++from pipelex.base_exceptions import PipelexError+from pipelex.cogt.llm.llm_job import LLMJob+from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract+from pipelex.cogt.llm.thinking_mode import ThinkingMode+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+from pipelex.cogt.model_backends.model_type import ModelType+from pipelex.core.memory.working_memory import WorkingMemory+from pipelex.core.stuffs.text_content import TextContent+from pipelex.errors.error_codes import ErrorCode+from pipelex.errors.problem import ProblemView, problem_metadata+from pipelex.pipeline.runner import PipelexMTHDSProtocol+from pipelex.system.registries.func_registry import pipe_func+from pipelex.tools.log.json_log_sink import JsonLogSink+from pipelex.tools.log.log_levels import LOGGING_LEVEL_VERBOSE+from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar+from tests.integration.pipelex.pipeline.test_data import RunContentMarkerTestData++# No `from __future__ import annotations`: the function a `PipeFunc` calls has its annotations read when it is bound.+MARKER = RunContentMarkerTestData.MARKER+++@pipe_func()+def run_content_quote_the_note(working_memory: WorkingMemory) -> TextContent:+ """A method's function refusing its input in a message that quotes it, as a function's own code is free to."""+ note = working_memory.get_stuff_as_str(name="note")+ msg = f"cannot file the note {note!r}"+ raise ValueError(msg)+++class MarkerAnsweringLLMWorker(LLMWorkerAbstract):+ """Answers every generation with the marker, which a structure's integer field refuses."""++ @override+ async def _gen_text(self, llm_job: LLMJob) -> str:+ return MARKER++ @override+ async def _gen_object(self, llm_job: LLMJob, *, schema: type[BaseModelTypeVar]) -> BaseModelTypeVar:+ return schema.model_validate(dict.fromkeys(schema.model_fields, MARKER))+++def _marker_answering_worker() -> MarkerAnsweringLLMWorker:+ inference_model = InferenceModelSpec(+ backend_name="stand_in",+ name="stand-in-llm",+ sdk="stand_in",+ model_type=ModelType.LLM,+ model_id="stand-in-llm-1",+ inputs=["text"],+ outputs=["text", "structured"],+ costs={},+ thinking_mode=ThinkingMode.NONE,+ max_tokens=None,+ max_prompt_images=None,+ )+ return MarkerAnsweringLLMWorker(inference_model=inference_model, reporting_delegate=None)+++@contextmanager+def _json_sink_on_root(*, buffer: io.StringIO) -> Generator[None]:+ """The ``json`` sink's handler on the root logger, beside whatever the session installed, for as long as the block runs."""+ handler = JsonLogSink(stream=buffer).handler+ root_logger = logging.getLogger()+ root_logger.addHandler(handler)+ try:+ yield+ finally:+ root_logger.removeHandler(handler)+ handler.close()+++def _cause_chain(error: BaseException) -> list[BaseException]:+ """The error and every exception below it, by ``__cause__`` or else ``__context__``."""+ chain: list[BaseException] = []+ current: BaseException | None = error+ while current is not None and current not in chain:+ chain.append(current)+ current = current.__cause__ or current.__context__+ return chain++[email protected](loop_scope="class")+class TestRunContentStaysOutOfSinks:+ @pytest.mark.parametrize(+ ("topic", "pipe_code", "inputs", "expected_code", "is_quoted_below"),+ [+ ("a number input given a text", "echo_amount", {"amount": MARKER}, CoreCode.INPUT_INVALID, False),+ ("a structure refusing a field's value", "echo_tally", {"tally": {"count": MARKER}}, CoreCode.INPUT_INVALID, True),+ (+ "an explicit envelope its structure refuses",+ "echo_tally",+ {"tally": {"concept": "run_content_marker.Tally", "content": {"count": MARKER}}},+ CoreCode.INPUT_INVALID,+ True,+ ),+ ("a date the content factory cannot read", "echo_date", {"when": MARKER}, CoreCode.INPUT_INVALID, False),+ ("a function quoting its input", "file_note", {"note": MARKER}, CoreCode.PIPE_FUNCTION_RAISED, True),+ ("a value the composer copied into a choice", "make_ticket", {"level": MARKER}, CoreCode.PIPE_OUTPUT_INVALID, True),+ ("a model answer the structure refuses", "count_notes", {"note": "three apples"}, CoreCode.RUNTIME_UNEXPECTED, True),+ ],+ )+ async def test_the_run_s_data_reaches_no_log_record_and_no_view(+ self,+ mocker: MockerFixture,+ caplog: pytest.LogCaptureFixture,+ topic: str,+ pipe_code: str,+ inputs: dict[str, Any],+ expected_code: ErrorCode,+ is_quoted_below: bool,+ ) -> None:+ """A run whose data holds a marker fails at one family of raise site, and the marker reaches no sink.++ Every log record the run wrote, at the lowest level and as the ``json`` sink writes it, the failure's message and+ every view of its problem are read for the marker. Where a foreign exception below the failure, pydantic's or the+ method function's, does quote it, the case says so, which proves the raise sites above kept it out.+ """+ mocker.patch("pipelex.cogt.content_generation.llm_generate.get_llm_worker", return_value=_marker_answering_worker())+ # Every Pipelex logger down to the lowest level; `caplog` puts the level back afterwards.+ caplog.set_level(LOGGING_LEVEL_VERBOSE, logger="pipelex")+ buffer = io.StringIO()++ with _json_sink_on_root(buffer=buffer), pytest.raises(PipelexError) as exc_info:+ await PipelexMTHDSProtocol().execute(pipe_code=pipe_code, mthds_contents=[RunContentMarkerTestData.MTHDS], inputs=inputs)++ error = exc_info.value+ operator = error.to_problem(view=ProblemView.OPERATOR)+ # The run failed where the case aims, on its data and on nothing else.+ assert operator.code == expected_code, topic+ assert any(MARKER in str(cause) for cause in _cause_chain(error)) is is_quoted_below, topic++ assert MARKER not in error.message, topic+ assert MARKER not in json.dumps(operator.to_wire()), topic+ assert MARKER not in json.dumps(error.to_problem(view=ProblemView.CALLER).to_wire()), topic+ assert MARKER not in json.dumps(problem_metadata(problem=operator).to_wire()), topic+ json_lines = [line for line in buffer.getvalue().splitlines() if line]+ assert json_lines, topic+ assert [line for line in json_lines if MARKER in line] == [], topic+ assert [record.getMessage() for record in caplog.records if MARKER in str(vars(record))] == [], topic++ async def test_a_library_logging_the_run_s_data_reaches_no_sink(self) -> None:+ """`instructor` logs each refused answer, which quotes the model's text: no sink of Pipelex writes its records."""+ buffer = io.StringIO()+ instructor_logger = logging.getLogger("instructor.core.retry")+ pipelex_logger = logging.getLogger("pipelex.marker_probe")+ previous_levels = (instructor_logger.level, pipelex_logger.level)+ instructor_logger.setLevel(logging.DEBUG)+ pipelex_logger.setLevel(logging.DEBUG)+ try:+ with _json_sink_on_root(buffer=buffer):+ instructor_logger.error("Validation error on attempt 1: count, input_value='%s'", MARKER)+ pipelex_logger.error("A line of Pipelex's own reaches the sink")+ finally:+ instructor_logger.setLevel(previous_levels[0])+ pipelex_logger.setLevel(previous_levels[1])++ json_lines = [line for line in buffer.getvalue().splitlines() if line]+ assert [json.loads(line)["message"] for line in json_lines] == ["A line of Pipelex's own reaches the sink"]+ assert [line for line in json_lines if MARKER in line] == []diff --git a/tests/integration/pipelex/pipeline/test_run_fault_views.py b/tests/integration/pipelex/pipeline/test_run_fault_views.pyindex 75ca7f489..fef6ddd5d 100644--- a/tests/integration/pipelex/pipeline/test_run_fault_views.py+++ b/tests/integration/pipelex/pipeline/test_run_fault_views.py@@ -106,8 +106,11 @@ class TestRunFaultViews:assert operator.diagnostics is not Noneassert operator.diagnostics.message.startswith("Error combining stuffs for concept Review")- async def test_a_deployment_validators_text_is_the_operators_alone(self) -> None:- """A deployment's structure class refusing the combine: its validator's text reaches the operator, never the caller."""+ async def test_a_deployment_validators_text_reaches_neither_view(self) -> None:+ """A deployment's structure class refusing the combine: its validator's text, which may quote the run's data, stays out.++ The caller reads the code's sentence, and the operator the refusal's location and its type, never the text.+ """# The process-global registry, which the run's own library is seeded from, as a deployment's Python module would.registry = KajsonManager.get_class_registry()registry.register_class(RunFaultViewsValidatedReview)@@ -133,7 +136,9 @@ class TestRunFaultViews:assert caller.location is not Noneassert caller.location.pipe == "analyze"assert operator.diagnostics is not None- assert validator_text in operator.diagnostics.message+ assert validator_text not in operator.diagnostics.message+ assert "DR-7" not in operator.diagnostics.message+ assert "value_error" in operator.diagnostics.messageasync def test_missing_required_input_is_the_callers_fault(self) -> None:"""A run missing a required input: the input domain, a sentence and a next step naming the input."""diff --git a/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py b/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.pyindex b9fb5398a..709d52abc 100644--- a/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py+++ b/tests/unit/pipelex/cogt/content_generation/test_render_generate_dry_branch.py@@ -13,10 +13,11 @@ from pipelex.cogt.content_generation.render_generate import render_page_views_anfrom pipelex.config import get_configfrom pipelex.system.job_metadata import JobMetadata, RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.tools.misc.exceptions import RemoteFileFetchErrorclass TestRenderGenerateDryBranch:- def _assignment(self, *, run_mode: PipeRunMode) -> RenderPageViewsAssignment:+ def _assignment(self, *, run_mode: PipeRunMode, input_name: str | None = None) -> RenderPageViewsAssignment:return RenderPageViewsAssignment(job_metadata=JobMetadata(run_metadata=RunMetadata(storage_scope="test/scope", read_scope=None, user_id="u", pipeline_run_id="run_render_dry")@@ -24,6 +25,7 @@ class TestRenderGenerateDryBranch:cogt_run_params=CogtRunParams(run_mode=run_mode),document_uri="file:///tmp/doc.pdf",page_views_dpi=72,+ input_name=input_name,)@pytest.mark.asyncio@@ -62,3 +64,19 @@ class TestRenderGenerateDryBranch:assert len(page_views) == 2assert factory.make_image_content.await_count == 2++ @pytest.mark.asyncio+ async def test_a_failed_fetch_names_the_input_the_document_came_from(self, mocker: MockerFixture) -> None:+ """The document's URL could not be fetched: the failure names the input, which the assignment carries, never the URL."""+ mocker.patch(+ "pipelex.tools.pdf.pypdfium2_renderer.pypdfium2_renderer.render_pdf_pages_from_uri",+ new=mocker.AsyncMock(side_effect=RemoteFileFetchError("Could not fetch a remote file", host="files.example.com")),+ )++ with pytest.raises(RemoteFileFetchError) as exc_info:+ await render_page_views_and_store(+ render_assignment=self._assignment(run_mode=PipeRunMode.LIVE, input_name="contracts[1]"),+ generated_content_factory=mocker.MagicMock(),+ )++ assert exc_info.value.input_name == "contracts[1]"diff --git a/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.py b/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.pynew file mode 100644index 000000000..bed32705d--- /dev/null+++ b/tests/unit/pipelex/cogt/extract/test_extract_fetch_failure.py@@ -0,0 +1,86 @@+import pytest+from mthds.protocol.problem.registry import CoreCode+from typing_extensions import override++from pipelex.cogt.extract.extract_input import ExtractInput+from pipelex.cogt.extract.extract_job import ExtractJob+from pipelex.cogt.extract.extract_job_components import ExtractJobConfig, ExtractJobParams, ExtractJobReport+from pipelex.cogt.extract.extract_output import ExtractOutput+from pipelex.cogt.extract.extract_worker_abstract import ExtractWorkerAbstract+from pipelex.cogt.llm.thinking_mode import ThinkingMode+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+from pipelex.cogt.model_backends.model_type import ModelType+from pipelex.cogt.usage.cost_category import CostCategory+from pipelex.errors.problem import ProblemView+from pipelex.system.job_metadata import JobMetadata, RunMetadata+from pipelex.tools.misc.exceptions import RemoteFileFetchError++SCANNED_PDF_URL = "https://example.com/scans/report.pdf"+++class _UnreachableFileExtractWorker(ExtractWorkerAbstract):+ """An extract worker whose fetch of the file to extract finds the host unreachable, as the fetch helper reports it."""++ @override+ async def _extract_pages(self, extract_job: ExtractJob) -> ExtractOutput:+ msg = "Could not fetch a remote file: the host could not be reached"+ raise RemoteFileFetchError(msg, host="example.com").with_error_code(CoreCode.INPUT_URL_UNREACHABLE)+++def _make_worker() -> _UnreachableFileExtractWorker:+ inference_model = InferenceModelSpec(+ backend_name="test",+ name="test-extractor",+ sdk="test_extract",+ model_type=ModelType.TEXT_EXTRACTOR,+ model_id="test-extractor-1",+ inputs=["pdf"],+ outputs=["text"],+ costs={CostCategory.INPUT: 1.0, CostCategory.OUTPUT: 1.0},+ thinking_mode=ThinkingMode.NONE,+ max_tokens=None,+ max_prompt_images=None,+ )+ return _UnreachableFileExtractWorker(extra_config={}, inference_model=inference_model)+++def _make_job(*, input_name: str | None) -> ExtractJob:+ return ExtractJob(+ extract_input=ExtractInput(document_uri=SCANNED_PDF_URL, input_name=input_name),+ job_params=ExtractJobParams.make_default_extract_job_params(),+ job_config=ExtractJobConfig(),+ job_report=ExtractJobReport(),+ job_metadata=JobMetadata(+ run_metadata=RunMetadata(storage_scope="test/scope", read_scope=None, user_id="test-user", pipeline_run_id="test-run")+ ),+ )++[email protected](loop_scope="class")+class TestExtractFetchFailure:+ @pytest.mark.parametrize(+ ("input_name", "expected_params", "expected_detail"),+ [+ (+ "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.",+ ),+ (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+ ) -> None:+ """The fetch knows the URL alone; the worker knows the input it came from, which the code's sentences name."""+ with pytest.raises(RemoteFileFetchError) as exc_info:+ await _make_worker().extract_pages(extract_job=_make_job(input_name=input_name))++ caller = exc_info.value.to_problem(view=ProblemView.CALLER)++ assert caller.code == CoreCode.INPUT_URL_UNREACHABLE+ assert caller.params is not None+ assert caller.params.as_wire() == expected_params+ assert caller.detail == expected_detail+ assert SCANNED_PDF_URL not in str(caller.to_wire())diff --git a/tests/unit/pipelex/cogt/inference/test_describe_instructor_failure.py b/tests/unit/pipelex/cogt/inference/test_describe_instructor_failure.pynew file mode 100644index 000000000..af4701829--- /dev/null+++ b/tests/unit/pipelex/cogt/inference/test_describe_instructor_failure.py@@ -0,0 +1,142 @@+from collections.abc import Callable++import pytest+import tenacity+from instructor import openai_schema+from instructor.core import InstructorRetryException+from pydantic import BaseModel, ValidationError++from pipelex.cogt.content_generation.llm_generate import make_object_list_schema+from pipelex.cogt.inference.error_classification import (+ ProviderErrorMetadata,+ describe_instructor_failure,+ extract_anthropic_metadata,+ extract_google_metadata,+ extract_mistral_metadata,+ extract_openai_metadata,+ extract_underlying_sdk_exception,+)++# A value no secret pattern matches, standing for the model's answer, which no message carries.+_ANSWER = "confidential-patient-diagnosis"+++class _Tally(BaseModel):+ count: int+++class _SdkError(Exception):+ """An error a provider's SDK raises as its own, whose text is the provider's."""+++def _validation_error_quoting_the_answer(*, schema: type[BaseModel], answer: object) -> ValidationError:+ """The error instructor's own validation raises on the model's answer: it validates with a subclass of the schema."""+ try:+ openai_schema(schema).model_validate(answer)+ except ValidationError as exc:+ return exc+ msg = "The answer was expected to be refused"+ raise AssertionError(msg)+++def _retry_error_whose_last_attempt_returned() -> tenacity.RetryError:+ last_attempt = tenacity.Future(attempt_number=2)+ last_attempt.set_result(_Tally(count=1))+ return tenacity.RetryError(last_attempt=last_attempt)+++def _retry_error_whose_last_attempt_raised(*, exc: BaseException) -> tenacity.RetryError:+ last_attempt = tenacity.Future(attempt_number=2)+ last_attempt.set_exception(exc)+ return tenacity.RetryError(last_attempt=last_attempt)+++def _wrapped(*, cause: BaseException | None) -> InstructorRetryException:+ """An `InstructorRetryException` as instructor raises it: its own text is the last exception's, the answer included."""+ wrapper = InstructorRetryException(+ f"1 validation error for _Tally: count, input_value='{_ANSWER}'",+ last_completion=None,+ n_attempts=2,+ total_usage=0,+ create_kwargs={},+ failed_attempts=[],+ )+ wrapper.__cause__ = cause+ return wrapper+++_EXTRACTORS: list[Callable[..., ProviderErrorMetadata]] = [+ extract_openai_metadata,+ extract_anthropic_metadata,+ extract_google_metadata,+ extract_mistral_metadata,+]+++class TestDescribeInstructorFailure:+ @pytest.mark.parametrize(+ ("topic", "cause", "expected"),+ [+ ("a retry error whose last attempt raised nothing", _retry_error_whose_last_attempt_returned(), "RetryError"),+ ("no cause at all", None, "InstructorRetryException"),+ ("a cause with a text of its own", ValueError(f"the model said {_ANSWER}"), "ValueError"),+ ],+ )+ def test_an_unrecovered_failure_is_named_by_its_class_alone(self, topic: str, cause: BaseException | None, expected: str) -> None:+ """Nothing was recovered: the wrapper's cause, or the wrapper, is named by its class, never by a text or a repr."""+ reason = describe_instructor_failure(instructor_exc=_wrapped(cause=cause))++ assert reason == expected, topic+ assert "0x" not in reason, topic+ assert _ANSWER not in reason, topic++ def test_a_retry_error_with_nothing_raised_recovers_nothing(self) -> None:+ """The case `describe_instructor_failure` serves: the extraction gives `None`, and the retry error's repr stays out."""+ instructor_exc = _wrapped(cause=_retry_error_whose_last_attempt_returned())++ assert extract_underlying_sdk_exception(instructor_exc) is None+ assert describe_instructor_failure(instructor_exc=instructor_exc) == "RetryError"++ @pytest.mark.parametrize("extract_metadata", _EXTRACTORS)+ def test_the_common_path_locates_the_refusal_by_the_requested_schema(self, extract_metadata: Callable[..., ProviderErrorMetadata]) -> None:+ """Re-asks exhausted on a refused answer: the recovered error is located by the schema, its answer never quoted."""+ refusal = _validation_error_quoting_the_answer(schema=_Tally, answer={"count": _ANSWER})+ underlying = extract_underlying_sdk_exception(_wrapped(cause=_retry_error_whose_last_attempt_raised(exc=refusal)))+ assert underlying is refusal++ metadata = extract_metadata(underlying, validated_type=_Tally)++ assert metadata.message.startswith("count: Input should be a valid integer")+ assert _ANSWER not in metadata.message++ def test_a_list_of_objects_is_located_through_its_wrapper(self) -> None:+ """The wrapper a list of objects is generated as carries its name as its title, so its refusal is located too."""+ list_schema = make_object_list_schema(item_class=_Tally, item_class_name="Tally")+ refusal = _validation_error_quoting_the_answer(schema=list_schema, answer={"items": [{"count": 1}, {"count": _ANSWER}]})++ metadata = extract_openai_metadata(refusal, validated_type=list_schema)++ assert metadata.message.startswith("items.1.count: Input should be a valid integer")+ assert _ANSWER not in metadata.message++ @pytest.mark.parametrize("extract_metadata", _EXTRACTORS)+ def test_any_other_parsing_failure_is_named_by_its_class_alone(self, extract_metadata: Callable[..., ProviderErrorMetadata]) -> None:+ """Instructor's OpenAI parser asserts on a refusal with the model's answer in its text: the recovered assertion is named by its class."""+ refusal = AssertionError(f"Unable to generate a response due to {_ANSWER}")+ underlying = extract_underlying_sdk_exception(_wrapped(cause=refusal))+ assert underlying is refusal++ metadata = extract_metadata(underlying, validated_type=_Tally, sdk_error_types=(_SdkError,))++ assert metadata.message == "AssertionError"+ assert metadata.sdk_exception_type == "AssertionError"++ @pytest.mark.parametrize("extract_metadata", _EXTRACTORS)+ def test_a_recovered_sdk_error_keeps_the_provider_s_text(self, extract_metadata: Callable[..., ProviderErrorMetadata]) -> None:+ """A call that failed in transport ends the loop on the SDK's own error, whose text the classification reads."""+ sdk_error = _SdkError("You exceeded your current quota")+ underlying = extract_underlying_sdk_exception(_wrapped(cause=sdk_error))++ metadata = extract_metadata(underlying, validated_type=_Tally, sdk_error_types=(_SdkError,))++ assert metadata.message == "You exceeded your current quota"diff --git a/tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py b/tests/unit/pipelex/cogt/inference/test_provider_classification_parity.pyindex 3c786e5fc..cdc9f669c 100644--- a/tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py+++ b/tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py@@ -8,6 +8,7 @@ This test fails fast in that case by walking the enum against a registry.from collections.abc import Callableimport pytest+from pydantic import BaseModel, ValidationErrorfrom pipelex.cogt.inference.error_classification import (ProviderErrorMetadata,@@ -46,6 +47,16 @@ _PROVIDER_TO_EXTRACT_FN: dict[ProviderName, Callable[..., ProviderErrorMetadata]}+class _Verdict(BaseModel):+ """A structure a model's answer must fit, as instructor validates it."""++ score: int+++# The model's answer, which a ValidationError's own text quotes and no metadata message may carry.+_MODEL_ANSWER = "zebra-quartz-ledger-5521"++class TestProviderClassificationParity:"""Walk the registry against the enum to catch unwired providers."""@@ -63,3 +74,21 @@ class TestProviderClassificationParity:assert metadata.provider is providerassert metadata.sdk_exception_type == "RuntimeError"assert metadata.message == "synthetic SDK error for parity check"++ @pytest.mark.parametrize("provider", list(ProviderName))+ def test_extract_fn_writes_a_refused_answer_without_the_answer(self, provider: ProviderName) -> None:+ """The validation error that ends instructor's re-asks quotes the model's answer, which the message never carries.++ The provider's metadata does not know the schema the answer was refused by, and a location read without it could+ quote a key of the answer's own, so the refusal is written by its reasons alone: the step's own message, which+ knows its output's class, gives the locations.+ """+ extract_fn = _PROVIDER_TO_EXTRACT_FN[provider]+ with pytest.raises(ValidationError) as refusal:+ _Verdict.model_validate({"score": _MODEL_ANSWER})+ assert _MODEL_ANSWER in str(refusal.value)++ validation_error = refusal.value+ metadata = extract_fn(validation_error, provider=provider) if provider.is_local_file_extractor else extract_fn(validation_error)++ assert metadata.message == "Input should be a valid integer, unable to parse string as an integer"diff --git a/tests/unit/pipelex/cogt/test_prompt_file_fetch_input.py b/tests/unit/pipelex/cogt/test_prompt_file_fetch_input.pynew file mode 100644index 000000000..4da171bd0--- /dev/null+++ b/tests/unit/pipelex/cogt/test_prompt_file_fetch_input.py@@ -0,0 +1,75 @@+from collections.abc import Awaitable, Callable++import pytest+from mthds.protocol.problem.registry import CoreCode+from pytest_mock import MockerFixture++from pipelex.cogt.document import prompt_document_utils+from pipelex.cogt.document.prompt_document_factory import PromptDocumentFactory+from pipelex.cogt.document.prompt_document_utils import prepare_prompt_document, prepare_prompt_document_as_base64+from pipelex.cogt.image import prompt_image_utils+from pipelex.cogt.image.prompt_image_factory import PromptImageFactory+from pipelex.cogt.image.prompt_image_utils import prepare_prompt_image, prepare_prompt_image_as_base64+from pipelex.errors.problem import ProblemView+from pipelex.tools.misc.exceptions import RemoteFileFetchError+from pipelex.tools.misc.file_fetch_utils import fetching_for_input++# The URL of a caller's input, which no message names.+_URL = "https://files.example.com/jane-doe-scan.png"+++def _unreachable() -> RemoteFileFetchError:+ return RemoteFileFetchError("Could not fetch a remote file: the server did not answer", host="files.example.com").with_error_code(+ CoreCode.INPUT_URL_UNREACHABLE+ )+++async def _prepare_image(*, input_name: str | None) -> object:+ return await prepare_prompt_image(PromptImageFactory.make_prompt_image(uri=_URL, input_name=input_name), is_http_url_enabled=False)+++async def _prepare_image_as_base64(*, input_name: str | None) -> object:+ return await prepare_prompt_image_as_base64(PromptImageFactory.make_prompt_image(uri=_URL, input_name=input_name))+++async def _prepare_document(*, input_name: str | None) -> object:+ return await prepare_prompt_document(PromptDocumentFactory.make_prompt_document(uri=_URL, input_name=input_name), is_http_url_enabled=False)+++async def _prepare_document_as_base64(*, input_name: str | None) -> object:+ return await prepare_prompt_document_as_base64(PromptDocumentFactory.make_prompt_document(uri=_URL, input_name=input_name))++[email protected](loop_scope="class")+class TestPromptFileFetchInput:+ @pytest.mark.parametrize(+ "prepare",+ [_prepare_image, _prepare_image_as_base64, _prepare_document, _prepare_document_as_base64],+ ids=["image", "image_as_base64", "document", "document_as_base64"],+ )+ async def test_a_failed_fetch_names_the_input_the_prompt_read_it_from(+ self, mocker: MockerFixture, prepare: Callable[..., Awaitable[object]]+ ) -> None:+ """A prompt's image or document fetched from its URL: the failure names the input, never the URL."""+ for module in (prompt_image_utils, prompt_document_utils):+ mocker.patch.object(module, "fetch_file_from_url_httpx", side_effect=_unreachable())++ with pytest.raises(RemoteFileFetchError) as exc_info:+ await prepare(input_name="scans[2]")++ caller = exc_info.value.to_problem(view=ProblemView.CALLER)+ assert caller.params is not None+ assert caller.params.as_wire() == {"input": "scans[2]", "host": "files.example.com"}+ assert "jane-doe-scan" not in str(caller.to_wire())++ async def test_a_url_no_input_gave_names_no_input(self) -> None:+ with pytest.raises(RemoteFileFetchError) as exc_info, fetching_for_input(input_name=None):+ raise _unreachable()++ assert exc_info.value.input_name is None++ async def test_an_input_already_named_is_kept(self) -> None:+ with pytest.raises(RemoteFileFetchError) as exc_info, fetching_for_input(input_name="outer"):+ raise _unreachable().with_input(input_name="inner")++ assert exc_info.value.input_name == "inner"diff --git a/tests/unit/pipelex/core/memory/input_shaper/data.py b/tests/unit/pipelex/core/memory/input_shaper/data.pyindex dffb24be2..4258d4eb1 100644--- a/tests/unit/pipelex/core/memory/input_shaper/data.py+++ b/tests/unit/pipelex/core/memory/input_shaper/data.py@@ -76,6 +76,12 @@ class ShaperRecord(StructuredContent):b: int | None = Field(default=None, description="Another optional number")+class ShaperLedger(StructuredContent):+ """A structure holding a dict, whose keys are the caller's own text."""++ scores: dict[str, int] = Field(description="A score by name")++class ShaperWeird(StructuredContent):"""A pathological structure whose fields are literally `concept` and `content` (collision-rule test)."""@@ -101,6 +107,7 @@ CONCEPT_DEFS: list[tuple[str, str, str | None]] = [("ShaperPerson", "ShaperPerson", None),("ShaperRecord", "ShaperRecord", None),("ShaperWeird", "ShaperWeird", None),+ ("ShaperLedger", "ShaperLedger", None),]CONCEPT_REFS: list[str] = [f"{SHAPER_TEST_DOMAIN}.{concept_code}" for concept_code, _, _ in CONCEPT_DEFS]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.pyindex 35c347cc0..153d0a509 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@@ -5,15 +5,18 @@ non-tabular values, singular declarations, and record dicts with sibling keys alto the normal shaping arms."""+import jsonfrom pathlib import Pathfrom typing import Any, castimport pytest+from mthds.protocol.problem.registry import CoreCodefrom pipelex.core.memory.exceptions import MultiplicityCountMismatchError, StructureValidationError, WrongScalarKindErrorfrom pipelex.core.memory.input_shaper import InputShaperfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.stuff_content import StuffContent+from pipelex.errors.problem import ProblemViewfrom pipelex.interpreter_hub import get_concept_libraryfrom pipelex.tools.tabular.exceptions import CsvErrorfrom tests.unit.pipelex.core.memory.input_shaper.data import ShaperPerson, build_input_specs@@ -105,3 +108,41 @@ class TestInputShaperCsvBySignature:InputShaper.shape({"people": "https://example.com/people.csv"}, input_specs=input_specs, concept_provider=get_concept_library(), read_scope=None)++ @pytest.mark.parametrize(+ ("topic", "url", "expected_location"),+ [+ ("a scheme Pipelex reads", "s3://bucket/people.csv", "a remote or non-local url, in the scheme 's3'"),+ ("a scheme Pipelex reads, written in capitals", "HTTPS://example.com/people.csv", "a remote or non-local url, in the scheme 'https'"),+ ("a scheme that is the caller's own text", "confidential-patient-diagnosis://records/people.csv", "a remote or non-local url"),+ ],+ )+ def test_a_remote_table_names_its_scheme_only_when_pipelex_reads_it(self, topic: str, url: str, expected_location: str):+ """A url's scheme is the caller's text: the refusal names one Pipelex reads, never one the caller made up."""+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])++ with pytest.raises(CsvError) as exc_info:+ InputShaper.shape({"people": {"url": url}}, input_specs=input_specs, concept_provider=get_concept_library(), read_scope=None)++ assert str(exc_info.value) == (+ "CSV input supports local file paths only in v1, but stuff 'people' for concept 'shaper_test.ShaperPerson' points at "+ f"{expected_location}. Download the file locally and reference it by path."+ ), topic+ operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)+ assert "confidential" not in json.dumps(operator.to_wire()), topic++ 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."""+ csv_path = tmp_path / "confidential-patient-diagnosis.csv"+ csv_path.write_text("name,confidential-column\nAda,x\n", encoding="utf-8")+ input_specs = build_input_specs([("people", "shaper_test.ShaperPerson", True)])++ with pytest.raises(CsvError) as exc_info:+ InputShaper.shape({"people": str(csv_path)}, 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"}+ 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.pyindex 8827b5862..41dd29d6b 100644--- a/tests/unit/pipelex/core/memory/input_shaper/test_errors.py+++ b/tests/unit/pipelex/core/memory/input_shaper/test_errors.py@@ -1,3 +1,4 @@+import jsonfrom typing import Anyimport pytest@@ -170,6 +171,16 @@ CALLER_VIEW_CASES: list[tuple[str, str, VariableMultiplicity | None, Any, CoreCo{"input": "my_input", "field": "amount"},"The input 'my_input' does not fit its concept's structure at 'amount'.",),+ # A key of a dict the value holds is the caller's own text: the field is named as far as the structure names it.+ (+ "structure-dict-value",+ "shaper_test.ShaperLedger",+ None,+ {"scores": {"confidential-patient-diagnosis": "high"}},+ CoreCode.INPUT_INVALID,+ {"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),@@ -238,6 +249,8 @@ class TestInputShaperErrors:assert caller.detail == (expected_detail or error_code_spec(expected_code).title)assert caller.location is not Noneassert caller.location.as_wire() == {"input": "my_input"}+ operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)+ assert "confidential-patient-diagnosis" not in json.dumps(operator.to_wire())def test_an_unknown_input_name_is_named_to_the_caller(self) -> None:input_specs = build_input_specs([("question", "native.Text", None)])diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.pyindex f75919cfe..669cb4f16 100644--- a/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py+++ b/tests/unit/pipelex/core/memory/input_shaper/test_explicit_forms.py@@ -2,6 +2,7 @@ import datetimefrom typing import Anyimport pytest+from mthds.protocol.problem.registry import CoreCodefrom pydantic import ValidationErrorfrom pipelex import log, pretty_print@@ -11,8 +12,10 @@ from pipelex.core.memory.exceptions import (MultiplicityCountMismatchError,)from pipelex.core.memory.input_shaper import InputShaper+from pipelex.core.stuffs.exceptions import StuffFactoryErrorfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.time_content import TimeContent+from pipelex.errors.problem import ProblemViewfrom pipelex.interpreter_hub import get_concept_libraryfrom tests.unit.pipelex.core.memory.input_shaper.data import OpeningTime, Question, ShaperInvoice, ShaperWeird, build_input_specs@@ -135,13 +138,38 @@ class TestInputShaperExplicitForms:@pytest.mark.parametrize("declared_concept", ["native.Number", "native.Anything"])def test_explicit_number_envelope_holding_nan_raises(self, declared_concept: str) -> None:- """An explicit envelope builds its content bottom-up, and `NumberContent` refuses a number JSON cannot hold."""+ """An explicit envelope builds its content bottom-up, and `NumberContent` refuses a number JSON cannot hold.++ The refusal is the input's, located by the content class's schema, and names the input and the field.+ """input_specs = build_input_specs([("payload", declared_concept, None)])provided: dict[str, Any] = {"concept": "Number", "content": {"number": float("nan")}}- with pytest.raises(ValidationError, match="number must be finite"):+ with pytest.raises(StuffFactoryError, match="number: Value error, number must be finite") as exc_info:InputShaper.shape({"payload": provided}, input_specs=input_specs, concept_provider=get_concept_library(), read_scope=None)+ assert isinstance(exc_info.value.__cause__, ValidationError)+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)+ assert problem.code == CoreCode.INPUT_INVALID+ assert problem.params is not None+ assert problem.params.as_wire() == {"input": "payload", "field": "number"}++ def test_explicit_structure_envelope_refusal_names_the_field_and_never_the_value(self) -> None:+ """An explicit envelope of a structure refused by its class: the field is located, the value it held never quoted."""+ input_specs = build_input_specs([("invoice", "shaper_test.ShaperInvoice", None)])+ provided: dict[str, Any] = {"concept": "shaper_test.ShaperInvoice", "content": {"invoice_number": "INV-1", "amount": "[email protected]"}}++ with pytest.raises(StuffFactoryError) as exc_info:+ InputShaper.shape(+ {"invoice": provided}, input_specs=input_specs, search_scope="shaper_test", concept_provider=get_concept_library(), read_scope=None+ )++ assert "amount: Input should be a valid number" in str(exc_info.value)+ assert "[email protected]" not in str(exc_info.value)+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)+ assert problem.params is not None+ assert problem.params.as_wire() == {"input": "invoice", "field": "amount"}+def test_explicit_single_into_fixed_count_raises(self) -> None:"""A single value is one item, never the N a fixed count declares."""input_specs = build_input_specs([("answers", "native.Text", 2)])diff --git a/tests/unit/pipelex/core/memory/input_shaper/test_fallback_refusal.py b/tests/unit/pipelex/core/memory/input_shaper/test_fallback_refusal.pyindex 20541e5d6..c8b7642b2 100644--- a/tests/unit/pipelex/core/memory/input_shaper/test_fallback_refusal.py+++ b/tests/unit/pipelex/core/memory/input_shaper/test_fallback_refusal.py@@ -66,7 +66,10 @@ class TestInputShaperFallbackRefusal:with pytest.raises(StructureValidationError, match=r"Input 'payload' could not be built as 'native\.Dynamic'") as exc_info:InputShaper.shape(payload_input, input_specs=input_specs, concept_provider=get_concept_library(), read_scope=None)- assert "a number (3)" in str(exc_info.value)+ # The value is described by its kind, never quoted: it is the run's input.+ refusal = str(exc_info.value).split("Expected shape")[0]+ assert "you provided a number," in refusal+ assert "3" not in refusalassert isinstance(exc_info.value.__cause__, StuffFactoryError)@pytest.mark.parametrize(@@ -179,10 +182,10 @@ class TestInputShaperFallbackRefusal:@pytest.mark.parametrize(("concept_ref", "multiplicity", "provided_value", "provided_description"),[- ("native.Rating", None, 2, "a number (2)"),+ ("native.Rating", None, 2, "a number"),("native.Rating", True, [1, 2], "a list of 2 item(s)"),- ("native.Rating", None, True, "a boolean (true)"),- ("native.Choice", None, 3, "a number (3)"),+ ("native.Rating", None, True, "a boolean"),+ ("native.Choice", None, 3, "a number"),],)def test_a_scalar_at_a_verdict_input_is_told_to_send_the_envelope(diff --git a/tests/unit/pipelex/core/memory/test_working_memory_basic.py b/tests/unit/pipelex/core/memory/test_working_memory_basic.pyindex 0b631d95b..198ff47f8 100644--- a/tests/unit/pipelex/core/memory/test_working_memory_basic.py+++ b/tests/unit/pipelex/core/memory/test_working_memory_basic.py@@ -3,6 +3,7 @@ from pytest_mock import MockerFixturefrom pipelex.core.concepts.concept_factory import ConceptFactoryfrom pipelex.core.concepts.native.concept_native import NativeConceptCode+from pipelex.core.memory.exceptions import WorkingMemoryFactoryErrorfrom pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemoryfrom pipelex.core.memory.working_memory_factory import WorkingMemoryFactoryfrom pipelex.core.stuffs.stuff_factory import StuffFactory@@ -59,3 +60,20 @@ class TestWorkingMemoryBasic:WorkingMemory(root={key: stuff})warning_mock.assert_called_once_with("A stuff name starts with an underscore, which is reserved for params", fields={"stuff_name": "_draft"})++ def test_a_nameless_stuff_is_refused_by_its_header_never_its_content(self):+ """A stuff's own text carries its content, the run's data: the refusal names its code and its concept alone."""+ content_text = "the run's own words, which no message carries"+ stuff = StuffFactory.make_stuff(+ concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT),+ content=TextContent(text=content_text),+ ).model_copy(update={"stuff_name": None})++ with pytest.raises(WorkingMemoryFactoryError) as single_refusal:+ WorkingMemoryFactory.make_from_single_stuff(stuff)+ with pytest.raises(WorkingMemoryFactoryError) as multiple_refusal:+ WorkingMemoryFactory.make_from_multiple_stuffs([stuff])++ for refusal in (single_refusal.value, multiple_refusal.value):+ assert stuff.header in str(refusal)+ assert content_text not in str(refusal)diff --git a/tests/unit/pipelex/core/stuffs/test_stuff_verify_content_type.py b/tests/unit/pipelex/core/stuffs/test_stuff_verify_content_type.pyindex 603df443c..0c496cd08 100644--- a/tests/unit/pipelex/core/stuffs/test_stuff_verify_content_type.py+++ b/tests/unit/pipelex/core/stuffs/test_stuff_verify_content_type.py@@ -1,10 +1,32 @@+from typing import Any+import pytest+from pydantic import BaseModel, ConfigDict, create_model-from pipelex.core.stuffs.exceptions import StuffContentTypeError+from pipelex.core.stuffs.exceptions import StuffContentTypeError, StuffContentValidationErrorfrom pipelex.core.stuffs.list_content import ListContent+from pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.core.stuffs.stuff import Stufffrom pipelex.core.stuffs.text_content import TextContent+# A key of the run's own data, which no message carries.+_PAYLOAD_KEY = "confidential-patient-diagnosis"+++class _Entry(BaseModel):+ model_config = ConfigDict(extra="forbid")++ score: int+++# Two classes of one name, as a domain-qualified dynamic class and its bare twin are: the content is converted by validation.+_LooseLedger = create_model("Ledger", __base__=StructuredContent, entries=(dict[str, Any], ...), owner=(dict[str, Any], {"score": 0}))+_Ledger = create_model("Ledger", __base__=StructuredContent, entries=(dict[str, _Entry], ...), owner=(_Entry, _Entry(score=0)))+++def _loose_ledger(**fields: Any) -> StructuredContent:+ return _LooseLedger.model_validate(fields)+class TestVerifyContentType:def test_verify_content_type_with_list_content_generic_raises_helpful_error(self):@@ -51,3 +73,33 @@ class TestVerifyContentType:error_message = str(exc_info.value)assert "TextContent" in error_messageassert "ListContent" in error_message++ @pytest.mark.parametrize(+ ("topic", "content", "expected_error"),+ [+ (+ "an invalid value under a key of the content's own",+ _loose_ledger(entries={_PAYLOAD_KEY: {"score": "high"}}),+ "entries.<key>.score: Input should be a valid integer, unable to parse string as an integer",+ ),+ (+ "an extra key under a key of the content's own",+ _loose_ledger(entries={_PAYLOAD_KEY: {"score": 1, _PAYLOAD_KEY: 2}}),+ "entries.<key>.<key>: Extra inputs are not permitted",+ ),+ (+ "an extra field of a nested model",+ _loose_ledger(entries={}, owner={"score": 1, _PAYLOAD_KEY: 2}),+ "owner.<key>: Extra inputs are not permitted",+ ),+ ],+ )+ def test_a_refused_conversion_names_the_schema_s_fields_never_the_content_s_keys(+ self, topic: str, content: StructuredContent, expected_error: str+ ) -> None:+ """A location quotes the keys a dict of the content holds, which are the run's data: only the schema's names are written."""+ with pytest.raises(StuffContentValidationError) as exc_info:+ Stuff.verify_content_type(content=content, content_type=_Ledger)++ assert exc_info.value.validation_error == expected_error, topic+ assert _PAYLOAD_KEY not in str(exc_info.value), topicdiff --git a/tests/unit/pipelex/kernel/test_run_judgment.py b/tests/unit/pipelex/kernel/test_run_judgment.pyindex 8701cb1d8..ead7a57b0 100644--- a/tests/unit/pipelex/kernel/test_run_judgment.py+++ b/tests/unit/pipelex/kernel/test_run_judgment.py@@ -111,7 +111,7 @@ class TestRunJudgment:assert list(assignment.questions) == ["question"]assert assignment.questions["question"].instructions == "Is this urgent, given that it says 'The roof is on fire.'?"assert assignment.prompt.text == "A message from a customer: The roof is on fire.\nThe photo they sent: [Image 1]"- assert assignment.prompt.images == [PromptImageUri(uri=_ROOF_PHOTO, mime_type="image/png")]+ assert assignment.prompt.images == [PromptImageUri(uri=_ROOF_PHOTO, mime_type="image/png", input_name="photo")]assert assignment.prompt.documents == []assert result.prompt == assignment.promptassert result.rendered_question == "Is this urgent, given that it says 'The roof is on fire.'?"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.pyindex 76631d0e0..6b455d437 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@@ -102,6 +102,37 @@ class _TransportFailingExecutor(PipeFuncExecutorProtocol):raise NotImplementedError(msg)+#: What a function's own text can quote: the run's input.+_FUNCTION_TEXT = "cannot file the note 'confidential-patient-diagnosis'"+++class _OutOfProcessExecutor(PipeFuncExecutorProtocol):+ """An out-of-process executor reporting what the function raised as a coded Pipelex error, as its carrier rebuilds it.++ The far process's message holds the function's own text, and no exception of the function's rides as its cause.+ """++ def __init__(self, *, failure: Exception) -> None:+ self.failure = failure++ @override+ async def run_pipe_func(+ self,+ *,+ job_metadata: JobMetadata,+ pipe_code: str,+ function_name: str,+ working_memory: WorkingMemory,+ pipe_run_params: PipeRunParams,+ ) -> PipeFuncExecutionResult:+ raise self.failure++ @override+ async def run_pipe_func_transported(self, *, request: PipeFuncExecutionRequest) -> PipeFuncExecutionResponse:+ msg = "Not used by this test"+ raise NotImplementedError(msg)++def _make_pipe_func() -> PipeFunc:blueprint = PipeFuncBlueprint(description="Read the parcel's line in the ledger",@@ -151,12 +182,16 @@ class TestPipeFuncFailureCode:assert caller.code == CoreCode.PIPE_FUNCTION_RAISEDassert isinstance(failure.__cause__, PipeFuncRaisedError)assert type(failure.__cause__.__cause__).__name__ == raised_type- assert f"Error: {raised_type}: " in failure.message- # What the function raised can carry whatever the process holds, so its text is the operator's alone.+ assert f"Error: The function raised {raised_type}" in failure.message+ # What the function raised can quote the run's inputs or whatever the process holds: its class names it, and its+ # text reaches no view, the operator's included.+ function_text = str(failure.__cause__.__cause__)+ assert function_text not in failure.messageassert raised_type not in str(caller.to_wire())operator = failure.to_problem(view=ProblemView.OPERATOR)assert operator.diagnostics is not Noneassert operator.diagnostics.message == failure.message+ assert function_text not in str(operator.to_wire())@pytest.mark.parametrize(("executor", "expected_code"),@@ -182,6 +217,35 @@ class TestPipeFuncFailureCode:assert failure.to_problem(view=ProblemView.CALLER).code == expected_code+ @pytest.mark.parametrize(+ ("failure", "expected_error"),+ [+ (PipeFuncRaisedError(f"KeyError: {_FUNCTION_TEXT}"), "Error: The function raised an exception"),+ (+ PipeFuncExecutionError(f"The function failed in the sandbox: {_FUNCTION_TEXT}"),+ "Error: PipeFuncExecutionError (runtime.unexpected)",+ ),+ (ConnectionResetError(f"The sandbox closed the call: {_FUNCTION_TEXT}"), "Error: ConnectionResetError"),+ ],+ ids=["function_raised_far_away", "coded_seam_failure", "foreign_transport_failure"],+ )+ @pytest.mark.asyncio+ async def test_an_out_of_process_failure_is_named_without_its_text(+ self,+ load_empty_library: Callable[[], str],+ mocker: MockerFixture,+ failure: Exception,+ expected_error: str,+ ) -> None:+ """Whatever an executor raised, its text can hold the function's own, which quotes the run's inputs: the step names its class."""+ load_empty_library()+ mocker.patch("pipelex.pipe_operators.func.pipe_func.is_pipe_func_sandbox_hosted", return_value=True)++ step_failure = await _failure_of(pipe_func=_make_pipe_func(), executor=_OutOfProcessExecutor(failure=failure), function=_raises_a_plain_error)++ assert step_failure.message.endswith(expected_error)+ assert _FUNCTION_TEXT not in step_failure.message+@pytest.mark.parametrize("function",[_returns_a_list_holding_a_dict, _returns_a_list_holding_a_number],diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.pyindex 7f8732dc9..d62ce3621 100644--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py@@ -1156,15 +1156,16 @@ class TestDeliveryExecutor:mock_client = mocker.AsyncMock()mock_client.__aenter__ = mocker.AsyncMock(return_value=mock_client)mock_client.__aexit__ = mocker.AsyncMock(return_value=False)- mock_client.post = mocker.AsyncMock(side_effect=httpx.ConnectError("Connection refused"))+ # The transport's text can quote the caller's webhook URL, a credential in its path included.+ mock_client.post = mocker.AsyncMock(side_effect=httpx.ConnectError("Connection refused by https://down.example.com/hook/token-4f9a"))mocker.patch("pipelex.pipe_run.delivery_executor.httpx.AsyncClient", return_value=mock_client)executor = DeliveryExecutor()assignment = DeliveryAssignment(- webhooks=[WebhookTarget(url="https://down.example.com")],+ webhooks=[WebhookTarget(url="https://down.example.com/hook/token-4f9a")],)- with pytest.raises(WebhookDeliveryError):+ with pytest.raises(WebhookDeliveryError) as exc_info:await executor.execute(pipe_output=None,storage_scope="test-user",@@ -1172,3 +1173,5 @@ class TestDeliveryExecutor:delivery_assignment=assignment,status=DeliveryStatus.COMPLETED,)++ assert str(exc_info.value) == "Webhook delivery failed for pipeline_run_id=plr-err: ConnectError"diff --git a/tests/unit/pipelex/pipe_run/test_located_failure.py b/tests/unit/pipelex/pipe_run/test_located_failure.pyindex c95b0d86a..20810f64b 100644--- a/tests/unit/pipelex/pipe_run/test_located_failure.py+++ b/tests/unit/pipelex/pipe_run/test_located_failure.py@@ -4,6 +4,7 @@ import loggingimport pytestfrom mthds.protocol.problem.registry import CoreCode, StepKind+from pydantic import BaseModel, ValidationErrorfrom typing_extensions import overridefrom pipelex.base_exceptions import PipelexError@@ -106,6 +107,36 @@ class TestLocatedFailureProblem:assert problem.diagnostics.error_class == "PipelexUnexpectedError"assert "boom" not in str(located.to_problem(view=ProblemView.CALLER).to_wire())+ @pytest.mark.parametrize(+ "foreign_fault",+ [+ KeyError("[email protected]"),+ ValueError("could not parse '[email protected]'"),+ RuntimeError("[email protected]"),+ ],+ )+ def test_a_foreign_exception_is_named_by_its_class_alone(self, foreign_fault: Exception) -> None:+ """A foreign exception's text can carry the run's data: the stand-in's message, the operator's diagnostics, is its class."""+ unexpected_failure = make_unexpected_failure(error=foreign_fault)++ assert unexpected_failure.message == type(foreign_fault).__name__+ assert unexpected_failure.__cause__ is foreign_fault+ operator = unexpected_failure.to_problem(view=ProblemView.OPERATOR)+ assert operator.diagnostics is not None+ assert "[email protected]" not in str(operator.to_wire())++ def test_a_foreign_validation_error_keeps_its_reasons_without_its_input(self) -> None:+ """A raw pydantic refusal names its reasons, which hold no value, and no location, since its model is not known."""++ class _Contact(BaseModel):+ emails: dict[str, int]++ with pytest.raises(ValidationError) as exc_info:+ _Contact.model_validate({"emails": {"[email protected]": "secret-value"}})+ unexpected_failure = make_unexpected_failure(error=exc_info.value)++ assert unexpected_failure.message == "ValidationError: Input should be a valid integer, unable to parse string as an integer"+def test_a_same_class_rethrow_keeps_its_added_context(self) -> None:"""An error raised from one of its own class restates the fault with context: the outer one is reported."""low_level = CogtError(message="size out of range", error_category=InferenceErrorCategory.CONTENT)diff --git a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py b/tests/unit/pipelex/pipe_run/test_pipe_router_run.pyindex 7c2a0a481..f3766e4eb 100644--- a/tests/unit/pipelex/pipe_run/test_pipe_router_run.py+++ b/tests/unit/pipelex/pipe_run/test_pipe_router_run.py@@ -18,7 +18,7 @@ from pipelex.pipe_run.pipe_router_protocol import PipeRouterProtocolfrom pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactoryfrom pipelex.system.job_metadata import JobMetadata, RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputif TYPE_CHECKING:from pipelex.pipe_machinery.pipe_abstract import PipeAbstract@@ -179,17 +179,19 @@ class TestPipeRouterRun:unexpected = exc_info.value.__cause__assert isinstance(unexpected, PipelexUnexpectedError)assert unexpected.__cause__ is foreign_error- assert unexpected.message == "ValueError: unexpected value"- assert exc_info.value.message == "Pipe 'stub_pipe' failed: ValueError: unexpected value"+ # Named by its class, never its text, which can carry anything of the run's data.+ assert unexpected.message == "ValueError"+ assert exc_info.value.message == "Pipe 'stub_pipe' failed: ValueError"operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)assert operator.code == CoreCode.RUNTIME_UNEXPECTEDassert operator.diagnostics is not Noneassert operator.diagnostics.error_class == "PipelexUnexpectedError"- assert operator.diagnostics.message == "ValueError: unexpected value"+ assert operator.diagnostics.message == "ValueError"+ assert "unexpected value" not in str(operator.to_wire())assert "unexpected value" not in str(exc_info.value.to_problem(view=ProblemView.CALLER).to_wire())- async def test_pydantic_validation_error_keeps_its_readable_rendering(self) -> None:- """A pydantic ValidationError is named and rendered the way the runner renders one."""+ async def test_pydantic_validation_error_is_rendered_without_the_value_it_refused(self) -> None:+ """A pydantic ValidationError is named and rendered by its locations and reasons, the value being the run's data."""with pytest.raises(ValidationError) as validation_info:_MiniPayload(count="not-a-number") # pyright: ignore[reportArgumentType]router = _StubPipeRouter(error=validation_info.value)@@ -199,7 +201,8 @@ class TestPipeRouterRun:unexpected = exc_info.value.__cause__assert isinstance(unexpected, PipelexUnexpectedError)- assert unexpected.message == f"ValidationError: {format_pydantic_validation_error(validation_info.value)}"+ assert unexpected.message == f"ValidationError: {format_validation_error_without_input(validation_error=validation_info.value)}"+ assert "not-a-number" not in unexpected.messageasync def test_already_located_failure_keeps_the_innermost_location(self) -> None:"""A failure a router below already located passes through untouched: the innermost location wins."""diff --git a/tests/unit/pipelex/pipe_run/test_pipe_run.py b/tests/unit/pipelex/pipe_run/test_pipe_run.pyindex 0d774b990..d408a5a1a 100644--- a/tests/unit/pipelex/pipe_run/test_pipe_run.py+++ b/tests/unit/pipelex/pipe_run/test_pipe_run.py@@ -165,9 +165,71 @@ class TestPipeRun:assert record_fields["pipe_code"] == "describe_company"assert record_fields["pipe_ref"] == "company.describe_company"assert record_fields["error.type"] == "RuntimeError"- assert record_fields["error.message"] == "router blew up"+ assert record_fields["error.code"] == "runtime.unexpected"assert failure_record.exc_info is None+ async def test_the_failure_line_carries_the_code_and_never_the_exception_s_text(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture+ ) -> None:+ """An exception's text can hold the caller's own words or a refused host: the line names its code and class alone."""+ caller_words = "the caller's own words, which no log line carries"+ mock_router = mocker.AsyncMock()+ mock_router.run = mocker.AsyncMock(side_effect=RuntimeError(caller_words))+ mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")+ mock_job = mocker.MagicMock()+ mock_job.pipe.code = "describe_company"+ mock_job.pipe.pipe_ref = "company.describe_company"+ mock_job.job_metadata = JobMetadata(+ run_metadata=RunMetadata(user_id="pytest", pipeline_run_id="plr-failure-text", storage_scope="test/scope", read_scope=None)+ )++ with pytest.raises(RuntimeError), caplog.at_level(logging.DEBUG, logger=pipe_run_module.__name__):+ await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job)++ own_records = [record for record in caplog.records if record.name == pipe_run_module.__name__]+ assert own_records+ for record in own_records:+ assert "error.message" not in vars(record)+ assert caller_words not in str(vars(record))++ @pytest.mark.parametrize("secondary_failure", ["delivery", "tracer_close"])+ async def test_a_failure_after_the_pipe_s_own_is_logged_by_class_and_code_alone(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, secondary_failure: str+ ) -> None:+ """A delivery's text names the caller's webhook URL, an OSError's the trace file: the line names the class and the code."""+ secret = "https://hooks.example.com/jane-doe/token-4f9a"+ mock_router = mocker.AsyncMock()+ mock_router.run = mocker.AsyncMock(side_effect=RuntimeError("router blew up"))+ mock_executor = mocker.patch("pipelex.pipe_run.pipe_run.DeliveryExecutor")+ mock_executor.return_value.execute = mocker.AsyncMock()+ tracer_manager = mocker.MagicMock()+ tracer_manager.close_tracer.return_value = None+ mocker.patch.object(pipe_run_module.GraphTracerManager, "get_instance", return_value=tracer_manager)+ expected_line: str+ expected_fields: dict[str, str]+ match secondary_failure:+ case "delivery":+ mock_executor.return_value.execute = mocker.AsyncMock(side_effect=WebhookDeliveryError(f"Webhook delivery failed: {secret}"))+ expected_line = "The delivery also failed after the pipe execution failed"+ expected_fields = {"error.type": "WebhookDeliveryError", "error.code": str(WebhookDeliveryError(secret).resolve_error_code())}+ case _:+ tracer_manager.close_tracer.side_effect = OSError(f"cannot close {secret}")+ expected_line = "The graph tracer could not be closed after the pipe execution failed"+ expected_fields = {"error.type": "OSError"}+ mock_job = mocker.MagicMock()+ mock_job.job_metadata = JobMetadata(+ run_metadata=RunMetadata(user_id="pytest", pipeline_run_id="plr-secondary", storage_scope="test/scope", read_scope=None)+ )++ with pytest.raises(RuntimeError, match="router blew up"), caplog.at_level(logging.ERROR, logger=pipe_run_module.__name__):+ await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job, delivery_assignment=DeliveryAssignment(storage=StorageTarget()))++ (secondary_record,) = [record for record in caplog.records if record.getMessage() == expected_line]+ record_fields = vars(secondary_record)+ assert {key: record_fields[key] for key in expected_fields} == expected_fields+ 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()@@ -320,7 +382,8 @@ class TestPipeRun:# The problem is the operator's, which each webhook projects to its own view.assert problem.diagnostics is not Noneassert problem.diagnostics.error_class == "PipelexUnexpectedError"- assert problem.diagnostics.message == "RuntimeError: router blew up"+ # Named by its class, never its text, which can carry anything of the run's data.+ assert problem.diagnostics.message == "RuntimeError"@pytest.mark.parametrize("assignment",diff --git a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py b/tests/unit/pipelex/pipe_run/test_tracing_assembly.pyindex b76aa0991..acfb98a38 100644--- a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py+++ b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py@@ -290,6 +290,28 @@ class TestTracingAssembly:assert result.graph_assembly_error is not Noneassert result.tokens_usages == [usage_event.tokens_usage]+ @pytest.mark.parametrize("failing_step", ["read", "assembly"])+ def test_an_assembly_error_never_quotes_a_traced_value(self, mocker: MockerFixture, failing_step: str) -> None:+ """The assembly's errors travel on the run's output: a refusal is written by its reasons, never the value it quotes."""+ self._enable_tracing(mocker)+ traced_value = "[email protected]"+ with pytest.raises(ValidationError) as caught:+ UsageReportEvent.model_validate({"sequence": traced_value})+ event_log = mocker.MagicMock()+ mocker.patch(f"{_MODULE}.make_event_log", return_value=event_log)+ match failing_step:+ case "read":+ event_log.read_events = mocker.MagicMock(side_effect=caught.value)+ case _:+ event_log.read_events = mocker.MagicMock(return_value=[_make_usage_event("plr-quote", "plr-quote:node_0")])+ mocker.patch(f"{_MODULE}.GraphSpecAssembler.assemble", side_effect=caught.value)++ result = assemble_tracing(pipeline_run_id="plr-quote", assemble_graph=True, assemble_usage=False)++ assert result.graph_assembly_error is not None+ assert "Input should be a valid integer" in result.graph_assembly_error+ assert traced_value not in result.graph_assembly_error+def test_unexpected_keyerror_propagates(self, mocker: MockerFixture) -> None:"""Programming bugs (KeyError) propagate — proves tightening from a blanket except Exception."""self._enable_tracing(mocker)diff --git a/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py b/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.pyindex c6777ce5d..54480e31e 100644--- a/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py+++ b/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py@@ -25,7 +25,7 @@ from pipelex.system.job_metadata import RunMetadatafrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.telemetry.events import EventName, EventProperty, Outcomefrom pipelex.tools.network.exceptions import SsrfBlockedError-from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.typing.pydantic_utils import format_validation_error_without_inputif TYPE_CHECKING:from pytest_mock import MockerFixture, MockType@@ -215,7 +215,7 @@ class TestRunnerExecuteErrorPaths:async def test_validation_error_wraps_into_pipe_execution_error(self, mocker: MockerFixture) -> None:"""A pydantic ValidationError raised by the pipe run becomes a PipeExecutionError- whose message names the failing model and embeds the formatted error.+ whose message names the failing model and the refusal's locations and reasons, never the value it refused."""env = self._patch_env(mocker)with pytest.raises(ValidationError) as validation_exc_info:@@ -232,5 +232,6 @@ class TestRunnerExecuteErrorPaths:wrapped = exc_info.valueassert wrapped.__cause__ is validation_errorassert "Input validation failed for '_MiniPayload'" in wrapped.message- assert format_pydantic_validation_error(validation_error) in wrapped.message+ assert format_validation_error_without_input(validation_error=validation_error) in wrapped.message+ assert "not-a-number" not in wrapped.messageenv.telemetry_manager.track_event.assert_not_called()diff --git a/tests/unit/pipelex/providers/test_instructor_retry_shapes.py b/tests/unit/pipelex/providers/test_instructor_retry_shapes.pyindex d8c28c5d5..71c62b502 100644--- a/tests/unit/pipelex/providers/test_instructor_retry_shapes.py+++ b/tests/unit/pipelex/providers/test_instructor_retry_shapes.py@@ -93,6 +93,25 @@ _OPENAI_INVALID_OUTPUT: _ScriptedResponse = ("usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},},)+# A model's refusal, which is its answer and the run's data: no message, diagnostic or provider text may carry it.+_REFUSAL_MARKER = "confidential-patient-diagnosis"+_OPENAI_REFUSAL: _ScriptedResponse = (+ 200,+ {+ "id": "chatcmpl-refusal",+ "object": "chat.completion",+ "created": 0,+ "model": "some-model",+ "choices": [+ {+ "index": 0,+ "finish_reason": "stop",+ "message": {"role": "assistant", "content": None, "refusal": f"I cannot discuss {_REFUSAL_MARKER}."},+ }+ ],+ "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},+ },+)_ANTHROPIC_INVALID_OUTPUT: _ScriptedResponse = (200,{@@ -194,6 +213,32 @@ def _advice_of(error: PipelexError) -> UserAction:return advice+def _make_openai_completions_worker(mocker: MockerFixture, *, client: openai.AsyncOpenAI) -> OpenAICompletionsLLMWorker:+ """The OpenAI completions worker over ``client`` and the real ``from_openai`` loop, built without its configuration."""+ worker = object.__new__(OpenAICompletionsLLMWorker)+ inference_model = mocker.MagicMock()+ inference_model.name = _MODEL_HANDLE+ inference_model.model_id = _WIRE_ID+ inference_model.desc = f"{_MODEL_HANDLE} → SDK[portkey_completions]•Backend[portkey]•Model[{_WIRE_ID}]"+ inference_model.thinking_mode = None+ inference_model.listed_constraints = []+ worker.inference_model = inference_model+ completions_factory = mocker.MagicMock()+ completions_factory.make_simple_messages = mocker.AsyncMock(return_value=[{"role": "user", "content": "Score this lead."}])+ completions_factory.make_extras = mocker.MagicMock(return_value=({}, {}))+ worker.openai_completions_factory = completions_factory+ worker.instructor_for_objects = from_openai(client, mode=Mode.TOOLS)+ return worker+++def _make_object_job(mocker: MockerFixture) -> Any:+ """A structured-generation job re-asking up to ``_MAX_ATTEMPTS`` times."""+ llm_job = make_llm_job(mocker)+ llm_job.job_params.seed = None+ llm_job.job_config.schema_reask_max_attempts = _MAX_ATTEMPTS+ return llm_job++@pytest.mark.asyncio(loop_scope="class")class TestInstructorRetryShapes:@pytest.mark.parametrize(("raised_by", "responses", "sdk_exception_class", "nb_parse_failures"), _API_ERROR_SHAPES)@@ -270,25 +315,11 @@ class TestInstructorRetryShapes:be retried or re-asked."""transport = _ScriptedTransport([_MODEL_NOT_ALLOWED])- worker = object.__new__(OpenAICompletionsLLMWorker)- inference_model = mocker.MagicMock()- inference_model.name = _MODEL_HANDLE- inference_model.model_id = _WIRE_ID- inference_model.desc = f"{_MODEL_HANDLE} → SDK[portkey_completions]•Backend[portkey]•Model[{_WIRE_ID}]"- inference_model.thinking_mode = None- inference_model.listed_constraints = []- worker.inference_model = inference_model- completions_factory = mocker.MagicMock()- completions_factory.make_simple_messages = mocker.AsyncMock(return_value=[{"role": "user", "content": "Score this lead."}])- completions_factory.make_extras = mocker.MagicMock(return_value=({}, {}))- worker.openai_completions_factory = completions_factory- llm_job = make_llm_job(mocker)- llm_job.job_params.seed = None- llm_job.job_config.schema_reask_max_attempts = _MAX_ATTEMPTS+ llm_job = _make_object_job(mocker)async with transport.make_http_client() as http_client:client = openai.AsyncOpenAI(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1", max_retries=0, http_client=http_client)- worker.instructor_for_objects = from_openai(client, mode=Mode.TOOLS)+ worker = _make_openai_completions_worker(mocker, client=client)with pytest.raises(LLMCompletionError) as exc_info:await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]@@ -324,3 +355,34 @@ class TestInstructorRetryShapes:assert f"'{_MODEL_HANDLE}'" in advice.detailassert _WIRE_ID not in advice.detailassert "HTTP 412" in _diagnostics_of(problem).message++ async def test_a_refusal_reaches_the_operator_by_its_class_alone(self, mocker: MockerFixture) -> None:+ """Instructor's OpenAI parser asserts on a refusal with the refusal in its text: the operator reads the assertion's class.++ The assertion is not re-asked, so it ends the loop on the first attempt and is what the worker recovers, which it+ must tell apart from an error of the OpenAI SDK, whose text is the provider's: the refusal is the model's answer.+ """+ transport = _ScriptedTransport([_OPENAI_REFUSAL])+ llm_job = _make_object_job(mocker)++ async with transport.make_http_client() as http_client:+ client = openai.AsyncOpenAI(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1", max_retries=0, http_client=http_client)+ worker = _make_openai_completions_worker(mocker, client=client)+ with pytest.raises(LLMCompletionError) as exc_info:+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ failure = exc_info.value+ assert transport.nb_requests == 1+ wrapper = failure.__cause__+ assert isinstance(wrapper, InstructorRetryException)+ assert isinstance(extract_underlying_sdk_exception(wrapper), AssertionError)+ assert failure.provider_metadata is not None+ assert failure.provider_metadata.message == "AssertionError"++ problem = failure.to_problem(view=ProblemView.OPERATOR)+ diagnostics = _diagnostics_of(problem)+ assert diagnostics.message.endswith(": AssertionError")+ assert _REFUSAL_MARKER not in diagnostics.message+ assert diagnostics.provider is not None+ assert diagnostics.provider.message == "AssertionError"+ assert _REFUSAL_MARKER not in json.dumps(problem.to_wire())diff --git a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.pyindex ea63fc806..ac6cbcffe 100644--- a/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py+++ b/tests/unit/pipelex/runtime_bridge/primitives/test_hydration.py@@ -598,6 +598,27 @@ class TestHydrateWorkingMemory:with pytest.raises(PipeJobError, match="invalid_stuff"):hydrate_working_memory(raw)+ def test_hydrate_locates_a_refused_content_by_its_class_and_never_quotes_it(self) -> None:+ """The content is the run's data: its refusal names the field its class declares, never the value or a key of it."""+ raw = {+ "root": {+ "invalid_stuff": {+ "stuff_code": "test",+ "stuff_name": "invalid_stuff",+ "concept": "native.Text",+ "content": {"text": {"[email protected]": "secret-value"}},+ },+ },+ "aliases": {},+ }++ with pytest.raises(PipeJobError) as exc_info:+ hydrate_working_memory(raw)++ assert "Failed to hydrate stuff 'invalid_stuff': text: Input should be a valid string" in str(exc_info.value)+ assert "[email protected]" not in str(exc_info.value)+ assert "secret-value" not in str(exc_info.value)+def test_hydrate_round_trips_absence_ledger(self) -> None:"""The absence ledger survives the dump_for_transport → hydrate round-trip: a recordedabsence must not degrade to a hard miss after cross-process transit.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.pynew file mode 100644index 000000000..122cf783d--- /dev/null+++ b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_failure_text.py@@ -0,0 +1,261 @@+from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++import pytest+from pydantic import BaseModel++from pipelex.errors.problem import ProblemView+from pipelex.system.exceptions import ToolError+from pipelex.tools.jinja2.exceptions import (+ Jinja2TemplateBudgetError,+ Jinja2TemplateInvalidError,+ Jinja2TemplateRenderError,+ 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.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.+_PAYLOAD_IDENTIFIER = "confidential_patient_diagnosis"+++class _Record(BaseModel):+ """A value whose public methods a template reads but may not call."""++ label: str = "a label"+++class _Chart:+ """A value declaring a method templates may call, named like the run's data, whose answer no render's budget affords."""++ __template_surface__ = TemplateSurface(callable_names=frozenset({_PAYLOAD_IDENTIFIER}), private_names=frozenset())++ def confidential_patient_diagnosis(self) -> range:+ return range(10**12)+++# 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:,} "+ "work units: "+)+++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`.+ """+ if is_async:+ with pytest.raises((ToolError, Jinja2TemplateSecurityError)) as async_exc_info:+ await render_jinja2_async(+ template_source=template_source,+ template_category=TemplateCategory.BASIC,+ templating_context=context,+ template_owner=TemplateOwner.METHOD,+ )+ return async_exc_info.value+ with pytest.raises((ToolError, Jinja2TemplateSecurityError)) as sync_exc_info:+ render_jinja2_sync(+ template_source=template_source,+ template_category=TemplateCategory.BASIC,+ templating_context=context,+ template_owner=TemplateOwner.METHOD,+ )+ return sync_exc_info.value++[email protected](loop_scope="class")+class TestJinja2RenderFailureText:+ @pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])+ @pytest.mark.parametrize(+ ("topic", "template_source", "context", "expected_error", "expected_message"),+ [+ (+ "a key of the data a lookup did not find",+ "Notes:\n{{ mapping[lookup].field }}",+ {"mapping": {}, "lookup": _PAYLOAD},+ Jinja2TemplateRenderError,+ "Jinja2 render — undefined error: the template reads a value that is not defined (UndefinedError, at line 2 of the template)",+ ),+ (+ "a template that includes the template a value names",+ "{% include lookup %}",+ {"lookup": _PAYLOAD},+ Jinja2TemplateInvalidError,+ (+ "Jinja2 render — the template cannot render as written: "+ "template not found: the template includes, imports or extends a template it cannot reach."+ ),+ ),+ (+ "a private name read by a key of the data",+ "{{ record[lookup] }}",+ {"record": object(), "lookup": f"_{_PAYLOAD.replace('-', '_')}"},+ Jinja2TemplateSecurityError,+ "Jinja2 render — refused by the template sandbox: A template may not read an unsafe name on a 'object' value.",+ ),+ (+ "a key of the data the template also writes as plain text",+ f"Patient {_PAYLOAD_IDENTIFIER}:\n{{{{ mapping[lookup].field }}}}",+ {"mapping": {}, "lookup": _PAYLOAD_IDENTIFIER},+ Jinja2TemplateRenderError,+ "Jinja2 render — undefined error: the template reads a value that is not defined (UndefinedError, at line 2 of the template)",+ ),+ (+ "a private name read by a key the template also writes as plain text",+ f"_{_PAYLOAD_IDENTIFIER} {{{{ 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 callable stored in a namespace under a key of the data",+ "{% set ns = namespace({lookup: record.count}) %}{{ ns }}",+ {"record": [], "lookup": _PAYLOAD},+ Jinja2TemplateSecurityError,+ (+ "Jinja2 render — refused by the template sandbox: A template may not store a method of a 'list' value in a namespace: "+ "a namespace holds data only."+ ),+ ),+ (+ "a method called by a name of the data",+ "{{ (record | attr(lookup))() }}",+ {"record": _Record(), "lookup": "model_dump"},+ Jinja2TemplateSecurityError,+ (+ "Jinja2 render — refused by the template sandbox: A template may not call a method of a '_Record' value: "+ "templates read data and call methods of plain values only."+ ),+ ),+ (+ "a syntax error at a token of the template",+ f"{{{{ note {_PAYLOAD_IDENTIFIER} }}}}",+ {"note": "a note"},+ Jinja2TemplateInvalidError,+ "Jinja2 render — the template cannot render as written: syntax error at line 1.",+ ),+ (+ "an operation on a value of the wrong type",+ "{{ count + lookup }}",+ {"count": 1, "lookup": _PAYLOAD},+ Jinja2TemplateRenderError,+ (+ "Jinja2 render — type error: the template applied an operation to a value of a type that does not support it "+ "(TypeError, at line 1 of the template)"+ ),+ ),+ ],+ )+ async def test_a_failure_on_the_run_s_data_quotes_none_of_it(+ self,+ topic: str,+ template_source: str,+ context: dict[str, Any],+ expected_error: type[PipelexError],+ expected_message: str,+ is_async: bool,+ ) -> None:+ """Jinja2's own text quotes what the template reached for, a key of the data included: the render writes it fixed."""+ error = await _render_failure(template_source=template_source, context=context, is_async=is_async)++ 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++ @pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])+ @pytest.mark.parametrize(+ ("topic", "template_source", "context", "expected_message"),+ [+ (+ "an attribute the template spells",+ "{{ invoice.total.amount }}",+ {"invoice": {}},+ "Jinja2 render — undefined error: the template reads 'total', which is not defined (UndefinedError, at line 1 of the template)",+ ),+ (+ "a private name the template spells",+ "{{ record._secret }}",+ {"record": object()},+ "Jinja2 render — refused by the template sandbox: A template may not read '_secret' on a 'object' value.",+ ),+ (+ "a private name the template writes as a literal key",+ "{{ record['_secret'] }}",+ {"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 }}",+ {"record": []},+ (+ "Jinja2 render — refused by the template sandbox: A template may not store the method 'count' of a 'list' value "+ "in a namespace, as 'helper': a namespace holds data only."+ ),+ ),+ (+ "a method the template calls by its name",+ "{{ record.model_dump() }}",+ {"record": _Record()},+ (+ "Jinja2 render — refused by the template sandbox: A template may not call the method 'model_dump' of a '_Record' value: "+ "templates read data and call methods of plain values only."+ ),+ ),+ ],+ )+ async def test_a_name_the_template_spells_is_kept(+ self, topic: str, template_source: str, context: dict[str, Any], expected_message: str, is_async: bool+ ) -> None:+ """A name the template itself writes is its own, and tells its author what to fix."""+ error = await _render_failure(template_source=template_source, context=context, is_async=is_async)++ assert str(error) == expected_message, topic++ async def test_a_text_format_named_by_the_data_is_never_quoted(self) -> None:+ """Pipelex's own filter refuses a format it does not know by listing those it knows, never the name it was handed."""+ error = await _render_failure(template_source="{{ note | format(lookup) }}", context={"note": "a note", "lookup": _PAYLOAD}, is_async=True)++ assert isinstance(error, Jinja2TemplateRenderError)+ assert (+ str(error) == "Jinja2 render — context error: 'Invalid text format: the format filter takes one of 'plain', 'markdown', 'html', 'json''"+ )+ assert "confidential" not in json.dumps(error.to_problem(view=ProblemView.OPERATOR).to_wire())++ @pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])+ @pytest.mark.parametrize(+ ("topic", "template_source"),+ [+ ("a method read by a name of the data", "{{ (chart | attr(lookup))() }}"),+ ("a method read by a key of the data", "{{ chart[lookup]() }}"),+ ],+ )+ async def test_a_call_the_budget_refuses_by_a_name_of_the_data_quotes_none_of_it(self, topic: str, template_source: str, is_async: bool) -> None:+ """A call overrunning the budget names the method only where the template spells it: here the name is the data's."""+ context = {"chart": _Chart(), "lookup": _PAYLOAD_IDENTIFIER}++ error = await _render_failure(template_source=template_source, context=context, is_async=is_async)++ assert isinstance(error, Jinja2TemplateBudgetError), topic+ assert str(error).startswith(f"{_BUDGET_REFUSAL_PREFIX}calling a method of a '_Chart' value needs about "), topic+ assert "confidential" not in json.dumps(error.to_problem(view=ProblemView.OPERATOR).to_wire()), topic++ @pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"])+ async def test_a_call_the_budget_refuses_by_a_name_the_template_spells_names_it(self, is_async: bool) -> None:+ """The method the template calls by its own name tells its author which call overran the budget."""+ error = await _render_failure(template_source=f"{{{{ chart.{_PAYLOAD_IDENTIFIER}() }}}}", context={"chart": _Chart()}, is_async=is_async)++ assert isinstance(error, Jinja2TemplateBudgetError)+ assert str(error).startswith(f"{_BUDGET_REFUSAL_PREFIX}calling the method '{_PAYLOAD_IDENTIFIER}' of a '_Chart' value needs about ")diff --git a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.pyindex 6610f7189..3246f876b 100644--- a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py+++ b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py@@ -61,9 +61,9 @@ class TestJinja2RenderOwner:@pytest.mark.parametrize(("template_source", "fault"),[- (_UNKNOWN_FILTER_IN_A_BRANCH, "No filter named 'frob_the_lane' found."),- (_UNKNOWN_FILTER_AT_THE_TOP, "No filter named 'frob_the_lane'."),- (_UNKNOWN_TEST_IN_A_BRANCH, "No test named 'frobbed' found."),+ (_UNKNOWN_FILTER_IN_A_BRANCH, "No filter named 'frob_the_lane' at line 1."),+ (_UNKNOWN_FILTER_AT_THE_TOP, "No filter named 'frob_the_lane' at line 1."),+ (_UNKNOWN_TEST_IN_A_BRANCH, "No test named 'frobbed' at line 1."),],ids=["filter_in_a_branch", "filter_at_compile", "test_in_a_branch"],)@@ -179,7 +179,10 @@ class TestJinja2RenderOwner:method_code: ErrorCode,pipelex_code: ErrorCode,) -> None:- """The same failure is the method's on a method's template and ours, or the data's, on Pipelex's own."""+ """The same failure is the method's on a method's template and ours, or the data's, on Pipelex's own.++ Its message never quotes the template, which is the caller's own text on a method's template.+ """for template_owner, expected_code in ((TemplateOwner.METHOD, method_code), (TemplateOwner.PIPELEX, pipelex_code)):error = await _render_failure(template_source,@@ -190,6 +193,7 @@ class TestJinja2RenderOwner:)assert type(error) is error_class, topicassert 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"def test_the_sync_render_is_coded_alike(self) -> None:with pytest.raises(Jinja2TemplateInvalidError) as exc_info:diff --git a/tests/unit/pipelex/tools/misc/fetch_ssrf_guard/test_every_redirect_hop_is_vetted.py b/tests/unit/pipelex/tools/misc/fetch_ssrf_guard/test_every_redirect_hop_is_vetted.pyindex 002333628..7029abad4 100644--- a/tests/unit/pipelex/tools/misc/fetch_ssrf_guard/test_every_redirect_hop_is_vetted.py+++ b/tests/unit/pipelex/tools/misc/fetch_ssrf_guard/test_every_redirect_hop_is_vetted.py@@ -28,7 +28,8 @@ class TestEveryRedirectHopIsVetted:async def test_a_redirect_to_a_private_destination_is_refused(self, mocker: MockerFixture, loopback_server: LoopbackServer) -> None:treat_only_the_localhost_name_as_private(mocker)- with pytest.raises(SsrfBlockedError, match="localhost"):+ # The refusal names no host, which is the run's data: the server's hits show the first hop was served.+ with pytest.raises(SsrfBlockedError, match="Refusing to connect"):await fetch_file_from_url_httpx(url=loopback_url(loopback_server, path=REDIRECT_TO_LOCALHOST_PATH))assert loopback_server.hits == [REDIRECT_TO_LOCALHOST_PATH]diff --git a/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py b/tests/unit/pipelex/tools/misc/test_file_fetch_utils.pyindex 27a52c227..9a8ea6626 100644--- a/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py+++ b/tests/unit/pipelex/tools/misc/test_file_fetch_utils.py@@ -1,3 +1,6 @@+import json+import logging+import httpximport pytestfrom mthds.protocol.problem.registry import CoreCode, ProblemDomain@@ -28,20 +31,20 @@ class TestFetchFileFromUrl:assert raw_bytes == b"%PDF-1.4"@pytest.mark.parametrize(- ("status_code", "expected_code"),+ ("status_code", "expected_code", "expected_params"),[- (404, CoreCode.INPUT_FILE_UNREADABLE),- (403, CoreCode.INPUT_FILE_UNREADABLE),- (429, CoreCode.INPUT_URL_UNREACHABLE),- (500, CoreCode.INPUT_URL_UNREACHABLE),- (503, CoreCode.INPUT_URL_UNREACHABLE),+ (404, CoreCode.INPUT_FILE_UNREADABLE, {}),+ (403, CoreCode.INPUT_FILE_UNREADABLE, {}),+ (429, CoreCode.INPUT_URL_UNREACHABLE, {"host": "example.com"}),+ (500, CoreCode.INPUT_URL_UNREACHABLE, {"host": "example.com"}),+ (503, CoreCode.INPUT_URL_UNREACHABLE, {"host": "example.com"}),],)- async def test_error_status_raises_an_input_error(self, status_code: int, expected_code: CoreCode) -> None:- """A 4xx/5xx becomes an input error, whose message names the URL and the status.+ 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.+ 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,7 +57,8 @@ class TestFetchFileFromUrl:operator = exc_info.value.to_problem(view=ProblemView.OPERATOR)assert operator.diagnostics is not Noneassert f"HTTP {status_code}" in operator.diagnostics.message- assert URL in operator.diagnostics.message+ assert "example.com" not in operator.diagnostics.message+ assert (operator.params.as_wire() if operator.params is not None else {}) == expected_params@pytest.mark.parametrize(("exc", "expected", "expected_code"),@@ -69,6 +73,45 @@ class TestFetchFileFromUrl:await fetch_file_from_url_httpx(url=URL, transport=_transport_raising(exc))assert exc_info.value.resolve_error_code() == expected_code+ 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"++ with pytest.raises(RemoteFileFetchError) as exc_info:+ await fetch_file_from_url_httpx(url=unparsable_url, transport=_transport_answering(200))++ 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())++ 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.++ `provider.response_invalid` declares neither the host nor the input, so neither reaches its problem, and building+ it logs no parameter dropped for want of a declaration.+ """+ with pytest.raises(RemoteFileFetchError) as exc_info:+ await fetch_file_from_url_httpx(url=URL, transport=_transport_answering(503))+ recoded = exc_info.value.with_input(input_name="scan").with_error_code(CoreCode.PROVIDER_RESPONSE_INVALID)++ with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):+ operator = recoded.to_problem(view=ProblemView.OPERATOR)++ assert operator.code == CoreCode.PROVIDER_RESPONSE_INVALID+ assert operator.params is None+ assert [record.getMessage() for record in caplog.records if "does not declare" in record.getMessage()] == []++ 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:+ await fetch_file_from_url_httpx(url=URL, transport=_transport_raising(httpx.ConnectError("boom")))++ caller = exc_info.value.with_input(input_name="scan").to_problem(view=ProblemView.CALLER)++ assert caller.params is not None+ assert caller.params.as_wire() == {"input": "scan", "host": "example.com"}+ assert caller.detail == "The URL of the input 'scan', on 'example.com', did not answer or answered with an error."+@pytest.mark.asyncio(loop_scope="class")class TestFetchFileAndContentTypeFromUrl:diff --git a/tests/unit/pipelex/tools/misc/test_http_utils.py b/tests/unit/pipelex/tools/misc/test_http_utils.pyindex 3b23199f3..6dd4121cb 100644--- a/tests/unit/pipelex/tools/misc/test_http_utils.py+++ b/tests/unit/pipelex/tools/misc/test_http_utils.py@@ -65,8 +65,10 @@ class TestValidateUrlResourceExists:],)def test_malformed_http_url_syntax_raises(self, url: str) -> None:- with pytest.raises(ValueError, match="not a valid http\\(s\\) URL"):+ with pytest.raises(ValueError, match="not a valid http\\(s\\) URL") as exc_info:validate_http_url_syntax(url=url)+ # The URL is an input's value, possibly a signed link, which the message never quotes.+ assert url not in str(exc_info.value)def test_user_agent_is_product_and_version_only(self) -> None:"""No URL in parentheses: that crawler signature is what bot walls stall on."""diff --git a/tests/unit/pipelex/tools/network/test_ssrf_guard.py b/tests/unit/pipelex/tools/network/test_ssrf_guard.pyindex 76822c762..9e0f94e49 100644--- a/tests/unit/pipelex/tools/network/test_ssrf_guard.py+++ b/tests/unit/pipelex/tools/network/test_ssrf_guard.py@@ -42,9 +42,11 @@ 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.assert exc_info.value.security_target_class == SecurityTargetClass.METADATA- assert "169.254.169.254" not in exc_info.value.message+ assert "169.254.169.254" not in str(exc_info.value)@pytest.mark.parametrize(("host", "target_class"),@@ -61,6 +63,7 @@ class TestSsrfGuard:with pytest.raises(SsrfBlockedError) as exc_info:await resolve_to_allowed_ips(host, port=80)assert exc_info.value.security_target_class == target_class+ assert host not in str(exc_info.value)async def test_resolve_blocks_mixed_public_and_private(self, mocker: MockerFixture) -> None:# A host resolving to both a public and a private IP is itself a rebinding@@ -77,8 +80,9 @@ class TestSsrfGuard:async def test_resolution_failure_maps_to_connect_error(self, mocker: MockerFixture) -> None:# A genuine DNS failure is not a security event — surface httpx's usual connect error.mocker.patch("socket.getaddrinfo", side_effect=socket.gaierror("name or service not known"))- with pytest.raises(httpcore.ConnectError):+ with pytest.raises(httpcore.ConnectError) as exc_info:await resolve_to_allowed_ips("nonexistent.invalid", port=80)+ assert "nonexistent.invalid" not in str(exc_info.value)async def test_resolution_timeout_maps_to_connect_timeout(self, mocker: MockerFixture) -> None:# DNS resolution is bounded by the connect timeout; a slow resolver surfaces asdiff --git a/tests/unit/pipelex/tools/tabular/test_csv_codec.py b/tests/unit/pipelex/tools/tabular/test_csv_codec.pyindex d4928640f..bb54b88c9 100644--- a/tests/unit/pipelex/tools/tabular/test_csv_codec.py+++ b/tests/unit/pipelex/tools/tabular/test_csv_codec.py@@ -404,6 +404,48 @@ class TestCsvCodec:assert "SUPERSECRET_TOKEN_xyz" not in messageassert "value" in message # the field is still named so the author can locate it+ @pytest.mark.parametrize(+ ("topic", "content", "row_model", "expected_error", "expected_in_message"),+ [+ ("a cell that does not coerce", "value\noops\n", IntRow, CsvCoercionError, "row 2 of the CSV file"),+ (+ "a column the concept does not declare",+ "value,confidential-patient-diagnosis\n1,2\n",+ IntRow,+ CsvColumnError,+ "Column(s) 2 of the CSV file",+ ),+ ("a repeated column", "value,value\n1,2\n", IntRow, CsvColumnError, "Column 2 of the CSV file repeats"),+ ("a file that does not decode", b"value\n\xe9\n", IntRow, CsvReadError, "invalid continuation byte"),+ ("a file that does not exist", None, IntRow, CsvReadError, "No such file or directory"),+ ],+ )+ def test_a_refusal_never_names_the_file_s_path_nor_its_own_text(+ self,+ tmp_path: Path,+ topic: str,+ content: str | bytes | None,+ row_model: type[StructuredContent],+ expected_error: type[Exception],+ expected_in_message: str,+ ) -> None:+ """The file is the caller's input: its path, a header cell the concept does not declare and its bytes are the run's data."""+ input_dir = tmp_path / "confidential-patient-folder"+ input_dir.mkdir()+ path = input_dir / "confidential-patient-diagnosis.csv"+ if isinstance(content, str):+ path.write_text(content, encoding="utf-8")+ elif isinstance(content, bytes):+ path.write_bytes(content)++ with pytest.raises(expected_error) as exc_info:+ list_content_from_csv(path, row_model=row_model)++ message = str(exc_info.value)+ assert expected_in_message in message, topic+ assert "confidential" not in message, topic+ assert "\\xe9" not in message, topic+def test_string_literal_and_str_enum_round_trip_on_read(self, tmp_path: Path) -> None:# The read-side coercion of accepted string Literal / StrEnum cells (flat_field_names accepts# them; this confirms the cell actually coerces to the member through list_content_from_csv).diff --git a/tests/unit/pipelex/tools/test_jinja2_required_variables.py b/tests/unit/pipelex/tools/test_jinja2_required_variables.pyindex 766b6c152..53d31bea9 100644--- a/tests/unit/pipelex/tools/test_jinja2_required_variables.py+++ b/tests/unit/pipelex/tools/test_jinja2_required_variables.py@@ -622,6 +622,16 @@ class TestDetectJinja2Variables:template_source=template_source,)+ def test_a_syntax_error_names_its_line_and_never_the_token(self):+ """Jinja2's message quotes the token it stopped at, the template's own text: the error names the fault and the line."""+ with pytest.raises(Jinja2DetectVariablesError) as exc_info:+ detect_jinja2_required_variables(+ template_category=TemplateCategory.LLM_PROMPT,+ template_source="Hello\n{{ note confidential_token }}",+ )++ assert str(exc_info.value) == "Jinja2 detect variables — syntax error at line 2 (TemplateSyntaxError), template_category: llm_prompt"+def test_set_with_variable(self):"""Test that set statements don't add their target to required variables."""template_source = """diff --git a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py b/tests/unit/pipelex/tools/test_jinja2_tag_filter.pyindex 76ccae8f7..8df81459b 100644--- a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py+++ b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py@@ -58,12 +58,13 @@ class TestTagFilterValidation:with pytest.raises(Jinja2ContextError, match="undefined"):await tag(context, value=Undefined())- async def test_tag_raises_on_undefined_with_tag_name(self, mocker: MockerFixture) -> None:- """Test tag raises error for undefined value with tag name in message."""+ async def test_tag_raises_on_undefined_with_tag_name_and_never_names_it(self, mocker: MockerFixture) -> None:+ """The tag name a template hands the filter can be the run's data: the refusal of an undefined value never names it."""context = self._make_context(mocker, tag_style=TagStyle.TICKS)- with pytest.raises(Jinja2ContextError, match="tag_name 'my_tag'"):- await tag(context, value=Undefined(), tag_name="my_tag")+ with pytest.raises(Jinja2ContextError, match="Cannot use tag filter on undefined value") as exc_info:+ await tag(context, value=Undefined(), tag_name="[email protected]")+ assert "[email protected]" not in str(exc_info.value)async def test_tag_with_string_converts_to_string(self, mocker: MockerFixture) -> None:"""Test tag filter converts plain string input."""diff --git a/tests/unit/pipelex/tools/test_log_error_fields.py b/tests/unit/pipelex/tools/test_log_error_fields.pyindex f29d26b4c..e1eaeced5 100644--- a/tests/unit/pipelex/tools/test_log_error_fields.py+++ b/tests/unit/pipelex/tools/test_log_error_fields.py@@ -17,6 +17,7 @@ from pipelex.tools.log.json_log_sink import EXCEPTION_KEY, LOGGER_KEY, MESSAGE_Kfrom pipelex.tools.log.log import Logfrom pipelex.tools.log.log_config import LogConfigfrom pipelex.tools.misc.toml_utils import load_toml_from_path+from pipelex.tools.typing.validation_exceptions import InputFreeValueErrorif TYPE_CHECKING:from collections.abc import Iterator@@ -46,6 +47,7 @@ class _Diagnosis(BaseModel):severity: int = 0code: str = "none"reviewed: bool = False+ ward: str = "A1"@field_validator("diagnosis")@classmethod@@ -64,6 +66,15 @@ class _Diagnosis(BaseModel):raise PydanticCustomError(error_type, message_template, {"code": value})return value+ @field_validator("ward")+ @classmethod+ def _ward_is_a_letter_and_a_floor(cls, value: str) -> str:+ if len(value) != 2:+ # A refusal that names the form it expected and never the value.+ msg = "A ward is named by its letter and its floor"+ raise InputFreeValueError(msg)+ return value+@field_validator("severity", mode="before")@classmethoddef _severity_is_spelt_out(cls, value: object) -> object:@@ -134,22 +145,50 @@ class TestLogErrorFields:assert error_fields(exc=exc, text=text) == {ERROR_TYPE_FIELD: expected[0], ERROR_MESSAGE_FIELD: expected[1]}, topicdef test_a_validation_error_is_written_as_its_locations_and_reasons_never_its_input(self) -> None:- """A pydantic error's own text quotes every value it refused, which is payload: a run's input or a model's response."""+ """A pydantic error's own text quotes every value it refused, which is payload: a run's input or a model's response.++ A dict's key is the input's too, so the location names it by the placeholder.+ """secret_looking = "sk-live-4f9a8b7c6d5e4f3a2b1c"with pytest.raises(ValidationError) as caught:- _Settings.model_validate({"retries": secret_looking, "limits": {"burst": secret_looking}})+ _Settings.model_validate({"retries": secret_looking, "limits": {_PAYLOAD: secret_looking}})assert secret_looking in str(caught.value)- fields = error_fields(exc=caught.value)+ fields = error_fields(exc=caught.value, validated_type=_Settings)assert fields == {ERROR_TYPE_FIELD: "ValidationError",ERROR_MESSAGE_FIELD: ("retries: Input should be a valid integer, unable to parse string as an integer; "- "limits.burst: Input should be a valid integer, unable to parse string as an integer"+ "limits.<key>: Input should be a valid integer, unable to parse string as an integer"),}assert secret_looking not in fields[ERROR_MESSAGE_FIELD]+ assert _PAYLOAD not in fields[ERROR_MESSAGE_FIELD]++ @pytest.mark.parametrize(+ ("topic", "validated_type"),+ [("no model given", None), ("a model the error did not come from", _Diagnosis)],+ )+ def test_a_validation_error_whose_model_is_not_known_is_written_as_its_reasons_alone(+ self, topic: str, validated_type: type[BaseModel] | None+ ) -> None:+ """Without the schema, nothing tells a field's name from a key of the input's own, so no location is written."""+ with pytest.raises(ValidationError) as caught:+ _Settings.model_validate({"retries": 3, "limits": {_PAYLOAD: "many"}})++ message = error_fields(exc=caught.value, validated_type=validated_type)[ERROR_MESSAGE_FIELD]++ assert message == "Input should be a valid integer, unable to parse string as an integer", topic++ def test_an_authored_document_s_refusal_keeps_its_locations(self) -> None:+ """A line about a method author's own document, or a value Pipelex built, writes the locations pydantic gives."""+ with pytest.raises(ValidationError) as caught:+ _Settings.model_validate({"retries": 3, "limits": {"max_calls": "many"}})++ message = error_fields(exc=caught.value, is_authored_input=True)[ERROR_MESSAGE_FIELD]++ assert message == "limits.max_calls: Input should be a valid integer, unable to parse string as an integer"def test_a_validation_error_at_the_root_names_its_reason_alone(self) -> None:with pytest.raises(ValidationError) as caught:@@ -171,7 +210,7 @@ class TestLogErrorFields:_Diagnosis.model_validate(document)assert _PAYLOAD in str(caught.value), topic- message = error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD]+ message = error_fields(exc=caught.value, validated_type=_Diagnosis)[ERROR_MESSAGE_FIELD]assert message == expected, topicassert _PAYLOAD not in message, topic@@ -183,20 +222,32 @@ class TestLogErrorFields:assert error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD] == "assertion_error"- def test_a_date_content_rejection_is_written_without_the_value_it_quotes(self) -> None:- """`DateContent`'s validator names the string it could not read as a date, which can be a run's input."""+ def test_a_date_content_rejection_keeps_its_sentence_which_names_no_value(self) -> None:+ """`DateContent`'s validator raises an `InputFreeValueError`, whose sentence names the form it expected alone."""with pytest.raises(ValidationError) as caught:DateContent.model_validate({"date": _PAYLOAD})- assert _PAYLOAD in caught.value.errors()[0]["msg"]+ assert _PAYLOAD not in caught.value.errors()[0]["msg"]- assert error_fields(exc=caught.value) == {ERROR_TYPE_FIELD: "ValidationError", ERROR_MESSAGE_FIELD: "date: value_error"}+ assert error_fields(exc=caught.value, validated_type=DateContent) == {+ ERROR_TYPE_FIELD: "ValidationError",+ ERROR_MESSAGE_FIELD: "date: Value error, The value is not an extended ISO 8601 calendar date (e.g. '2026-07-07').",+ }++ def test_an_input_free_value_error_keeps_its_sentence_beside_a_custom_one(self) -> None:+ """A validator raising `InputFreeValueError` declares its sentence holds nothing of the value, so it is kept."""+ with pytest.raises(ValidationError) as caught:+ _Diagnosis.model_validate({"diagnosis": _PAYLOAD, "ward": _PAYLOAD})++ assert error_fields(exc=caught.value, validated_type=_Diagnosis)[ERROR_MESSAGE_FIELD] == (+ "diagnosis: value_error; ward: Value error, A ward is named by its letter and its floor"+ )def test_pydantic_own_reasons_are_kept_beside_a_custom_one(self) -> None:"""Only the validator's message goes: the reasons pydantic wrote itself, which quote no input, stay readable."""with pytest.raises(ValidationError) as mixed:_Diagnosis.model_validate({"diagnosis": _PAYLOAD, "reviewed": "not a boolean"})- assert error_fields(exc=mixed.value)[ERROR_MESSAGE_FIELD] == (+ assert error_fields(exc=mixed.value, validated_type=_Diagnosis)[ERROR_MESSAGE_FIELD] == ("diagnosis: value_error; reviewed: Input should be a valid boolean, unable to interpret input")@@ -205,8 +256,15 @@ class TestLogErrorFields:[("an unknown tag of a discriminated union", _Shipment, {"item": {"kind": _PAYLOAD}}, _PAYLOAD, "item: union_tag_invalid"),("a value that is no UUID", _Record, {"record_id": _PAYLOAD}, "found `o`", "record_id: uuid_parsing"),- ("a key a nested model forbids", _StrictSettings, {"limits": {_PAYLOAD: 1}}, None, "limits: Extra inputs are not permitted"),- ("a key the root model forbids", _StrictSettings, {_PAYLOAD: 1}, None, "Extra inputs are not permitted"),+ ("a key a nested model forbids", _StrictSettings, {"limits": {_PAYLOAD: 1}}, None, "limits.<key>: Extra inputs are not permitted"),+ ("a key the root model forbids", _StrictSettings, {_PAYLOAD: 1}, None, "<key>: Extra inputs are not permitted"),+ (+ "a key of a dict",+ _Settings,+ {"retries": 1, "limits": {_PAYLOAD: "many"}},+ None,+ "limits.<key>: Input should be a valid integer, unable to parse string as an integer",+ ),],)def test_a_message_or_a_location_drawn_from_the_input_never_reaches_the_line(@@ -227,7 +285,7 @@ class TestLogErrorFields:else:assert _PAYLOAD in [str(part) for part in error["loc"]], topic- fields = error_fields(exc=caught.value)+ fields = error_fields(exc=caught.value, validated_type=model)fresh, buffer = json_bufferfresh.warning("A document was refused", fields=fields)@@ -241,7 +299,7 @@ class TestLogErrorFields:with pytest.raises(ValidationError) as caught:_Bounded.model_validate({"code": _PAYLOAD})- assert error_fields(exc=caught.value)[ERROR_MESSAGE_FIELD] == "code: String should have at most 8 characters"+ assert error_fields(exc=caught.value, validated_type=_Bounded)[ERROR_MESSAGE_FIELD] == "code: String should have at most 8 characters"def test_a_text_given_for_a_validation_error_is_carried_as_given(self) -> None:with pytest.raises(ValidationError) as caught:diff --git a/tests/unit/pipelex/tools/typing/test_validation_error_locations.py b/tests/unit/pipelex/tools/typing/test_validation_error_locations.pynew file mode 100644index 000000000..dfb084bc0--- /dev/null+++ b/tests/unit/pipelex/tools/typing/test_validation_error_locations.py@@ -0,0 +1,163 @@+from typing import Annotated, Any, Literal++import pytest+from pydantic import AliasChoices, AliasPath, BaseModel, ConfigDict, Field, RootModel, TypeAdapter, ValidationError+from pydantic_core import SchemaValidator+from pytest_mock import MockerFixture++from pipelex.tools.typing import pydantic_utils+from pipelex.tools.typing.pydantic_utils import (+ PAYLOAD_KEY_PLACEHOLDER,+ empty_dict_factory_of,+ empty_list_factory_of,+ format_validation_error_without_input,+ validation_error_locations,+)++# A key of the run's own data, which no location carries.+_PAYLOAD_KEY = "confidential-patient-diagnosis"+++class _Leaf(BaseModel):+ model_config = ConfigDict(extra="forbid")++ score: int+++class _Cat(BaseModel):+ kind: Literal["cat"]+ meow: int+++class _Dog(BaseModel):+ kind: Literal["dog"]+ bark: int+++class _Outer(BaseModel):+ model_config = ConfigDict(extra="forbid")++ entries: dict[str, _Leaf] = Field(default_factory=dict)+ ids: dict[int, int] = Field(default_factory=empty_dict_factory_of(int, _val=int))+ items: list[_Leaf] = Field(default_factory=empty_list_factory_of(_Leaf))+ maybe: _Leaf | None = None+ either: int | _Leaf = 0+ pet: Annotated[_Cat | _Dog, Field(discriminator="kind")] | None = None+ aliased: int = Field(default=0, alias="Aliased")+ pair: tuple[int, _Leaf] | None = None+ loose: dict[str, Any] = Field(default_factory=dict)+++class _Aliases(BaseModel):+ nested: int = Field(default=0, validation_alias=AliasPath("outer", 0))+ chosen: int = Field(default=0, validation_alias=AliasChoices("chosen_one", AliasPath("chosen_path", "inner")))+++class _Ledger(RootModel[dict[str, _Leaf]]):+ pass+++def _locations(*, model: type[BaseModel], document: object) -> list[str | None]:+ with pytest.raises(ValidationError) as caught:+ model.model_validate(document)+ return validation_error_locations(validation_error=caught.value, validated_type=model)+++class TestValidationErrorLocations:+ @pytest.mark.parametrize(+ ("topic", "model", "document", "expected"),+ [+ ("an invalid value under a dict's key", _Outer, {"entries": {_PAYLOAD_KEY: {"score": "high"}}}, ["entries.<key>.score"]),+ ("an extra key under a dict's key", _Outer, {"entries": {_PAYLOAD_KEY: {"score": 1, _PAYLOAD_KEY: 2}}}, ["entries.<key>.<key>"]),+ ("an extra key of a nested model", _Outer, {"maybe": {"score": 1, _PAYLOAD_KEY: 2}}, ["maybe.<key>"]),+ ("an extra key of the model itself", _Outer, {_PAYLOAD_KEY: 1}, ["<key>"]),+ ("a dict's key refused itself", _Outer, {"ids": {_PAYLOAD_KEY: 1}}, ["ids.<key>.[key]"]),+ ("an int key of a dict", _Outer, {"ids": {"5": "five"}}, ["ids.<key>"]),+ ("a position in a list", _Outer, {"items": [{"score": 1}, {"score": "high"}]}, ["items.1.score"]),+ ("a position in a tuple", _Outer, {"pair": [1, {"score": "high"}]}, ["pair.1.score"]),+ ("the choices of a union", _Outer, {"either": "high"}, ["either.int", "either._Leaf"]),+ ("a tagged union's tag", _Outer, {"pet": {"kind": "cat", "meow": "loud"}}, ["pet.cat.meow"]),+ ("a field's alias", _Outer, {"Aliased": "high"}, ["Aliased"]),+ ("a root model's dict", _Ledger, {_PAYLOAD_KEY: {"score": "high"}}, ["<key>.score"]),+ ("an alias path", _Aliases, {"outer": ["high"]}, ["outer.0"]),+ ("an alias choice's path", _Aliases, {"chosen_path": {"inner": "high"}}, ["chosen_path.inner"]),+ ],+ )+ def test_a_location_names_what_the_schema_names_and_hides_the_input_s_keys(+ self, topic: str, model: type[BaseModel], document: object, expected: list[str | None]+ ) -> None:+ locations = _locations(model=model, document=document)++ assert locations == expected, topic+ assert all(_PAYLOAD_KEY not in (location or "") for location in locations), topic++ def test_an_error_of_another_model_is_given_no_location(self) -> None:+ """A location is read off the schema only when the error came from it: another model's would name the wrong things."""+ with pytest.raises(ValidationError) as caught:+ _Outer.model_validate({"entries": {_PAYLOAD_KEY: {"score": "high"}}})++ assert validation_error_locations(validation_error=caught.value, validated_type=_Leaf) == [None]+ assert validation_error_locations(validation_error=caught.value, validated_type=None) == [None]++ def test_the_formatted_error_reads_the_same_locations(self) -> None:+ with pytest.raises(ValidationError) as caught:+ _Outer.model_validate({"entries": {_PAYLOAD_KEY: {"score": "high", _PAYLOAD_KEY: 2}}})++ formatted = format_validation_error_without_input(validation_error=caught.value, validated_type=_Outer)++ assert formatted == (+ f"entries.{PAYLOAD_KEY_PLACEHOLDER}.score: Input should be a valid integer, unable to parse string as an integer; "+ f"entries.{PAYLOAD_KEY_PLACEHOLDER}.{PAYLOAD_KEY_PLACEHOLDER}: Extra inputs are not permitted"+ )++ def test_an_authored_document_is_located_as_pydantic_gives_it(self) -> None:+ """A method author's own document, or a value Pipelex built, holds no run's data: its keys are written as they are."""+ with pytest.raises(ValidationError) as caught:+ _Outer.model_validate({"entries": {"opening_hours": {"score": "high"}}})++ assert validation_error_locations(validation_error=caught.value, validated_type=None, is_authored_input=True) == [+ "entries.opening_hours.score"+ ]+ assert format_validation_error_without_input(validation_error=caught.value, is_authored_input=True) == (+ "entries.opening_hours.score: Input should be a valid integer, unable to parse string as an integer"+ )++ def test_a_type_adapter_locates_what_it_validated(self) -> None:+ """A type that is no model, such as a list or a union of models, is validated by a TypeAdapter, which locates it the same way."""+ adapter: TypeAdapter[list[_Outer]] = TypeAdapter(list[_Outer])+ with pytest.raises(ValidationError) as caught:+ adapter.validate_python([{}, {"entries": {_PAYLOAD_KEY: {"score": "high"}}}])++ assert validation_error_locations(validation_error=caught.value, validated_type=adapter) == ["1.entries.<key>.score"]++ def test_each_located_reason_is_written_once_in_the_order_it_first_comes(self) -> None:+ with pytest.raises(ValidationError) as caught:+ _Outer.model_validate({"items": [{"score": "high"}, {"score": 1, _PAYLOAD_KEY: 2}, {"score": "low"}], "maybe": {"score": "x"}})++ formatted = format_validation_error_without_input(validation_error=caught.value, validated_type=_Outer)++ assert formatted == (+ "items.0.score: Input should be a valid integer, unable to parse string as an integer; "+ f"items.1.{PAYLOAD_KEY_PLACEHOLDER}: Extra inputs are not permitted; "+ "items.2.score: Input should be a valid integer, unable to parse string as an integer; "+ "maybe.score: Input should be a valid integer, unable to parse string as an integer"+ )+ assert format_validation_error_without_input(validation_error=caught.value) == (+ "Input should be a valid integer, unable to parse string as an integer; Extra inputs are not permitted"+ )++ def test_a_union_choice_s_label_is_read_once_per_schema(self, mocker: MockerFixture) -> None:+ """The label of a union's choice is pydantic's title for it, read once for the validated type, not once per error."""++ class _Choices(BaseModel):+ either: list[int | _Leaf]++ spy = mocker.patch.object(pydantic_utils, "SchemaValidator", wraps=SchemaValidator)+ with pytest.raises(ValidationError) as caught:+ _Choices.model_validate({"either": ["a", "b", "c"]})++ first = validation_error_locations(validation_error=caught.value, validated_type=_Choices)+ second = validation_error_locations(validation_error=caught.value, validated_type=_Choices)++ assert first == second == [f"either.{position}.{choice}" for position in range(3) for choice in ("int", "_Leaf")]+ assert spy.call_count == 2diff --git a/tests/unit/pipelex/tracing/test_dynamodb_event_log.py b/tests/unit/pipelex/tracing/test_dynamodb_event_log.pyindex 727d7a84e..927ac412f 100644--- a/tests/unit/pipelex/tracing/test_dynamodb_event_log.py+++ b/tests/unit/pipelex/tracing/test_dynamodb_event_log.py@@ -204,6 +204,21 @@ class TestDynamoDBEventLog:assert event_log.read_events(_RUN_ID) == events+ def test_a_refusal_locates_the_field_and_never_quotes_the_traced_value(self, mocker: MockerFixture) -> None:+ """The refusal travels into the run's assembly errors: it names the refused field, never the traced value it held."""+ event_log, mock_table = self._make_event_log_with_table(mocker)+ payload = json.loads(_decision_events(mode=PipeRunMode.LIVE)[0].model_dump_json())+ payload["sequence"] = "traced-value-from-the-run"+ mock_table.query.return_value = {+ "Items": [{"PK": f"PIPELINE_RUN#{_RUN_ID}", "SK": "EVENT#wf_flow#primary#0000000000", "payload": json.dumps(payload)}]+ }++ with pytest.raises(EventLogSchemaMismatchError) as refusal:+ event_log.read_events(_RUN_ID)++ assert f"{payload['event_kind']}.sequence: Input should be a valid integer" in str(refusal.value)+ assert "traced-value-from-the-run" not in str(refusal.value)+def test_an_event_stored_without_a_mode_is_refused(self, mocker: MockerFixture) -> None:"""A payload written before every event stated its mode is in a shape this version refuses, never read as live."""event_log, mock_table = self._make_event_log_with_table(mocker)diff --git a/tests/unit/pipelex/tracing/test_ndjson_event_log.py b/tests/unit/pipelex/tracing/test_ndjson_event_log.pyindex fd8d16d59..4b87afe5f 100644--- a/tests/unit/pipelex/tracing/test_ndjson_event_log.py+++ b/tests/unit/pipelex/tracing/test_ndjson_event_log.py@@ -1,5 +1,6 @@"""Tests for NdjsonEventLog."""+import jsonimport loggingimport multiprocessingfrom pathlib import Path@@ -253,6 +254,24 @@ class TestNdjsonEventLog:assert "traced-value" not in str(refusal.value)+ def test_a_refusal_locates_the_field_and_never_quotes_the_value_it_held(self, tmp_path: Path) -> None:+ """A refused field holding a traced value: the refusal names the field by the event models' schema, never the value."""+ event_log = NdjsonEventLog(traces_dir=str(tmp_path))+ event_log.emit(make_trace_event(sequence=0))+ event_log.close()++ ndjson_file = _only_run_file(tmp_path / "run_001")+ refused_line = json.loads(make_trace_event(sequence=1).model_dump_json())+ refused_line["sequence"] = "traced-value-from-the-run"+ with open(ndjson_file, "a", encoding="utf-8") as fhandle:+ fhandle.write(json.dumps(refused_line) + "\n")++ with pytest.raises(EventLogSchemaMismatchError) as refusal:+ event_log.read_events("run_001")++ assert f"{refused_line['event_kind']}.sequence: Input should be a valid integer" in str(refusal.value)+ assert "traced-value-from-the-run" not in str(refusal.value)+def test_a_line_naming_no_execution_is_refused_with_the_others(self, tmp_path: Path) -> None:"""A line whose `workflow_id` is empty names no execution: it is counted with the lines the models refuse,rather than read and then failing whoever first asks for its chain.