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/Log-style-polish · L-261010-e43b46 (#1403)
Louis Choquele4d2ee2b093c
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 0981111ce..2e9d6a73e 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "17299",+ "message": "17530","color": "blue","cacheSeconds": 300}diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex a4ce4acd4..f71ff9d56 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:27af491de53630e46b102be16d3f416bde2273196f41f6186aacc18e69065033"+digest = "sha256:28d7d45c73daa1f5e9f217d43878037d98508effdb35ba278d1cbd66d2f1c5b0"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-10T01:15:46Z"-rationale = "clean-pass: the generic failure branches of pipelex run (execute_run in commands/run/_run_core.py) and pipelex graph render (graph_render_cmd) now print the exception's type and message through the new print_unexpected_failure in error_handlers.py, beside the unchanged ERROR log line with its traceback, header line and exit code 1. Read docs/tools/cli/index.md, run.md and the rest of docs/tools/cli/: none describes what an unexpected local failure prints (run.md's failure prose covers hosted runs and bundle refusals, index.md's --traceback covers the known-error branches through print_traceback_if_requested, which did not move), so nothing is stale. Grepped pipelex/cli/agent_cli for both modules and the new helper: the agent CLI runs its own run core and never reaches either branch, so pipelex/cli/agent_cli/CLAUDE.md is unaffected."+reviewed_at = "2026-10-10T11:26:22Z"+rationale = "clean-pass: the triggers change log lines only. The agent run core's cost-summary warning and graph render's refused-spec error are reworded to one sentence, same level and fields, and the IDE-extension DEBUG line of both init modules carries the EOFError as error fields rather than in its text; no option, output, prompt or exit code moved. Read docs/tools/cli/ and pipelex/cli/agent_cli/CLAUDE.md for the old and new messages, the cost summary, a refused graph spec and the IDE extension suggestion: no page quotes any of these log lines. The agent CLAUDE.md claim that cost_report is absent when cost-summary aggregation fails, caught and skipped, still matches run_pipeline_core, which logs the warning and leaves the report out. Nothing was stale."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -36,7 +36,7 @@ rationale = "clean-pass: the generic failure branches of pipelex run (execute_ru"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:a1c530d110482485ce462f199b9e79fac29f8896""pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6"-"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:64995a638dfd3a0d0da3325d89e0aec318cceb58"+"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:4f11b537de3be6c4cbab7e53309bdda44b01d390""pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:cea011e61feb082a7b9d82d7693b4fd3246737e5""pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df""pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:86988b3506ebc057df6a55d8862105ba6ceb693b"@@ -80,10 +80,10 @@ rationale = "clean-pass: the generic failure branches of pipelex run (execute_ru"pipelex/cli/commands/fix/_fix_core.py" = "blob:aa698305e6b60dfb7caf133698dc1d5c1f5f68f1""pipelex/cli/commands/fix/app.py" = "blob:6f019930e8e3e0043ee46d87493ba4602eb33a76""pipelex/cli/commands/fix/bundle_cmd.py" = "blob:427364cc453957dfe0cec879f019050329c13b3c"-"pipelex/cli/commands/graph_cmd.py" = "blob:1ffd1aa7342631eed79f68fe6dacc0959d3014c3"+"pipelex/cli/commands/graph_cmd.py" = "blob:d215ad2b66c4421364c90f2d8f875b6312dadfe4""pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/commands/init/backends.py" = "blob:04a1a06f1003ed0c7157ec4ca6c8659e4e09fe6b"-"pipelex/cli/commands/init/command.py" = "blob:f5cbca22f8ea19957f271af2d9844d9191263520"+"pipelex/cli/commands/init/backends.py" = "blob:0cc3543c78f832149ebbbf3cc8beafee619e4f63"+"pipelex/cli/commands/init/command.py" = "blob:7282c6937f2e5a29a468685e3193df475b09ef0e""pipelex/cli/commands/init/config_files.py" = "blob:8345ae46e7f77a6f49f526ed20c8dd8263f118f3""pipelex/cli/commands/init/credentials.py" = "blob:1817fd9b1988e4fea528a3977259b57f7274b69b""pipelex/cli/commands/init/ide_extension.py" = "blob:9f0ec1494c07062246ecc906bc55b7f2cf95c715"diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex 917a1bd23..a18ea83e2 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -1,8 +1,8 @@contract = "config-docs"-digest = "sha256:cf7d6bb91764d7e38386d38f133a9b721ac88591be65f4679a807eeb077c67cf"+digest = "sha256:e3d7f15c7d521e6963df9e168da7eb62cb2b4c244f491d6f463f111091a42042"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-10T01:52:31Z"-rationale = "real-catch: pipelex/pipelex.toml gained two shipped defaults under [runtime.log.package_log_levels], httpx2 = WARNING and httpcore2 = INFO. Re-read docs/configuration: logging-config.md's Package-Specific Log Levels section now says the HTTP clients under the inference SDKs default to httpx WARNING and httpcore INFO with the same levels for their forks; its quantified claims (OFF silences only the loggers the section does not pin, silence for everything takes every entry of that section at OFF) are about the section as a set and still hold; the override example and the best-practice list name no default. No other configuration page names a package level. No model moved: configs.py and config_cogt.py are untouched, package_log_levels is an open dict[str, LogLevel] node, check-migration-schemas reported the fingerprint moved additively with no entry needed, and the head goldens defaults@7 and fingerprint@7 were regenerated with make umig; the ledgers need no entry."+reviewed_at = "2026-10-10T11:26:01Z"+rationale = "real-catch: the triggers add is_show_path to RichLogConfig and pipelex.toml (default false, a prose comment above the table), reword the stale-configuration warning to one message with its remedy in user_action, and reword two DEBUG lines of aws_config. logging-config.md, the only configuration page listing the rich_log keys, documents is_show_path in Display Options and in the full example. The stale-warning example in inference-backend-config.md was rendered through ConsoleLogSink to check it: the message, the quoted migration_steps JSON and the advice line under it match, but the path was written with a leading ellipsis the console never prints for a path that short, since it cuts only past 80 characters, so the example now gives the full path the console prints. The other mentions of the stale warning (telemetry-config.md, the DEV and is_markup_enabled paragraphs of logging-config.md) quote no message and still hold. configs.py, config_cogt.py and the ledgers need nothing: check-migration-schemas passes with the additive key, and no validator moved."[trigger_files]"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b"@@ -10,18 +10,18 @@ rationale = "real-catch: pipelex/pipelex.toml gained two shipped defaults under"pipelex/graph/graph_config.py" = "blob:dc0939a6d2730c0a10b88aa1a6e0b2dd583462a6""pipelex/language/mthds_config.py" = "blob:353009ad8c59dc5266bdd9dfa42b1ad18b67dca7""pipelex/methods/methods_config.py" = "blob:76ca9a0e64f8c10ef6a355aafd0d79d36b09f06a"-"pipelex/pipelex.toml" = "blob:c9de2007e32ec4e0043fd9a153f0d4aabe3ae04a"+"pipelex/pipelex.toml" = "blob:dbc550b61a1c9f5473f0ed9d88ebfd3cc420e119""pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc""pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332""pipelex/system/configuration/config_loader.py" = "blob:2850f6b39df6ad2afafefc4d431672cb6ee91ced""pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339""pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160"-"pipelex/system/configuration/config_surface.py" = "blob:7d865822cb339818ac54bbd0d623ad0b39f690fd"+"pipelex/system/configuration/config_surface.py" = "blob:49424a8103a5611f5b2885135dd699273bde57c8""pipelex/system/configuration/configs.py" = "blob:1754391061f3be47e28088a4f8ea85e60b1cdd2b""pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5""pipelex/system/telemetry/telemetry_config.py" = "blob:068a785d97a2d52ee43e82e723cd944b8b6601bc"-"pipelex/tools/aws/aws_config.py" = "blob:e27dc96bf0b2ef98a45354712421252fe0b893b5"-"pipelex/tools/log/log_config.py" = "blob:4c2f9545758e9c04228aedd88adb68125adad7aa"+"pipelex/tools/aws/aws_config.py" = "blob:0a7c9dbf276e61355b1fa79b9db8caf252450a39"+"pipelex/tools/log/log_config.py" = "blob:97019b2cf36ed04513f547059b72be4e6bfcbf05""pipelex/tools/log/log_levels.py" = "blob:12b94e4d4793a70156ac547ee20c9d483910ecae""pipelex/tools/network/network_config.py" = "blob:e12d1d0e4a40d04859f10a77addeaf8fe2b00414""pipelex/tools/secrets/secrets_config.py" = "blob:cf30aaec1c76c9cabc0531a5b9fe681e153d7024"diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.tomlindex b2da02b18..dc444bf42 100644--- a/.drift/acks/hub-layering-convention.toml+++ b/.drift/acks/hub-layering-convention.toml@@ -1,10 +1,10 @@contract = "hub-layering-convention"-digest = "sha256:81bac50d761cef4a2fae569e987ff576588869e0d05eb25e8037cb83959c0680"-reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-07T13:45:51Z"-rationale = "real-catch: the guard now declares pipelex.hosted in KERNEL_LAYER_PACKAGES. hub-layering.md's declared-package list names it, and the paragraph accounting for every top-level package says why it is declared in its first commit: a hosted run boots nothing and reads config, builds the pipelex-sdk client and maps the run without loading an interpreter module, while what needs a bundle parsed stays in pipelex.cli. The kernel-layer import-closure test gained its three entry points and measures it clean."+digest = "sha256:a6c9b398552db5a716bbd6fe02c68c4f10a1bcae770e232be643c55b52585880"+reviewed_by = "Claude (Opus 5.5)"+reviewed_at = "2026-10-10T11:27:08Z"+rationale = "clean-pass: runtime_hub.py rewords two warnings (a second set_config, and a live run forced dry under a keyless boot, whose advice now rides user_action) and imports USER_ACTION_FIELD from pipelex.tools.log.log_fields, a kernel-layer leaf; no accessor was added, moved or removed and KERNEL_LAYER_PACKAGES is unchanged. Ran the page's two mechanical checks from the code: every public function and class defined at module level in runtime_hub.py and interpreter_hub.py appears in the partition tables, and every package of the guard's KERNEL_LAYER_PACKAGES is named under the layer rule. check-hub-layering passes with the new import. Nothing was stale."[trigger_files]"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:fda2237457fe0b6830ff2ae8f720698735bec4c3""pipelex/interpreter_hub.py" = "blob:327e75d0fbb5bdf46f6cbf06024f83840f0106d0"-"pipelex/runtime_hub.py" = "blob:05f84b9604b9f904e7df96d222b8856123ce9e91"+"pipelex/runtime_hub.py" = "blob:65beba670c857897858b75fd17bbbc03ba84e750"diff --git a/.drift/acks/log-call-convention.toml b/.drift/acks/log-call-convention.tomlindex a881b04ab..dc83f1a80 100644--- a/.drift/acks/log-call-convention.toml+++ b/.drift/acks/log-call-convention.toml@@ -1,9 +1,9 @@contract = "log-call-convention"-digest = "sha256:e8879f0f0bde0d0af33ac33fb0a6f4101114bbb96e9ba748e87cdad596d289fe"+digest = "sha256:e73094dfee8b747ad3576bee34f145b55ab7b1892c36acf389d12b25c884e026"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-10T09:16:37Z"-rationale = "clean-pass: the contract now also triggers on check_log_calls_cmd.py, whose options and output the page's Running it section states, and that section was re-derived from the command module. --quiet trims only a pass, to one line giving the baselined calls left and, when a comparison ran, that none were added since the trusted revision, while a failure still prints every call and entry; --prune rewrites the baseline without its stale signatures and then checks, never adding one; --report prints the baseline by package area, largest first, and returns before any gating; --against needs a ref that resolves, load_trusted_baseline raising otherwise; --against-merge-base skips the comparison with a notice when resolve_merge_base finds no merge base, and giving both options is an error; a failure lists each unlisted call with its file, line, qualified name and breaches, then the remedies of the rules seen, then the stale signatures under their keys, then the growth with both counts. The make wiring (--quiet with --against-merge-base origin/dev, or --against LOG_CALL_BASELINE_REF), the agent-check and check aggregates, the Lint (log calls) job under Lint (all), and the pre-main fresh check's base fetch and manual-run message match the Makefile and the workflows. The flag spellings and the -q alias are declared in pipelex/cli/dev_cli/_dev_cli.py, which is not a trigger. log_call_guard.py is unchanged since the last ack. The page needed no change."+reviewed_at = "2026-10-10T11:28:34Z"+rationale = "real-catch: log_call_guard.py adds the wording rules lowercase-start, trailing-period and backtick at every level, identifier and length (MAX_MESSAGE_LENGTH 80) at INFO and above, and spliced-exception at every level, each with a remedy, reads a captured name through every binding of its function for the exception rule and the receiver, keeps the two sides of a concatenation past the fold bound apart, and puts the exception route in the signature with the handler binding written as except target. Checked log-calls.md against the code and the guard tests: the rule table, the vocabulary words that pass, the start and end that a value keeps open, the length counted on literal runs with its at-least detail, the values the exception rule reads (placeholders, the right operand of a percent, format arguments, any non-literal part), the exception method call, captured names in a callback, a rebound handler name, the signature format and the remedies in the failure output all hold. Probing find_offending_calls_in_source showed one overstatement: lowercase-start refuses a first character that is a lowercase letter, so a message opening with a quote or a digit passes, where the table said its first letter and the DEBUG paragraph said a message starts with a capital. Both now say what the guard checks."[trigger_files]"pipelex/cli/dev_cli/commands/check_log_calls_cmd.py" = "blob:47b6d88ea61446d2788f7fc7ee826cb1ffc7f582"-"pipelex/cli/dev_cli/commands/log_call_guard.py" = "blob:f763d3d4448541d65273a44eef4eaa90cb2d35c4"+"pipelex/cli/dev_cli/commands/log_call_guard.py" = "blob:6459fc9d2badf56749fb614f9fa07ecdaabef26f"diff --git a/.drift/acks/logging-docs.toml b/.drift/acks/logging-docs.tomlindex a22d37363..e848a962f 100644--- a/.drift/acks/logging-docs.toml+++ b/.drift/acks/logging-docs.toml@@ -1,9 +1,9 @@contract = "logging-docs"-digest = "sha256:26e4b90b98c1001b981f1d060d55c18383d988ec2704b2efa1f98f4af51c811d"+digest = "sha256:d9ec388a1a3a14e1cf3fa4316211776c0a55a6a33d646202bd93c5aa3e5265b0"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-10T09:16:44Z"-rationale = "clean-pass: the only change to the triggers is console_fields.py's module docstring, which still gave LEFT_CUT_FIELDS as file.name alone after storage_key joined the set and now names the constant instead of listing its members; no constant or code moved, and error_fields.py is the blob the last ack reviewed. Re-derived the page's left-cut sentence from the code: it gives every LEFT_CUT_FIELD_SUFFIXES ending and both LEFT_CUT_FIELDS names, file.name and storage_key, so the page was already right where the docstring was not. Rechecked against the code the FIELD_STYLES keys and colours with unmapped fields and keys dimmed, the hidden run identifiers and data, the 80 cut and the 2000 cut of both FIELD_MAX_LENGTHS entries, the layout cut, the quoting characters, and the pydantic and extra_forbidden rules against SCHEMA_CONTEXT_KEYS and _pydantic_own_reason; all still hold. The page needed no change."+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."[trigger_files]-"pipelex/tools/log/console_fields.py" = "blob:cb51c6004ad7704f80f1753043180fb8e34b517c"+"pipelex/tools/log/console_fields.py" = "blob:10c4516405dfdfe889590ef0d8e1914f56600a2f""pipelex/tools/log/error_fields.py" = "blob:515b7649ddd22dceb192faa21713732ec61cd6e0"diff --git a/.drift/acks/pipelex-kernel-docs.toml b/.drift/acks/pipelex-kernel-docs.tomlindex 92d5f2f8a..d87ba7c08 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:fb848d94ab17c80a70f8e6118a66de94ae5be10c3688e8c3e55f224d6106e3d9"-reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-09T22:54:09Z"-rationale = "clean-pass: judgment_ops.py's no-probability warning keeps its level and becomes a fixed message with pipe_code, threshold and model_handle as fields, and llm_ops.py's two cycle and hop-limit lines in concrete_llm_model_handle move from WARNING to DEBUG with fixed messages; no kernel function, parameter or behaviour moved. Re-read pipelex-kernel.md: its run_judgment paragraph still holds (a live run with a declared threshold and no probability logs a warning), and it describes no log line of concrete_llm_model_handle."+digest = "sha256:e6e3f137fdaf249212cfe9710089203db64a6cf09219861edc1438ee8bf4d3d7"+reviewed_by = "Claude (Opus 5.5)"+reviewed_at = "2026-10-10T11:27:10Z"+rationale = "clean-pass: judgment_ops.py rewords the warning of run_judgment when a declared threshold meets an answer with no probability, same level and the same pipe_code, threshold and model_handle fields; no kernel function, parameter or behaviour moved. Re-read pipelex-kernel.md and checked its run_judgment paragraph against make_verdict_content: threshold_applied is false only when a threshold is declared, the answer has no probability and the run is not dry, and run_judgment warns exactly then, so the claim that a live run logs a warning and reports threshold_applied as false still holds; the page quotes no message. Nothing was stale."[trigger_files]"pipelex/kernel/__init__.py" = "blob:c4f1b0fe2ccc17db9110733f71b612f4ac1ba4ce"@@ -16,7 +16,7 @@ rationale = "clean-pass: judgment_ops.py's no-probability warning keeps its leve"pipelex/kernel/img_gen_ops.py" = "blob:b85360f6c118e93be53bf8d1a04504ccb7552469""pipelex/kernel/img_gen_prompt.py" = "blob:1f6347e10eaab2eb229fa1cee080c6bbc7878bd2""pipelex/kernel/img_gen_results.py" = "blob:46b4ca11c70d906ae6d58ce66461f9b3414f1bfa"-"pipelex/kernel/judgment_ops.py" = "blob:97acd7bdff4279b3c0ed01cc48f31716f0347cb4"+"pipelex/kernel/judgment_ops.py" = "blob:4b01f5618b8484ae29041151c8cd3f8ad523ce70""pipelex/kernel/judgment_results.py" = "blob:40ba1258cc81d34df3e427d5511ccd40c6edf789""pipelex/kernel/llm_ops.py" = "blob:d37a9c3718a37f5e7d1550d1512dddbf79032cae""pipelex/kernel/llm_prompt_content.py" = "blob:eabf0ee760c3a26b8967973d511e712e9275e99b"diff --git a/AGENTS.md b/AGENTS.mdindex b93a0daae..da8134ede 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -202,7 +202,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.-- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. It is one short sentence, subject first, starting with a capital and ending with no period or `...`, with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in a `user_action` field ("Wording a message" in `docs/tools/logging.md`). A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text, at any level; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.#### StrEnum and Self typediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 16cabbc13..7728d70cf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,27 @@# Changelog+## [Unreleased]++### Added++- **A log line's advice in `user_action`**: a log call puts what its reader should do in a `user_action` field, one imperative sentence, and the `console` sink prints it whole on a line of its own under the record, after `→ `, in cyan, while every other sink writes it as a field like any other. Pipelex's own warnings carry their advice there, such as `Run pipelex migrate to update it` on a stale configuration file, so their message says only what happened.++### Changed++- **Console lines without the emoji prefix or the path column (Breaking)**: a line logged under the `pipelex` package or a `pipelex_` one, the runtime's, the API server's or a plugin's named that way, and a line logged on the root logger start with their message, and a line another library logged starts with that library's top-level package name, dimmed, such as `httpx: `, where every line used to start with an emoji or a bracketed logger name. The column naming the source file and line of each record is off by default; set `is_show_path = true` under `[runtime.log.rich_log]` to show it, `is_link_path_enabled` still making it clickable. The `pipelex.tools.log.log_formatter` module is gone with its `EmojiLogFormatter`, so code that formatted records with it uses the stdlib's `logging.Formatter`.+- **Log messages are one short sentence (Breaking)**: Pipelex's log messages, and its API server's, say what happened in one sentence that starts with a capital and ends with no period, and at `INFO` and above hold no identifier and no backtick in at most 80 characters, the advice they used to append now riding `user_action`. Warnings about one event became one: whichever kind of inference job carried no usage, the line is `An inference job reported no usage` with `inference_job_type`; a stale configuration file is `A configuration file is out of date and was migrated in memory only` whatever its remedy; and a `PipeBatch` over a large list is `A PipeBatch fans out over a large list without durable execution`, bounded or not, with `max_concurrency` absent when the fan-out is unbounded. What breaks is a log query or an alert written against an old message.+- **The API server's refusals of a caller's credentials log at `DEBUG` (Breaking)**: a request with no bearer token, an expired or invalid token or a wrong API key logs `A caller's credentials were refused` at `DEBUG`, with `auth_mode` and `auth_refusal_reason` (`missing_bearer_token`, `expired_token`, `invalid_token` or `api_key_mismatch`), since the error line the server writes at `WARNING` for every `401` already records the refusal. A token that verifies but whose `user_id` claim is missing, not a path-safe segment or the reserved single-tenant id still logs at `WARNING`, its `user_action` telling the token issuer what to fix, and an unset `JWT_SECRET_KEY` or `API_KEY` logs at `ERROR` with the variable's name in `env_var`. An alert on the old authentication warnings counts the `401` error lines instead.+- **Exceptions ride as fields at every level**: a `DEBUG` or `VERBOSE` line about a handled exception, such as a Google client that could not be closed, has a fixed message and carries the exception's class and text as `error.type` and `error.message`, as the lines at `INFO` and above already did, rather than splicing them into its text. The retry line names the class of what the attempt raised under `error.type` rather than `exception_type`.+- **`make check-log-calls` holds a message's wording and its exceptions**: the log-call guard also refuses, at every level, a message that starts with a lowercase letter, ends with a period or an ellipsis, holds a backtick or splices a handled exception into its text, through an f-string, a `%`, a `.format()` or a task's `exception()`, and, at `INFO` and above, a message that holds an identifier, a word with an underscore or a call such as `setup()`, or runs past 80 characters. The rules are `lowercase-start`, `trailing-period`, `backtick`, `spliced-exception`, `identifier` and `length`, specified on the log-call guard's page of the contributor documentation, and every call in the tree passes them with an empty baseline.++### Fixed++- **A Google client's close at teardown is no longer garbage-collected**: when a Google LLM or image-generation worker was torn down inside a running event loop, nothing but the loop referenced the background task closing its async client, and a loop holds its tasks weakly, so the task could be collected before the client was closed, with the `asyncio` error `Task was destroyed but it is pending!`. Each close task is now held until it is done.++### Security++- **The API server refuses to start on an unknown `AUTH_MODE` (Breaking)**: a value that is not exactly `none`, `jwt` or `api_key`, such as `jwtt` or `JWT`, now stops the server at startup with `InvalidAuthModeError`, whose message names the valid modes, where the server used to log a warning and serve every `/v1` route without authentication. An unset or empty `AUTH_MODE` still means `none`. A deployment that booted on a mistyped mode sets it to the mode it meant.+## [v0.81.1] - 2026-10-10### Addeddiff --git a/CLAUDE.md b/CLAUDE.mdindex f505697bf..2693e3c99 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4,7 +4,7 @@`make` targets activate the virtual environment themselves; anything else (`pytest`, `pipelex`, `pipelex-dev`) runs from `.venv/bin/` (`.venv\Scripts\` on Windows), never bare. The Makefile is the reference for every target and alias; without `make`, read the target there and run its prerequisites one by one.-- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the log-call check (`clc`: a log message at INFO and above is a literal with its values in `fields=`, and no log message holds Rich markup, against `log_call_baseline.toml`, which only shrinks: the check refuses an entry the baseline at the merge base with `origin/dev` does not list; see `docs/contribute/log-calls.md`), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.+- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the log-call check (`clc`: a log message at INFO and above is a literal with its values in `fields=`, no log message holds Rich markup, starts with a lowercase letter, ends with a period or holds a backtick, at INFO and above none names an identifier or runs past 80 characters, and none splices a handled exception into its text, against `log_call_baseline.toml`, which only shrinks: the check refuses an entry the baseline at the merge base with `origin/dev` does not list; see `docs/contribute/log-calls.md`), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.- **The Pipelex API server is the `api/` workspace member** (the `pipelex-api` distribution, package `pipelex_api`; its guide is `api/CLAUDE.md`). It runs the pipelex of the same commit from its own environment, `api/.venv`, which its targets provision themselves. `make agent-check` ends with `api-agent-check` (`make -C api agent-check`: its install, ruff, pyright, mypy, and the drift checks of its OpenAPI artifact and of its vendored inference tree) and `make agent-test` with `api-agent-test`, so a library change that breaks the server, moves its wire or leaves its inference tree behind fails in the same change. A kit change reaches the server's tree through `make up-kit-configs` (`ukc`); a change to the server's wire is committed with `make -C api openapi-export`.- **Keyword-only arguments** (the convention is in the standards and in `docs/contribute/keyword-only-arguments.md`): `make check-keyword-only` (`cko`) is the gate, `make fix-keyword-only` (`fko`) inserts the bare `*` where it can — on ungranted subjects too — and reports the shapes it cannot fix, and `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (`sgr`) grants a positional subject. Grant before `make agent-check`, which runs the fixer.- **Drift contracts.** When `make drift-check` reports an open contract: `make drift-plan`, review and fix the stale targets, `git add` the trigger files, then `make drift-ack CONTRACT=<id> RATIONALE="<verdict>: …"`, the rationale opening with its verdict, `real-catch`, `clean-pass` or `friction`. No bypass flag; "clean-pass: reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md` and the `/drift-review` skill.diff --git a/Makefile b/Makefileindex 2af1104c8..b155f0a59 100644--- a/Makefile+++ b/Makefile@@ -185,7 +185,7 @@ make check-rich-imports - Refuse a module-level Rich import or reach outsimake cri - Shorthand -> check-rich-importsmake check-actions-allowlist - Refuse a workflow action outside the committed Actions allowlistmake caa - Shorthand -> check-actions-allowlist-make check-log-calls - Refuse an interpolated log message at INFO+ and Rich markup in any log message, against a baseline that only shrinks from origin/dev's merge base (LOG_CALL_BASELINE_REF=<ref> to compare with another)+make check-log-calls - Refuse an interpolated log message at INFO+, Rich markup, a message worded against the conventions and a spliced exception, against a baseline that only shrinks from origin/dev's merge base (LOG_CALL_BASELINE_REF=<ref> to compare with another)make clc - Shorthand -> check-log-callsmake check-TODOs - Check for TODOsdiff --git a/api/.env.example b/api/.env.exampleindex 178074fa2..c226a1365 100644--- a/api/.env.example+++ b/api/.env.example@@ -18,21 +18,24 @@ OPENAI_API_KEY=# Authentication (optional — defaults to AUTH_MODE=none)# ──────────────────────────────────────────────────────────────────────────────-# One of: none | api_key | jwt+# One of: none | api_key | jwt, spelled exactly. Unset or empty means none;+# any other value refuses to start the server.# AUTH_MODE=none# Used when AUTH_MODE=api_key. Clients pass: Authorization: Bearer <API_KEY># API_KEY=-# Used when AUTH_MODE=jwt. Tokens must be HS256 and contain an "email" claim.+# Used when AUTH_MODE=jwt. Tokens must be HS256 and carry a "user_id" claim+# that is a single path-safe segment.# JWT_SECRET_KEY=# When AUTH_MODE=none and the API sits behind a trusted reverse proxy that-# performs authentication and forwards identity via X-User-Email / X-User-Sub-# / X-User-Id / X-Auth-Method headers, set this to "true" to honor those-# headers. DEFAULT IS OFF: if you set this, you MUST ensure your proxy strips-# inbound copies of those headers before adding its own — otherwise any-# external client can spoof user identity by sending the headers themselves.+# performs authentication and forwards the caller's id in the X-User-Id+# header, set this to "true" to honor that header, the only one the server+# reads. DEFAULT IS OFF: if you set this, you MUST ensure your proxy strips+# inbound copies of the header before adding its own — otherwise any+# external client can spoof user identity by sending the header itself.+# With it on, a request arriving without X-User-Id is refused with a 401.# TRUST_FORWARDED_IDENTITY_HEADERS=false# ──────────────────────────────────────────────────────────────────────────────diff --git a/api/CLAUDE.md b/api/CLAUDE.mdindex cb96e3606..a06cd8abd 100644--- a/api/CLAUDE.md+++ b/api/CLAUDE.md@@ -230,7 +230,8 @@ if upload_size > MAX_UPLOAD_BYTES:## Authentication-- Three modes via `AUTH_MODE` env var: `none` (default), `jwt`, `api_key`+- The `AUTH_MODE` env var names an `AuthMode` member: `none` (default), `jwt`, `api_key`+- Unset or empty means `none`; any other value raises `InvalidAuthModeError` when `main.py` selects the dependency at import, so the server refuses to boot. The match is exact, case included, and there is no fallback: a mistyped mode must never serve the routes unauthenticated- `none`: No auth (self-hosted default, or behind API Gateway in hosted version)- `jwt`: Validate `Authorization: Bearer <jwt>` using `JWT_SECRET_KEY`- `api_key`: Validate `Authorization: Bearer <key>` against `API_KEY` env vardiff --git a/api/pipelex_api/main.py b/api/pipelex_api/main.pyindex 41bd75e4e..962529c9f 100644--- a/api/pipelex_api/main.py+++ b/api/pipelex_api/main.py@@ -187,7 +187,9 @@ fastapi_app.include_router(health_router)# detection before they have credentials).fastapi_app.include_router(version_router, prefix="/v1")-# Register all other routes WITH authentication (auto-selects based on AUTH_MODE env var: none/jwt/api_key).+# Register all other routes WITH authentication, the dependency selected by the AUTH_MODE env var. An+# unrecognized AUTH_MODE raises `InvalidAuthModeError` here and the app fails to boot, the same fail-fast+# posture as ERROR_DISCLOSURE above: a mistyped mode must never serve these routes unauthenticated.# The API mounts at `/v1` — the SDKs compose `{MTHDS_BASE_URL}/v1/{endpoint}` (master D10); no `/api/v1`# mount and no alias remain.auth_dependency = get_auth_dependency()diff --git a/api/pipelex_api/method_cache.py b/api/pipelex_api/method_cache.pyindex f69ab8785..39e21fe01 100644--- a/api/pipelex_api/method_cache.py+++ b/api/pipelex_api/method_cache.py@@ -182,7 +182,7 @@ class MethodCloneCache:except OSError:# A concurrent request installed the same SHA between the check and the# rename; its copy is identical (same commit), so use it.- log.debug(f"Method clone cache: lost the install race for {fetched.commit_sha}, reusing the winner's copy")+ log.debug(f"A concurrent request installed method clone {fetched.commit_sha} first, and its copy is used")self._evict()return self._package_from_clone(ref=ref, clone_dir=target_dir, commit_sha=fetched.commit_sha)finally:diff --git a/api/pipelex_api/method_source.py b/api/pipelex_api/method_source.pyindex a6ebb18cc..9420d0bec 100644--- a/api/pipelex_api/method_source.py+++ b/api/pipelex_api/method_source.py@@ -97,7 +97,7 @@ def _fetch_package(method_ref: str) -> FetchedMethodPackage:# The tag and the commit say which version of the package a hosted run executed; the tag is `None` when the# reference named none and the default branch was fetched.log.info(- "A method_ref was resolved to a package",+ "A method reference was resolved to a package",fields={"method_ref": ref.ref_str,"package_address": package.provenance.address,diff --git a/api/pipelex_api/security.py b/api/pipelex_api/security.pyindex fbe8a59b4..c1097a037 100644--- a/api/pipelex_api/security.py+++ b/api/pipelex_api/security.py@@ -1,4 +1,7 @@-"""Authentication module with configurable AUTH_MODE (none, jwt, api_key).+"""Authentication module: the `AUTH_MODE` environment variable selects one of the `AuthMode` members.++An unset or empty `AUTH_MODE` means `none`. Any other value must spell a member exactly, or the server refuses to+start (`InvalidAuthModeError`): a mistyped mode must never serve the API without the authentication it asked for.User identity is extracted during auth and stored on request.state.user as a RequestUser.Route handlers access it via the get_request_user dependency.@@ -15,11 +18,14 @@ from pipelex import logfrom pipelex.system.environment import get_optional_envfrom pipelex.system.storage_scope import SINGLE_TENANT_USER_IDfrom pipelex.tools.log.error_fields import error_fields+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pydantic import BaseModel, Fieldfrom pipelex_api.error_types import ErrorTypefrom pipelex_api.errors import raise_bad_request, raise_internal_server_error, raise_unauthenticated+AUTH_MODE_ENV_VAR = "AUTH_MODE"+# JWT Configuration (only used when AUTH_MODE=jwt)JWT_ALGORITHM = "HS256"@@ -86,6 +92,28 @@ class AuthMode(StrEnum):API_KEY = "api_key"+class AuthRefusalReason(StrEnum):+ """Why the server refused a caller's own credentials, as the `auth_refusal_reason` field of the line that says so.++ These are the caller's mistakes, answered with a 401 the exception handler records at WARNING with its `error.type`+ and `detail`, so the line naming the reason is diagnosis and logs at DEBUG. A token that verifies but whose+ `user_id` claim is unusable is no caller's mistake: whoever minted it holds the server's secret, so it is the+ deployment's issuer that is misconfigured, and that line stays a WARNING the operator can act on.+ """++ MISSING_BEARER_TOKEN = "missing_bearer_token"+ EXPIRED_TOKEN = "expired_token"+ INVALID_TOKEN = "invalid_token"+ API_KEY_MISMATCH = "api_key_mismatch"+++#: The message of every line saying the server refused a caller's own credentials, its reason a field.+CREDENTIALS_REFUSED_MESSAGE = "A caller's credentials were refused"++#: The advice of every line about a verified token whose user id claim the server cannot use.+TOKEN_ISSUER_USER_ACTION = "Have the token issuer put a path-safe user_id claim in every token, never the single-tenant id"++class ForwardedIdentityHeader(StrEnum):"""HTTP headers a trusted reverse proxy may forward to authenticatea caller when `TRUST_FORWARDED_IDENTITY_HEADERS=true`.@@ -117,16 +145,28 @@ def _set_request_user(request: Request, user_id: str) -> None:request.state.user = RequestUser(user_id=user_id)+class InvalidAuthModeError(ValueError):+ """Raised at startup when `AUTH_MODE` holds a value that is not an `AuthMode` member."""++def get_auth_mode() -> AuthMode:- """Read AUTH_MODE from environment. Defaults to 'none'."""- raw = get_optional_env("AUTH_MODE")+ """Resolve `AUTH_MODE` to an `AuthMode`.++ Returns `AuthMode.NONE` when the variable is unset or empty, the documented default. Any other value must spell a+ member exactly, case included, or `InvalidAuthModeError` is raised: the server is assembled at import+ (`pipelex_api.main` resolves the auth dependency there), so a mistyped mode refuses to start rather than serving+ every authenticated route without authentication. There is deliberately no case-insensitive match and no+ fallback, so a value is either a mode or an error naming the valid spellings.+ """+ raw = get_optional_env(AUTH_MODE_ENV_VAR)if not raw:return AuthMode.NONEtry:return AuthMode(raw)- except ValueError:- log.warning("AUTH_MODE names no known mode, so the server falls back to no authentication", fields={"env_var": "AUTH_MODE", "auth_mode": raw})- return AuthMode.NONE+ except ValueError as exc:+ valid = ", ".join(f"'{mode}'" for mode in AuthMode)+ msg = f"{AUTH_MODE_ENV_VAR}={raw!r} is not a valid authentication mode. Valid values: {valid}."+ raise InvalidAuthModeError(msg) from excasync def verify_jwt(@@ -139,12 +179,14 @@ async def verify_jwt(# is configured with `auto_error=False` so this branch (rather than# FastAPI's default `HTTPException`) shapes the response — same RFC# 7807 `application/problem+json` as every other 401.- log.warning("JWT auth requested without a Bearer token")+ log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.JWT, "auth_refusal_reason": AuthRefusalReason.MISSING_BEARER_TOKEN})raise_unauthenticated("Missing or malformed Authorization header")jwt_secret = get_optional_env("JWT_SECRET_KEY")if not jwt_secret:- log.error("JWT_SECRET_KEY environment variable is not set")+ log.error(+ "An environment variable the authentication mode requires is not set", fields={"env_var": "JWT_SECRET_KEY", "auth_mode": AuthMode.JWT}+ )raise_internal_server_error("Server configuration error: JWT_SECRET_KEY not configured", error_type=ErrorType.SERVER_MISCONFIGURED)token = credentials.credentials@@ -163,12 +205,15 @@ async def verify_jwt(# the id becomes the owner segment of every storage key.user_id = payload.get("user_id")if not user_id:- log.warning("JWT missing user_id claim")+ log.warning("A verified token has no user id claim", fields={USER_ACTION_FIELD: TOKEN_ISSUER_USER_ACTION})raise_unauthenticated("Invalid token: missing user_id claim", error_type=ErrorType.INVALID_TOKEN)if not isinstance(user_id, str) or not is_safe_user_id(user_id):# The claim is refused, so it is not `user.id`, which names an authenticated caller and is always a string:# the line carries the type the claim was decoded as, and never its value.- log.warning("A JWT's user_id claim is not a path-safe segment", fields={"claim_type": type(user_id).__name__})+ log.warning(+ "A verified token's user id claim is not a path-safe segment",+ fields={"claim_type": type(user_id).__name__, USER_ACTION_FIELD: TOKEN_ISSUER_USER_ACTION},+ )raise_unauthenticated("Invalid token: user_id claim must be a single path-safe segment", error_type=ErrorType.INVALID_TOKEN)if user_id == SINGLE_TENANT_USER_ID:# Path-safe, but reserved for the no-user-model deployment. An@@ -176,7 +221,7 @@ async def verify_jwt(# land in the single-tenant namespace of a server that DOES have# users — beside whatever a no-auth deployment of the same image# wrote there.- log.warning("JWT user_id claim is the reserved single-tenant id")+ log.warning("A verified token's user id claim is the reserved single-tenant id", fields={USER_ACTION_FIELD: TOKEN_ISSUER_USER_ACTION})raise_unauthenticated(f"Invalid token: user_id claim must not be the reserved {SINGLE_TENANT_USER_ID!r} value",error_type=ErrorType.INVALID_TOKEN,@@ -186,10 +231,13 @@ async def verify_jwt(return payloadexcept jwt.ExpiredSignatureError:- log.warning("JWT token has expired")+ log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.JWT, "auth_refusal_reason": AuthRefusalReason.EXPIRED_TOKEN})raise_unauthenticated("Token expired", error_type=ErrorType.TOKEN_EXPIRED)except jwt.InvalidTokenError as exc:- log.warning("A JWT failed validation", fields=error_fields(exc=exc))+ log.debug(+ CREDENTIALS_REFUSED_MESSAGE,+ fields={"auth_mode": AuthMode.JWT, "auth_refusal_reason": AuthRefusalReason.INVALID_TOKEN, **error_fields(exc=exc)},+ )raise_unauthenticated("Invalid token", error_type=ErrorType.INVALID_TOKEN)@@ -202,17 +250,17 @@ async def verify_api_key(credentials: Annotated[HTTPAuthorizationCredentials | N# Missing, empty, or non-Bearer `Authorization` header. See the# matching branch in `verify_jwt` for why this lives here and not# in `HTTPBearer`'s default `auto_error=True` behavior.- log.warning("API key auth requested without a Bearer token")+ log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.API_KEY, "auth_refusal_reason": AuthRefusalReason.MISSING_BEARER_TOKEN})raise_unauthenticated("Missing or malformed Authorization header")api_key = get_optional_env("API_KEY")if not api_key:- log.error("API_KEY environment variable is not set")+ log.error("An environment variable the authentication mode requires is not set", fields={"env_var": "API_KEY", "auth_mode": AuthMode.API_KEY})raise_internal_server_error("Server configuration error: API_KEY not configured", error_type=ErrorType.SERVER_MISCONFIGURED)if credentials.credentials != api_key:- log.warning("API key mismatch")+ log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.API_KEY, "auth_refusal_reason": AuthRefusalReason.API_KEY_MISMATCH})raise_unauthenticated("Invalid authentication token", error_type=ErrorType.INVALID_TOKEN)return credentials.credentials@@ -245,13 +293,19 @@ async def no_auth(request: Request) -> None:# is missing, misconfigured, or bypassed — and continuing under a shared# owner is how a multi-tenant server silently becomes a single namespace# where every tenant reads the others' outputs. It is now a hard failure.- log.warning("TRUST_FORWARDED_IDENTITY_HEADERS is on but no X-User-Id was forwarded")+ log.warning(+ "No user id was forwarded though forwarded identity headers are trusted",+ fields={+ "env_var": "TRUST_FORWARDED_IDENTITY_HEADERS",+ USER_ACTION_FIELD: "Make sure the proxy in front of the server authenticates every request and forwards X-User-Id",+ },+ )raise_unauthenticated("Identity required: no X-User-Id was forwarded", error_type=ErrorType.INVALID_TOKEN)if not is_safe_user_id(user_id):# A non-empty but path-unsafe id: the proxy intended to authenticate# someone and sent a malformed value. Fail closed.# No value: the header is refused, so it names no caller, and it is whatever text anyone reaching the server sent.- log.warning("A forwarded X-User-Id is not a path-safe segment, and the request is refused")+ log.warning("A forwarded user id is not a path-safe segment and the request was refused")raise_bad_request("Forwarded X-User-Id must be a single path-safe segment", error_type=ErrorType.BAD_REQUEST)_set_request_user(request, user_id=user_id)@@ -277,6 +331,8 @@ def get_auth_dependency() -> Any:- none: No authentication (self-hosted default, or behind API Gateway)- jwt: Validate JWT tokens- api_key: Validate static API key++ Raises `InvalidAuthModeError` when `AUTH_MODE` names no mode (see `get_auth_mode`)."""auth_mode = get_auth_mode()match auth_mode:diff --git a/api/tests/unit/test_method_ref_run.py b/api/tests/unit/test_method_ref_run.pyindex 3db0d4571..ca28e3d7c 100644--- a/api/tests/unit/test_method_ref_run.py+++ b/api/tests/unit/test_method_ref_run.py@@ -132,7 +132,7 @@ class TestMethodRefRun:response = client.post("/v1/execute", json={"method_ref": method_ref, "inputs": {"text": "hi"}})assert response.status_code == 200, response.text- (resolution_record,) = [record for record in caplog.records if record.getMessage() == "A method_ref was resolved to a package"]+ (resolution_record,) = [record for record in caplog.records if record.getMessage() == "A method reference was resolved to a package"]record_fields = vars(resolution_record)assert record_fields["method_ref"] == method_refassert record_fields["package_address"] == STUB_METHOD_ADDRESSdiff --git a/api/tests/unit/test_security_auth_mode.py b/api/tests/unit/test_security_auth_mode.pynew file mode 100644index 000000000..27fabf813--- /dev/null+++ b/api/tests/unit/test_security_auth_mode.py@@ -0,0 +1,49 @@+"""Unit tests for AUTH_MODE resolution: an unset or empty value means `none`, any other value must name a mode."""++import pytest++from pipelex_api.security import AUTH_MODE_ENV_VAR, AuthMode, InvalidAuthModeError, get_auth_dependency, get_auth_mode+++class TestAuthMode:+ def test_defaults_to_none_when_unset(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.delenv(AUTH_MODE_ENV_VAR, raising=False)+ assert get_auth_mode() is AuthMode.NONE++ def test_empty_value_defaults_to_none(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setenv(AUTH_MODE_ENV_VAR, "")+ assert get_auth_mode() is AuthMode.NONE++ @pytest.mark.parametrize("mode", list(AuthMode))+ def test_each_mode_resolves_to_itself(self, monkeypatch: pytest.MonkeyPatch, mode: AuthMode):+ monkeypatch.setenv(AUTH_MODE_ENV_VAR, mode.value)+ assert get_auth_mode() is mode++ @pytest.mark.parametrize("raw", ["jwtt", "apikey", "api-key", "true", "off", " ", " jwt"])+ def test_rejects_unknown_value(self, monkeypatch: pytest.MonkeyPatch, raw: str):+ # An unknown value used to fall back to no authentication, so a typo served every route unauthenticated.+ monkeypatch.setenv(AUTH_MODE_ENV_VAR, raw)+ with pytest.raises(InvalidAuthModeError):+ get_auth_mode()++ @pytest.mark.parametrize("raw", ["JWT", "Api_Key", "NONE"])+ def test_rejects_wrong_case(self, monkeypatch: pytest.MonkeyPatch, raw: str):+ # The match is strict: a value differing from a mode only by case is refused, never folded onto that mode.+ monkeypatch.setenv(AUTH_MODE_ENV_VAR, raw)+ with pytest.raises(InvalidAuthModeError):+ get_auth_mode()++ def test_error_names_the_value_and_every_valid_mode(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setenv(AUTH_MODE_ENV_VAR, "jwtt")+ with pytest.raises(InvalidAuthModeError) as exc_info:+ get_auth_mode()+ message = str(exc_info.value)+ assert "'jwtt'" in message+ for mode in AuthMode:+ assert f"'{mode.value}'" in message++ def test_dependency_selection_refuses_unknown_value(self, monkeypatch: pytest.MonkeyPatch):+ # `pipelex_api.main` selects the dependency at import, so this raise is what stops the server from starting.+ monkeypatch.setenv(AUTH_MODE_ENV_VAR, "jwtt")+ with pytest.raises(InvalidAuthModeError):+ get_auth_dependency()diff --git a/api/tests/unit/test_security_log_levels.py b/api/tests/unit/test_security_log_levels.pynew file mode 100644index 000000000..b37e67bbb--- /dev/null+++ b/api/tests/unit/test_security_log_levels.py@@ -0,0 +1,140 @@+"""Tests for the levels and fields at which api/security logs a refused or unusable credential."""++import logging+from typing import Annotated++import jwt+import pytest+from fastapi import Depends, FastAPI+from fastapi.testclient import TestClient+from pipelex.system.storage_scope import SINGLE_TENANT_USER_ID+from pipelex.tools.log.log_fields import carried_attributes+from pytest_mock import MockerFixture++from pipelex_api.exception_handlers import register_exception_handlers+from pipelex_api.security import RequestUser, get_request_user, verify_api_key, verify_jwt+from tests.unit._constants import RoutePath++JWT_SECRET = "test-jwt-secret-do-not-use-in-prod"+API_KEY = "test-api-key-static"+USER_ID_UUID = "11111111-1111-4111-1111-111111111111"+SECURITY_LOGGER = "pipelex_api.security"+++async def _whoami_jwt(+ _payload: Annotated[dict[str, object], Depends(verify_jwt)],+ user: Annotated[RequestUser | None, Depends(get_request_user)],+) -> dict[str, str | None]:+ if user is None:+ return {"user_id": None}+ return {"user_id": user.user_id}+++async def _ping_api_key(_token: Annotated[str, Depends(verify_api_key)]) -> dict[str, str]:+ return {"ok": "yes"}+++def _build_jwt_client() -> TestClient:+ app = FastAPI()+ app.add_api_route(RoutePath.WHOAMI, _whoami_jwt, methods=["GET"])+ register_exception_handlers(app)+ return TestClient(app)+++def _build_api_key_client() -> TestClient:+ app = FastAPI()+ app.add_api_route(RoutePath.PING, _ping_api_key, methods=["GET"])+ register_exception_handlers(app)+ return TestClient(app)+++def _security_records(caplog: pytest.LogCaptureFixture) -> list[logging.LogRecord]:+ return [record for record in caplog.records if record.name == SECURITY_LOGGER]+++class TestSecurityLogLevels:+ """A caller's own credential mistakes log at DEBUG, their reason a field; the server's misconfigurations keep their level.++ The exception handler records every 401 at WARNING with its `error.type` and `detail` already, so a stale client's+ refusals flooded the warnings twice over when the security module warned as well.+ """++ @pytest.mark.parametrize(+ ("client_kind", "secret", "authorization", "expected_mode", "expected_reason"),+ [+ ("jwt", JWT_SECRET, None, "jwt", "missing_bearer_token"),+ ("jwt", JWT_SECRET, "expired", "jwt", "expired_token"),+ ("jwt", JWT_SECRET, "Bearer not.a.real.token", "jwt", "invalid_token"),+ ("api_key", API_KEY, None, "api_key", "missing_bearer_token"),+ ("api_key", API_KEY, "Bearer wrong-key", "api_key", "api_key_mismatch"),+ ],+ ids=["jwt without a token", "an expired jwt", "an invalid jwt", "api key without a token", "a wrong api key"],+ )+ def test_a_callers_refused_credentials_log_at_debug_with_their_reason(+ self,+ *,+ mocker: MockerFixture,+ caplog: pytest.LogCaptureFixture,+ client_kind: str,+ secret: str,+ authorization: str | None,+ expected_mode: str,+ expected_reason: str,+ ):+ mocker.patch("pipelex_api.security.get_optional_env", return_value=secret)+ client = _build_jwt_client() if client_kind == "jwt" else _build_api_key_client()+ route = RoutePath.WHOAMI if client_kind == "jwt" else RoutePath.PING+ if authorization == "expired":+ authorization = f"Bearer {jwt.encode({'user_id': USER_ID_UUID, 'exp': 0}, JWT_SECRET, algorithm='HS256')}"+ headers = {"Authorization": authorization} if authorization is not None else {}++ with caplog.at_level(logging.DEBUG, logger=SECURITY_LOGGER):+ response = client.get(route, headers=headers)++ assert response.status_code == 401+ (record,) = _security_records(caplog)+ assert record.levelno == logging.DEBUG+ assert record.getMessage() == "A caller's credentials were refused"+ carried = carried_attributes(record=record)+ assert carried["auth_mode"] == expected_mode+ assert carried["auth_refusal_reason"] == expected_reason++ @pytest.mark.parametrize(+ ("client_kind", "expected_env_var"),+ [("jwt", "JWT_SECRET_KEY"), ("api_key", "API_KEY")],+ )+ def test_a_missing_secret_still_logs_at_error_naming_the_variable(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, client_kind: str, expected_env_var: str+ ):+ mocker.patch("pipelex_api.security.get_optional_env", return_value=None)+ client = _build_jwt_client() if client_kind == "jwt" else _build_api_key_client()+ route = RoutePath.WHOAMI if client_kind == "jwt" else RoutePath.PING++ with caplog.at_level(logging.DEBUG, logger=SECURITY_LOGGER):+ response = client.get(route, headers={"Authorization": "Bearer anything"})++ assert response.status_code == 500+ (record,) = _security_records(caplog)+ assert record.levelno == logging.ERROR+ assert carried_attributes(record=record)["env_var"] == expected_env_var++ @pytest.mark.parametrize(+ "claims",+ [{"iat": 0}, {"user_id": "a/b"}, {"user_id": SINGLE_TENANT_USER_ID}],+ ids=["no user id claim", "an unsafe user id claim", "the single-tenant id"],+ )+ def test_a_verified_token_with_an_unusable_claim_still_warns_the_operator(+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, claims: dict[str, object]+ ):+ """A token that verifies was minted by whoever holds the server's secret, so its unusable claim is the issuer's to fix."""+ mocker.patch("pipelex_api.security.get_optional_env", return_value=JWT_SECRET)+ client = _build_jwt_client()+ token = jwt.encode(claims, JWT_SECRET, algorithm="HS256")++ with caplog.at_level(logging.DEBUG, logger=SECURITY_LOGGER):+ response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})++ assert response.status_code == 401+ (record,) = _security_records(caplog)+ assert record.levelno == logging.WARNING+ assert "user_action" in carried_attributes(record=record)diff --git a/api/tests/unit/test_security_no_auth.py b/api/tests/unit/test_security_no_auth.pyindex 5112df316..1dcd3a1b5 100644--- a/api/tests/unit/test_security_no_auth.py+++ b/api/tests/unit/test_security_no_auth.py@@ -134,9 +134,7 @@ class TestNoAuthForwardedHeaders:# The refused header names no caller, so it is never logged as `user.id`, nor logged at all: anyone reaching# the server could otherwise have any text recorded as a user.(record,) = [- record- for record in caplog.records- if record.getMessage() == "A forwarded X-User-Id is not a path-safe segment, and the request is refused"+ record for record in caplog.records if record.getMessage() == "A forwarded user id is not a path-safe segment and the request was refused"]carried = carried_attributes(record=record)assert OTelLogAttr.USER_ID not in carrieddiff --git a/api/tests/unit/test_security_verifiers.py b/api/tests/unit/test_security_verifiers.pyindex 787fcd6c7..9c8678e05 100644--- a/api/tests/unit/test_security_verifiers.py+++ b/api/tests/unit/test_security_verifiers.py@@ -144,7 +144,7 @@ class TestSecurityVerifiers:response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})assert response.status_code == 401- (record,) = [record for record in caplog.records if record.getMessage() == "A JWT's user_id claim is not a path-safe segment"]+ (record,) = [record for record in caplog.records if record.getMessage() == "A verified token's user id claim is not a path-safe segment"]carried = carried_attributes(record=record)assert carried.get("claim_type") == expected_claim_typeassert OTelLogAttr.USER_ID not in carrieddiff --git a/docs/api-server/configuration.md b/docs/api-server/configuration.mdindex d3eb6639b..8288567d5 100644--- a/docs/api-server/configuration.md+++ b/docs/api-server/configuration.md@@ -19,7 +19,7 @@ The API reads its settings from environment variables. With Docker, the easiestOPENAI_API_KEY=your-openai-api-key# Authentication for the API itself (optional — defaults to AUTH_MODE=none)-AUTH_MODE=none # one of: none | api_key | jwt+AUTH_MODE=none # one of: none | api_key | jwt (any other value refuses to start)API_KEY=your-api-key # used when AUTH_MODE=api_keyJWT_SECRET_KEY=your-jwt-secret # used when AUTH_MODE=jwtdiff --git a/docs/api-server/index.md b/docs/api-server/index.mdindex 16d6f5f2e..32ea198c6 100644--- a/docs/api-server/index.md+++ b/docs/api-server/index.md@@ -94,7 +94,7 @@ To run methods on it from the `pipelex` CLI, give its origin, without `/v1`, to## Authentication-The API supports three authentication modes via the `AUTH_MODE` environment variable:+The `AUTH_MODE` environment variable selects how the API authenticates its callers, with one of the modes below. An unset or empty `AUTH_MODE` means `none`. Any other value must spell a mode exactly as written here, lowercase included, or the server refuses to start with an error naming the valid modes: a mistyped mode never serves the API without the authentication it asked for.### No Authentication (Default)diff --git a/docs/api-server/logging.md b/docs/api-server/logging.mdindex c9be1a010..f67743ed6 100644--- a/docs/api-server/logging.md+++ b/docs/api-server/logging.md@@ -72,6 +72,13 @@ Every field in that table is a **record attribute**, which is a different thingDisposition follows the HTTP status, not the error domain: a `4xx` is a caller mistake and logs at `WARNING` without a traceback; a `5xx` is a server fault and logs at `ERROR` with one. See [Error Responses](error-responses.md) for the response side of the same failure.+## Authentication lines++The error line above is the record of every refused request, a `401` included, at `WARNING`. The authentication check before it says why it refused, at a level that depends on who has to act:++- **A caller's own mistake logs at `DEBUG`**: no bearer token, an expired or invalid token, a wrong API key. Each is the line `A caller's credentials were refused`, its `auth_mode` naming the mode in force and its `auth_refusal_reason` one of `missing_bearer_token`, `expired_token`, `invalid_token` and `api_key_mismatch`, with an invalid token's `error.type` and `error.message` beside it. The operator can do nothing about a client holding a stale token, so its refusals add nothing to the warnings beyond the error line of each request.+- **A misconfiguration of the deployment keeps its level**: forwarded identity headers trusted while a request arrives without a user id log at `WARNING`, and an unset `JWT_SECRET_KEY` or `API_KEY` at `ERROR`, each naming the variable in `env_var`. An unknown `AUTH_MODE` writes no line here, because the server refuses to start with it (see [Authentication](index.md#authentication)). A token that verifies against the server's secret but whose `user_id` claim is missing, is not a path-safe segment or is the reserved single-tenant id logs at `WARNING` too: whoever minted it holds the secret, so it is the deployment's token issuer that needs fixing, which the line's `user_action` says.+## ConfigurationThe keys live in `[runtime.log]` of the server's own `api/.pipelex/pipelex.toml`, which the image copies to `/root/.pipelex/`:diff --git a/docs/configuration/config-practical/logging-config.md b/docs/configuration/config-practical/logging-config.mdindex 1d0fcfb8b..e14564048 100644--- a/docs/configuration/config-practical/logging-config.md+++ b/docs/configuration/config-practical/logging-config.md@@ -158,12 +158,14 @@ Configuration section: `[runtime.log.rich_log]`, read only when `sink = "console```tomlis_show_time = falseis_show_level = true+is_show_path = falseis_link_path_enabled = true```- `is_show_time`: Show timestamp in logs- `is_show_level`: Show log level-- `is_link_path_enabled`: Make file paths clickable+- `is_show_path`: Show the source file and line that logged each record, in a column at the right of the line. It is off by default: the column takes about 25 characters of every line and makes a long one wrap+- `is_link_path_enabled`: Make that path clickable, where the terminal supports links### Syntax Highlighting@@ -301,6 +303,7 @@ anthropic = "INFO"[runtime.log.rich_log]is_show_time = falseis_show_level = true+is_show_path = falseis_link_path_enabled = truehighlighter_name = "json"is_rich_tracebacks = truediff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.mdindex 6a1df848c..0b8b50f2a 100644--- a/docs/configuration/config-technical/inference-backend-config.md+++ b/docs/configuration/config-technical/inference-backend-config.md@@ -694,7 +694,8 @@ Common error types:You do not have to do anything about that at boot. Pipelex reads the migration history for the `inference/backends/` files, carries the out-of-date ones forward **in memory**, and starts with a warning line for each file, the file and what the migration history carried forward following the message as fields:```-WARNING 🧠: A configuration file is out of date and was read as if it had been migrated, and nothing was written; run `pipelex migrate` to update it file.path=/Users/me/.pipelex/inference/backends/openai.toml migration_steps=["Drop prompting_target from every backend definition"] has_blocked_steps=false+WARNING A configuration file is out of date and was migrated in memory only file.path=/Users/me/.pipelex/inference/backends/openai.toml migration_steps="[\"Drop prompting_target from every backend definition\"]" has_blocked_steps=false+ → Run pipelex migrate to update it```Nothing has been written at that point, so the warning comes back at the next boot until you run the command:diff --git a/docs/contribute/log-calls.md b/docs/contribute/log-calls.mdindex 6986337aa..1d65dce0e 100644--- a/docs/contribute/log-calls.md+++ b/docs/contribute/log-calls.md@@ -5,11 +5,11 @@ description: "The guard that holds Pipelex's own log calls to the log-call conve# Log-call guard-Pipelex's log calls follow the [log-call conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields`, no markup. Most of them are for review; the ones that can be read off the source are held by `make check-log-calls` on every call: a message at INFO and above is a literal written at the call, and no message holds Rich markup at any level. This page is the guard's specification. The calls that broke the rules when the guard arrived were listed in a committed baseline that can only shrink, so that new code was held to the conventions from the start while the existing calls were converted. Every one of them has been converted since: the baseline lists no call, and since it can only shrink, it stays empty, so every log call is held to the rules.+Pipelex's log calls follow the [log-call conventions](../tools/logging.md#log-call-conventions): a fixed message, worded as one short sentence, its values in `fields`, no markup and no exception in its text. Most of them are for review; the ones that can be read off the source are held by `make check-log-calls` on every call: a message at INFO and above is a literal written at the call, no message holds Rich markup, a message keeps the mechanical rules of its wording, and no message splices a handled exception into its text. This page is the guard's specification. The calls that broke the rules when the guard arrived were listed in a committed baseline that can only shrink, so that new code was held to the conventions from the start while the existing calls were converted. Every one of them has been converted since: the baseline lists no call, and since it can only shrink, it stays empty, so every log call is held to the rules.## What it reads-The guard parses every Python module in `pipelex/`, except the facade's own package `pipelex/tools/log/`, and in the API server's `api/pipelex_api/`, which logs through the same facade. It reads the calls of the `log` facade, however a module reaches it: the name it imports `log` under, from `pipelex` or from `pipelex.tools.log.log`, an alias, a relative import and a star import included, or an attribute path through a module it imports, `pipelex.log.warning(...)` after `import pipelex`, `m.log.info(...)` after `from pipelex.tools.log import log as m`, `x.log.info(...)` after `import pipelex.tools.log.log as x`. The receiver is read where the call is made, through the bindings of its name that can reach the call, as a message's names are below, save that a name captured from an enclosing function is followed, through every binding that function makes: it is the facade when one of them imports the facade, so a parameter or a local named `log`, a stdlib logger say, is not the facade, and neither is a `log` imported in another function, while one imported in an enclosing function is. A call's message is its first positional argument, or its `content=` keyword, and its `title=` and `inline=` keywords count as part of it, since the dispatch renders both into the message. A title or an inline title that is statically `None`, `title=None` or a name bound only to `None` and literals, is no message text at all. A `**` expansion of a dict literal whose keys are all strings passes its `content`, `title` and `inline` entries like keywords, `log.warning(**{"content": f"Value {value}"})` being read as `log.warning(content=f"Value {value}")`; any other `**` expansion in a facade call, `log.warning(**params)`, could carry the message or a title, so the call is refused as `non-literal`, at every level, since neither rule can read through it.+The guard parses every Python module in `pipelex/`, except the facade's own package `pipelex/tools/log/`, and in the API server's `api/pipelex_api/`, which logs through the same facade. It reads the calls of the `log` facade, however a module reaches it: the name it imports `log` under, from `pipelex` or from `pipelex.tools.log.log`, an alias, a relative import and a star import included, or an attribute path through a module it imports, `pipelex.log.warning(...)` after `import pipelex`, `m.log.info(...)` after `from pipelex.tools.log import log as m`, `x.log.info(...)` after `import pipelex.tools.log.log as x`. The receiver is read where the call is made, through the bindings of its name that can reach the call, as a message's names are below, save that a name captured from an enclosing function is followed, through every binding that function makes: it is the facade when one of them imports the facade, so a parameter or a local named `log`, a stdlib logger say, is not the facade, and neither is a `log` imported in another function, while one imported in an enclosing function is. A call's message is its first positional argument, or its `content=` keyword, and its `title=` and `inline=` keywords count as part of it, since the dispatch renders both into the message. A title or an inline title that is statically `None`, `title=None` or a name bound only to `None` and literals, is no message text at all. A `**` expansion of a dict literal whose keys are all strings passes its `content`, `title` and `inline` entries like keywords, `log.warning(**{"content": f"Value {value}"})` being read as `log.warning(content=f"Value {value}")`; any other `**` expansion in a facade call, `log.warning(**params)`, could carry the message or a title, so the call is refused as `non-literal`, at every level, since no rule can read through it.## The rules@@ -54,9 +54,41 @@ A markup tag is what Rich reads as one, matched with Rich's own tag pattern:A bracketed word that is no style, `list[int]`, `[Errno 2]` or `items[index]`, is text and passes, and so does a tag escaped with a backslash. The tests that check the messages a live run logs, described under [Messages are plain text](../tools/logging.md#messages-are-plain-text), read tags by this same rule, the guard's `find_markup_tags`, so the source and the run are held to one definition.+### The wording of a message++The text of a message is held to the rules of [Wording a message](../tools/logging.md#wording-a-message) that can be read off the source; the rest of that section, the subject first, one thing per sentence, the past tense, is for review.++| Rule | Where | What it refuses |+| --- | --- | --- |+| `lowercase-start` | Every level | A message whose first character is a lowercase letter, `"loaded the library"`, leading whitespace skipped; one that starts with a quote or a digit passes |+| `trailing-period` | Every level | A message that ends with a period or an ellipsis, `.`, `...` or `…`, trailing whitespace skipped |+| `backtick` | Every level | A backtick anywhere in the message |+| `identifier` | INFO and above | A word holding an underscore, `needs_inference` or `PIPELEX_API_KEY`, or a call written with empty parentheses, `setup()` or `Loader.load()` |+| `length` | INFO and above | A message of more than 80 characters |++A word of Pipelex's own vocabulary is a word like any other, so `PipeBatch`, `METHODS.toml` and a plural written `model(s)` pass. On `log.debug` and `log.verbose`, which a person at a terminal reads, a message may name an identifier and run long, but it still starts with no lowercase letter, ends with no period and holds no backtick.++The rules read the text the markup rule reads: the literal text of the message, of its title and of its inline title, each as a text of its own, folded across concatenations, named literals and `+=` extensions the way it reaches the console, the format string of a `%` or a `.format()` read as written. A message can reach the console as several texts, a conditional between two literals or a name bound to a different literal on each branch, and each of them is read: one that breaks a rule is enough, so `"Loaded" if cached else "loading..."` breaks `lowercase-start` and `trailing-period`.++A value the guard cannot read, an f-string's placeholder or a name bound to no literal, keeps the texts around it apart, as it does for markup, and could be anything. So a text that starts with such a value passes `lowercase-start`, `f"{count} pipes were loaded"`, and one that ends with one passes `trailing-period`, while `backtick` and `identifier` read every literal part, never across a value. A `+` whose two sides could combine into more texts than the fold's bound reads as if such a value stood between them: its left side keeps the start of the message, its right side the end. The length counts the literal parts alone, since a value is at least empty: a message whose literal text runs past 80 characters is refused whatever it splices, `the message is at least 95 characters long`, while one that only its values would push past the bound is not. At INFO and above the message is a literal anyway, by the first rule, so the length is exact there for every message that passes that rule.++### No exception in the text++On every method, no value a message splices into its text reaches a handled exception, which rides the record or its fields and never the message, as [Exceptions](../tools/logging.md#exceptions) explains. A call that breaks it is refused as `spliced-exception`.++The values a message splices are an f-string's placeholders, the right operand of a `%`, the arguments of a `.format()` call, and any part of the message that is no literal text, a call's result or an attribute, the message itself included: `log.debug(exc)` and `log.debug("A cleanup failed: " + str(exc))` splice the exception as surely as `log.debug(f"A cleanup failed: {exc}")`. A message held in a name is read through its bindings, as above, so `msg = f"A cleanup failed: {exc}"` then `log.debug(msg)` is refused too.++A spliced value reaches a handled exception when it:++- reads a name one of whose bindings that can reach the read is an `except ... as` target, `{exc}`, `{exc!r}` or `{type(exc).__name__}`;+- reads a name bound to a value that reaches one in turn, however many bindings away, `detail = str(exc)` then `{detail}`;+- calls a method named `exception`, a finished task's `t.exception()`, a retry outcome's or `sys.exception()`, which return an exception no handler binds.++A name captured from an enclosing function is read through every binding that function makes, as the facade's receiver is, so a callback a handler registers, `lambda: log.debug(f"A cleanup failed: {exc}")`, splices the handler's exception. A name bound by a handler and rebound before the read holds what it was rebound to, and a handler's target reaches nothing past its handler, where Python deletes it. A value that reaches the exception counts whatever it takes from it, its text, its class's name or a count of its errors: what a line needs of an exception rides in `error_fields`, and anything else in a field of its own.+## The baseline-`log_call_baseline.toml`, at the repo root, lists the calls exempted from the rules until they are converted. It started with every call that broke one when the guard arrived, and lists none now that they are all converted. Its key is the call's file and enclosing qualified name, `<relative_path>::<qualified_name>`, the classes and functions joined by dots, or `<module>` for a call made at module level. Under the key, each call is listed by its **signature**, once per call that carries it. A signature is the call's method, its message's source text with any `**` expansion it cannot read, the rules it breaks between brackets, and, after `where`, every binding the guard read to judge it, sorted, which is every binding that can reach the names it read, a binding it does not read written as what binds it (`<parameter>`, `<for target>`, `<enclosing function>`, `<unbound>`). In a baseline that still listed calls, two entries would read like these, made up for the example:+`log_call_baseline.toml`, at the repo root, lists the calls exempted from the rules until they are converted. It started with every call that broke one when the guard arrived, and lists none now that they are all converted. Its key is the call's file and enclosing qualified name, `<relative_path>::<qualified_name>`, the classes and functions joined by dots, or `<module>` for a call made at module level. Under the key, each call is listed by its **signature**, once per call that carries it. A signature is the call's method, its message's source text with any `**` expansion it cannot read, the rules it breaks between brackets, and, after `where`, every binding the guard read to judge it, sorted, which is every binding that can reach the names it read, a binding it does not read written as what binds it (`<parameter>`, `<for target>`, `<enclosing function>`, `<unbound>`), and, for a call that splices an exception, the bindings that exception is reached through, the handler's own binding written as `<except target>`. In a baseline that still listed calls, two entries would read like these, made up for the example:```tomlversion = 1@@ -101,7 +133,7 @@ A failure lists each call the baseline does not list, at its file and line, with## Converting a call-1. Rewrite the call by the [conventions](../tools/logging.md#log-call-conventions): a fixed message, its values in `fields` under the names of the vocabulary table, a handled exception through `error_fields` at WARNING and below or `include_exception=True` at ERROR and above, except one that is re-raised, one that failed while another propagated and a swallowed `ValidationError`, which ride as `error_fields` at every level.+1. Rewrite the call by the [conventions](../tools/logging.md#log-call-conventions): a fixed message worded as [Wording a message](../tools/logging.md#wording-a-message) says, its advice in `user_action`, its values in `fields` under the names of the vocabulary table, a handled exception through `error_fields` at WARNING and below or `include_exception=True` at ERROR and above, except one that is re-raised, one that failed while another propagated and a swallowed `ValidationError`, which ride as `error_fields` at every level.2. Run `make check-log-calls`. It reports the call's signature as stale; editing what a listed call logs without converting it reports the old signature as stale and the new one as unlisted.3. Remove the signature, by hand or with `.venv/bin/pipelex-dev check-log-calls --prune`, and commit the file with the change.diff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex 1882dbed5..d965f39f3 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -554,7 +554,7 @@ The rules this encodes:- **The main configuration's warning waits for the logger.** That configuration is what configures logging, so when its retry succeeds there is no logger yet — the loader parks the warning (`config_manager.take_stale_configuration_warning()`) and the boot emits it right after `log.configure`. The telemetry and service loaders run after that point and warn directly. The warning is the same either way; only *when* it is said moves.- **The inference backend loader parks its warning too, and for a different reason: a caller, not boot order.** By the time backends load, logging has been configured for a while. What that loader has instead is `pipelex doctor`, which probes the backend files by loading the whole library **once per backend** — so a loader that logged for itself would repeat one stale directory's warning a dozen times in one report. It hands the warning over instead (`take_stale_configuration_warning()`), and the caller that owes the user a copy takes it: the models-manager setup emits it exactly once per boot, the doctor's per-backend probe simply never asks, and no abstract interface widens to carry it. One warning per load, not one per backend probe.- **The warning names `pipelex migrate` only for a file the command would reach.** The retry replays whatever the loader merged, and a loader pointed at a directory of its own — an embedder's `config_dir=`, or this repository's `tests/pipelex_{run_mode}.toml` — merges files [outside the walk](#the-commands). For those the warning says the file is the caller's to update where it lives, and does not name a command that would then report nothing to do; a load that spans both gets both remedies, each on the lines of its own files. Same rule as [the remedy on a validation error](#every-surface-reports-it-the-same-way-and-none-of-them-says-start-over): *a remedy is named only where it would write*. The walk is `config_manager.existing_config_dirs`, which is also where `config_directories_to_migrate` reads it — one derivation, read from both ends, so a boot cannot promise what the command declines. Reach is per *surface*, not per path: the file must sit in the directory **its own surface** owns under one of those roots, so a `telemetry.toml` dropped into `inference/backends/` is out of reach exactly as it was before any surface owned a subdirectory.-- **The warning is a line per stale file.** Each line is a fixed message naming the file's remedy, `pipelex migrate` or an edit where the file lives, with the file in `file.path`, the titles of the ledger steps the replay carried in `migration_steps` and whether one of them is blocked in `has_blocked_steps`. The message follows the [log-call conventions](tools/logging.md#log-call-conventions): the files are values, so they ride fields rather than the text, and a list of paths in one field would be cut short on the console, which writes each field on one line at a fixed width. Everything on the line but the path is ledger text; nothing read from the user's file reaches it.+- **The warning is a line per stale file.** Each line is the same fixed message, `A configuration file is out of date and was migrated in memory only`, with the file's remedy, `pipelex migrate` or an edit where the file lives, as its advice in `user_action`, the file in `file.path`, the titles of the ledger steps the replay carried in `migration_steps` and whether one of them is blocked in `has_blocked_steps`. The message follows the [log-call conventions](tools/logging.md#log-call-conventions): the files are values, so they ride fields rather than the text, and a list of paths in one field would be cut short on the console, which writes each field on one line at a fixed width. Everything on the line but the path is ledger text; nothing read from the user's file reaches it.- **The healthy path is untouched.** The replay runs only on the failure path, so a current configuration never reads a ledger, never re-parses a document, and never even imports the migration engine. (Not "never loads tomlkit": the ordinary configuration read has always imported it. What a healthy boot avoids is the second, DOM-level read.) Replay neutrality is what makes the retry free when it does run.- **One shared helper**, called by each configuration-surface loader — and that helper is also where `[meta] schema_version` is stripped. The strip belongs there and **not** in the generic TOML reader, which also reads `.mthds` files, backend definitions and the kit index, none of which reserve that key.diff --git a/docs/tools/logging.md b/docs/tools/logging.mdindex 726f44362..6506b4e46 100644--- a/docs/tools/logging.md+++ b/docs/tools/logging.md@@ -202,7 +202,7 @@ pipelex-pipe_operators-pipe_llm = "DEBUG"httpx = "WARNING"```-The record's `pathname`, `lineno` and `funcName` point at the calling line, which is what the `console` sink links to 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.+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.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).@@ -223,10 +223,10 @@ log.error("Expected list[int], got [red]str[/red]")``````text-ERROR 🧠: Expected list[int], got [red]str[/red]+ERROR Expected list[int], got [red]str[/red]```-A tag-shaped span in a message is text like any other: a `list[int]` in a type complaint, a bracketed path, the `[cycle]` marker in the rendering of a circular content, and the `[name]: ` prefix the console puts before a line from a logger with no emoji, such as `[myapp.jobs.nightly]: `. Colour is the console's own: it styles the [fields after the message](#fields-after-the-message) by their names and draws the few [layouts](#layouts), so a call is coloured by naming its fields, never by writing markup into its message. No sink but the console has ever read markup, so a message carrying a tag would reach the `json`, `otlp` and `gcp` sinks with the tag in it, and the rule for a Pipelex log call is to write none. Two checks hold the calls to it, by one reading of what a tag is: a tag Rich would apply as styling, a closing tag, an `@` handler, or a tag naming a style, `[bold]` or `[link=https://pipelex.com]`. A bracketed word that names no style, `list[int]` or `[openai]`, passes, since it prints as written. The [log-call guard](../contribute/log-calls.md), `make check-log-calls`, reads the source of every call: it refuses such a tag in the literal text of a message, its title or its inline title, at every level, that text folded across concatenations and named literals the way it reaches the console. A test checks the messages of one run: it runs the pipes of one test bundle live, a sequence nesting a structuring step, parallel summaries and a condition, with a stand-in worker answering every model call, and fails on any message the run logs, at any level, that holds such a tag, whatever built it. A message the guard cannot read, a value built at run time, is covered only when that run logs it.+A tag-shaped span in a message is text like any other: a `list[int]` in a type complaint, a bracketed path, the `[cycle]` marker in the rendering of a circular content. Colour is the console's own: it styles the [fields after the message](#fields-after-the-message) by their names and draws the few [layouts](#layouts), so a call is coloured by naming its fields, never by writing markup into its message. No sink but the console has ever read markup, so a message carrying a tag would reach the `json`, `otlp` and `gcp` sinks with the tag in it, and the rule for a Pipelex log call is to write none. Two checks hold the calls to it, by one reading of what a tag is: a tag Rich would apply as styling, a closing tag, an `@` handler, or a tag naming a style, `[bold]` or `[link=https://pipelex.com]`. A bracketed word that names no style, `list[int]` or `[openai]`, passes, since it prints as written. The [log-call guard](../contribute/log-calls.md), `make check-log-calls`, reads the source of every call: it refuses such a tag in the literal text of a message, its title or its inline title, at every level, that text folded across concatenations and named literals the way it reaches the console. A test checks the messages of one run: it runs the pipes of one test bundle live, a sequence nesting a structuring step, parallel summaries and a condition, with a stand-in worker answering every model call, and fails on any message the run logs, at any level, that holds such a tag, whatever built it. A message the guard cannot read, a value built at run time, is covered only when that run logs it.Rich still honours its own per-record `markup` attribute, which a third-party library may set on a record it logs to ask for markup. No Pipelex call can set it: a field of that name is [reserved](#names-that-are-not-yours-to-give) and lands under `field_markup`.@@ -239,15 +239,43 @@ log.info("Scanned the inputs", fields={"file_count": 7, "source": "inbox/march"}``````text-INFO 🧠: Scanned the inputs file_count=7 source=inbox/march+INFO Scanned the inputs file_count=7 source=inbox/march```-- **What is shown.** The fields the call attached, in the order it gave them, under the name each landed on (`field_name` for a field called `name`). The run identifiers (`request_id`, `pipeline_run_id`, `pipe_run_id`) are left out, since they are the same on every line of a run and would drown the message, and so is `data`, the structured content the message already renders. Nothing else on the record is shown: neither the stdlib's own attributes, nor Pipelex's marks, nor what a record factory or a third-party library stamped on it.+- **What is shown.** The fields the call attached, in the order it gave them, under the name each landed on (`field_name` for a field called `name`). The run identifiers (`request_id`, `pipeline_run_id`, `pipe_run_id`) are left out, since they are the same on every line of a run and would drown the message, and so is `data`, the structured content the message already renders, while `user_action` prints on a line of its own ([The advice under the line](#the-advice-under-the-line)). Nothing else on the record is shown: neither the stdlib's own attributes, nor Pipelex's marks, nor what a record factory or a third-party library stamped on it.- **How a value is written.** On one line: a string as itself, a number, a boolean, `None`, a mapping, a list or a pydantic model as compact JSON, and anything else as its text. That text is written bare, or quoted when it is empty or holds a space, an `=`, a `"`, a `\` or a character a terminal would act on. Inside the quotes a backslash is written `\\`, a quote `\"` and any character a terminal would act on as its escape (`"line\nbreak"`), so `fields={"a": "b=c"}` prints `a="b=c"` rather than a second pair. A number, a boolean and `None` print bare (`7`, `true`, `null`), and so does a list of numbers (`[1,2]`), while a JSON rendering holding a string holds a quote and is quoted like a string: `["a","b"]` prints `"[\"a\",\"b\"]"`. A value longer than 80 characters is cut short and ends with `…`, its text, a string's or a JSON rendering's, being cut before it is quoted and escaped, so a quoted value keeps both its quotes, no escape is split, and no unbalanced quote or bracket is left whose tail could read as a pair of its own, except `error.message`, a handled exception's text, which is cut only past 2000 characters, quoted and escaped the same way: its diagnosis, a cause chain or a parse error's location, is what a fragment would lose, while a dependency's raw output, a validation error's every line or git's stderr, would flood the terminal uncut. `finding_message`, the text of a PipeDocGen template finding, gets the same generous cut, being the part of its warning a reader acts on. A path is cut at its start instead and begins with `…`, so the file's name stays on the line while the directory every line of a run shares goes. A field is taken for a path by its name: one ending in `.path`, `_path`, `_paths`, `_dir`, `_dirs`, `_file` or `_files`, such as `file.path`, `root_path`, `override_paths`, `library_dirs` or `template_file`, and `file.name` and `storage_key`, whose ends are a file's name too. A list of paths is cut the same way, its JSON rendering at its start before it is quoted, so the last path's file name stays and the cut list is still one quoted value: `override_paths="…/.pipelex/inference/backends_override.toml\"]"`. A path that is not on disk, `url.path` or a `variable_path`, is cut at its start as well, its end being what tells it apart. These cuts are the console's alone: every other sink writes each value whole. A key is written the same way, so a field whose name holds a line break, a space, an `=` or an escape sequence is quoted and escaped rather than forging a line or a second pair: `fields={"x=1": 2}` prints `"x=1"=2`. The [redaction](#redaction) has run before the console renders, so a secret is already `[REDACTED]`.- **Never markup.** The suffix is built as styled Rich `Text`, not as a markup string, so a value carrying `[red]x[/red]` prints exactly that.There is no setting to hide the suffix: it carries the values a message used to interpolate, so hiding it would hide what the line is about.+### The advice under the line++A record's advice, its `user_action` field, is not written in the suffix: the console prints it whole on a line of its own under the record, after `→`, in cyan, since it is the part of the record a reader acts on. A traceback the record carries prints under the advice.++```python+log.warning(+ "A configuration file is out of date and was migrated in memory only",+ fields={"file.path": "/home/me/project/.pipelex/pipelex.toml", "user_action": "Run pipelex migrate to update it"},+)+```++```text+WARNING A configuration file is out of date and was migrated in memory only file.path=/home/me/project/.pipelex/pipelex.toml+ → Run pipelex migrate to update it+```++Every other sink writes `user_action` as the field it is, so a log store can count the events by their message whatever advice each one gave.++### Another library's lines++A line has no prefix when its logger's top-level package is `pipelex` or starts with `pipelex_`, which covers the runtime, the API server's `pipelex_api` and a plugin whose package is named that way, and none when it was logged on the root logger. A line another library logged, an HTTP client's or a provider SDK's, starts with the top-level package of its logger, dimmed, so the reader still sees which library spoke:++```text+INFO httpx: HTTP Request: POST https://api.example.com/v1/chat/completions "HTTP/1.1 200 OK"+```++Your own application's lines, logged through `log` from a module of `myapp`, start with `myapp: ` the same way. The package name is styled text the console adds, never part of the message, so no other sink writes it: they carry the logger's full name as the record's own.+### The style mapA field's value is coloured by the field's name, wherever it appears, from one table in `pipelex/tools/log/console_fields.py` (`FIELD_STYLES`): a pipe code red, a concept (`output_concept`, `concept_ref`, `concept_code`) bold green, a pipe type white, a stuff name cyan and a domain bold magenta, the colours the pipe announcement and the stuff renderings have always used. A field outside the map, and every key, is dimmed. The colour follows the name the field was given, so a `pipe_code` that landed on `field_pipe_code` because a record factory owns `pipe_code` is still red. So a call is coloured by naming its fields, never by writing markup into its message. The map lives in code, with no configuration key; extending it is a one-line change beside the sink.@@ -267,12 +295,12 @@ log.info(``````text-INFO 🧠: ↳ PipeCompose: compose_company → Company+INFO ↳ PipeCompose: compose_company → Company```-- **The console renders the layout in place of the message**, after the logger's emoji, and every other sink ignores it: the `json`, `otlp` and `gcp` sinks write the plain message, `Pipe run starts`, and the fields, and never the layout's name, which rides the record under a reserved mark. The name is explicit at the call, so rewording the message cannot lose the layout, and it is a `LogLayout` member, so a misspelt one is a type error.+- **The console renders the layout in place of the message**, and every other sink ignores it: the `json`, `otlp` and `gcp` sinks write the plain message, `Pipe run starts`, and the fields, and never the layout's name, which rides the record under a reserved mark. The name is explicit at the call, so rewording the message cannot lose the layout, and it is a `LogLayout` member, so a misspelt one is a type error.- **Every value is escaped** with Rich's own escape before it is substituted, the values the layout derives included, so a field carrying `[red]x[/red]` prints literally. A value is written on one line and cut short past 80 characters, as in the suffix, except that it is never quoted, a string or a JSON rendering alike.-- **The fields a layout presents are not repeated after it**; any other field the call gave still follows as the suffix, and the run identifiers stay hidden.+- **The fields a layout presents are not repeated after it**; any other field the call gave still follows as the suffix, the advice still prints under the line, and the run identifiers stay hidden.- **A layout that cannot be filled costs nothing but itself.** A field it needs is missing, a value its derivation refuses, or anything else the layout raises: the console falls back to the message and shows every field after it.- **A layout is for a string message.** A call whose content is anything else, a mapping, a list or a model, keeps its layout off the record, and the console renders its message: the message is the only place that content renders, since the suffix never repeats `data`, and a content JSON refuses, a circular one for instance, lives only in the message's `repr`. A record whose [redaction](#redaction) failed loses its layout too, so the notice saying the scrub failed is what prints.- **A layout replaces the whole message.** A line rendered through a layout shows neither the title nor the inline text the call gave, nor any [caller information](#caller-information), all of which belong to the message it replaces. A traceback the record carries still prints under the line, as it does under a message, and the fields stay on the line above it, whether Rich renders the traceback or `is_rich_tracebacks = false` has it printed as plain text.@@ -290,18 +318,8 @@ A layout is a `ConsoleLayout`: a `template` of Rich markup whose placeholders ar### Rich Formatting- Color coding and syntax highlighting for JSON and other data structures-- Clickable file paths pointing at the calling line- Word wrapping for better readability--### Emoji Support--Built-in emoji indicators for different components, keyed on the logger name's prefix:--- 🧠 Pipelex core messages-- ⚪️ OpenAI-related logs-- 🌀 Google-related logs-- ⚡️ Network connections-- *️⃣ JSON processing+- A column naming the source file and line of each record, at the right of the line, when `is_show_path` is on; it is off by default, since it takes about 25 characters of every line and makes a long one wrap. With `is_link_path_enabled`, that path is clickable where the terminal supports links (see [Logging Configuration](../configuration/config-practical/logging-config.md#display-options))### Caller Information@@ -348,8 +366,8 @@ A handle names one model per model type, so a query groups by `gen_ai.operation.Rates are per million tokens, so a call billed by the request or by the page records each unit as a million tokens in and out, and the rate table prices one unit: a Linkup search or fetch is one request, and an extraction whose provider reports no usage is priced by its pages. Its usage says so in its `pricing_unit`, `request` or `page` rather than `token`, and the event carries the call's cost and no token counts, since a request or a page is not a token. A worker records such a usage with `record_unit_priced_usage` (`pipelex.cogt.usage.usage_cost`), a plugin's worker as much as a provider's, and never writes the counts itself.```text-INFO 🧠: claude-5.5-sonnet chat · 2,048 → 512 tokens · $0.009216 · done in 1.23 s-INFO 🧠: claude-5.5-sonnet chat · failed after 2.40 s error.type=LLMCompletionError+INFO claude-5.5-sonnet chat · 2,048 → 512 tokens · $0.009216 · done in 1.23 s+INFO claude-5.5-sonnet chat · failed after 2.40 s error.type=LLMCompletionError``````json@@ -371,11 +389,11 @@ Every live pipe run ends with `Pipe run ends`, on the logger `pipelex.pipe_machi| `duration_ms`, `outcome`, `error.type` | | As above |```text-INFO 🧠: PipeSequence: brief_company → Text-INFO 🧠: ↳ PipeLLM: describe_company → Text-INFO 🧠: claude-5.5-sonnet chat · 1,000 → 200 tokens · $0.004 · done in 1.23 s-INFO 🧠: ↳ PipeLLM: describe_company done in 1.25 s-INFO 🧠: PipeSequence: brief_company done in 1.31 s+INFO PipeSequence: brief_company → Text+INFO ↳ PipeLLM: describe_company → Text+INFO claude-5.5-sonnet chat · 1,000 → 200 tokens · $0.004 · done in 1.23 s+INFO ↳ PipeLLM: describe_company done in 1.25 s+INFO PipeSequence: brief_company done in 1.31 s``````json@@ -404,7 +422,7 @@ A test runs a small method live, with stand-in workers answering every model cal## Log-call conventions-Pipelex's own log calls, in `pipelex/` and in the API server's `api/pipelex_api/`, follow these conventions, so that a line written today can be grouped, counted and filtered in a log store tomorrow. The [log-call guard](../contribute/log-calls.md), `make check-log-calls`, holds every call to the ones that can be read off the source, the fixed message at INFO and above and the absence of markup; the rest is for review. Code of your own that logs through `log` is welcome to follow them too.+Pipelex's own log calls, in `pipelex/` and in the API server's `api/pipelex_api/`, follow these conventions, so that a line written today can be grouped, counted and filtered in a log store tomorrow. The [log-call guard](../contribute/log-calls.md), `make check-log-calls`, holds every call to the ones that can be read off the source: the fixed message at INFO and above, the absence of markup, the mechanical rules of [wording a message](#wording-a-message), and no handled exception spliced into the text; the rest is for review. Code of your own that logs through `log` is welcome to follow them too.### A fixed message@@ -423,6 +441,31 @@ log.warning()```+### Wording a message++A message says what happened, and how it was handled when that matters, in one short sentence a reader takes in at a glance. The [log-call guard](../contribute/log-calls.md) holds every call to the rules below that can be read off the source, a capital, no trailing period and no backtick at every level, no identifier and at most 80 characters at INFO and above; the rest is for review.++- **One shape.** The subject comes first, then what happened to it, in the past tense or as a state: "A pipe of a dependency could not be loaded", "The routing profiles were read with override files merged over the base", "A stuff name starts with an underscore". A failure is "could not be", never "Failed to". The [summary events](#summary-events) and the pipe-run announcement keep their present-tense names, `Inference call ends`, `Pipe run ends` and `Pipe run starts`, which name events rather than tell what happened.+- **Short.** At INFO and above a message holds at most 80 characters, so the line, its fields included, mostly stays on one line of a terminal. A consequence the reader needs goes in the sentence when it fits, "A model waterfall that leads back to itself resolves to no model", and the rest in fields; a second clause after "so" or ";" is a sign the sentence carries two things.+- **Advice in `user_action`.** What the reader should do rides in the `user_action` field, one imperative sentence written like a message, a command included as plain text: `fields={"user_action": "Run pipelex migrate to update it"}`. One event with several remedies is then one message with several `user_action` values, so a log store counts the event once whatever the cause. The console prints the advice on a line of its own under the record ([The advice under the line](#the-advice-under-the-line)), and every other sink writes it as a field. Pipelex's error reports carry their advice under the same name.+- **No identifier and no backtick.** A message is written for the person reading the log, not for the code: no snake_case name, no call, no `needs_inference=False`, no backticks. What the reader needs of an identifier is a field's value: an environment variable's name rides in `env_var`, a job's class in `inference_job_type`. A word of Pipelex's own vocabulary, a pipe type such as `PipeBatch` or a file such as `METHODS.toml`, is a word like any other.+- **A capital, no period, no prefix.** A message starts with a capital letter and ends with no period and no `...`, and carries no subsystem tag such as `OTel:`, since the logger's name already says where a line comes from.+- **DEBUG and VERBOSE follow the same wording**, beside the f-strings they may keep, and one thing has one verb: a client that is made is "Made" on every line, never "Init" on one and "Initializing" on the next.++```python+# Not this: the event, its consequence and the remedy in one sentence of 137 characters+log.warning(+ "A method reference pins a tag the installed copy was not fetched at, so the installed copy is used; removing it re-fetches the pinned tag",+ fields={"method_ref": method_ref, "installed_tag": installed_tag},+)++# This: what happened in one sentence, the remedy in user_action+log.warning(+ "A method's installed copy was used though not fetched at the pinned tag",+ fields={"method_ref": method_ref, "installed_tag": installed_tag, "user_action": "Remove the installed copy to fetch the pinned tag"},+)+```+### Values in fieldsWhat 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.@@ -504,12 +547,14 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventio| `env_var` | string | The name of an environment variable, never its value || `default_value` | integer | The value a setting falls back to when its environment variable holds none it can use || `auth_mode` | string | The authentication mode the API server's `AUTH_MODE` names |+| `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_domain` | string | Who fixes a failure, as an error report classifies it: `input`, `config`, `runtime` || `error_category` | string | A failure's Pipelex classification, as an error report carries it || `retryable` | boolean | Whether retrying the failed call as it was can help, as an error report says || `detail` | string | The explanation an API error response gives its caller |+| `user_action` | string | What the reader of a line should do about it, one imperative sentence: `Run pipelex migrate to update it`. The console prints it on a line of its own under the record, as [The advice under the line](#the-advice-under-the-line) shows || `provider_status_code` | integer | The HTTP status an inference provider answered a failed call with || `provider_request_id` | string | The id an inference provider gave a failed call |@@ -517,7 +562,7 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventio### Exceptions-An exception rides the record, never the message. Spliced into the text, `{exc}` makes the message vary, loses the exception's type and traceback, and gets only the pattern half of the [redaction](#redaction), where a field also has its control characters escaped. So:+An exception rides the record, never the message, at every level, DEBUG and VERBOSE included, as the [log-call guard](../contribute/log-calls.md#no-exception-in-the-text) holds every call to. Spliced into the text, `{exc}` makes the message vary, loses the exception's type and traceback, and gets only the pattern half of the [redaction](#redaction), where a field also has its control characters escaped. So:- **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.@@ -532,7 +577,7 @@ An exception rides the record, never the message. Spliced into the text, `{exc}`- **No run identifier in the text.** `request_id`, `pipeline_run_id` and `pipe_run_id` are stamped on every record by the [run-scoped context](#the-run-scoped-context); a message repeating one is noise, and a field passing one is only for a call that speaks about a run it is not running under.- **No payload contents, at any level.** No prompt text, no base64 data, no raw response and no whole object: a size, a count, a hash or a code instead, as the [level table](#log-levels) already says of every level.-- **No markup and no emoji in a message.** Colour is the console sink's job: it colours a value by its field's name and draws the few [layouts](#layouts), and its emoji are its own per-logger decoration. Markup in a message travels to every sink as literal tags, the console's included, since it reads no message as markup (see [Messages are plain text](#messages-are-plain-text)). Markup keeps its place in the CLI's own output and in the pretty-print channel, which are presentation to a person and not log records.+- **No markup and no emoji in a message.** Colour is the console sink's job: it colours a value by its field's name and draws the few [layouts](#layouts). Markup in a message travels to every sink as literal tags, the console's included, since it reads no message as markup (see [Messages are plain text](#messages-are-plain-text)). Markup keeps its place in the CLI's own output and in the pretty-print channel, which are presentation to a person and not log records.### Choosing a leveldiff --git a/docs/under-the-hood/log-sink-plugins.md b/docs/under-the-hood/log-sink-plugins.mdindex 1c40a4a04..3c9d207a1 100644--- a/docs/under-the-hood/log-sink-plugins.md+++ b/docs/under-the-hood/log-sink-plugins.md@@ -130,7 +130,7 @@ class LogSinkPlugin:| Sink | What it does | Where it reads its settings ||------|--------------|-----------------------------|| `json` | One JSON object per line on the configured stream: `time`, `severity`, `logger`, `message`, `exception` when there is one, `trace_id`, `span_id` and `trace_flags` in hex when OpenTelemetry's current span names a trace, under the keys OpenTelemetry specifies for trace context in a JSON log that is not OTLP, `pipelex.trace_id` and `pipelex.span_id` in hex when a Pipelex span is active, then the fields, the context identifiers and `data` flat beside them, a field named like one of those keys under a `field_` prefix on every line, a non-finite float as the string `"NaN"`, `"Infinity"` or `"-Infinity"`. The key names are the ones the CloudWatch agent, the Google Cloud Logging agent and any OTLP collector ingest without a parser, and no ANSI ever. What the hosted plane's runner and worker select. | `console_log_target` |-| `console` | The Rich handler with the emoji formatter and every `[runtime.log.rich_log]` setting, which reads no message as markup, shows a record's fields after its message, coloured by name, and renders the layouts a call names (see [Console rendering](../tools/logging.md#console-rendering)). Rich, the `cli` extra, is imported when the handler is built, and a process that selects another sink never loads it through this path. | `console_log_target`, `[runtime.log.rich_log]` |+| `console` | The Rich handler with every `[runtime.log.rich_log]` setting, which reads no message as markup, shows a record's fields after its message, coloured by name, starts a line another library logged with that library's top-level package name, dimmed, and renders the layouts a call names (see [Console rendering](../tools/logging.md#console-rendering)). The column naming each record's source file is off unless `is_show_path` turns it on. Rich, the `cli` extra, is imported when the handler is built, and a process that selects another sink never loads it through this path. | `console_log_target`, `[runtime.log.rich_log]` || `otlp` | The OpenTelemetry logs signal: a `LoggerProvider` carrying the same service identity as the tracer, a `BatchLogRecordProcessor` and the OTLP HTTP log exporter. The message is the body, the level maps onto the OTel severity scale, the fields, identifiers and `data` ride as attributes (a mapping as JSON text), an exception lands under the `exception.*` semantic-convention keys, each record is filed under OpenTelemetry's current span, with the active Pipelex span as the `pipelex.trace_id` and `pipelex.span_id` attributes, and a collector receives the logs beside the spans the runtime already exports. The keys the sink writes itself, the `code.*` source location, the two `pipelex.*` keys and the `exception.*` set, are reserved on every record whether or not it carries an exception, so a field named like one of them rides under a `field_` prefix rather than being overwritten. A filter on the handler rejects the records of the sink's own export path, the SDK's by logger name and the transport's by the context value the SDK sets around an export, before the handler's lock is taken, so an export failure never re-enters the pipeline and a shutdown never waits on itself. | `[runtime.log.otlp]` || `gcp` | Google Cloud Logging through the `google-cloud-logging` client library, behind the `gcp-logging` extra. Each record becomes one struct entry: the level maps onto the Cloud Logging severity scale (which has nothing below `DEBUG`, so `VERBOSE` lands there), the message, the logger, the exception and the fields become the JSON payload, the run-scoped identifiers become the entry's labels, which is what Cloud Logging indexes, the entry's `trace`, `spanId` and `traceSampled` name OpenTelemetry's current span, the trace project-qualified, and the active Pipelex span rides in the payload as `pipelex.trace_id` and `pipelex.span_id`. The entries leave through the client library's background-thread transport, which batches them off the calling thread. The factory refreshes the credentials once before that transport starts, so credentials Google refuses stop the boot with `GcpLogSinkCredentialsError` rather than losing every record in silence. **Most processes on Google Cloud want `json` instead**: a platform whose logging agent reads the container's stdout, Cloud Run and GKE among them, ingests what that sink writes and needs no client at all; `gcp` is for a process with no such agent in front of it, or one writing to a log or a project that is not the ambient one. | `[runtime.log.gcp]` |@@ -138,7 +138,7 @@ The `otlp` factory imports the OpenTelemetry logs SDK when it runs, and the `gcp### Why `console` is the default-`pipelex/pipelex.toml` ships `sink = "console"`. A user who installs the CLI expects the rendering the CLI always had, the emoji, the colours, the clickable paths, and a default that changed it would be a regression for every terminal. A server is the process that must choose, and it chooses in its own configuration: it selects `json` in its `pipelex.toml`, as the [API server](../api-server/logging.md) does. Nothing at boot catches a server that forgot. The `console` factory checks that Rich imports, and stops the boot naming the `cli` extra and the `json` alternative when it does not, but Rich is installed with or without the extra, because `typer` and `instructor`, both core dependencies, require it unconditionally. So a server that forgot to select `json` boots on the `console` sink and ships ANSI to its log agent. A host whose log pipeline depends on JSON asserts the effective sink at boot itself, after every configuration layer is merged, as our Temporal plugin does. How the rest of the runtime keeps Rich off a server's path, and why that is not the same as keeping it out of the install, is in [Rich Imports](../contribute/rich-imports.md).+`pipelex/pipelex.toml` ships `sink = "console"`. A user who installs the CLI reads its logs in a terminal and expects them rendered for one: the level, the fields after each message coloured by name, the advice on a line of its own and the pipe-run tree. A default that wrote JSON objects instead would hand every terminal a stream meant for a log store. A server is the process that must choose, and it chooses in its own configuration: it selects `json` in its `pipelex.toml`, as the [API server](../api-server/logging.md) does. Nothing at boot catches a server that forgot. The `console` factory checks that Rich imports, and stops the boot naming the `cli` extra and the `json` alternative when it does not, but Rich is installed with or without the extra, because `typer` and `instructor`, both core dependencies, require it unconditionally. So a server that forgot to select `json` boots on the `console` sink and ships ANSI to its log agent. A host whose log pipeline depends on JSON asserts the effective sink at boot itself, after every configuration layer is merged, as our Temporal plugin does. How the rest of the runtime keeps Rich off a server's path, and why that is not the same as keeping it out of the install, is in [Rich Imports](../contribute/rich-imports.md).---diff --git a/drift.toml b/drift.tomlindex d0962ee67..ccf7233cb 100644--- a/drift.toml+++ b/drift.toml@@ -141,14 +141,18 @@ review = [verify_commands = [][contracts.logging-docs]-description = "The logging doc restates the console's field rules and the handled-exception fields and must track the two modules that decide them."+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# 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# those sets, or a length moved, silently falsifies a sentence quantifying over it, which is the-# staleness this contract exists to catch. The field-vocabulary table on the same page stays+# 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+# both passages name what a terminal shows of a record, the fields after the message, their+# colours and the advice line, so a change to what the console renders is reviewed there too, not+# only on the logging page it links to. The field-vocabulary table on the logging page stays# outside any contract on purpose: its entries come from call sites everywhere, which no trigger# list could name, and a field joins the table in the change that first logs it. No verify# command: no gate checks these rules apart from the modules' own tests, which `make agent-test`@@ -159,5 +163,6 @@ triggers = []review = ["docs/tools/logging.md",+ "docs/under-the-hood/log-sink-plugins.md",]verify_commands = []diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.pyindex 64995a638..4f11b537d 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py@@ -169,7 +169,7 @@ async def run_pipeline_core(cost_summary = CostRegistry.build_cost_summary(tokens_usages=pipe_output.tokens_usages)except PipelexError as cost_summary_error:log.warning(- "The run succeeded but its cost summary could not be built, so the output carries no cost report",+ "The cost summary of a successful run could not be built",fields=error_fields(exc=cost_summary_error),)else:diff --git a/pipelex/cli/commands/graph_cmd.py b/pipelex/cli/commands/graph_cmd.pyindex 1ffd1aa73..d215ad2b6 100644--- a/pipelex/cli/commands/graph_cmd.py+++ b/pipelex/cli/commands/graph_cmd.py@@ -200,7 +200,7 @@ def graph_render_cmd(# would write. No sink reads a log message as markup, so the fields hold the text as written; the# console print below does read markup, and a path may hold brackets, so it prints the text escaped.log.error(- "The graph spec was refused, so no graph was rendered", fields={OTelLogAttr.FILE_PATH: str(input_file), **error_fields(exc=spec_error)}+ "The graph spec was refused and no graph was rendered", fields={OTelLogAttr.FILE_PATH: str(input_file), **error_fields(exc=spec_error)})console = get_console()console.print(f"\n[bold red]Failed to render graph[/bold red]\n\n{escape(str(spec_error))}\n")diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.pyindex 04a1a06f1..0cc3543c7 100644--- a/pipelex/cli/commands/init/backends.py+++ b/pipelex/cli/commands/init/backends.py@@ -22,6 +22,7 @@ from pipelex.cli.commands.init.ui.backends_ui import (from pipelex.kit.paths import get_kit_configs_dirfrom pipelex.runtime_hub import get_consolefrom pipelex.system.configuration.config_loader import config_manager+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_with_tomlkit, save_toml_to_path@@ -118,7 +119,7 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confisuggest_extension_install_if_needed(console=console)except EOFError as exc:# No stdin available for the install prompt — skip the optional IDE extension suggestion.- log.debug(f"IDE extension suggestion skipped: {exc}")+ log.debug("The IDE extension suggestion was skipped, since no input could answer it", fields=error_fields(exc=exc))# Business logic: Update and save backends.toml first (local operation)update_backends_in_toml(toml_doc, selected_indices=selected_indices, backend_options=backend_options)diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.pyindex f5cbca22f..7282c6937 100644--- a/pipelex/cli/commands/init/command.py+++ b/pipelex/cli/commands/init/command.py@@ -61,6 +61,7 @@ from pipelex.migration.former_release import (from pipelex.runtime_hub import get_consolefrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME+from pipelex.tools.log.error_fields import error_fields#: The focuses whose run asks where runs execute when it sets up inference: the full setup, and a first setup reached#: through `config`. `inference` configures this machine's backends on purpose and leaves the setting as it is.@@ -481,7 +482,7 @@ def _suggest_extension(*, console: Console) -> None:suggest_extension_install_if_needed(console=console)except EOFError as exc:# No stdin available for the install prompt — skip the optional IDE extension suggestion.- log.debug(f"IDE extension suggestion skipped: {exc}")+ log.debug("The IDE extension suggestion was skipped, since no input could answer it", fields=error_fields(exc=exc))def execute_initialization(*, console: Console, inspection: InitInspection, choices: InitChoices) -> None:diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.pyindex c1f1a2897..c1a9a6d91 100644--- a/pipelex/cli/dev_cli/_dev_cli.py+++ b/pipelex/cli/dev_cli/_dev_cli.py@@ -425,7 +425,10 @@ def check_rich_imports_command(sys.exit(1)[email protected](name="check-log-calls", help="Refuse an interpolated log message at INFO and above, and Rich markup in any log message")+ name="check-log-calls",+ help="Refuse an interpolated log message at INFO and above, Rich markup, a message worded against the conventions, and a spliced exception",+)def check_log_calls_command(prune: Annotated[bool,diff --git a/pipelex/cli/dev_cli/commands/log_call_guard.py b/pipelex/cli/dev_cli/commands/log_call_guard.pyindex f763d3d44..6459fc9d2 100644--- a/pipelex/cli/dev_cli/commands/log_call_guard.py+++ b/pipelex/cli/dev_cli/commands/log_call_guard.py@@ -18,25 +18,41 @@ and in the ``api/`` member's ``api/pipelex_api/``:(``[red]``, ``[bold green]``, ``[link=https://…]``) or as one of its theme's style names. The text is read the wayit reaches the console: a ``+`` of literals, named ones included, is folded into one text before it is scanned. Abracketed word that is no style, ``list[int]``, is text and passes. A tag escaped with a backslash passes.--The title and the inline title join the message (the dispatch renders them into it), so both rules read them too,-and a title or an inline title that is statically ``None`` is no text at all. A ``**`` expansion of a dict literal-with string keys passes its entries as keywords; any other ``**`` expansion could carry the message, so it is refused-as ``non-literal`` at every level. DEBUG and VERBOSE may keep an f-string; the markup rule holds there as everywhere.+3. **The wording rules.** At every level, a message starts with no lowercase letter (``lowercase-start``), ends with+ no period and no ellipsis (``trailing-period``) and holds no backtick (``backtick``); at INFO and above it also+ names no identifier, a word holding an underscore or a call written ``name()`` (``identifier``), and holds at most+ ``MAX_MESSAGE_LENGTH`` characters (``length``). They read the texts the markup rule reads, each text a message can+ reach the console as, and one text that breaks a rule is enough: a conditional between a good and a bad literal+ breaks it. A text that starts or ends with a value the guard cannot read passes the rule about that end, and the+ length counts a text's literal parts alone, the least it can hold once its values are spliced in.+4. **The exception rule, at every level** (``spliced-exception``). No value a message splices into its text reaches+ a handled exception: an f-string's placeholder, a value a ``%`` or a ``.format()`` formats, or any part of the+ message that is no literal text, the message itself included. A value reaches one when it calls a+ ``.exception()`` method, or reads a name bound by ``except ... as``, directly or through the bindings of the names+ it reads (``detail = str(exc)``), a captured name included.++The title and the inline title join the message (the dispatch renders them into it), so every rule reads them too,+each as a text of its own, and a title or an inline title that is statically ``None`` is no text at all. A ``**``+expansion of a dict literal with string keys passes its entries as keywords; any other ``**`` expansion could carry+the message, so it is refused as ``non-literal`` at every level. DEBUG and VERBOSE may keep an f-string, a long+message and an identifier; every other rule holds there as everywhere.**Names** are read by Python's own scoping: the scope the call is made in (a comprehension reading as part of thescope it is written in), then the enclosing functions, class bodies never among them, then the module. Of a name'sbindings there, only those that can reach the read count, by the scope's control flow: the nearest alongstraight-line code, the nearest on each path through an ``if``, a ``try`` or a ``match``, those a loop's later passescarry back, and none past a ``return``, a ``raise``, a ``break`` or a ``continue``. A name bound in an enclosing-function is not followed. The facade itself is found the same way: a call's receiver is the facade where an import-of the facade reaches it. One index of every scope's bindings and flow is built per module, in one walk.+function is not followed, save by the exception rule, which reads it through every binding that function makes. The+facade itself is found the same way: a call's receiver is the facade where an import of the facade reaches it, a+captured receiver read through every binding of its function too. One index of every scope's bindings and flow is+built per module, in one walk.**The baseline.** The calls that broke the rules when the guard arrived are listed in the committed``log_call_baseline.toml`` at the repo root, under the key ``<relative_path>::<qualified_name>`` of the function thatmakes them, ``<module>`` for a module-level call, each by its signature: the method, the message's source text, the-rules the call breaks and every binding that reaches the names the guard read to judge it-(``warning: msg [f-string] where msg = f"Loaded {alias}"``), rendered the same on every supported Python. Line+rules the call breaks and every binding that reaches the names the guard read to judge it, the bindings a spliced+exception is reached through included (``warning: msg [f-string] where msg = f"Loaded {alias}"``), rendered the same+on every supported Python. Linenumbers never enter it. The comparison with the tree is exact both ways: a call the baseline does not list fails,and so does a listed signature no call matches any more, whether the call now complies, moved to another function,or had its message, a binding of it or the rules it breaks change, until its entry is removed. Changing a listed@@ -58,6 +74,7 @@ import astimport copyimport itertoolsimport json+import reimport subprocess # ruff: ignore[suspicious-subprocess-import]import tomllibfrom collections import Counter@@ -103,11 +120,15 @@ FACADE_PATHS = frozenset({"pipelex.log", "pipelex.tools.log.log.log"})FACADE_STAR_MODULES = frozenset({"pipelex", "pipelex.tools.log.log"})FACADE_NAME = "log"-#: The facade's methods at INFO and above, where a message is a literal.-INTERPOLATION_BOUND_METHODS = frozenset({"info", "warning", "error", "critical"})+#: The facade's methods at INFO and above, where a message is a literal, names no identifier and is short.+INFO_AND_ABOVE_METHODS = frozenset({"info", "warning", "error", "critical"})++#: Every method of the facade that emits a line, where a message holds no markup, keeps the wording rules that hold at+#: every level and splices no exception.+EMITTING_METHODS = frozenset({"verbose", "debug", *INFO_AND_ABOVE_METHODS})-#: Every method of the facade that emits a line, where a literal message holds no markup.-MARKUP_BOUND_METHODS = frozenset({"verbose", "debug", *INTERPOLATION_BOUND_METHODS})+#: The longest a message may be at INFO and above, in characters.+MAX_MESSAGE_LENGTH = 80#: The keyword a call may pass its message under instead of positionally.CONTENT_KEYWORD = "content"@@ -139,6 +160,12 @@ class LogCallRule(StrEnum):FORMAT_CALL = "format-call"NON_LITERAL = "non-literal"MARKUP = "markup"+ LOWERCASE_START = "lowercase-start"+ TRAILING_PERIOD = "trailing-period"+ BACKTICK = "backtick"+ IDENTIFIER = "identifier"+ LENGTH = "length"+ SPLICED_EXCEPTION = "spliced-exception"@propertydef remedy(self) -> str:@@ -149,6 +176,24 @@ class LogCallRule(StrEnum):return "write the message as a literal at the call and pass what varies in `fields=`"case LogCallRule.MARKUP:return "drop the tag: the console colours a value by its field's name, or draws a named layout"+ case LogCallRule.LOWERCASE_START:+ return "start the message with a capital letter, its subject first"+ case LogCallRule.TRAILING_PERIOD:+ return "end the message with no period and no ellipsis"+ case LogCallRule.BACKTICK:+ return "write the message as plain prose: what a backtick would quote rides in a field"+ case LogCallRule.IDENTIFIER:+ return "say it in words and carry the identifier as a field's value, an environment variable's name in `env_var` for instance"+ case LogCallRule.LENGTH:+ return (+ f"say what happened in one sentence of at most {MAX_MESSAGE_LENGTH} characters, "+ "the values in `fields=` and the advice in `user_action`"+ )+ case LogCallRule.SPLICED_EXCEPTION:+ return (+ "write a fixed message and pass the exception in `fields=` as `**error_fields(exc=...)`, "+ "or with `include_exception=True` at ERROR and above"+ )class RuleBreach(NamedTuple):@@ -799,6 +844,8 @@ class _ScopeIndex:def __init__(self, *, module: ast.Module, package: str) -> None:self.module_scope = _Scope(kind=_ScopeKind.MODULE, parent=None)self.call_scopes: dict[ast.Call, _Scope] = {}+ # The scope each name is read in, so a name met anywhere in an expression, a lambda's body included, resolves.+ self.read_scopes: dict[ast.Name, _Scope] = {}self._package = packageself._scopes: list[_Scope] = [self.module_scope]self._serials = itertools.count()@@ -1014,6 +1061,7 @@ class _ScopeIndex:scope=scope, event=_Branch(paths=(self._collected(nodes=[body], scope=scope), self._collected(nodes=[orelse], scope=scope))))case ast.Name(id=name, ctx=ast.Load()):+ self.read_scopes[node] = scopeself._emit(scope=scope, event=_Read(node=node, name=name))case ast.Name(id=name, ctx=ast.Store()):self._bind_opaque(name=name, kind=_OpaqueBinding.ASSIGNMENT_TARGET, scope=scope, lineno=node.lineno)@@ -1205,8 +1253,12 @@ class _ScopeIndex:found.update(binding for binding in location.moved_bindings.get(name, []) if binding.scope.statement_scope is not flow)return sorted(found, key=lambda binding: (binding.lineno, binding.serial))- def receiver_bindings(self, *, node: ast.Name, scope: _Scope) -> list[_Binding]:- """The bindings a call's receiver may hold where the call is made, a captured name's every binding included."""+ def possible_bindings(self, *, node: ast.Name, scope: _Scope) -> list[_Binding]:+ """The bindings a name may hold where it is read, a captured name's every binding included.++ How a call's receiver is read, and a name the exception rule follows: a name captured from an enclosing+ function may hold whatever that function binds it to.+ """reach = self.reaching(node=node, scope=scope)if not isinstance(reach, str):return reach@@ -1242,10 +1294,30 @@ _MAX_FOLDED_SHAPES = 256_Seen: TypeAlias = frozenset[_Binding]+#: The bindings a name reaches a handled exception through, as a signature writes them, the last binding the exception's.+_Route: TypeAlias = tuple[str, ...]+++class _Splice(NamedTuple):+ """A value a message splices into its text that reaches a handled exception.++ Attributes:+ source: The spliced value's source text, as the report names it.+ route: The bindings it reaches the exception through, which join the call's signature.+ """++ source: str+ route: _Route++def _folded(*, left: set[_Shape], right: set[_Shape]) -> set[_Shape]:- """The shapes of a concatenation: each left text's last run joined to each right text's first run."""+ """The shapes of a concatenation: each left text's last run joined to each right text's first run.++ Past the bound, the sides are kept apart as if a value the guard cannot read stood between them: each left text+ keeps its start and each right text its end, and no run joins across.+ """if len(left) * len(right) > _MAX_FOLDED_SHAPES:- return left | right+ return {(*left_shape, "") for left_shape in left} | {("", *right_shape) for right_shape in right}return {(*left_shape[:-1], left_shape[-1] + right_shape[0], *right_shape[1:]) for left_shape, right_shape in itertools.product(left, right)}@@ -1423,6 +1495,104 @@ class _MessageReader:return {_UNKNOWN_SHAPE}return self._name_shapes(node=binding.prior, scope=binding.scope, seen=seen)+ # ---- the spliced exceptions, for the exception rule -------------------------------++ def spliced_exceptions(self, *, expr: ast.expr, scope: _Scope, seen: _Seen) -> list[_Splice]:+ """The values a message expression splices into its text that reach a handled exception, in source order.++ The message is read the way ``shapes`` reads it, down to the values it splices: an f-string's placeholders,+ the values a ``%`` formats, the arguments of a ``.format()`` call, and any expression that is no literal+ text, the message itself included. A name is read through its bindings, a captured name through every binding+ of the function it is captured from, and a name bound by ``except ... as`` is the exception itself.+ """+ match expr:+ case ast.Constant():+ return []+ case ast.JoinedStr(values=values):+ placeholders = [value.value for value in values if isinstance(value, ast.FormattedValue)]+ return [splice for placeholder in placeholders for splice in self._splice(value=placeholder, seen=seen)]+ case ast.BinOp(op=ast.Add(), left=left, right=right):+ return [*self.spliced_exceptions(expr=left, scope=scope, seen=seen), *self.spliced_exceptions(expr=right, scope=scope, seen=seen)]+ case ast.BinOp(op=ast.Mod(), left=left, right=right):+ return [*self.spliced_exceptions(expr=left, scope=scope, seen=seen), *self._splice(value=right, seen=seen)]+ case ast.Call(func=ast.Attribute(attr="format", value=receiver), args=args, keywords=keywords):+ arguments = [*args, *(keyword.value for keyword in keywords)]+ spliced = [splice for argument in arguments for splice in self._splice(value=argument, seen=seen)]+ return [*self.spliced_exceptions(expr=receiver, scope=scope, seen=seen), *spliced]+ case ast.IfExp(body=body, orelse=orelse):+ return [*self.spliced_exceptions(expr=body, scope=scope, seen=seen), *self.spliced_exceptions(expr=orelse, scope=scope, seen=seen)]+ case ast.Name():+ return self._name_spliced_exceptions(node=expr, scope=scope, seen=seen)+ case _:+ return self._splice(value=expr, seen=seen)++ def _name_spliced_exceptions(self, *, node: ast.Name, scope: _Scope, seen: _Seen) -> list[_Splice]:+ """What a name splices through each binding it may hold, the binding leading every route it is on."""+ splices: list[_Splice] = []+ for binding in self._index.possible_bindings(node=node, scope=scope):+ if binding in seen:+ continue+ rendered = binding.render(name=node.id)+ if binding.opaque == _OpaqueBinding.EXCEPT_TARGET:+ splices.append(_Splice(source=node.id, route=(rendered,)))+ continue+ if binding.opaque is not None or binding.value is None:+ continue+ inner_seen = seen | {binding}+ found: list[_Splice] = []+ if binding.prior is not None:+ found.extend(self._name_spliced_exceptions(node=binding.prior, scope=binding.scope, seen=inner_seen))+ if binding.operator is None or isinstance(binding.operator, ast.Add):+ found.extend(self.spliced_exceptions(expr=binding.value, scope=binding.scope, seen=inner_seen))+ else:+ found.extend(self._splice(value=binding.value, seen=inner_seen))+ splices.extend(_Splice(source=splice.source, route=(rendered, *splice.route)) for splice in found)+ return splices++ def _splice(self, *, value: ast.expr, seen: _Seen) -> list[_Splice]:+ """A value spliced into a message, when it reaches a handled exception."""+ route = self._exception_route(expr=value, visited=set(seen))+ if route is None:+ return []+ return [_Splice(source=_short_source(expr=value), route=route)]++ def _exception_route(self, *, expr: ast.expr, visited: set[_Binding]) -> _Route | None:+ """The bindings through which an expression reaches a handled exception, or ``None`` when it reaches none.++ It reaches one when it calls a ``.exception()`` method, a finished task's or a retry outcome's, or reads a+ name one of whose bindings is an ``except ... as`` target or binds a value that reaches one in turn. Whether+ a binding reaches one does not depend on the way to it, so each binding is followed once.+ """+ for node in ast.walk(expr):+ match node:+ case ast.Call(func=ast.Attribute(attr="exception")):+ return ()+ case ast.Name(ctx=ast.Load()):+ scope = self._index.read_scopes.get(node)+ route = None if scope is None else self._name_exception_route(node=node, scope=scope, visited=visited)+ if route is not None:+ return route+ case _:+ pass+ return None++ def _name_exception_route(self, *, node: ast.Name, scope: _Scope, visited: set[_Binding]) -> _Route | None:+ for binding in self._index.possible_bindings(node=node, scope=scope):+ if binding in visited:+ continue+ visited.add(binding)+ rendered = binding.render(name=node.id)+ if binding.opaque == _OpaqueBinding.EXCEPT_TARGET:+ return (rendered,)+ if binding.opaque is not None or binding.value is None:+ continue+ route = self._exception_route(expr=binding.value, visited=visited)+ if route is None and binding.prior is not None:+ route = self._name_exception_route(node=binding.prior, scope=binding.scope, visited=visited)+ if route is not None:+ return (rendered, *route)+ return None+def markup_tags_of(*, shapes: Iterable[_Shape]) -> list[str]:"""The distinct markup tags the runs of these shapes hold, in a stable order."""@@ -1435,6 +1605,79 @@ def markup_tags_of(*, shapes: Iterable[_Shape]) -> list[str]:return tags+# --------------------------------------------------------------------------------------+# Wording: what the text of a message says, read off its shapes+#+# A rule about how a text starts or ends reads the first or the last run of each shape, so a text that starts or ends+# with a value the guard cannot read passes it. A rule about what a text holds reads every run, never across a value.+# The length counts a shape's runs alone, the least its text can be once its values are spliced in.+# --------------------------------------------------------------------------------------++#: The periods that end a text, an ellipsis written as three periods or as one character included.+_TRAILING_PERIOD_PATTERN = re.compile(r"[.…]+$")++#: A call written with empty parentheses, ``load()`` or ``Loader.load()``, else a word.+_IDENTIFIER_CANDIDATE_PATTERN = re.compile(r"(?:\w+\.)*\w+\(\)|\w+")+++def _lowercase_start_of(*, text: str) -> str | None:+ """The first word of a text that starts with a lowercase letter, or ``None``; leading whitespace is skipped."""+ stripped = text.lstrip()+ if not stripped or not stripped[0].islower():+ return None+ return stripped.split(maxsplit=1)[0]+++def _trailing_period_of(*, text: str) -> str | None:+ """The periods, or the ellipsis, a text ends with, or ``None``; trailing whitespace is skipped."""+ match = _TRAILING_PERIOD_PATTERN.search(text.rstrip())+ return match.group() if match else None+++def _identifiers_in(*, text: str) -> list[str]:+ """The identifiers a text holds, in order: each call written ``name()``, and each word holding an underscore."""+ identifiers: list[str] = []+ for match in _IDENTIFIER_CANDIDATE_PATTERN.finditer(text):+ token = match.group()+ if token.endswith("()") or ("_" in token and token.strip("_")):+ identifiers.append(token)+ return identifiers+++def _shape_length(*, shape: _Shape) -> int:+ return sum(len(run) for run in shape)+++def wording_breaches(*, shapes: Iterable[_Shape], part_name: str, is_info_and_above: bool) -> list[RuleBreach]:+ """The wording rules a part of a message breaks, read off every text it can reach the console as.++ At every level a text starts with no lowercase letter, ends with no period and no ellipsis, and holds no backtick;+ at INFO and above it also holds no identifier and is at most ``MAX_MESSAGE_LENGTH`` characters long. A shape+ that breaks a rule is enough: a conditional between a good and a bad literal breaks it.+ """+ ordered_shapes = sorted(shapes)+ breaches: list[RuleBreach] = []+ first_words = dict.fromkeys(word for shape in ordered_shapes if (word := _lowercase_start_of(text=shape[0])) is not None)+ breaches.extend(RuleBreach(rule=LogCallRule.LOWERCASE_START, detail=f"{part_name} starts with the lowercase `{word}`") for word in first_words)+ endings = dict.fromkeys(ending for shape in ordered_shapes if (ending := _trailing_period_of(text=shape[-1])) is not None)+ breaches.extend(RuleBreach(rule=LogCallRule.TRAILING_PERIOD, detail=f"{part_name} ends with `{ending}`") for ending in endings)+ if any("`" in run for shape in ordered_shapes for run in shape):+ breaches.append(RuleBreach(rule=LogCallRule.BACKTICK, detail=f"{part_name} holds a backtick"))+ if not is_info_and_above:+ return breaches+ identifiers = dict.fromkeys(identifier for shape in ordered_shapes for run in shape for identifier in _identifiers_in(text=run))+ for identifier in identifiers:+ kind = "call" if identifier.endswith("()") else "identifier"+ breaches.append(RuleBreach(rule=LogCallRule.IDENTIFIER, detail=f"{part_name} holds the {kind} `{identifier}`"))+ longest = max(ordered_shapes, key=lambda shape: _shape_length(shape=shape), default=None)+ if longest is not None and _shape_length(shape=longest) > MAX_MESSAGE_LENGTH:+ # A shape of several runs splices values the guard cannot read, so its literal runs are the least it holds.+ bound = "" if len(longest) == 1 else "at least "+ detail = f"{part_name} is {bound}{_shape_length(shape=longest)} characters long, more than {MAX_MESSAGE_LENGTH}"+ breaches.append(RuleBreach(rule=LogCallRule.LENGTH, detail=detail))+ return breaches++# --------------------------------------------------------------------------------------# The facade# --------------------------------------------------------------------------------------@@ -1573,13 +1816,13 @@ class _LogCallCollector(ast.NodeVisitor):The receiver's name is the facade when a binding that can reach the call imports the facade, under whatevername or module path: a parameter or a local of that name, or an import made in another function, is not."""- if not isinstance(node.func, ast.Attribute) or node.func.attr not in MARKUP_BOUND_METHODS:+ if not isinstance(node.func, ast.Attribute) or node.func.attr not in EMITTING_METHODS:return Nonereceiver = _receiver_root(expr=node.func.value)if receiver is None:return Noneroot, attributes = receiver- for binding in self._index.receiver_bindings(node=root, scope=self._index.call_scopes[node]):+ for binding in self._index.possible_bindings(node=root, scope=self._index.call_scopes[node]):if binding.import_path is not None and ".".join([binding.import_path, *attributes]) in FACADE_PATHS:return node.func.attrreturn None@@ -1587,22 +1830,35 @@ class _LogCallCollector(ast.NodeVisitor):def _check_call(self, *, node: ast.Call, method: str) -> None:scope = self._index.call_scopes[node]parts, unread_expansions = message_parts_of(call=node)+ is_info_and_above = method in INFO_AND_ABOVE_METHODStrace: set[str] = set()reader = _MessageReader(index=self._index, trace=trace)- # A `**` expansion the guard cannot read may carry the message or a title, so neither rule can be checked.+ # A `**` expansion the guard cannot read may carry the message or a title, so no rule can be checked through it.breaches = [RuleBreach(rule=LogCallRule.NON_LITERAL, detail=f"`**{_short_source(expr=expansion)}` is an expansion whose keywords cannot be read")for expansion in unread_expansions]- if method in INTERPOLATION_BOUND_METHODS:+ if is_info_and_above:for label, expr in parts:form = reader.form(expr=expr, scope=scope, seen=frozenset(), allows_none=label is not None)if form is not None:breaches.append(RuleBreach(rule=form.rule, detail=f"{_part_name(label=label)} is {form.detail}"))for label, expr in parts:- for tag in markup_tags_of(shapes=reader.shapes(expr=expr, scope=scope, seen=frozenset())):- breaches.append(RuleBreach(rule=LogCallRule.MARKUP, detail=f"{_part_name(label=label)} holds the markup tag `{tag}`"))+ part_name = _part_name(label=label)+ shapes = reader.shapes(expr=expr, scope=scope, seen=frozenset())+ for tag in markup_tags_of(shapes=shapes):+ breaches.append(RuleBreach(rule=LogCallRule.MARKUP, detail=f"{part_name} holds the markup tag `{tag}`"))+ breaches.extend(wording_breaches(shapes=shapes, part_name=part_name, is_info_and_above=is_info_and_above))+ # Only the bindings a spliced exception is reached through join the trace: they are what that rule read.+ spliced_sources: list[str] = []+ for splice in reader.spliced_exceptions(expr=expr, scope=scope, seen=frozenset()):+ trace.update(splice.route)+ if splice.source not in spliced_sources:+ spliced_sources.append(splice.source)+ breaches.extend(+ RuleBreach(rule=LogCallRule.SPLICED_EXCEPTION, detail=f"{part_name} splices the exception `{source}`") for source in spliced_sources+ )if not breaches:returndiff --git a/pipelex/cogt/content_generation/generated_content_factory.py b/pipelex/cogt/content_generation/generated_content_factory.pyindex 68ab05e75..1815bbec7 100644--- a/pipelex/cogt/content_generation/generated_content_factory.py+++ b/pipelex/cogt/content_generation/generated_content_factory.py@@ -224,7 +224,7 @@ class GeneratedContentFactory:# so there is nothing to refuse and the URL is kept as it came.actual_bytes, fetched_mime_type = await self._fetch_remote_content(url=url)except RemoteFileFetchError as exc:- log.warning("A generated image could not be fetched from its remote URL, so the URL is kept as it came", fields=error_fields(exc=exc))+ log.warning("A generated image could not be fetched, and its remote URL was kept", fields=error_fields(exc=exc))public_url = urlelse:if not declared_mime_type and fetched_mime_type:diff --git a/pipelex/cogt/img_gen/img_gen_args_factory.py b/pipelex/cogt/img_gen/img_gen_args_factory.pyindex 033fefdd7..df531f76a 100644--- a/pipelex/cogt/img_gen/img_gen_args_factory.py+++ b/pipelex/cogt/img_gen/img_gen_args_factory.py@@ -37,6 +37,7 @@ from pipelex.cogt.img_gen.img_gen_model_rules import (SpecificTaxonomy,)from pipelex.config import get_config+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.misc.image_utils import ImageFormatfrom pipelex.tools.uri.prepared_file import PreparedFileBase64, PreparedFileHttpUrl@@ -269,7 +270,7 @@ class ImgGenArgsFactory:match prompt_taxonomy:case PromptTaxonomy.POSITIVE_ONLY:if negative_text:- log.warning("A negative prompt was given to an image model that takes none, so it is ignored")+ log.warning("A negative prompt given to an image model that takes none was ignored")return {"prompt": positive_text}case PromptTaxonomy.WITH_NEGATIVE:args_dict: dict[str, Any] = {"prompt": positive_text}@@ -501,8 +502,8 @@ class ImgGenArgsFactory:if num_inference_steps not in acceptable_steps:# TODO: prevent this when building presets and paramslog.warning(- "SDXL Lightning takes 1, 2, 4 or 8 inference steps, so the requested number is replaced by 4",- fields={"nb_steps": num_inference_steps},+ "An unsupported number of inference steps for SDXL Lightning was replaced by 4",+ fields={"nb_steps": num_inference_steps, USER_ACTION_FIELD: "Request 1, 2, 4 or 8 inference steps"},)num_inference_steps = 4else:diff --git a/pipelex/cogt/img_gen/img_gen_gpt_mapping.py b/pipelex/cogt/img_gen/img_gen_gpt_mapping.pyindex c2da2a8a7..4b3b7125d 100644--- a/pipelex/cogt/img_gen/img_gen_gpt_mapping.py+++ b/pipelex/cogt/img_gen/img_gen_gpt_mapping.py@@ -189,7 +189,7 @@ class ImgGenGptMapping:# A tier is a portable request, not a hand-picked size: note it quietly.log.verbose("The image size a tier derives is above the model's 2560x1440 reliability boundary", fields=size_fields)else:- log.warning("The requested image size is valid but above the model's 2560x1440 reliability boundary", fields=size_fields)+ log.warning("The requested image size is above the model's 2560x1440 reliability boundary", fields=size_fields)@classmethoddef moderation_literal(cls, *, is_moderated: bool | None) -> GptImageModerationType | None:diff --git a/pipelex/cogt/img_gen/img_gen_param_support.py b/pipelex/cogt/img_gen/img_gen_param_support.pyindex 103cb5dc0..15a3e7fe6 100644--- a/pipelex/cogt/img_gen/img_gen_param_support.py+++ b/pipelex/cogt/img_gen/img_gen_param_support.py@@ -71,7 +71,7 @@ class ImgGenParamSupport:try:taxonomy = AspectRatioTaxonomy(taxonomy_value)except ValueError:- log.debug(f"Abstaining: unknown AspectRatioTaxonomy '{taxonomy_value}' for model '{model_name}'")+ log.debug(f"An unknown AspectRatioTaxonomy '{taxonomy_value}' of model '{model_name}' was not checked")return _SUPPORTEDtry:ImgGenArgsFactory.make_args_from_aspect_ratio(@@ -98,7 +98,7 @@ class ImgGenParamSupport:try:taxonomy = BackgroundTaxonomy(taxonomy_value)except ValueError:- log.debug(f"Abstaining: unknown BackgroundTaxonomy '{taxonomy_value}' for model '{model_name}'")+ log.debug(f"An unknown BackgroundTaxonomy '{taxonomy_value}' of model '{model_name}' was not checked")return _SUPPORTEDtry:ImgGenArgsFactory.make_args_from_background(@@ -123,7 +123,7 @@ class ImgGenParamSupport:try:taxonomy = OutputFormatTaxonomy(taxonomy_value)except ValueError:- log.debug(f"Abstaining: unknown OutputFormatTaxonomy '{taxonomy_value}'")+ log.debug(f"An unknown OutputFormatTaxonomy '{taxonomy_value}' was not checked")return _SUPPORTEDtry:ImgGenArgsFactory.make_args_from_output_format(@@ -151,7 +151,7 @@ class ImgGenParamSupport:try:taxonomy = InputFidelityTaxonomy(taxonomy_value)except ValueError:- log.debug(f"Abstaining: unknown InputFidelityTaxonomy '{taxonomy_value}' for model '{model_name}'")+ log.debug(f"An unknown InputFidelityTaxonomy '{taxonomy_value}' of model '{model_name}' was not checked")return _SUPPORTEDtry:ImgGenArgsFactory.make_args_from_input_fidelity(diff --git a/pipelex/cogt/img_gen/img_gen_prompt.py b/pipelex/cogt/img_gen/img_gen_prompt.pyindex ced41000a..f7b90928f 100644--- a/pipelex/cogt/img_gen/img_gen_prompt.py+++ b/pipelex/cogt/img_gen/img_gen_prompt.py@@ -33,7 +33,7 @@ class ImgGenPrompt(BaseModel):raise ImgGenPromptError(msg)case ProblemReaction.LOG:if self.positive_text == "":- log.warning("ImgGen prompt positive_text should not be an empty string")+ log.warning("The positive text of an image generation prompt is empty")@overridedef __str__(self) -> str:diff --git a/pipelex/cogt/llm/llm_prompt.py b/pipelex/cogt/llm/llm_prompt.pyindex 9d9bb7649..07889be28 100644--- a/pipelex/cogt/llm/llm_prompt.py+++ b/pipelex/cogt/llm/llm_prompt.py@@ -6,6 +6,7 @@ from pipelex.cogt.document.prompt_document import PromptDocument, PromptDocumentfrom pipelex.cogt.exceptions import LLMPromptParameterErrorfrom pipelex.cogt.image.prompt_image import PromptImage, PromptImageUrifrom pipelex.system.runtime import ProblemReaction, runtime_manager+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.misc.string_utils import is_none_or_has_text, is_not_none_and_has_textfrom pipelex.tools.uri.uri_read_scope import UriReference@@ -50,9 +51,12 @@ class LLMPrompt(BaseModel):if self.system_text == "":log.debug("The prompt's system text is empty, so it is treated as absent")else:- log.error("The prompt's system text has no letter or digit in it; it should be absent or contain text")+ log.error(+ "The system text of a prompt has no letter or digit in it",+ fields={USER_ACTION_FIELD: "Leave the system text out or give it some text"},+ )if not is_not_none_and_has_text(text=self.user_text):- log.error("user_text should contain text")+ log.error("The user text of a prompt has no letter or digit in it")@overridedef __str__(self) -> str:diff --git a/pipelex/cogt/llm/llm_worker_abstract.py b/pipelex/cogt/llm/llm_worker_abstract.pyindex ee4fd94bc..6e899d6b8 100644--- a/pipelex/cogt/llm/llm_worker_abstract.py+++ b/pipelex/cogt/llm/llm_worker_abstract.py@@ -201,12 +201,12 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):# Skip if telemetry is disabled (no otel_context)if otel_context is None:- log.verbose("OTel: the job carries no otel_context, so no LLM span is started")+ log.verbose("No LLM span was started, since the job carries no OpenTelemetry context")return Nonetracer = TelemetryManagerAbstract.get_instance_tracer()if tracer is None:- log.verbose("OTel: no tracer is available, so no LLM span is started")+ log.verbose("No LLM span was started, since no tracer is available")return Noneunit_job_id = job_metadata.unit_job_id@@ -418,7 +418,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):requested_temperature = self._scaled_temperature(inference_model=self.inference_model, temperature=llm_job.job_params.temperature)if fixed_temperature is not None and requested_temperature != fixed_temperature:log.warning(- "The model takes a fixed temperature, so it is used in place of the requested one",+ "The model's fixed temperature was used in place of the requested one",fields={"model_handle": self.inference_model.name,"backend_name": self.inference_model.backend_name,diff --git a/pipelex/cogt/models/model_deck.py b/pipelex/cogt/models/model_deck.pyindex 9601dc8ce..8cc32aa77 100644--- a/pipelex/cogt/models/model_deck.py+++ b/pipelex/cogt/models/model_deck.py@@ -50,6 +50,7 @@ from pipelex.system.exceptions import ConfigValidationErrorfrom pipelex.system.runtime import ProblemReactionfrom pipelex.system.telemetry.otel_constants import OTelLogAttrfrom pipelex.tools.log.error_fields import error_fields+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.urls import URLsLLM_PRESET_DISABLED = "disabled"@@ -73,9 +74,13 @@ def _warn_if_ambiguous_bare_handle(matching_reference_kinds.append(ModelReferenceKind.WATERFALL)if matching_reference_kinds:log.warning(- "A bare model name also names a preset, an alias or a waterfall, and is read as a direct model handle; "- "prefix it ($ or preset:, @ or alias:, ~ or waterfall:) to avoid the ambiguity",- fields={"model_handle": name, "model_type": model_type, "matching_reference_kinds": matching_reference_kinds},+ "An ambiguous bare model name was read as a direct model handle",+ fields={+ "model_handle": name,+ "model_type": model_type,+ "matching_reference_kinds": matching_reference_kinds,+ USER_ACTION_FIELD: "Prefix the name with $ or preset: for a preset, @ or alias: for an alias, ~ or waterfall: for a waterfall",+ },)@@ -1027,7 +1032,7 @@ class ModelDeck(ConfigModel):waterfall_key = f"{NAMESPACE_WATERFALL}{waterfall_name}"if waterfall_key in visited:if not is_quiet:- log.warning("A model waterfall leads back to itself, so it resolves to no model", fields={"model_handle": waterfall_key})+ log.warning("A model waterfall that leads back to itself resolves to no model", fields={"model_handle": waterfall_key})return Nonestep_visited = visited | {waterfall_key}ideal_model_handle = fallback_list[0]@@ -1065,14 +1070,15 @@ class ModelDeck(ConfigModel):if fallback_index > 0 and not is_quiet and waterfall_name not in self._logged_fallback_warnings:# Waterfall success: we explain what happened in the logslog.info(- "A waterfall's first model is not in the model deck, so a fallback model replaces it; the results may not have "- "the expected quality, and the method may hit feature limits such as the context window. Consider getting access "- "to the first model",+ "A fallback model replaces a waterfall's first model, which the deck lacks",fields={"model_handle": waterfall_key,"ideal_model_handle": ideal_model_handle,"fallback_model_handle": fallback,OTelLogAttr.URL_FULL: URLs.backend_provider_docs,+ USER_ACTION_FIELD: (+ "Get access to the first model, since a fallback may lower the quality or hit limits such as its context window"+ ),},)# Mark this warning as logged for this waterfall_name@@ -1097,7 +1103,7 @@ class ModelDeck(ConfigModel):alias_key = f"{NAMESPACE_ALIAS}{alias_name}"if alias_key in visited:if not is_quiet:- log.warning("A model alias leads back to itself, so it resolves to no model", fields={"model_handle": alias_key})+ log.warning("A model alias that leads back to itself resolves to no model", fields={"model_handle": alias_key})return Noneif not is_quiet:log.verbose(f"Alias '{alias_name}' -> '{alias_target}'")@@ -1222,11 +1228,11 @@ class ModelDeck(ConfigModel):return Noneif served_types := self.inference_models.types_serving(handle=ref.name):log.warning(- "A model handle is served as another model type than the one requested, so it is skipped",+ "A model handle served as another model type than requested was skipped",fields={"model_handle": ref.name, "model_type": model_type, "served_model_types": served_types},)return None- log.verbose(f"Skipping model handle '{model_handle}' because it was not found in the model deck, it could be an external plugin.")+ log.verbose(f"Model handle '{model_handle}' was skipped: the model deck lacks it, and an external plugin may serve it")return Nonedef is_handle_defined(self, model_handle: str, *, model_type: ModelType) -> bool:diff --git a/pipelex/config.py b/pipelex/config.pyindex 6f68de84f..fbcbf3fa2 100644--- a/pipelex/config.py+++ b/pipelex/config.py@@ -3,6 +3,7 @@ from pipelex.plugins.pipe_func_executor_registry import DIRECT_PIPE_FUNC_EXECUTIfrom pipelex.runtime_hub import get_optional_config, get_required_configfrom pipelex.system.configuration.configs import PipelexConfigfrom pipelex.system.environment import get_optional_env+from pipelex.tools.log.log_fields import USER_ACTION_FIELDMETHODS_FETCH_ON_MISS_ENV_VAR = "PIPELEX_METHODS_FETCH_ON_MISS"@@ -51,8 +52,8 @@ def is_method_fetch_on_miss_enabled() -> bool:if normalized in _ENV_FALSY:return Falselog.warning(- "An environment variable holds no recognized boolean (1/0, true/false, yes/no, on/off), so it is ignored and the config decides",- fields={"env_var": METHODS_FETCH_ON_MISS_ENV_VAR},+ "An environment variable holding no recognized boolean was ignored",+ fields={"env_var": METHODS_FETCH_ON_MISS_ENV_VAR, USER_ACTION_FIELD: "Set it to 1 or 0, true or false, yes or no, or on or off"},)optional_config = get_optional_config()if not isinstance(optional_config, PipelexConfig):diff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.pyindex af07fdbf3..a67efa89f 100644--- a/pipelex/core/concepts/concept_factory.py+++ b/pipelex/core/concepts/concept_factory.py@@ -36,7 +36,7 @@ def _is_valid_structure_class(*, structure_class_name: str) -> bool:return Trueif get_class_registry().has_class(name=structure_class_name):log.warning(- "A class registered under a concept's structure class name is not a StuffContent subclass, so the concept does not use it",+ "A concept's registered structure class is not a StuffContent and was not used",fields={"structure_class_name": structure_class_name},)return Falsediff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.pyindex fee3b4581..70d00128f 100644--- a/pipelex/core/memory/working_memory_factory.py+++ b/pipelex/core/memory/working_memory_factory.py@@ -162,8 +162,8 @@ class WorkingMemoryFactory(BaseModel):else:# Fallback to TextContent if we can't get the proper classlog.debug(- f"Could not get structure class '{structure_class_name}' for "- f"concept '{named_stuff_spec.concept.code}', falling back to TextContent",+ f"The structure class '{structure_class_name}' of concept '{named_stuff_spec.concept.code}' "+ "is not available, and TextContent is used in its place",)text_typed_named_stuff_spec = TypedNamedStuffSpec.make_from_named(named=named_stuff_spec,@@ -174,7 +174,7 @@ class WorkingMemoryFactory(BaseModel):except ValidationError as exc:# Fallback to TextContent when the typed stuff spec fails pydantic validationlog.warning(- "The structure class of an input's concept could not be used, so the input is mocked as text",+ "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,@@ -209,7 +209,7 @@ class WorkingMemoryFactory(BaseModel):if structure_class and issubclass(structure_class, StuffContent):return TypedNamedStuffSpec.make_from_named(named=named, structure_class=structure_class)log.debug(- f"Could not get structure class '{structure_class_name}' for concept '{concept.code}', falling back to TextContent",+ f"The structure class '{structure_class_name}' of concept '{concept.code}' is not available, and TextContent is used in its place",)return TypedNamedStuffSpec.make_from_named(named=named, structure_class=TextContent)@@ -283,7 +283,7 @@ class WorkingMemoryFactory(BaseModel):# Mock build (polyfactory) or content validation (pydantic) failed for this dynamic# class — fall back to text content. Unexpected errors propagate.log.warning(- "A mock input could not be built from its concept's structure, so a text stand-in is used",+ "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,diff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.pyindex 82f9e715e..ad392ce8c 100644--- a/pipelex/core/stuffs/stuff.py+++ b/pipelex/core/stuffs/stuff.py@@ -146,7 +146,7 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffConteif names_match:content_dict = content.smart_dump()validated_content = content_type.model_validate(content_dict)- log.verbose(f"Model validation passed: converted {type(content).__name__} to {content_type.__name__}")+ log.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)diff --git a/pipelex/graph/graph_factory.py b/pipelex/graph/graph_factory.pyindex 8cac0c727..07200713d 100644--- a/pipelex/graph/graph_factory.py+++ b/pipelex/graph/graph_factory.py@@ -206,7 +206,7 @@ def save_graph_outputs_to_dir(# loud, because the agent CLI's directory is the user's own bundle directory.file_path.unlink()log.warning(- "Removed an I/O artifact an earlier run left beside the graphspec, which carries none of its own",+ "An I/O artifact an earlier run left beside the graphspec was removed",fields={OTelLogAttr.FILE_PATH: str(file_path)},)diff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.pyindex 7e0705db7..a08f9f2ac 100644--- a/pipelex/graph/graph_tracer_manager.py+++ b/pipelex/graph/graph_tracer_manager.py@@ -146,7 +146,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):# value is ambiguous (None both when no tracer existed and when a costs-only tracer# legitimately tears down without a GraphSpec).if key in self._tracers:- log.warning("Replacing a graph tracer left over by an interrupted execution whose cleanup never ran", fields={"tracer_key": key})+ log.warning("A graph tracer left over by an interrupted execution was replaced", fields={"tracer_key": key})try:self.close_tracer(key)except Exception as stale_teardown_exc: # ruff: ignore[blind-except]@@ -156,7 +156,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):# leak state deciding setup success). close_tracer pops before tearing down,# so the key is free either way.log.warning(- "The teardown of a stale graph tracer raised; replacing it anyway",+ "The teardown of a stale graph tracer failed, and the tracer was replaced",fields={"tracer_key": key, **error_fields(exc=stale_teardown_exc)},)diff --git a/pipelex/kernel/judgment_ops.py b/pipelex/kernel/judgment_ops.pyindex 97acd7bdf..4b01f5618 100644--- a/pipelex/kernel/judgment_ops.py+++ b/pipelex/kernel/judgment_ops.py@@ -160,7 +160,7 @@ async def run_judgment(content, threshold_applied = make_verdict_content(answer=answer, threshold=threshold, is_dry=cogt_run_params.run_mode.is_dry)if threshold_applied is False:log.warning(- "A judgment declares a threshold, but its model reported no probability, so the model's own verdict stands",+ "A judgment's model reported no probability, and its own verdict stands",fields={"pipe_code": job_metadata.pipe_code, "threshold": threshold, "model_handle": judgment_setting.model},)return JudgmentResult(diff --git a/pipelex/kit/agent_rules/commands.md b/pipelex/kit/agent_rules/commands.mdindex 42d34bb22..3b762187f 100644--- a/pipelex/kit/agent_rules/commands.md+++ b/pipelex/kit/agent_rules/commands.md@@ -2,7 +2,7 @@`make` targets activate the virtual environment themselves; anything else (`pytest`, `pipelex`, `pipelex-dev`) runs from `.venv/bin/` (`.venv\Scripts\` on Windows), never bare. The Makefile is the reference for every target and alias; without `make`, read the target there and run its prerequisites one by one.-- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the log-call check (`clc`: a log message at INFO and above is a literal with its values in `fields=`, and no log message holds Rich markup, against `log_call_baseline.toml`, which only shrinks: the check refuses an entry the baseline at the merge base with `origin/dev` does not list; see `docs/contribute/log-calls.md`), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.+- **`make agent-check` after every code change, and fix everything it reports.** Its prerequisites are `fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check`: the import and keyword-only fixers, ruff, pyright, mypy, `plxt` over TOML/MTHDS/PLX, the migration-ledger replay (`cl`), the hub-layering check, the Rich import check (`cri`: Rich is the `cli` extra, so no module outside `pipelex/cli/` imports it at module level or reaches it through a CLI module), the Actions allowlist check (`caa`: every workflow action must be one `.github/actions-allowlist.toml` allows), the log-call check (`clc`: a log message at INFO and above is a literal with its values in `fields=`, no log message holds Rich markup, starts with a lowercase letter, ends with a period or holds a backtick, at INFO and above none names an identifier or runs past 80 characters, and none splices a handled exception into its text, against `log_call_baseline.toml`, which only shrinks: the check refuses an entry the baseline at the merge base with `origin/dev` does not list; see `docs/contribute/log-calls.md`), the drift contracts, and the server's own gate. The drift digest reads the git index, so stage your changes before the check.- **The Pipelex API server is the `api/` workspace member** (the `pipelex-api` distribution, package `pipelex_api`; its guide is `api/CLAUDE.md`). It runs the pipelex of the same commit from its own environment, `api/.venv`, which its targets provision themselves. `make agent-check` ends with `api-agent-check` (`make -C api agent-check`: its install, ruff, pyright, mypy, and the drift checks of its OpenAPI artifact and of its vendored inference tree) and `make agent-test` with `api-agent-test`, so a library change that breaks the server, moves its wire or leaves its inference tree behind fails in the same change. A kit change reaches the server's tree through `make up-kit-configs` (`ukc`); a change to the server's wire is committed with `make -C api openapi-export`.- **Keyword-only arguments** (the convention is in the standards and in `docs/contribute/keyword-only-arguments.md`): `make check-keyword-only` (`cko`) is the gate, `make fix-keyword-only` (`fko`) inserts the bare `*` where it can — on ungranted subjects too — and reports the shapes it cannot fix, and `make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"` (`sgr`) grants a positional subject. Grant before `make agent-check`, which runs the fixer.- **Drift contracts.** When `make drift-check` reports an open contract: `make drift-plan`, review and fix the stale targets, `git add` the trigger files, then `make drift-ack CONTRACT=<id> RATIONALE="<verdict>: …"`, the rationale opening with its verdict, `real-catch`, `clean-pass` or `friction`. No bypass flag; "clean-pass: reviewed, no doc change needed" is a legitimate rationale. See `docs/contribute/drift-contracts.md` and the `/drift-review` skill.diff --git a/pipelex/kit/agent_rules/python_standards.md b/pipelex/kit/agent_rules/python_standards.mdindex 79a68098d..21d82a7a0 100644--- a/pipelex/kit/agent_rules/python_standards.md+++ b/pipelex/kit/agent_rules/python_standards.md@@ -75,7 +75,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.-- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. It is one short sentence, subject first, starting with a capital and ending with no period or `...`, with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in a `user_action` field ("Wording a message" in `docs/tools/logging.md`). A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text, at any level; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.### StrEnum and Self typediff --git a/pipelex/libraries/domain/domain_metadata_merge.py b/pipelex/libraries/domain/domain_metadata_merge.pyindex 43c247e8f..51df659b5 100644--- a/pipelex/libraries/domain/domain_metadata_merge.py+++ b/pipelex/libraries/domain/domain_metadata_merge.py@@ -45,5 +45,5 @@ def merge_domain_metadata_field(conflict_fields: dict[str, str] = {"domain_code": domain_code, "metadata_field": metadata_field}if show_values_on_conflict:conflict_fields.update(established_value=established, incoming_value=incoming)- log.warning("Two declarations of one domain give one of its fields different values, so the first is kept", fields=conflict_fields)+ log.warning("Two declarations of a domain disagree on a field, and the first value is kept", fields=conflict_fields)return establisheddiff --git a/pipelex/libraries/library.py b/pipelex/libraries/library.pyindex b057aadb9..56b8abc40 100644--- a/pipelex/libraries/library.py+++ b/pipelex/libraries/library.py@@ -364,8 +364,8 @@ class Library(BaseModel):)raise LibraryError(msg)log.verbose(- f"Concept '{concept.concept_ref}' refines cross-package concept '{concept.refines}' "- f"from unloaded dependency '{alias}', skipping validation"+ f"The validation of concept '{concept.concept_ref}' was skipped: it refines cross-package concept "+ f"'{concept.refines}' from unloaded dependency '{alias}'")def validate_domain_library_with_libraries(self) -> None:diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.pyindex 7a2d9b83d..cda2f29f8 100644--- a/pipelex/libraries/library_manager.py+++ b/pipelex/libraries/library_manager.py@@ -67,6 +67,7 @@ from pipelex.runtime_hub import get_class_registryfrom pipelex.system.registries.class_registry_utils import ClassRegistryUtilsfrom pipelex.system.registries.func_registry_utils import FuncRegistryUtilsfrom pipelex.tools.log.error_fields import error_fields+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.misc.semver import SemVerError, parse_constraint, parse_version, version_satisfiesfrom pipelex.validation_error_types import PipeValidationErrorType@@ -463,12 +464,12 @@ class LibraryManager(LibraryManagerAbstract):# (worker-local leak state deciding setup success would be the M1 class again).# _pop_and_teardown_library forgets the entry pop-first, so the id is free either way.log.warning(- "The teardown of a stale library raised; continuing with a fresh library",+ "The teardown of a stale library failed, and a fresh library was made",fields={"library_id": library_id, **error_fields(exc=stale_teardown_exc)},)else:if removed_existing:- log.warning("Tore down a library left over by an interrupted execution whose cleanup never ran", fields={"library_id": library_id})+ log.warning("A library left over by an interrupted execution was torn down", fields={"library_id": library_id})_library_id, the_library = self.open_library(library_id=library_id)return the_library@@ -1135,18 +1136,19 @@ class LibraryManager(LibraryManagerAbstract):current_version = parse_version(MTHDS_STANDARD_VERSION)except SemVerError as exc:log.warning(- "The mthds_version constraint of a package could not be parsed",+ "The MTHDS version constraint of a package could not be parsed",fields={"package_address": package_address, "mthds_version_constraint": mthds_version_constraint, **error_fields(exc=exc)},)returnif not version_satisfies(current_version, constraint=constraint):log.warning(- "A package requires another MTHDS standard version than this runtime's; some features may not work correctly",+ "A package requires another MTHDS standard version than this runtime's",fields={"package_address": package_address,"mthds_version_constraint": mthds_version_constraint,"mthds_standard_version": MTHDS_STANDARD_VERSION,+ USER_ACTION_FIELD: "Run the package on a Pipelex release that implements its MTHDS version, or some features may fail",},)diff --git a/pipelex/libraries/library_utils.py b/pipelex/libraries/library_utils.pyindex d61898969..15a370edb 100644--- a/pipelex/libraries/library_utils.py+++ b/pipelex/libraries/library_utils.py@@ -38,7 +38,7 @@ def get_pipelex_mthds_files_from_package() -> list[Path]:_find_mthds_in_traversable(child, collected=collected)except (PermissionError, OSError) as exc:log.warning(- "A directory of the pipelex package could not be read, so its MTHDS files are left out",+ "A directory of the pipelex package could not be read and was left out",fields={OTelLogAttr.FILE_PATH: str(traversable), **error_fields(exc=exc)},)@@ -60,9 +60,7 @@ def get_pipelex_package_dir_for_imports() -> Path | None:if pkg_path.exists() and pkg_path.is_dir():return pkg_pathexcept (TypeError, ValueError, OSError) as exc:- log.warning(- "The pipelex package is not a directory on the filesystem, so its modules cannot be imported from it", fields=error_fields(exc=exc)- )+ log.warning("The pipelex package is not a directory, and its modules were not imported", fields=error_fields(exc=exc))return None@@ -72,7 +70,7 @@ def get_pipelex_mthds_files_from_dirs(dirs: set[Path]) -> list[Path]:for dir_path in dirs:if not dir_path.exists():- log.debug(f"Directory does not exist, skipping: {dir_path}")+ log.debug(f"A directory that does not exist was skipped: {dir_path}")continue# Find all .mthds files in the directory, excluding problematic directories@@ -87,5 +85,5 @@ def get_pipelex_mthds_files_from_dirs(dirs: set[Path]) -> list[Path]:if is_pipelex_file(mthds_file):all_mthds_paths.append(mthds_file)else:- log.debug(f"Skipping non-Pipelex MTHDS file: {mthds_file}")+ log.debug(f"An MTHDS file that is not a Pipelex file was skipped: {mthds_file}")return all_mthds_pathsdiff --git a/pipelex/methods/fetch_on_miss.py b/pipelex/methods/fetch_on_miss.pyindex bb16c1fad..c82840ead 100644--- a/pipelex/methods/fetch_on_miss.py+++ b/pipelex/methods/fetch_on_miss.py@@ -32,6 +32,7 @@ from pipelex.methods.fetching import fetch_method_packagefrom pipelex.methods.method_ref import MethodRef, looks_like_method_ref, parse_method_reffrom pipelex.methods.structures_check import describe_structured_content_violations, scan_structured_content_classesfrom pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.log_fields import USER_ACTION_FIELD# The remedy every refusal ends with. It names no directory: on a host, the runtime's own store is not the caller's to write.MANUAL_INSTALL_HINT = "install the package where this runtime runs (for example with `mthds install <address>`)"@@ -83,7 +84,7 @@ def find_vendored_method(*, full_address: str, methods_dirs: list[Path]) -> Instversion = vendored.manifest.versionif lookup.ref.tag not in {version, f"v{version}"}:log.warning(- "A method reference pins a tag, and the copy shipped with the request is another version, which is used",+ "A shipped method copy was used though its version is not the pinned tag",fields={"method_ref": lookup.ref.ref_str, "package_version": version},)return vendored@@ -95,14 +96,15 @@ def _warn_on_tag_mismatch(*, installed: InstalledMethod, ref: MethodRef | None)returnif installed.provenance is not None and installed.provenance.tag == ref.tag:return- mismatch_fields: dict[str, str | None] = {"method_ref": ref.ref_str, OTelLogAttr.FILE_PATH: str(installed.path)}+ mismatch_fields: dict[str, str | None] = {+ "method_ref": ref.ref_str,+ OTelLogAttr.FILE_PATH: str(installed.path),+ USER_ACTION_FIELD: "Remove the installed copy to fetch the pinned tag",+ }if installed.provenance is not None:# Absent when the copy's provenance was never recorded, and None when the copy was fetched with no tag.mismatch_fields["installed_tag"] = installed.provenance.tag- log.warning(- "A method reference pins a tag the installed copy was not fetched at, so the installed copy is used; removing it re-fetches the pinned tag",- fields=mismatch_fields,- )+ log.warning("A method's installed copy was used though not fetched at the pinned tag", fields=mismatch_fields)def resolve_address_based_method(@@ -186,11 +188,14 @@ def resolve_address_based_method(violations = scan_structured_content_classes(package_dir=fetched.package_dir)if violations:- # The remedy is in the message, which the console never cuts; `STRUCTURES_REFUSAL_REMEDY` says it at length in the refusal.+ # The remedy rides in `user_action`, which the console prints whole; `STRUCTURES_REFUSAL_REMEDY` says it at length in the refusal.log.warning(- "A fetched method declares Python structure classes: it runs locally, but hosted execution refuses them, "- "so declare these types as MTHDS concepts with inline structures",- fields={"package_address": fetched.full_address, "structure_classes": describe_structured_content_violations(violations=violations)},+ "A fetched method declares Python structure classes, which hosted runs refuse",+ fields={+ "package_address": fetched.full_address,+ "structure_classes": describe_structured_content_violations(violations=violations),+ USER_ACTION_FIELD: "Declare these types as MTHDS concepts with inline structures",+ },)name = fetched.manifest.name or fetched.package_dir.namediff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]index c9de2007e..dbc550b61 100644--- a/pipelex/migration/goldens/pipelex-config/[email protected]+++ b/pipelex/migration/goldens/pipelex-config/[email protected]@@ -95,9 +95,13 @@ urllib3-util-retry = "INFO"pipelex = "INFO"+# The settings of the "console" sink. is_show_path adds a column at the right of every line naming the+# source file and line that logged it, which makes a long line wrap; is_link_path_enabled makes that+# path clickable where the terminal supports links.[runtime.log.rich_log]is_show_time = falseis_show_level = true+is_show_path = falseis_link_path_enabled = truehighlighter_name = "json"is_rich_tracebacks = truediff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]index bf6a6a423..13ba9ae1a 100644--- a/pipelex/migration/goldens/pipelex-config/[email protected]+++ b/pipelex/migration/goldens/pipelex-config/[email protected]@@ -1214,6 +1214,12 @@"default": true,"open_node": false},+ "runtime.log.rich_log.is_show_path": {+ "value_type": "bool",+ "required": true,+ "default": false,+ "open_node": false+ },"runtime.log.rich_log.is_show_time": {"value_type": "bool","required": true,diff --git a/pipelex/migration/runner.py b/pipelex/migration/runner.pyindex fac92f5d4..95ba179cf 100644--- a/pipelex/migration/runner.py+++ b/pipelex/migration/runner.py@@ -289,7 +289,7 @@ def _prune_older_backups(*, snapshot: FileSnapshot, backup: WrittenBackup) -> No# An older backup that would not go is a housekeeping failure on a file that is already# migrated and already backed up. Not the plan's to report as a failure of the file.log.warning(- "A change to a configuration file was backed up, but an older backup of the file could not be pruned",+ "An older backup of a configuration file could not be pruned",fields={OTelLogAttr.FILE_PATH: str(snapshot.path), "backup_path": str(backup.path), **error_fields(exc=exc, text=exc.strerror)},)@@ -314,7 +314,7 @@ def _discard_created_backup(*, backup: WrittenBackup, snapshot: FileSnapshot) ->backup.path.unlink(missing_ok=True)except OSError as exc:log.warning(- "A backup made for a removal that did not happen could not be removed, so it stays beside the file",+ "A backup made for a removal that did not happen could not be removed",fields={OTelLogAttr.FILE_PATH: str(snapshot.path), "backup_path": str(backup.path), **error_fields(exc=exc, text=exc.strerror)},)return None@@ -376,7 +376,7 @@ def _discard_backup(*, backup: WrittenBackup, snapshot: FileSnapshot, new_contenbackup.path.unlink(missing_ok=True)except OSError as exc:log.warning(- "A backup made for a write that did not happen could not be removed, so it stays beside the file",+ "A backup made for a write that did not happen could not be removed",fields={OTelLogAttr.FILE_PATH: str(snapshot.path), "backup_path": str(backup.path), **error_fields(exc=exc, text=exc.strerror)},)diff --git a/pipelex/mthds_parsing/validation_error_categorizer.py b/pipelex/mthds_parsing/validation_error_categorizer.pyindex 6de0c3379..52662b034 100644--- a/pipelex/mthds_parsing/validation_error_categorizer.py+++ b/pipelex/mthds_parsing/validation_error_categorizer.py@@ -530,5 +530,5 @@ def categorize_blueprint_validation_error(return syntax_error# No categorizer knows it: keep it as an item of its own, never dropped because another item exists.- log.verbose(f"Pipelex bundle blueprint validation error that is not categorized: {error_scope} - {source} - {domain}")+ log.verbose(f"A bundle blueprint validation error is not categorized: {error_scope} - {source} - {domain}")return _make_uncategorized_blueprint_error(error=error, domain=domain, source=source, pipe_code=pipe_code)diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.pyindex 0ccd71a4d..86b3d9861 100644--- a/pipelex/pipe_controllers/batch/pipe_batch.py+++ b/pipelex/pipe_controllers/batch/pipe_batch.py@@ -18,6 +18,7 @@ from pipelex.pipe_run.pipe_job_factory import PipeJobFactoryfrom pipelex.pipe_run.pipe_run_params import BatchParams, PipeRunParamsfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.misc.async_utils import gather_boundedfrom pipelex.urls import URLs@@ -35,22 +36,16 @@ LARGE_BATCH_ADVISORY_THRESHOLD = 100def warn_of_large_batch(*, pipe_code: str, item_count: int, max_concurrency: int | None) -> None:"""Advise a durable execution backend for a batch past ``LARGE_BATCH_ADVISORY_THRESHOLD`` items.- Each case has its own message, which says what the fan-out is: bounded, it is backpressure, and unbounded it is not- even that. ``max_concurrency`` is always an integer, so a log query reads one type: it is absent from the line when- the configuration's ``"unbounded"`` resolved to no bound at all.+ Bounded or not, the fan-out is one event: a bound is backpressure, and neither is durable, rate-limited execution.+ ``max_concurrency`` is always an integer, so a log query reads one type: it is absent from the line when the+ configuration's ``"unbounded"`` resolved to no bound at all."""- if max_concurrency is None:- log.warning(- "A PipeBatch fans out over a large list with unbounded fan-out, which is neither backpressure nor durable execution; "- "for a workload this size, consider a durable execution backend for rate-limited, resumable runs",- fields={"pipe_code": pipe_code, "item_count": item_count, OTelLogAttr.URL_FULL: URLs.durable_execution},- )- return- log.warning(- "A PipeBatch fans out over a large list with bounded fan-out, which is backpressure and not durable execution; "- "for a workload this size, consider a durable execution backend for rate-limited, resumable runs",- fields={"pipe_code": pipe_code, "item_count": item_count, "max_concurrency": max_concurrency, OTelLogAttr.URL_FULL: URLs.durable_execution},- )+ fields: dict[str, str | int] = {"pipe_code": pipe_code, "item_count": item_count}+ if max_concurrency is not None:+ fields["max_concurrency"] = max_concurrency+ fields[OTelLogAttr.URL_FULL] = URLs.durable_execution+ fields[USER_ACTION_FIELD] = "Consider a durable execution backend for rate-limited, resumable runs"+ log.warning("A PipeBatch fans out over a large list without durable execution", fields=fields)class PipeBatch(PipeController):diff --git a/pipelex/pipe_machinery/pipe_abstract.py b/pipelex/pipe_machinery/pipe_abstract.pyindex d107496f8..fb2d86372 100644--- a/pipelex/pipe_machinery/pipe_abstract.py+++ b/pipelex/pipe_machinery/pipe_abstract.py@@ -48,6 +48,7 @@ from pipelex.system.telemetry.otel_factory import OtelFactoryfrom pipelex.system.telemetry.telemetry_identity import make_run_identity_span_attributesfrom pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstractfrom pipelex.tools.log.console_layouts import LogLayout+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.log.summary_event import SummaryEventfrom pipelex.tools.misc.package_utils import get_package_versionfrom pipelex.tools.misc.string_utils import get_root_from_dotted_path, is_snake_case@@ -257,8 +258,8 @@ class PipeAbstract(ABC, BaseModel):if "." in code:bare_code = code.rsplit(".", maxsplit=1)[1]log.warning(- "A pipe code carries a namespace prefix, which was stripped: write the pipe code bare",- fields={"pipe_code": bare_code, "pipe_ref": code},+ "A namespace prefix was stripped from a pipe code",+ fields={"pipe_code": bare_code, "pipe_ref": code, USER_ACTION_FIELD: "Write the pipe code bare"},)code = bare_codeif not is_snake_case(code):diff --git a/pipelex/pipe_operators/func/direct_pipe_func_executor.py b/pipelex/pipe_operators/func/direct_pipe_func_executor.pyindex 6c0575d44..8285c44d0 100644--- a/pipelex/pipe_operators/func/direct_pipe_func_executor.py+++ b/pipelex/pipe_operators/func/direct_pipe_func_executor.py@@ -133,7 +133,7 @@ class DirectPipeFuncExecutor(PipeFuncExecutorProtocol):for emitted in emit_python_structures(qualified_library):generated_target = workdir / emitted.filenameif generated_target.exists():- log.verbose(f"Structures file '{emitted.filename}' was shipped by the method; keeping the shipped copy over the generated one.")+ log.verbose(f"The structures file '{emitted.filename}' the method shipped was kept over the generated one")continuegenerated_target.parent.mkdir(parents=True, exist_ok=True)generated_target.write_text(emitted.content, encoding="utf-8")diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.pyindex 0c107b011..e6d9faa31 100644--- a/pipelex/pipe_run/delivery_executor.py+++ b/pipelex/pipe_run/delivery_executor.py@@ -215,7 +215,7 @@ class DeliveryExecutor:# Treated as missing, the caller then fails the delivery: the record is lost, and this line says why. The# 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, so the delivery has no result to render",+ "The absence record of the main output is malformed",fields=error_fields(exc=validation_error),)return None@@ -253,7 +253,7 @@ class DeliveryExecutor:return get_concept_library().resolve_wire_concept_ref(concept_ref=concept_ref)except ConceptRefAmbiguousError as exc:log.warning(- "A concept ref is ambiguous in the current library; the delivery renders the result raw",+ "A delivered result's concept ref is ambiguous and the result was rendered raw",fields={"concept_ref": concept_ref, **error_fields(exc=exc)},)return None@@ -262,13 +262,13 @@ class DeliveryExecutor:except RuntimeError as exc:# The contextvar still names a library, but the hub that held it is gone. A delivery# outlives the run it renders, so this is a race to survive, not a state to assert.- log.warning("The current library is no longer reachable; the delivery renders the result raw", fields=error_fields(exc=exc))+ log.warning("The current library is gone and a delivered result was rendered raw", fields=error_fields(exc=exc))return Nonetry:is_native_ref = NativeConceptCode.is_valid_native_concept_ref(concept_ref=concept_ref)except QualifiedRefError as exc:log.warning(- "A concept ref is malformed; the delivery renders the result raw",+ "A delivered result's concept ref is malformed and the result was rendered raw",fields={"concept_ref": concept_ref, **error_fields(exc=exc)},)return None@@ -293,20 +293,20 @@ class DeliveryExecutor:concept_ref = stuff_raw["concept"]if not isinstance(concept_ref, str):# A stale runtime dumped the whole concept object here: worth a redeploy, so a warning.- log.warning("The delivered result does not name its concept by a concept ref string; the delivery renders it raw")+ log.warning("A delivered result names no concept ref string and was rendered raw")return Noneconcept = cls._resolve_concept_locally(concept_ref=concept_ref)if concept is None:# A crate-free delivery worker does not know a method's own concepts by design, so this is the# expected path for most hosted results: worth a debug line, not a warning nobody can act on.- log.debug("The delivered result's concept is not known here; the delivery renders it raw", fields={"concept_ref": concept_ref})+ log.debug("A delivered result's concept is not known here and was rendered raw", fields={"concept_ref": concept_ref})return None# A structureless concept (`native.Anything`) names no class to look up: its content carries its own.if concept.declares_a_structure_class:item_class = get_class_registry().get_class(name=concept.structure_class_name)if item_class is None or not issubclass(item_class, StuffContent):log.warning(- "The structure class of the delivered result's concept is not registered here; the delivery renders it raw",+ "A delivered result's structure class is unregistered here and was rendered raw",fields={"concept_ref": concept_ref, "structure_class_name": concept.structure_class_name},)return None@@ -319,7 +319,7 @@ class DeliveryExecutor:)except (PipeJobError, ValidationError, KajsonException, KeyError, TypeError) as exc:log.warning(- "The delivered result could not be hydrated; the delivery renders it raw",+ "A delivered result could not be hydrated and was rendered raw",fields=error_fields(exc=exc),)return None@@ -377,7 +377,7 @@ class DeliveryExecutor:self._add_optional_text_file(files=files, filename="reactflow.html", text=graph_outputs.reactflow_html, content_type="text/html")except Exception as exc: # ruff: ignore[blind-except]# Best-effort: graph generation spans a deep mermaid/reactflow render tree; a graph failure must never fail result delivery.- log.warning("Failed to generate graph outputs", fields=error_fields(exc=exc))+ log.warning("The graph outputs could not be generated", fields=error_fields(exc=exc))@classmethodasync def _try_add_rendered_file(@@ -394,7 +394,7 @@ class DeliveryExecutor:except Exception as exc: # ruff: ignore[blind-except]# Best-effort: per-format rendering (incl. jinja2 viewer); a single render failure must not drop the other result files.log.warning(- "A result file could not be rendered; the delivery goes on without it",+ "A result file could not be rendered and was left out of the delivery",fields={"file.name": filename, **error_fields(exc=exc)},)returndiff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.pyindex b3315ce83..3aff07748 100644--- a/pipelex/pipe_run/dry_run_in_process.py+++ b/pipelex/pipe_run/dry_run_in_process.py@@ -73,7 +73,7 @@ async def best_effort_graph_spec(*, pipe_ref: str | None, library_id: str | Noneif foreign_fault is not None and not isinstance(foreign_fault, (FactoryException, ValueError)):raiselog.warning(- "The graph dry run produced no graph; the validation result carries none",+ "The graph dry run produced no graph",fields={"caller": log_context, **_graph_target_fields(pipe=pipe, target=pipe_ref), **error_fields(exc=graph_error)},)return Nonediff --git a/pipelex/pipe_run/pipe_run.py b/pipelex/pipe_run/pipe_run.pyindex c21e4584f..7df9a3875 100644--- a/pipelex/pipe_run/pipe_run.py+++ b/pipelex/pipe_run/pipe_run.py@@ -76,7 +76,7 @@ class PipeRun(PipeRunProtocol):# belongs to whoever catches it, the CLI or the API's handler, which would otherwise print it twice.# `pipe_code` is the bare code `Pipe run starts` carries for the same pipe, so one query finds both lines.log.error(- "Pipe execution failed",+ "The execution of a pipe failed",fields={"pipe_code": pipe_job.pipe.code, "pipe_ref": pipe_job.pipe.pipe_ref, **error_fields(exc=exc)},)finally:@@ -90,7 +90,7 @@ class PipeRun(PipeRunProtocol):# 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.log.error(- "Closing the graph tracer also failed after the pipe execution failed; the execution error is raised",+ "The graph tracer could not be closed after the pipe execution failed",fields=error_fields(exc=close_error),)@@ -129,7 +129,7 @@ class PipeRun(PipeRunProtocol):raise# As fields with no traceback, for the same reason as the tracer's: the execution error is chained onto it.log.error(- "The delivery also failed after the pipe execution failed; the execution error is raised",+ "The delivery also failed after the pipe execution failed",fields=error_fields(exc=delivery_error),)@@ -158,5 +158,5 @@ class PipeRun(PipeRunProtocol):try:pipe_output.pipe_io_artifacts = build_pipe_io_artifacts(get_own_pipes())except Exception as build_error: # ruff: ignore[blind-except]- log.warning("The I/O artifacts of the run could not be built; the run keeps its result", fields=error_fields(exc=build_error))+ log.warning("The I/O artifacts of a run could not be built", fields=error_fields(exc=build_error))pipe_output.pipe_io_artifacts_error = f"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}"diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.pyindex 620f3fb93..0ee76ee47 100644--- a/pipelex/pipe_run/pipe_run_params.py+++ b/pipelex/pipe_run/pipe_run_params.py@@ -264,7 +264,7 @@ class PipeRunParams(BaseModel):# raise: this runs inside run_pipe()'s `finally`, where raising would mask the# in-flight exception.log.error(- "The pipe stack is unbalanced: the pipe popped is not the last one pushed",+ "The pipe popped off the pipe stack is not the last one pushed",fields={"pipe_code": pipe_code, "popped_pipe_code": popped_pipe_code},)diff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.pyindex 876d59d9d..f0ba26ce5 100644--- a/pipelex/pipe_run/tracing_assembly.py+++ b/pipelex/pipe_run/tracing_assembly.py@@ -169,7 +169,7 @@ def _assemble_tracing_events(event_log.close()except (OSError, json.JSONDecodeError, ValidationError, PipelexConfigError, MissingDependencyError, EventLogError) as read_error:message = f"Tracing assembly failed to read events for pipeline_run_id={pipeline_run_id}: {read_error}"- log.warning("Tracing assembly could not read the run's trace events", fields=error_fields(exc=read_error))+ log.warning("The trace events of a run could not be read for its tracing assembly", fields=error_fields(exc=read_error))if assemble_graph:result.graph_assembly_error = messageif assemble_usage:diff --git a/pipelex/pipelex.toml b/pipelex/pipelex.tomlindex c9de2007e..dbc550b61 100644--- a/pipelex/pipelex.toml+++ b/pipelex/pipelex.toml@@ -95,9 +95,13 @@ urllib3-util-retry = "INFO"pipelex = "INFO"+# The settings of the "console" sink. is_show_path adds a column at the right of every line naming the+# source file and line that logged it, which makes a long line wrap; is_link_path_enabled makes that+# path clickable where the terminal supports links.[runtime.log.rich_log]is_show_time = falseis_show_level = true+is_show_path = falseis_link_path_enabled = truehighlighter_name = "json"is_rich_tracebacks = truediff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.pyindex 88dc5c7da..9cb46827e 100644--- a/pipelex/pipeline/bundle_validator.py+++ b/pipelex/pipeline/bundle_validator.py@@ -67,6 +67,7 @@ from pipelex.system.configuration.configs import PipelineExecutionConfigfrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.storage_scope import DRY_RUN_STORAGE_SCOPE, DRY_RUN_USER_IDfrom pipelex.system.telemetry.events import EventName, EventProperty+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_errorif TYPE_CHECKING:@@ -358,7 +359,10 @@ class BundleValidator:pipe.validate_with_libraries()except PipeNotFoundError as not_found_error:error_message = f"Skipped dry run for pipe '{pipe.pipe_ref}': unresolved dependency: {not_found_error}"- log.verbose(error_message)+ log.verbose(+ "A pipe's dry run was skipped for an unresolved dependency",+ fields={"pipe_ref": pipe.pipe_ref, **error_fields(exc=not_found_error)},+ )results[pipe.pipe_ref] = DryRunOutput(pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.SKIPPED, error_message=error_message)@@ -497,7 +501,7 @@ class BundleValidator:# cause/context chain — testing exc itself first — to reclassify it as SKIPPED.if self._root_cause_is(exc=exc, exc_type=PipeNotFoundError):error_message = f"Skipped dry run for pipe '{pipe.pipe_ref}': unresolved dependency: {exc}"- log.verbose(error_message)+ log.verbose("A pipe's dry run was skipped for an unresolved dependency", fields={"pipe_ref": pipe.pipe_ref, **error_fields(exc=exc)})return DryRunOutput(pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.SKIPPED, error_message=error_message)formatted_error = format_pydantic_validation_error(exc) if isinstance(exc, ValidationError) else str(exc)error_message = f"Dry run failed for pipe '{pipe.pipe_ref}': {formatted_error}"diff --git a/pipelex/pipeline/execution_seams.py b/pipelex/pipeline/execution_seams.pyindex ca18b77f1..f30b8c2a3 100644--- a/pipelex/pipeline/execution_seams.py+++ b/pipelex/pipeline/execution_seams.py@@ -148,7 +148,7 @@ def acquire_library(except (OSError, RuntimeError):resolved_uri = Path(uri)if resolved_uri in current_library.loaded_mthds_paths:- log.verbose(f"Bundle '{uri}' already loaded from library directories, skipping")+ log.verbose(f"Bundle '{uri}' was skipped, already loaded from library directories")else:blueprints_to_load.append(blueprint)diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.pyindex 61567f529..4ce72e06f 100644--- a/pipelex/pipeline/pipeline_run_setup.py+++ b/pipelex/pipeline/pipeline_run_setup.py@@ -488,7 +488,7 @@ async def pipeline_run_setup(# it, so its traceback would print the setup error's text, which the setup error's own# catcher reports, and which can quote a run's inputs.log.error(- "Closing the graph tracer also failed while cleaning up after the setup failed; the setup error is raised",+ "The graph tracer could not be closed after the run setup failed",fields=error_fields(exc=close_error),)finally:diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.pyindex dc2fc8e9c..5bf251052 100644--- a/pipelex/pipeline/validate_in_process.py+++ b/pipelex/pipeline/validate_in_process.py@@ -182,7 +182,7 @@ async def _validate_bundles_in_scope(# As fields and no traceback: the validation error is chained onto this one, so its traceback would# print the validation error's text, which can quote the bundle, and which its own catcher reports.log.error(- "The teardown of the validation library also failed after the validation failed; the original error is raised",+ "The validation library could not be torn down after the validation failed",fields={"caller": log_context, "library_id": validation_library_id, **error_fields(exc=teardown_error)},)return build_validation_report(diff --git a/pipelex/providers/anthropic/anthropic_factory.py b/pipelex/providers/anthropic/anthropic_factory.pyindex ed985a93f..f0f437fa5 100644--- a/pipelex/providers/anthropic/anthropic_factory.py+++ b/pipelex/providers/anthropic/anthropic_factory.py@@ -123,8 +123,8 @@ class AnthropicFactory:raise AwsCredentialsError(msg) from excif is_bedrock_token_in_env:log.debug(- f"Ignoring {BEDROCK_TOKEN_VAR_NAME} from the environment: "- f'bedrock_access_variant = "{BedrockAccessVariant.AWS_ACCESS}" signs with the configured AWS access keys.'+ f"The {BEDROCK_TOKEN_VAR_NAME} environment variable was ignored, since "+ f'bedrock_access_variant = "{BedrockAccessVariant.AWS_ACCESS}" signs with the configured AWS access keys')return AsyncAnthropicBedrockSigV4(aws_access_key=aws_access_key_id,diff --git a/pipelex/providers/bedrock/bedrock_client_aiobotocore.py b/pipelex/providers/bedrock/bedrock_client_aiobotocore.pyindex b41588d51..ff48be2dd 100644--- a/pipelex/providers/bedrock/bedrock_client_aiobotocore.py+++ b/pipelex/providers/bedrock/bedrock_client_aiobotocore.py@@ -14,9 +14,9 @@ if TYPE_CHECKING:class BedrockClientAiobotocore(BedrockClientProtocol):def __init__(self, aws_region: str):- log.debug(f"Init BedrockClientAiobotocore with region '{aws_region}'")self.aws_region = aws_regionself.session = get_session()+ log.debug(f"A Bedrock client was made on aiobotocore for region '{aws_region}'")@overrideasync def chat(diff --git a/pipelex/providers/bedrock/bedrock_client_boto3.py b/pipelex/providers/bedrock/bedrock_client_boto3.pyindex 151861ad0..c96079a86 100644--- a/pipelex/providers/bedrock/bedrock_client_boto3.py+++ b/pipelex/providers/bedrock/bedrock_client_boto3.py@@ -12,8 +12,8 @@ from pipelex.providers.bedrock.bedrock_message import BedrockMessageDictListclass BedrockClientBoto3(BedrockClientProtocol):def __init__(self, aws_region: str):- log.debug(f"Initializing BedrockClientBoto3 with region '{aws_region}'")self.boto3_client = boto3.client(service_name="bedrock-runtime", region_name=aws_region) # pyright: ignore[reportUnknownMemberType]+ log.debug(f"A Bedrock client was made on boto3 for region '{aws_region}'")@overrideasync def chat(diff --git a/pipelex/providers/google/google_factory.py b/pipelex/providers/google/google_factory.pyindex 950d97fbd..65a46c957 100644--- a/pipelex/providers/google/google_factory.py+++ b/pipelex/providers/google/google_factory.py@@ -1,9 +1,12 @@import asyncioimport base64+from collections.abc import Coroutine+from typing import Any, ClassVarfrom google.genai import types as genai_typesfrom google.genai.client import Client as GoogleGenAiClient+from pipelex import logfrom pipelex.cogt.document.prompt_document import PromptDocumentfrom pipelex.cogt.document.prompt_document_utils import prepare_prompt_document_as_base64from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError@@ -14,9 +17,13 @@ from pipelex.cogt.llm.llm_prompt import LLMPromptfrom pipelex.cogt.model_backends.backend import InferenceBackendfrom pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategoryfrom pipelex.config import get_config+from pipelex.tools.log.error_fields import error_fieldsclass GoogleFactory:+ # The background tasks closing a Google async client, each held until it is done (see schedule_client_close)+ _pending_client_closes: ClassVar[set["asyncio.Task[None]"]] = set()+@classmethoddef make_google_client(cls, backend: InferenceBackend) -> GoogleGenAiClient:"""Create a Google Gemini API client."""@@ -27,6 +34,31 @@ class GoogleFactory:http_options = genai_types.HttpOptions(retry_options=genai_types.HttpRetryOptions(attempts=transport_max_retries + 1))return GoogleGenAiClient(api_key=backend.api_key, http_options=http_options)+ @classmethod+ def schedule_client_close(cls, *, event_loop: asyncio.AbstractEventLoop, close_coroutine: Coroutine[Any, Any, None]) -> None:+ """Close a Google async client in a background task on a running event loop, for a worker's teardown.++ The event loop keeps only a weak reference to a task, so a close task nothing else holds could be garbage-collected+ before it finishes. The class holds each one until it is done, when its done callbacks drop it and log a failure.+ """+ close_task = event_loop.create_task(close_coroutine)+ cls._pending_client_closes.add(close_task)+ close_task.add_done_callback(cls._pending_client_closes.discard)+ close_task.add_done_callback(lambda done: cls.log_client_close_failure(close_task=done))++ @classmethod+ def log_client_close_failure(cls, *, close_task: "asyncio.Task[None]") -> None:+ """Say at DEBUG why the background task closing a Google async client failed, as that task's done callback.++ A worker's teardown never raises, so a close that fails is only logged. A cancelled task holds no exception to+ read: ``Task.exception()`` raises ``CancelledError`` for it, which would escape the callback.+ """+ if close_task.cancelled():+ return+ close_exc = close_task.exception()+ if close_exc is not None:+ log.debug("A Google async client could not be closed", fields=error_fields(exc=close_exc))+@classmethodasync def prepare_image_part(cls, prompt_image: PromptImage) -> genai_types.Part:"""Convert a PromptImage to Google genai Part format.diff --git a/pipelex/providers/google/google_img_gen_worker.py b/pipelex/providers/google/google_img_gen_worker.pyindex d37d2be07..c92adbe55 100644--- a/pipelex/providers/google/google_img_gen_worker.py+++ b/pipelex/providers/google/google_img_gen_worker.py@@ -20,6 +20,7 @@ from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inffrom pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.providers.google.google_factory import GoogleFactoryfrom pipelex.reporting.reporting_protocol import ReportingProtocol+from pipelex.tools.log.error_fields import error_fieldsclass GoogleImgGenWorker(ImgGenWorkerAbstract):@@ -54,29 +55,25 @@ class GoogleImgGenWorker(ImgGenWorkerAbstract):try:# First, try to use the loop captured at creation time if it's still runningif self._event_loop is not None and self._event_loop.is_running():- # Schedule cleanup on the captured loop and store reference to prevent garbage collection- task = self._event_loop.create_task(self.genai_async_client.aclose())- # Add a callback to log any errors that occur during cleanup- task.add_done_callback(lambda t: log.debug(f"Google async client cleanup error: {t.exception()}") if t.exception() else None)+ # Schedule cleanup on the captured loop+ GoogleFactory.schedule_client_close(event_loop=self._event_loop, close_coroutine=self.genai_async_client.aclose())return# Otherwise, try to get the current running looptry:current_loop = asyncio.get_running_loop()- # Schedule cleanup on the current running loop and store reference to prevent garbage collection- task = current_loop.create_task(self.genai_async_client.aclose())- # Add a callback to log any errors that occur during cleanup- task.add_done_callback(lambda t: log.debug(f"Google async client cleanup error: {t.exception()}") if t.exception() else None)+ # Schedule cleanup on the current running loop+ GoogleFactory.schedule_client_close(event_loop=current_loop, close_coroutine=self.genai_async_client.aclose())except RuntimeError:# No running event loop, we can safely use asyncio.run()try:asyncio.run(self.genai_async_client.aclose())except Exception as exc: # ruff: ignore[blind-except]# Best-effort: asyncio.run() runs aclose(), whose failure surface is not enumerable; teardown must never fail.- log.debug(f"Error closing Google async client during teardown: {exc}")+ log.debug("A Google async client could not be closed", fields=error_fields(exc=exc))except Exception as exc: # ruff: ignore[blind-except]# Best-effort cleanup boundary: teardown must never fail, whatever client/event-loop close throws.- log.debug(f"Error during Google async client teardown: {exc}")+ log.debug("A Google async client could not be closed", fields=error_fields(exc=exc))@overrideasync def _gen_image(@@ -135,7 +132,7 @@ class GoogleImgGenWorker(ImgGenWorkerAbstract):usage_metadata: genai_types.GenerateContentResponseUsageMetadata | None = response.usage_metadataif not usage_metadata:- log.warning("No usage metadata returned from Google")+ log.warning("Google returned no usage metadata")if usage_metadata and (img_gen_tokens_usage := img_gen_job.job_report.img_gen_tokens_usage):request_tokens = GoogleFactory.extract_token_usage(usage_metadata)diff --git a/pipelex/providers/google/google_llm_worker.py b/pipelex/providers/google/google_llm_worker.pyindex 4036e249a..86f06b833 100644--- a/pipelex/providers/google/google_llm_worker.py+++ b/pipelex/providers/google/google_llm_worker.py@@ -31,6 +31,7 @@ from pipelex.config import get_configfrom pipelex.providers.google.google_exceptions import GoogleLLMWorkerErrorfrom pipelex.providers.google.google_factory import GoogleFactoryfrom pipelex.reporting.reporting_protocol import ReportingProtocol+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.typing.pydantic_utils import BaseModelTypeVarif TYPE_CHECKING:@@ -82,29 +83,25 @@ class GoogleLLMWorker(LLMWorkerAbstract):try:# First, try to use the loop captured at creation time if it's still runningif self._event_loop is not None and self._event_loop.is_running():- # Schedule cleanup on the captured loop and store reference to prevent garbage collection- task = self._event_loop.create_task(self.genai_async_client.aclose())- # Add a callback to log any errors that occur during cleanup- task.add_done_callback(lambda t: log.debug(f"Google async client cleanup error: {t.exception()}") if t.exception() else None)+ # Schedule cleanup on the captured loop+ GoogleFactory.schedule_client_close(event_loop=self._event_loop, close_coroutine=self.genai_async_client.aclose())return# Otherwise, try to get the current running looptry:current_loop = asyncio.get_running_loop()- # Schedule cleanup on the current running loop and store reference to prevent garbage collection- task = current_loop.create_task(self.genai_async_client.aclose())- # Add a callback to log any errors that occur during cleanup- task.add_done_callback(lambda t: log.debug(f"Google async client cleanup error: {t.exception()}") if t.exception() else None)+ # Schedule cleanup on the current running loop+ GoogleFactory.schedule_client_close(event_loop=current_loop, close_coroutine=self.genai_async_client.aclose())except RuntimeError:# No running event loop, we can safely use asyncio.run()try:asyncio.run(self.genai_async_client.aclose())except Exception as exc: # ruff: ignore[blind-except]# Best-effort: asyncio.run() runs aclose(), whose failure surface is not enumerable; teardown must never fail.- log.debug(f"Error closing Google async client during teardown: {exc}")+ log.debug("A Google async client could not be closed", fields=error_fields(exc=exc))except Exception as exc: # ruff: ignore[blind-except]# Best-effort cleanup boundary: teardown must never fail, whatever client/event-loop close throws.- log.debug(f"Error during Google async client teardown: {exc}")+ log.debug("A Google async client could not be closed", fields=error_fields(exc=exc))########################################################## Reasoning helpersdiff --git a/pipelex/providers/mistral/mistral_factory.py b/pipelex/providers/mistral/mistral_factory.pyindex 2fecb430a..dad1b2f1e 100644--- a/pipelex/providers/mistral/mistral_factory.py+++ b/pipelex/providers/mistral/mistral_factory.py@@ -39,6 +39,7 @@ from pipelex.cogt.model_backends.backend import InferenceBackendfrom pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategoryfrom pipelex.config import get_configfrom pipelex.providers.mistral.mistral_exceptions import MistralExtractResponseError+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.uri.prepared_file import PreparedFileBase64, PreparedFileHttpUrl, PreparedFileLocalPath@@ -261,7 +262,7 @@ class MistralFactory:return base64_strexcept ValueError as exc:# base64 decode/encode failed (binascii.Error / UnicodeDecodeError, both ValueError subclasses) — return the original string unmodified- log.debug(f"Error cleaning base64: {exc}")+ log.debug("A base64 image could not be cleaned and was kept as it came", fields=error_fields(exc=exc))return base64_str@classmethoddiff --git a/pipelex/providers/openai/openai_client_factory.py b/pipelex/providers/openai/openai_client_factory.pyindex 5dbae6677..5a86f0bf9 100644--- a/pipelex/providers/openai/openai_client_factory.py+++ b/pipelex/providers/openai/openai_client_factory.py@@ -51,7 +51,6 @@ class OpenAIClientFactory:the_client: openai.AsyncOpenAImatch sdk_variant:case OpenAISdkVariant.AZURE_OPENAI | OpenAISdkVariant.AZURE_OPENAI_RESPONSES:- log.debug(f"Making AsyncAzureOpenAI client with endpoint: {backend.endpoint}")if backend.endpoint is None:msg = "Azure OpenAI endpoint is not set"raise OpenAIClientFactoryError(msg)@@ -61,6 +60,7 @@ class OpenAIClientFactory:api_version=backend.get_extra_config(AzureExtraField.API_VERSION),max_retries=transport_max_retries,)+ log.debug(f"An AsyncAzureOpenAI client was made with endpoint {backend.endpoint}")case (OpenAISdkVariant.OPENAI| OpenAISdkVariant.OPENAI_RESPONSES@@ -68,11 +68,11 @@ class OpenAIClientFactory:| OpenAISdkVariant.BLACKBOXAI_IMG_GEN| OpenAISdkVariant.OPENROUTER_IMG_GEN):- log.debug(f"Making AsyncOpenAI client with endpoint: {backend.endpoint}")the_client = openai.AsyncOpenAI(api_key=api_key,base_url=backend.endpoint,max_retries=transport_max_retries,)+ log.debug(f"An AsyncOpenAI client was made with endpoint {backend.endpoint}")return the_clientdiff --git a/pipelex/providers/openai/openai_img_gen_worker.py b/pipelex/providers/openai/openai_img_gen_worker.pyindex a09e835d8..cac564576 100644--- a/pipelex/providers/openai/openai_img_gen_worker.py+++ b/pipelex/providers/openai/openai_img_gen_worker.py@@ -76,7 +76,7 @@ class OpenAIImgGenWorker(ImgGenWorkerAbstract):# only valid on the images.edit route (images.generate rejects it with a 400).if "image" in args_dict:if args_dict.pop("moderation", None) is not None:- log.warning("OpenAI images.edit does not accept 'moderation'; dropping the kwarg")+ log.warning("The moderation setting was dropped from an OpenAI image edit, which takes none")images_response = cast("ImagesResponse", await self.openai_client.images.edit(**args_dict))else:images_response = cast("ImagesResponse", await self.openai_client.images.generate(**args_dict))diff --git a/pipelex/providers/typesafe/typesafe_judgment_worker.py b/pipelex/providers/typesafe/typesafe_judgment_worker.pyindex 66c843416..770224abc 100644--- a/pipelex/providers/typesafe/typesafe_judgment_worker.py+++ b/pipelex/providers/typesafe/typesafe_judgment_worker.py@@ -102,8 +102,7 @@ class TypesafeJudgmentWorker(JudgmentWorkerAbstract):"""if response.model != self.inference_model.model_id:log.warning(- "The provider answered under another model than the pinned one, so verdicts and their thresholds may not mean what "- "they meant under the pinned model",+ "A judgment was answered by another model than the pinned one",fields={"model_handle": self.inference_model.name,"backend_name": self.inference_model.backend_name,diff --git a/pipelex/reporting/cost_report_renderer.py b/pipelex/reporting/cost_report_renderer.pyindex 11e72232a..c8ee18aef 100644--- a/pipelex/reporting/cost_report_renderer.py+++ b/pipelex/reporting/cost_report_renderer.py@@ -81,7 +81,7 @@ def render_run_cost_report(print_to_console=print_to_console,)except (OSError, UnicodeEncodeError, PipelexError) as cost_report_error:- log.warning("The cost report could not be generated; the run itself succeeded", fields=error_fields(exc=cost_report_error))+ log.warning("The cost report of a successful run could not be generated", fields=error_fields(exc=cost_report_error))def render_cost_report_for_output(pipe_output: PipeOutput) -> None:diff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.pyindex a09b599cd..3a3596945 100644--- a/pipelex/reporting/reporting_manager.py+++ b/pipelex/reporting/reporting_manager.py@@ -128,7 +128,7 @@ class ReportingManager(ReportingProtocol):llm_tokens_usage = llm_job.job_report.llm_tokens_usageif not llm_tokens_usage:- log.warning("LLM job has no llm_tokens_usage")+ self._warn_of_missing_usage(inference_job=llm_job)returnself._emit_usage_event(llm_job, tokens_usage=llm_tokens_usage)@@ -137,7 +137,7 @@ class ReportingManager(ReportingProtocol):img_gen_tokens_usage = img_gen_job.job_report.img_gen_tokens_usageif not img_gen_tokens_usage:- log.warning("ImgGen job has no img_gen_tokens_usage")+ self._warn_of_missing_usage(inference_job=img_gen_job)returnself._emit_usage_event(img_gen_job, tokens_usage=img_gen_tokens_usage)@@ -146,7 +146,7 @@ class ReportingManager(ReportingProtocol):extract_tokens_usage = extract_job.job_report.extract_tokens_usageif not extract_tokens_usage:- log.warning("Extract job has no extract_tokens_usage")+ self._warn_of_missing_usage(inference_job=extract_job)returnself._emit_usage_event(extract_job, tokens_usage=extract_tokens_usage)@@ -155,7 +155,7 @@ class ReportingManager(ReportingProtocol):search_tokens_usage = search_job.job_report.search_tokens_usageif not search_tokens_usage:- log.warning("Search job has no search_tokens_usage")+ self._warn_of_missing_usage(inference_job=search_job)returnself._emit_usage_event(search_job, tokens_usage=search_tokens_usage)@@ -164,11 +164,16 @@ class ReportingManager(ReportingProtocol):judgment_tokens_usage = judgment_job.job_report.judgment_tokens_usageif not judgment_tokens_usage:- log.warning("Judgment job has no judgment_tokens_usage")+ self._warn_of_missing_usage(inference_job=judgment_job)returnself._emit_usage_event(judgment_job, tokens_usage=judgment_tokens_usage)+ @classmethod+ def _warn_of_missing_usage(cls, *, inference_job: InferenceJobAbstract) -> None:+ """Warn that an inference job reported no usage: one event whichever family the job is of, its class a field."""+ log.warning("An inference job reported no usage", fields={"inference_job_type": type(inference_job).__name__})+def _emit_usage_event(self, inference_job: InferenceJobAbstract, *, tokens_usage: AnyTokensUsage) -> None:"""Emit a UsageReportEvent for this job.@@ -294,7 +299,7 @@ class ReportingManager(ReportingProtocol):try:process_event_log = ActivityEventLogCache.get_or_create(tracing_config)except (OSError, MissingDependencyError, PipelexConfigError) as exc:- log.warning("The runner-side activity event log could not be built, so a usage event was dropped", fields=error_fields(exc=exc))+ log.warning("The activity event log could not be built and a usage event was dropped", fields=error_fields(exc=exc))returnif process_event_log is None:@@ -332,6 +337,6 @@ class ReportingManager(ReportingProtocol):self._report_judgment_job(judgment_job=inference_job)else:log.error(- "The reporting manager cannot report this type of inference job, so its usage is lost",+ "The usage of an inference job of an unknown type was lost",fields={"inference_job_type": type(inference_job).__name__},)diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex 98eef4283..db9d4ec7d 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -743,7 +743,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.self.class_registry.teardown()func_registry.teardown()- log.verbose(f"{PACKAGE_NAME} version {PACKAGE_VERSION} teardown done (except config & logs)")+ log.verbose(f"The {PACKAGE_NAME} {PACKAGE_VERSION} runtime was torn down, except its config and logs")finally:# The runtime hub releases its process-global config and boot-scoped flags. ``class_registry_scoping``# is reset herediff --git a/pipelex/runtime_hub.py b/pipelex/runtime_hub.pyindex 05f84b960..65beba670 100644--- a/pipelex/runtime_hub.py+++ b/pipelex/runtime_hub.py@@ -47,6 +47,7 @@ from pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.registries.class_registry_access import get_class_registry as _get_active_class_registryfrom pipelex.system.registries.func_registry import FuncRegistryfrom pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.misc.pretty import PrettyPrinter, PrettyPrintModefrom pipelex.tools.misc.rich_extra import require_richfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract@@ -188,7 +189,7 @@ class RuntimeHub:def set_config(self, config: ConfigRoot):if self._config is not None:- log.warning("set_config() got called but it has already been set")+ log.warning("A second configuration was ignored, since one is already set")returnself._config = config@@ -663,8 +664,8 @@ def resolve_run_mode_for_boot(*, requested: PipeRunMode) -> PipeRunMode:"""if is_dry_run_forced() and requested.is_live:log.warning(- "LIVE run requested under a keyless boot (needs_inference=False): forcing run_mode to DRY — "- "outputs will be synthetic mocks, not real inference."+ "A live run was forced dry because this boot has no inference",+ fields={USER_ACTION_FIELD: "Boot with inference to get real outputs rather than synthetic mocks"},)return PipeRunMode.DRYreturn requesteddiff --git a/pipelex/system/configuration/config_surface.py b/pipelex/system/configuration/config_surface.pyindex 7d865822c..49424a810 100644--- a/pipelex/system/configuration/config_surface.py+++ b/pipelex/system/configuration/config_surface.py@@ -39,6 +39,7 @@ from pipelex.migration.exceptions import MigrationLedgerErrorfrom pipelex.migration.ledger import MigrationLedger, load_ledger_cached, packaged_migration_dirfrom pipelex.migration.plan import MigrationPlanfrom pipelex.system.telemetry.otel_constants import OTelLogAttr+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.misc.json_utils import deep_update# The reserved in-file table and key. Every configuration-surface reader tolerates them and@@ -269,46 +270,35 @@ class StaleConfigurationWarning(NamedTuple):A loader builds it when its retry succeeds and either emits it there or parks it for the callerthat owes the user the one copy of it (`take_stale_configuration_warning` on the mainconfiguration's loader and on the inference backend library). **It is emitted as one line per- stale file**, each a fixed message naming that file's remedy with the file in `file.path`: the- file list is a value, a value rides a field, and a field the console cuts at its width cannot- carry a list of paths a person has to read. A load that spans files in and out of the walk+ stale file**, each the same fixed message with the file in `file.path` and that file's remedy in+ `user_action`: the file list is a value, a value rides a field, and a field the console cuts at its+ width cannot carry a list of paths a person has to read. A load that spans files in and out of the walktherefore gets both remedies, each on the lines of its own files."""files: list[StaleConfigurationFile]def emit(self) -> None:- """One line per stale file, a fixed message naming that file's remedy.+ """One line per stale file, one fixed message, with that file's remedy as its advice.The remedy is the command where it reaches the file, with the changes it reports it cannot apply where some- steps are blocked, and the file's own place where it does not. Every message says that nothing was written,- which is why the same warning comes back at the next boot.+ steps are blocked, and the file's own place where it does not. The message says that the file was migrated in+ memory only, which is why the same warning comes back at the next boot. Whatever its remedy, a stale file is one+ event, so a log store counts every stale file under the one message."""for stale_file in self.files:if stale_file.is_reached_by_migrate and stale_file.has_blocked_steps:- log.warning(- "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "- "run `pipelex migrate` to update it, and make by hand the changes it reports it cannot apply",- fields=stale_file.log_fields(),- )+ user_action = "Run pipelex migrate to update it, and make by hand the changes it reports it cannot apply"elif stale_file.is_reached_by_migrate:- log.warning(- "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "- "run `pipelex migrate` to update it",- fields=stale_file.log_fields(),- )+ user_action = "Run pipelex migrate to update it"elif stale_file.has_blocked_steps:- log.warning(- "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "- "`pipelex migrate` does not reach it, so update it where it lives, including changes no migration can apply for you",- fields=stale_file.log_fields(),- )+ user_action = "Update it where it lives, with the changes no migration can apply, since pipelex migrate does not reach it"else:- log.warning(- "A configuration file is out of date and was read as if it had been migrated, and nothing was written; "- "`pipelex migrate` does not reach it, so update it where it lives",- fields=stale_file.log_fields(),- )+ user_action = "Update it where it lives, since pipelex migrate does not reach it"+ log.warning(+ "A configuration file is out of date and was migrated in memory only",+ fields={**stale_file.log_fields(), USER_ACTION_FIELD: user_action},+ )def stale_configuration_warning(*, plans: Sequence[MigrationPlan], walked_dirs: Sequence[Path]) -> StaleConfigurationWarning:diff --git a/pipelex/system/environment.py b/pipelex/system/environment.pyindex b46b9946b..16db3e36f 100644--- a/pipelex/system/environment.py+++ b/pipelex/system/environment.py@@ -110,7 +110,7 @@ def get_positive_int_env(*, env_var: str, default: int) -> int:parsed = 0if parsed <= 0:log.warning(- "An environment variable holds no positive integer, so its default applies",+ "An environment variable holding no positive integer was ignored for its default",fields={"env_var": env_var, "default_value": default},)return defaultdiff --git a/pipelex/system/registries/func_registry_utils.py b/pipelex/system/registries/func_registry_utils.pyindex a1dba3107..08c875c36 100644--- a/pipelex/system/registries/func_registry_utils.py+++ b/pipelex/system/registries/func_registry_utils.py@@ -31,9 +31,7 @@ class FuncRegistryUtils:functions_registered = 0if not hasattr(package, "__path__"):- log.warning(- "A PipeFunc package is a plain module with no submodules to walk, so nothing was registered", fields={"module_name": package_name}- )+ log.warning("Nothing was registered from a PipeFunc package that is a plain module", fields={"module_name": package_name})return 0log.verbose(f"Walking package {package_name} at {package.__path__}")@@ -70,7 +68,7 @@ class FuncRegistryUtils:source_file=modname,)log.warning(- "A function decorated with @pipe_func is not eligible, and was not registered",+ "An ineligible PipeFunc function was not registered",fields={"function_name": func_name, "module_name": modname, "eligibility_error": eligibility_error},)@@ -203,7 +201,7 @@ class FuncRegistryUtils:source_file=str(file_path),)log.warning(- "A function decorated with @pipe_func is not eligible, and was not registered",+ "An ineligible PipeFunc function was not registered",fields={"function_name": func_name, OTelLogAttr.FILE_PATH: str(file_path), "eligibility_error": eligibility_error},)except ModuleFileError:@@ -216,13 +214,13 @@ class FuncRegistryUtils:# registry" raised much later by the PipeFunc validator, with the real ImportError (the# actual cause) otherwise swallowed here and invisible.log.warning(- "A Python file could not be imported while registering PipeFuncs, so its functions are unavailable",+ "A Python file could not be imported while registering PipeFuncs",fields={OTelLogAttr.FILE_PATH: str(file_path), **error_fields(exc=exc)},)except SyntaxError as exc:# Potentially problematic: invalid Python syntax may indicate broken codelog.warning(- "A Python file has a syntax error, so its PipeFuncs are unavailable",+ "A Python file with a syntax error was skipped while registering PipeFuncs",fields={OTelLogAttr.FILE_PATH: str(file_path), **error_fields(exc=exc)},)diff --git a/pipelex/system/telemetry/exception_capture.py b/pipelex/system/telemetry/exception_capture.pyindex 40066cb62..9bcb47253 100644--- a/pipelex/system/telemetry/exception_capture.py+++ b/pipelex/system/telemetry/exception_capture.py@@ -7,6 +7,7 @@ from pipelex import logfrom pipelex.system.caller_identity import CallerIdentity, find_stamped_caller_identity, get_current_caller_identityfrom pipelex.system.telemetry.otel_constants import PostHogAttrfrom pipelex.system.telemetry.telemetry_identity import StreamIdentityRule, TelemetryIdentity+from pipelex.tools.log.error_fields import error_fieldsif TYPE_CHECKING:# Deferred import: avoid pulling heavy SDK at module-load time@@ -141,7 +142,7 @@ class ExceptionCapture:client.capture_exception(posthog_exc_info, properties={PostHogAttr.PROCESS_PERSON_PROFILE: False})except Exception as capture_exc: # ruff: ignore[blind-except]# Telemetry must never break the app: a failed exception capture is logged at debug and swallowed.- log.debug(f"Failed to capture exception to PostHog: {capture_exc}")+ log.debug("An exception could not be captured to PostHog", fields=error_fields(exc=capture_exc))@classmethoddef is_marked_as_captured(cls, *, exception: "ExceptionArg") -> bool:diff --git a/pipelex/system/telemetry/posthog_span_exporter.py b/pipelex/system/telemetry/posthog_span_exporter.pyindex ac584b65c..9411da8a6 100644--- a/pipelex/system/telemetry/posthog_span_exporter.py+++ b/pipelex/system/telemetry/posthog_span_exporter.py@@ -23,6 +23,7 @@ from pipelex.system.telemetry.otel_constants import ()from pipelex.system.telemetry.telemetry_config import TelemetryRedactionConfigfrom pipelex.system.telemetry.telemetry_identity import RunIdentityPolicy, TelemetryIdentity+from pipelex.tools.log.error_fields import error_fieldsclass PostHogSpanExporter(SpanExporter):@@ -372,7 +373,7 @@ class PostHogSpanExporter(SpanExporter):except Exception as exc: # ruff: ignore[blind-except]# Fail silently to avoid breaking app- log.debug(f"Failed to export span to PostHog: {exc}")+ log.debug("A span could not be exported to PostHog", fields=error_fields(exc=exc))return SpanExportResult.SUCCESSdiff --git a/pipelex/system/telemetry/telemetry_identity.py b/pipelex/system/telemetry/telemetry_identity.pyindex 1f7b11381..751626635 100644--- a/pipelex/system/telemetry/telemetry_identity.py+++ b/pipelex/system/telemetry/telemetry_identity.py@@ -52,6 +52,7 @@ from pipelex.system.caller_identity import CallerIdentityfrom pipelex.system.storage_scope import DRY_RUN_USER_ID, LOCAL_USER_ID, SINGLE_TENANT_USER_IDfrom pipelex.system.telemetry.otel_constants import LangfuseSpanAttr, PipelexSpanAttrfrom pipelex.system.telemetry.telemetry_config import PostHogMode+from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tools.log.log import logfrom pipelex.tools.misc.json_utils import pure_json_str@@ -273,22 +274,22 @@ class TelemetryIdentity(BaseModel):if raw is None:return {}if not isinstance(raw, str):- log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_EXTRAS}': expected a JSON string, got {type(raw).__name__}")+ log.debug(f"The span attribute '{PipelexSpanAttr.RUN_EXTRAS}' holds a {type(raw).__name__}, not a JSON string, and was ignored")return {}try:decoded = json.loads(raw)except ValueError as exc:- log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_EXTRAS}': not decodable JSON ({exc})")+ log.debug(f"The span attribute '{PipelexSpanAttr.RUN_EXTRAS}' is not decodable JSON and was ignored", fields=error_fields(exc=exc))return {}if not isinstance(decoded, dict):- log.debug(f"Ignoring span attribute '{PipelexSpanAttr.RUN_EXTRAS}': expected a JSON object, got {type(decoded).__name__}")+ log.debug(f"The span attribute '{PipelexSpanAttr.RUN_EXTRAS}' holds a {type(decoded).__name__}, not a JSON object, and was ignored")return {}extras: dict[str, str] = {}for extras_key, extras_value in decoded.items(): # type: ignore[union-attr]if isinstance(extras_key, str) and isinstance(extras_value, str):extras[extras_key] = extras_valueelse:- log.debug(f"Ignoring a non-string entry in span attribute '{PipelexSpanAttr.RUN_EXTRAS}'")+ log.debug(f"An entry of the span attribute '{PipelexSpanAttr.RUN_EXTRAS}' that is not a string was ignored")return extrasdiff --git a/pipelex/system/telemetry/telemetry_manager.py b/pipelex/system/telemetry/telemetry_manager.pyindex 56e24808e..d49f37fa3 100644--- a/pipelex/system/telemetry/telemetry_manager.py+++ b/pipelex/system/telemetry/telemetry_manager.py@@ -69,11 +69,11 @@ class TelemetryManager(TelemetryManagerAbstract):otlp_exporters=telemetry_config.otlp,langfuse_config=telemetry_config.langfuse,)- log.verbose("AI tracing enabled: OpenTelemetry tracer created")+ log.verbose("AI tracing is enabled, and an OpenTelemetry tracer was made")else:self._otel_tracer = Noneself._tracer_provider = None- log.verbose("AI tracing disabled: No OpenTelemetry tracer created")+ log.verbose("AI tracing is disabled, and no OpenTelemetry tracer was made")# Wrap capture_exception to sanitize before sendingif self.custom_posthog_client:@@ -160,7 +160,7 @@ class TelemetryManager(TelemetryManagerAbstract):return Nonesanitized = self._sanitized_exception_arg(exception=resolved)except Exception as sanitize_exc: # ruff: ignore[blind-except]- log.debug(f"Dropped an exception capture the privacy redaction could not complete: {sanitize_exc!r}")+ log.debug("An exception capture the privacy redaction could not complete was dropped", fields=error_fields(exc=sanitize_exc))return Noneresult = original_capture_exception(sanitized, **kwargs)ExceptionCapture.carry_capture_marks(source=sanitized, target=resolved)@@ -331,17 +331,17 @@ class TelemetryManager(TelemetryManagerAbstract):self._exception_capture.close()except Exception as exc: # ruff: ignore[blind-except]# Telemetry teardown must never break the app: a close failure is logged at debug and swallowed.- log.debug(f"Error closing exception capture: {exc}")+ log.debug("The exception capture could not be closed", fields=error_fields(exc=exc))# Then, shutdown the TracerProvider to flush all pending spans# This MUST happen before PostHog shutdown, otherwise spans won't be exportedif self._tracer_provider:try:- log.verbose("Shutting down OTel TracerProvider (flushing pending spans)...")+ log.verbose("The OpenTelemetry tracer provider is shutting down and flushing its pending spans")self._tracer_provider.shutdown()except Exception as exc: # ruff: ignore[blind-except]# Suppress any shutdown errors to avoid cascading failures- log.debug(f"Error during TracerProvider shutdown: {exc}")+ log.debug("The OpenTelemetry tracer provider could not be shut down", fields=error_fields(exc=exc))# Then shutdown the PostHog clientif self.custom_posthog_client:@@ -349,7 +349,7 @@ class TelemetryManager(TelemetryManagerAbstract):self.custom_posthog_client.shutdown()except Exception as exc: # ruff: ignore[blind-except]# Suppress any shutdown errors to avoid cascading failures- log.debug(f"Error during custom PostHog shutdown: {exc}")+ log.debug("The custom PostHog client could not be shut down", fields=error_fields(exc=exc))# Clear singleton instanceTelemetryManagerAbstract.clear_instance()@@ -382,7 +382,7 @@ class TelemetryManager(TelemetryManagerAbstract):case PostHogMode.IDENTIFIED:if not self.telemetry_config.custom_posthog.user_id:log.warning(- "An event could not be tracked as identified because no user_id is set, and was tracked as anonymous",+ "An event with no user id to identify it was tracked as anonymous",fields={"event_name": event_name},)self._capture_custom_event(event_name, properties=tracked_properties, identity=TelemetryIdentity.make_anonymous())@@ -423,7 +423,7 @@ class TelemetryManager(TelemetryManagerAbstract):dict must not carry that mark away with it."""if not self.custom_posthog_client:- log.error("Could not track event to custom telemetry because custom_posthog_client is not set")+ log.error("An event could not be tracked to custom telemetry, which has no PostHog client")returncapture_properties = dict(properties)if identity.distinct_id:@@ -448,7 +448,7 @@ class TelemetryManager(TelemetryManagerAbstract):def is_custom_portkey_logging_enabled(self, *, is_debug_configured: bool) -> bool:is_debug: bool = is_debug_configuredif not is_debug and self.telemetry_config.custom_portkey.force_debug_enabled:- log.verbose("Force-enabling Portkey logging (debug mode) because custom_portkey.force_debug_enabled is set in telemetry configuration")+ log.verbose("Portkey logging (debug mode) is forced on by custom_portkey.force_debug_enabled in the telemetry configuration")is_debug = Trueif is_debug and is_env_var_truthy(OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY):# DEBUG rather than WARNING: honouring DO_NOT_TRACK over every other setting is the documented rule, not a@@ -464,7 +464,7 @@ class TelemetryManager(TelemetryManagerAbstract):def is_custom_portkey_tracing_enabled(self) -> bool:if self.telemetry_config.custom_portkey.force_tracing_enabled and not is_env_var_truthy(OTelConstants.DO_NOT_TRACK_ENV_VAR_KEY):# DEBUG, not INFO: this is asked on every Portkey inference call, and a setting the user chose is no milestone.- log.debug("Force-enabling Portkey tracing because custom_portkey.force_tracing_enabled is set in telemetry configuration")+ log.debug("Portkey tracing is forced on by custom_portkey.force_tracing_enabled in the telemetry configuration")return Trueelse:return Falsediff --git a/pipelex/tools/aws/aws_config.py b/pipelex/tools/aws/aws_config.pyindex e27dc96bf..0a7c9dbf2 100644--- a/pipelex/tools/aws/aws_config.py+++ b/pipelex/tools/aws/aws_config.py@@ -38,7 +38,7 @@ class AwsConfig(ConfigModel):def get_aws_access_keys_with_method(self, *, api_key_method: AwsKeyMethod) -> tuple[str, str, str]:match api_key_method:case AwsKeyMethod.ENV:- log.debug("Getting AWS access keys from environment (key id and secret access key).")+ log.debug("AWS access keys are read from the environment")try:aws_access_key_id = get_required_env(AWS_ACCESS_KEY_ID_VAR_NAME)aws_secret_access_key = get_required_env(AWS_SECRET_ACCESS_KEY_VAR_NAME)@@ -48,7 +48,7 @@ class AwsConfig(ConfigModel):raise AwsCredentialsError(msg) from exccase AwsKeyMethod.SECRET_PROVIDER:- log.debug("Getting AWS secret access key from secrets provider (key id and secret access key).")+ log.debug("AWS access keys are read from the secrets provider")try:aws_access_key_id = get_secret(AWS_ACCESS_KEY_ID_VAR_NAME)aws_secret_access_key = get_secret(AWS_SECRET_ACCESS_KEY_VAR_NAME)diff --git a/pipelex/tools/log/console_fields.py b/pipelex/tools/log/console_fields.pyindex cb51c6004..10c451640 100644--- a/pipelex/tools/log/console_fields.py+++ b/pipelex/tools/log/console_fields.py@@ -22,6 +22,9 @@ unbalanced quote or bracket whose tail reads as another pair. A key is written tline break, a space, an equals sign or an escape sequence can forge neither a line nor a pair. Redaction has alreadyrun when the console renders a record, so what is rendered is what the scrub left.+A record's advice, its ``user_action`` field, is not part of the suffix: it prints whole on a line of its own under the+record, after ``ADVICE_MARK``, since it is what the reader acts on.+Colour follows the name the field was given, from ``FIELD_STYLES``, wherever the field appears, and whatevercollision prefix it landed under; a field outside the map renders dimmed. The map is one table in code, thecolours the pipe announcement has always used. Nothing here imports Rich: the suffix is a list of@@ -40,7 +43,7 @@ from pydantic import BaseModelfrom pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELDfrom pipelex.tools.log.log_context import PIPE_RUN_ID_FIELD, PIPELINE_RUN_ID_FIELD, REQUEST_ID_FIELD-from pipelex.tools.log.log_fields import DATA_FIELD, attached_field_names, given_field_name+from pipelex.tools.log.log_fields import DATA_FIELD, USER_ACTION_FIELD, attached_field_names, given_field_namefrom pipelex.tools.log.log_sink import json_fallback, spell_non_finiteif TYPE_CHECKING:@@ -105,6 +108,10 @@ ESCAPE = "\\"# otherwise read as the end of a pair, the start of the next or an escape, so the suffix cannot be forged.QUOTED_CHARACTERS = frozenset({FIELD_SEPARATOR, KEY_VALUE_SEPARATOR, QUOTE, ESCAPE})+# What starts the line the advice of a record prints on, under the record, and the style the advice is printed in.+ADVICE_MARK = "→ "+ADVICE_STYLE = "cyan"+# A segment of the suffix: its text, and the Rich style it is printed in.StyledSegment = tuple[str, str]@@ -134,11 +141,12 @@ def field_style(*, name: str) -> str:def field_suffix_segments(*, fields: Mapping[str, Any], presented_fields: frozenset[str]) -> list[StyledSegment]:"""The suffix for these fields, a space before each ``key=value``, as styled segments; none when nothing is left to show.- The run identifiers, ``data`` and the fields a layout already presented are left out.+ The run identifiers, ``data``, the fields a layout already presented and the advice, which prints on a line of its+ own, are left out."""segments: list[StyledSegment] = []for name, value in fields.items():- if name in CONSOLE_HIDDEN_FIELDS or name in presented_fields:+ if name in CONSOLE_HIDDEN_FIELDS or name in presented_fields or given_field_name(name=name) == USER_ACTION_FIELD:continuesegments.append((FIELD_SEPARATOR, ""))# The key is written like a value: a name a caller chose can hold a line break that would forge a@@ -149,6 +157,23 @@ def field_suffix_segments(*, fields: Mapping[str, Any], presented_fields: frozenreturn segments+def advice_segments(*, fields: Mapping[str, Any]) -> list[StyledSegment]:+ """The advice the fields carry under ``USER_ACTION_FIELD``, as the line printed under the record; none when they carry none.++ The advice is written whole, on one line, since it is the part of the record its reader acts on: a string as+ itself, anything else as compact JSON, every character a terminal would act on escaped. Read off the name the+ caller gave rather than the one it landed on, as the style is.+ """+ segments: list[StyledSegment] = []+ for name, value in fields.items():+ if given_field_name(name=name) != USER_ACTION_FIELD:+ continue+ string_text = _string_value_text(value=value)+ advice = one_line_text(text=string_text if string_text is not None else _non_string_text(value=value))+ segments.append((f"\n{ADVICE_MARK}{advice}", ADVICE_STYLE))+ return segments++def field_max_length(*, name: str) -> int:"""The longest the console writes a field's value: its entry in ``FIELD_MAX_LENGTHS``, else ``FIELD_VALUE_MAX_LENGTH``.diff --git a/pipelex/tools/log/console_log_sink.py b/pipelex/tools/log/console_log_sink.pyindex c7bc7bd0d..9cae4e3d3 100644--- a/pipelex/tools/log/console_log_sink.py+++ b/pipelex/tools/log/console_log_sink.py@@ -1,11 +1,12 @@-"""The ``console`` sink: the Rich handler with the emoji formatter and every ``[runtime.log.rich_log]`` setting.+"""The ``console`` sink: the Rich handler with every ``[runtime.log.rich_log]`` setting.The handler reads no message as Rich markup: a message is the caller's text, made of values nobody chose,and prints as written, ``list[int]`` and ``[red]`` included. The colour is the sink's own: it renders a-record's fields after its message as a styled ``key=value`` suffix, and a record that names a layout-through that layout's template; what is shown and how it is coloured is in ``console_fields`` and-``console_layouts``. A traceback printed as text, with Rich tracebacks off, goes under the line, after the-suffix.+record's fields after its message as a styled ``key=value`` suffix, a record's advice on a line of its own+under it, and a record that names a layout through that layout's template; what is shown and how it is+coloured is in ``console_fields`` and ``console_layouts``. A line from another library than Pipelex starts+with that library's package name, dimmed, as ``console_prefix`` decides; a Pipelex line has no prefix. A+traceback printed as text, with Rich tracebacks off, goes under the line, after the suffix and the advice.Rich is the ``cli`` extra. It is imported when the handler is built and nowhere else in this module, sothis module asks for Rich only where this sink is the one selected; a process that selects another sink@@ -19,22 +20,21 @@ module does. What is true is that nothing here is the reason.from __future__ import annotations+import loggingimport sysfrom typing import TYPE_CHECKINGfrom typing_extensions import override-from pipelex.tools.log.console_fields import attached_fields, field_suffix_segments+from pipelex.tools.log.console_fields import advice_segments, attached_fields, field_suffix_segmentsfrom pipelex.tools.log.console_layouts import console_layout+from pipelex.tools.log.console_prefix import foreign_package_namefrom pipelex.tools.log.log_config import HighlighterNamefrom pipelex.tools.log.log_fields import LAYOUT_MARK-from pipelex.tools.log.log_formatter import EmojiLogFormatter, channel_prefixfrom pipelex.tools.log.log_sink import LogSink, LogSinkMethod, stream_for_targetfrom pipelex.tools.misc.rich_extra import require_richif TYPE_CHECKING:- import logging-from rich.console import ConsoleRenderablefrom rich.logging import RichHandler@@ -47,6 +47,10 @@ CONSOLE_SINK_MISSING_MESSAGE = (f"or select the '{LogSinkMethod.JSON}' sink in [runtime.log] for a process with no terminal.")+#: What follows another library's package name before its message, and the style the two are printed in.+PACKAGE_PREFIX_SEPARATOR = ": "+PACKAGE_PREFIX_STYLE = "dim"+class ConsoleLogSink(LogSink):"""A ``RichHandler`` on the configured stream, rendering the message, or its layout, and the fields after it."""@@ -83,19 +87,20 @@ class ConsoleLogSink(LogSink):@overridedef render_message(self, record: logging.LogRecord, message: str) -> ConsoleRenderable:- """The message, or the layout the call named, then the fields as a styled ``key=value`` suffix, then any traceback text.+ """The message, or the layout the call named, then the fields as a styled ``key=value`` suffix, then any advice and traceback text.- The message is plain text, read as no markup, and the suffix is assembled as ``Text`` from styled- segments and appended after the highlighter has run on the message, so the highlighter never reads- a field's value.+ A line from another library than Pipelex starts with that library's package name, dimmed. The message+ is plain text, read as no markup, and the prefix, the suffix and the advice are assembled as ``Text``+ from styled segments around it after the highlighter has run on the message, so the highlighter never+ reads a field's value. The advice, a ``user_action`` field, prints on a line of its own under the line.A layout that cannot be filled, whatever it raises, falls back to the message, and every fieldthen goes to the suffix. The dispatch stamps a layout only on a call whose content is a string,so a structured content, which only its message renders, never meets one.With Rich tracebacks off, what Rich hands over is the formatter's whole output: the message line,then the exception's text and any stack text. That tail is split off the line and printed under- it, after the suffix, so the fields stay on the line they describe and a layout keeps the- traceback. It is printed as plain text, so nothing in a traceback is ever read as markup. A record+ it, after the suffix and the advice, so the fields stay on the line they describe and a layout keeps+ the traceback. It is printed as plain text, so nothing in a traceback is ever read as markup. A recordwith no such text renders exactly as before."""formatter = self.formatter@@ -111,7 +116,7 @@ class ConsoleLogSink(LogSink):try:layout_markup = layout.render_markup(fields=fields)# No emoji codes either: a value spelled `:fire:` is a value, not a picture.- message_text = Text.assemble(channel_prefix(logger_name=record.name), Text.from_markup(layout_markup, emoji=False))+ message_text = Text.from_markup(layout_markup, emoji=False)presented_fields = layout.presented_fieldsexcept Exception: # ruff: ignore[blind-except]# A layout's derivation is code each layout brings, filled with values each call@@ -122,12 +127,16 @@ class ConsoleLogSink(LogSink):if message_text is None:message_text = super().render_message(record, message_line)if isinstance(message_text, Text):+ package_name = foreign_package_name(logger_name=record.name)+ if package_name is not None:+ message_text = Text.assemble((f"{package_name}{PACKAGE_PREFIX_SEPARATOR}", PACKAGE_PREFIX_STYLE), message_text)segments = field_suffix_segments(fields=fields, presented_fields=presented_fields)+ segments.extend(advice_segments(fields=fields))if segments:message_text.append_text(Text.assemble(*segments))if appended_text:# The formatter puts a line break before the exception text only when the message does- # not already end in one, and the suffix or a layout now stands between the two.+ # not already end in one, and the suffix, the advice or a layout now stands between the two.if not message_text.plain.endswith("\n") and not appended_text.startswith("\n"):message_text.append("\n")message_text.append_text(Text(appended_text))@@ -144,14 +153,14 @@ class ConsoleLogSink(LogSink):console=Console(file=stream_for_target(target=self._target)),show_time=config.is_show_time,show_level=config.is_show_level,+ show_path=config.is_show_path,enable_link_path=config.is_link_path_enabled,highlighter=highlighter,# A message is the caller's text, and none of Pipelex's carries markup: colour comes from the# fields and the layouts, which style their own text. Read as markup, a message loses whatever- # is shaped like a tag, the `[name]: ` channel prefix of a lowercase logger, a `list[int]`, the- # `[cycle]` marker of a circular content, or raises on a bracketed path. Rich still honours its- # own per-record `markup` attribute, which no Pipelex call can set: a field of that name is- # reserved and lands under the `field_` prefix.+ # is shaped like a tag, a `list[int]`, the `[cycle]` marker of a circular content, or raises on a+ # bracketed path. Rich still honours its own per-record `markup` attribute, which no Pipelex call+ # can set: a field of that name is reserved and lands under the `field_` prefix.markup=False,rich_tracebacks=config.is_rich_tracebacks,tracebacks_word_wrap=config.is_tracebacks_word_wrap,@@ -159,7 +168,10 @@ class ConsoleLogSink(LogSink):tracebacks_suppress=config.tracebacks_suppress,keywords=config.keywords_to_hilight,)- handler.setFormatter(EmojiLogFormatter())+ # The stdlib's plain formatter, the message alone: what goes before it is styled in ``render_message``, which+ # Rich calls on every line, one carrying a traceback included, and a traceback Rich does not render itself+ # is the formatter's tail, which ``render_message`` splits off by the message the formatter gives.+ handler.setFormatter(logging.Formatter())self._rich_handler = handlerreturn handlerdiff --git a/pipelex/tools/log/console_prefix.py b/pipelex/tools/log/console_prefix.pynew file mode 100644index 000000000..27c5818fe--- /dev/null+++ b/pipelex/tools/log/console_prefix.py@@ -0,0 +1,30 @@+"""What the console puts before a record's message: nothing on a Pipelex line, the package name of any other library.++Nearly every line on a Pipelex console is Pipelex's own, so a prefix naming Pipelex says nothing and costs columns. A+line from another library, an HTTP client's or a provider SDK's, starts with its logger's top-level package name, which+the sink prints dimmed, so the reader still sees which library spoke. The root logger's lines carry no prefix either.+"""++#: The logger of a record logged on the root logger, which names no library.+ROOT_LOGGER_NAME = "root"++#: The top-level package of the runtime's own loggers.+PIPELEX_PACKAGE = "pipelex"++#: What starts the top-level package of a Pipelex distribution beside the runtime, ``pipelex_api`` or a plugin's named that+#: way. A plugin whose package is named otherwise gets its prefix like any other library.+PIPELEX_PACKAGE_PREFIX = f"{PIPELEX_PACKAGE}_"+++def foreign_package_name(*, logger_name: str) -> str | None:+ """The top-level package of a logger that is not Pipelex's, which the console prints before the message; else ``None``.++ A logger under ``pipelex`` or a ``pipelex_`` package, the runtime's, the API server's or a plugin's named that way,+ and the root logger have none.+ """+ if logger_name == ROOT_LOGGER_NAME:+ return None+ package = logger_name.split(".", 1)[0]+ if package == PIPELEX_PACKAGE or package.startswith(PIPELEX_PACKAGE_PREFIX):+ return None+ return packagediff --git a/pipelex/tools/log/log_config.py b/pipelex/tools/log/log_config.pyindex 4c2f95457..97019b2cf 100644--- a/pipelex/tools/log/log_config.py+++ b/pipelex/tools/log/log_config.py@@ -54,6 +54,7 @@ class RichLogConfig(ConfigModel):is_show_time: boolis_show_level: bool+ is_show_path: boolis_link_path_enabled: boolhighlighter_name: HighlighterName = Field(strict=False)is_rich_tracebacks: booldiff --git a/pipelex/tools/log/log_fields.py b/pipelex/tools/log/log_fields.pyindex 5fbcbe96a..16a55e168 100644--- a/pipelex/tools/log/log_fields.py+++ b/pipelex/tools/log/log_fields.py@@ -26,6 +26,11 @@ if TYPE_CHECKING:# The attribute a ``dict`` or ``list`` content is carried under, JSON-ready, beside its console rendering.DATA_FIELD = "data"+# The field a line's advice rides in: what its reader should do about the event, one imperative sentence, the name+# Pipelex's error reports give their advice. The message says what happened; the advice varies with the cause while+# the event does not, so it stays out of the message. The console prints it on a line of its own under the record.+USER_ACTION_FIELD = "user_action"+# The prefix an entry takes when its name is one the record already owns.COLLIDING_FIELD_PREFIX = "field_"diff --git a/pipelex/tools/log/log_formatter.py b/pipelex/tools/log/log_formatter.pydeleted file mode 100644index a27e41071..000000000--- a/pipelex/tools/log/log_formatter.py+++ /dev/null@@ -1,54 +0,0 @@-import logging--from typing_extensions import override---# TODO: move these to the config-def emoji_for_channel(channel_name: str) -> str | None:- channel_emojis: dict[str, str] = {- "root": "",- "werkzeug": "📡",- "urllib3.connectionpool": "⚡️",- }-- emoji = channel_emojis.get(channel_name)- if emoji == "":- # blank emoji is OK- return emoji- elif emoji:- return emoji- elif channel_name.startswith("google"):- return "🌀"- elif channel_name.startswith("openai"):- return "⚪️"- elif channel_name.startswith("kajson"):- # space added to make it look better- return "*️⃣ "- elif channel_name.startswith("pipelex"):- return "🧠"- else:- return None---class EmojiLogFormatter(logging.Formatter):- """The console sink's formatter: an emoji for the logger's prefix, then the message, and the record left as it was.-- The prefix goes on in ``formatMessage`` rather than ``format``: the Rich handler renders a record- that carries ``exc_info`` from ``formatMessage`` alone and discards what ``format`` returned, so a- prefix built anywhere else vanished from exactly the lines that carry a traceback. The base class's- ``format`` sets ``record.message``, calls this, and appends the exception text.- """-- @override- def formatMessage(self, record: logging.LogRecord) -> str:- return f"{channel_prefix(logger_name=record.name)}{record.message}"---def channel_prefix(*, logger_name: str) -> str:- """What the console puts before a record's message: the logger's emoji, nothing for the root, else the logger's name in brackets."""- emoji = emoji_for_channel(logger_name)- if emoji == "":- return ""- if emoji:- return f"{emoji}: "- return f"[{logger_name}]: "diff --git a/pipelex/tools/misc/tenacity_utils.py b/pipelex/tools/misc/tenacity_utils.pyindex f24920652..61d57e115 100644--- a/pipelex/tools/misc/tenacity_utils.py+++ b/pipelex/tools/misc/tenacity_utils.py@@ -3,6 +3,7 @@ from typing import Anyfrom tenacity import RetryCallStatefrom pipelex import log+from pipelex.tools.log.error_fields import ERROR_TYPE_FIELDdef log_retry(retry_state: RetryCallState) -> None:@@ -10,11 +11,11 @@ def log_retry(retry_state: RetryCallState) -> None:The message names the outcome, a retry, and not a failure, because a retry is not always one: apoller retries on a result, while the job it polls is still queued or running. The attempt just made- and the wait before the next one ride as fields, and `exception_type`, the class of what the attempt+ and the wait before the next one ride as fields, and `error.type`, the class of what the attemptraised, only when it raised."""if not retry_state.outcome:- log.error("Tenacity retry state outcome is None")+ log.error("A retry state carries no outcome")returnexc = retry_state.outcome.exception()wait_seconds = retry_state.next_action.sleep if retry_state.next_action else 0.0@@ -23,5 +24,5 @@ def log_retry(retry_state: RetryCallState) -> None:"wait_seconds": wait_seconds,}if exc is not None:- fields["exception_type"] = type(exc).__name__+ fields[ERROR_TYPE_FIELD] = type(exc).__name__log.debug("Retrying", fields=fields)diff --git a/pipelex/tracing/activity_event_log.py b/pipelex/tracing/activity_event_log.pyindex 71e83d457..d85452b80 100644--- a/pipelex/tracing/activity_event_log.py+++ b/pipelex/tracing/activity_event_log.py@@ -96,7 +96,7 @@ class ActivityEventLogCache:# land in the workflow's replay-rebuilt buffer (replay determinism), whether the activity runs co-located with# the workflow router or on a separate worker pool.log.info(- "Activity-side usage event emission engaged, through this process's activity event log",+ "Usage events are emitted through this process's activity event log",fields={"writer_id": writer_id, "workflow_id": workflow_id},)diff --git a/pipelex/tracing/graphspec_assembler.py b/pipelex/tracing/graphspec_assembler.pyindex 867d69775..2f0c1cd43 100644--- a/pipelex/tracing/graphspec_assembler.py+++ b/pipelex/tracing/graphspec_assembler.py@@ -603,9 +603,7 @@ class _AssemblerState:own_usages = own_usages_by_node.get(reported_node_id)if own_usages is None:if reported_node_id != UNATTRIBUTED_NODE_ID:- log.warning(- "A usage report names a node the trace never started, so its usage is left unattributed", fields={"node_id": reported_node_id}- )+ log.warning("The usage of a node the trace never started was left unattributed", fields={"node_id": reported_node_id})unattributed_usages.extend(usages)continueown_usages.extend(usages)diff --git a/pipelex/tracing/usage_attribution.py b/pipelex/tracing/usage_attribution.pyindex 9c6c1d778..ad6c1f66a 100644--- a/pipelex/tracing/usage_attribution.py+++ b/pipelex/tracing/usage_attribution.py@@ -227,7 +227,7 @@ def _walk_subtree(if node_id in subtree_by_node:continueif node_id in in_progress:- log.warning("The node parentage of a graph has a cycle, so a subtree's usage rollup is incomplete", fields={"node_id": node_id})+ log.warning("A cycle in a graph's node parentage left a subtree's usage rollup incomplete", fields={"node_id": node_id})continuein_progress.add(node_id)diff --git a/subject_grants.toml b/subject_grants.tomlindex a5242b243..1a4b19c26 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -5952,10 +5952,6 @@ rationale = "Setter: installs the log_config; single operand."param = "content"rationale = "Logs the content; single operand (formatting keyword-only)."-["pipelex/tools/log/log_formatter.py::emoji_for_channel"]-param = "channel_name"-rationale = "Renders the channel_name; single operand."-["pipelex/tools/markdown/markdown_parser.py::_join_text_fragments"]param = "state"rationale = "markdown-it rule callback: the inline ruler calls each rule with its state positionally."diff --git a/tests/conftest.py b/tests/conftest.pyindex 6ae824dcd..129d942dc 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -13,6 +13,7 @@ from pipelex.system.environment import PIPELEX_HOME_ENV_KEYfrom pipelex.system.job_metadata import JobMetadata, RunMetadatafrom pipelex.system.runtime import IntegrationMode, runtime_managerfrom pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract+from pipelex.tools.log.error_fields import error_fieldsif TYPE_CHECKING:from pipelex.system.telemetry.telemetry_manager import TelemetryManager@@ -39,7 +40,7 @@ def _fast_telemetry_teardown(self: "TelemetryManager") -> None:try:self._exception_capture.close() # pyright: ignore[reportPrivateUsage]except Exception as exc:- log.debug(f"Error closing exception capture: {exc}")+ log.debug("The exception capture could not be closed", fields=error_fields(exc=exc))if self._tracer_provider: # pyright: ignore[reportPrivateUsage]try:self._tracer_provider.shutdown() # pyright: ignore[reportPrivateUsage]diff --git a/tests/e2e/pipelex/cli/test_migrate_commands.py b/tests/e2e/pipelex/cli/test_migrate_commands.pyindex da74b2e73..ab2a198b6 100644--- a/tests/e2e/pipelex/cli/test_migrate_commands.py+++ b/tests/e2e/pipelex/cli/test_migrate_commands.py@@ -129,7 +129,7 @@ PLANTED_BACKEND_VALUE = "a_prompting_target_no_report_may_ever_render"# How each line of `stale_configuration_warning` opens. Matched in full rather than on a fragment: the# same boot also prints a deck-staleness notice, and "out of date" appears in both.-STALE_CONFIGURATION_OPENING = "A configuration file is out of date and was read as if it had been migrated"+STALE_CONFIGURATION_OPENING = "A configuration file is out of date and was migrated in memory only"def _old_shape_telemetry_document() -> str:diff --git a/tests/helpers/console_log_rendering.py b/tests/helpers/console_log_rendering.pyindex 423f345bb..7ea214b9b 100644--- a/tests/helpers/console_log_rendering.py+++ b/tests/helpers/console_log_rendering.py@@ -47,10 +47,12 @@ def console_handler() -> RichHandler:return handler-def record_with_fields(*, message: str, extra: dict[str, Any] | None = None, layout: LogLayout | str | None = None) -> logging.LogRecord:+def record_with_fields(+ *, message: str, extra: dict[str, Any] | None = None, layout: LogLayout | str | None = None, logger_name: str = "pipelex.tools.demo"+) -> logging.LogRecord:"""A record as the dispatch builds it: the extra attached through the fields channel, the layout under its mark."""record = logging.LogRecord(- name="pipelex.tools.demo", level=logging.INFO, pathname="/repo/pipelex/module.py", lineno=42, msg=message, args=(), exc_info=None+ name=logger_name, level=logging.INFO, pathname="/repo/pipelex/module.py", lineno=42, msg=message, args=(), exc_info=None)attach_log_record_extra(record=record, extra=extra or {})if layout is not None:diff --git a/tests/integration/pipelex/libraries/test_vendored_methods_dirs.py b/tests/integration/pipelex/libraries/test_vendored_methods_dirs.pyindex f67623e3b..b6d17470c 100644--- a/tests/integration/pipelex/libraries/test_vendored_methods_dirs.py+++ b/tests/integration/pipelex/libraries/test_vendored_methods_dirs.py@@ -98,7 +98,7 @@ class TestVendoredMethodsDirs:pin_warnings = [(record.__dict__["method_ref"], record.__dict__["package_version"])for record in caplog.records- if record.getMessage() == "A method reference pins a tag, and the copy shipped with the request is another version, which is used"+ if record.getMessage() == "A shipped method copy was used though its version is not the pinned tag"]assert pin_warnings == [(pinned_alias, "1.0.0")]diff --git a/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.py b/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.pyindex fccde27ae..a74750b13 100644--- a/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.py+++ b/tests/unit/pipelex/cli/dev/test_log_call_guard_scopes.py@@ -104,11 +104,6 @@ class TestLogCallGuardScopes:),("a for target", "def load(items):\n for MSG in items:\n log.info(MSG)\n", LogCallRule.NON_LITERAL),("a with target", "def load(path):\n with open(path) as MSG:\n log.info(MSG)\n", LogCallRule.NON_LITERAL),- (- "an except target",- "def load(path):\n try:\n open(path)\n except OSError as MSG:\n log.info(MSG)\n",- LogCallRule.NON_LITERAL,- ),("an import alias", "def load():\n from somewhere import thing as MSG\n log.info(MSG)\n", LogCallRule.NON_LITERAL),("an unpacking", "def load(pair):\n MSG, _other = pair\n log.info(MSG)\n", LogCallRule.NON_LITERAL),],@@ -116,6 +111,11 @@ class TestLogCallGuardScopes:def test_every_binding_form_shadows_the_module_s_literal(self, topic: str, body: str, expected_rule: LogCallRule) -> None:assert _rules(body) == [[expected_rule]], topic+ def test_an_except_target_shadows_the_module_s_literal_and_is_the_exception_itself(self) -> None:+ """The name is no literal, and what it holds is the handled exception, which the message would carry as its text."""+ body = "def load(path):\n try:\n open(path)\n except OSError as MSG:\n log.info(MSG)\n"+ assert _rules(body) == [[LogCallRule.NON_LITERAL, LogCallRule.SPLICED_EXCEPTION]]+@pytest.mark.parametrize(("topic", "body"),[diff --git a/tests/unit/pipelex/cli/dev/test_log_call_guard_spliced_exception.py b/tests/unit/pipelex/cli/dev/test_log_call_guard_spliced_exception.pynew file mode 100644index 000000000..a54c03cbd--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_log_call_guard_spliced_exception.py@@ -0,0 +1,124 @@+from __future__ import annotations++import textwrap++import pytest++from pipelex.cli.dev_cli.commands.log_call_guard import LogCallRule, OffendingCall, find_offending_calls_in_source++SAMPLE_PATH = "pipelex/core/sample_module.py"+HEADER = "from pipelex import log\nfrom pipelex.tools.log import error_fields\n"++EVERY_METHOD = ["verbose", "debug", "info", "warning", "error", "critical"]+++def _offending(body: str) -> list[OffendingCall]:+ return find_offending_calls_in_source(source=HEADER + textwrap.dedent(body), relative_path=SAMPLE_PATH)+++def _rules(body: str) -> list[list[LogCallRule]]:+ return [[breach.rule for breach in call.breaches] for call in _offending(body)]+++def _details(body: str, *, rule: LogCallRule) -> list[str]:+ return [breach.detail for call in _offending(body) for breach in call.breaches if breach.rule == rule]+++class TestLogCallGuardSplicedException:+ @pytest.mark.parametrize("method", EVERY_METHOD)+ @pytest.mark.parametrize(+ ("topic", "message", "expected_source"),+ [+ ("an f-string placeholder", 'f"A cleanup failed: {exc}"', "exc"),+ ("a converted placeholder", 'f"A cleanup failed: {exc!r}"', "exc"),+ ("an expression of the exception", 'f"A cleanup failed: {type(exc).__name__}"', "type(exc).__name__"),+ ("a percent format", '"A cleanup failed: %s" % exc', "exc"),+ ("a percent format of a tuple", '"A cleanup of %s failed: %s" % (path, exc)', "(path, exc)"),+ ("a .format() argument", '"A cleanup failed: {}".format(exc)', "exc"),+ ("a .format() keyword", '"A cleanup failed: {error}".format(error=exc)', "exc"),+ ("the exception as the message", "exc", "exc"),+ ("the exception's text as the message", "str(exc)", "str(exc)"),+ ("the exception's text concatenated", '"A cleanup failed: " + str(exc)', "str(exc)"),+ ],+ )+ def test_a_handled_exception_spliced_into_the_text_is_refused_at_every_level(+ self, method: str, topic: str, message: str, expected_source: str+ ) -> None:+ body = f"def clean(path):\n try:\n path.unlink()\n except OSError as exc:\n log.{method}({message})\n"+ assert _details(body, rule=LogCallRule.SPLICED_EXCEPTION) == [f"the message splices the exception `{expected_source}`"], topic++ def test_an_exception_method_s_result_is_refused_wherever_it_is_called(self) -> None:+ """A finished task's or a retry outcome's `.exception()` is the exception, though no handler binds it."""+ body = 'def clean(task):\n task.add_done_callback(lambda t: log.debug(f"A cleanup failed: {t.exception()}"))\n'+ assert _details(body, rule=LogCallRule.SPLICED_EXCEPTION) == ["the message splices the exception `t.exception()`"]++ @pytest.mark.parametrize(+ ("topic", "body", "expected_signature"),+ [+ (+ "a placeholder naming the handler's target",+ ' except OSError as exc:\n log.debug(f"A cleanup failed: {exc}")\n',+ 'debug: f"A cleanup failed: {exc}" [spliced-exception] where exc = <except target>',+ ),+ (+ "a message bound to an f-string splicing it",+ ' except OSError as exc:\n msg = f"A cleanup failed: {exc}"\n log.debug(msg)\n',+ 'debug: msg [spliced-exception] where exc = <except target>; msg = f"A cleanup failed: {exc}"',+ ),+ (+ "a placeholder naming the exception's text",+ ' except OSError as exc:\n detail = str(exc)\n log.debug(f"A cleanup failed: {detail}")\n',+ 'debug: f"A cleanup failed: {detail}" [spliced-exception] where detail = str(exc); exc = <except target>',+ ),+ (+ "a name captured from the handler by a callback",+ ' except OSError as exc:\n path.on_close(lambda: log.debug(f"A cleanup failed: {exc}"))\n',+ 'debug: f"A cleanup failed: {exc}" [spliced-exception] where exc = <except target>',+ ),+ ],+ )+ def test_the_exception_is_followed_through_the_bindings_that_reach_it(self, topic: str, body: str, expected_signature: str) -> None:+ """The signature carries the bindings the exception is reached through, the handler's target last in the route."""+ source = f"def clean(path):\n try:\n path.unlink()\n{body}"+ assert [call.signature for call in _offending(source)] == [expected_signature], topic++ @pytest.mark.parametrize(+ ("topic", "body"),+ [+ ("a parameter named like an exception", 'def clean(exc):\n log.debug(f"A cleanup failed: {exc}")\n'),+ (+ "the exception in fields",+ (+ "def clean(path):\n try:\n path.unlink()\n except OSError as exc:\n"+ ' log.warning("A cleanup failed", fields={**error_fields(exc=exc)})\n'+ ),+ ),+ (+ "the exception on the record at ERROR",+ (+ "def clean(path):\n try:\n path.unlink()\n except OSError:\n"+ ' log.error("A cleanup failed", include_exception=True)\n'+ ),+ ),+ (+ "a name the handler bound, rebound before the read",+ (+ "def clean(path):\n try:\n path.unlink()\n except OSError as exc:\n pass\n"+ ' exc = path.name\n log.debug(f"A cleanup ran on {exc}")\n'+ ),+ ),+ (+ "a value of the handler that is not the exception",+ (+ "def clean(path):\n try:\n path.unlink()\n except OSError:\n name = path.name\n"+ ' log.debug(f"A cleanup of {name} failed")\n'+ ),+ ),+ ],+ )+ def test_a_message_that_reaches_no_handled_exception_passes(self, topic: str, body: str) -> None:+ assert _offending(body) == [], topic++ def test_an_interpolated_exception_at_info_and_above_breaks_both_rules(self) -> None:+ body = 'def clean(path):\n try:\n path.unlink()\n except OSError as exc:\n log.warning(f"A cleanup failed: {exc}")\n'+ assert _rules(body) == [[LogCallRule.F_STRING, LogCallRule.SPLICED_EXCEPTION]]diff --git a/tests/unit/pipelex/cli/dev/test_log_call_guard_wording.py b/tests/unit/pipelex/cli/dev/test_log_call_guard_wording.pynew file mode 100644index 000000000..5e4f8d9a7--- /dev/null+++ b/tests/unit/pipelex/cli/dev/test_log_call_guard_wording.py@@ -0,0 +1,201 @@+from __future__ import annotations++import textwrap++import pytest++from pipelex.cli.dev_cli.commands.log_call_guard import MAX_MESSAGE_LENGTH, LogCallRule, OffendingCall, find_offending_calls_in_source++SAMPLE_PATH = "pipelex/core/sample_module.py"+HEADER = "from pipelex import log\n"++EVERY_METHOD = ["verbose", "debug", "info", "warning", "error", "critical"]+INFO_AND_ABOVE = ["info", "warning", "error", "critical"]+BELOW_INFO = ["verbose", "debug"]+++def _offending(body: str) -> list[OffendingCall]:+ return find_offending_calls_in_source(source=HEADER + textwrap.dedent(body), relative_path=SAMPLE_PATH)+++def _rules(body: str) -> list[list[LogCallRule]]:+ return [[breach.rule for breach in call.breaches] for call in _offending(body)]+++def _details(body: str, *, rule: LogCallRule) -> list[str]:+ return [breach.detail for call in _offending(body) for breach in call.breaches if breach.rule == rule]+++class TestLogCallGuardWording:+ @pytest.mark.parametrize("method", EVERY_METHOD)+ @pytest.mark.parametrize(+ ("topic", "message", "expected_detail"),+ [+ ("a lowercase first word", '"loaded the library"', "the message starts with the lowercase `loaded`"),+ ("a lowercase word after leading whitespace", '" loaded the library"', "the message starts with the lowercase `loaded`"),+ ("a lowercase file name", '"pipelex.toml was read"', "the message starts with the lowercase `pipelex.toml`"),+ ],+ )+ def test_a_lowercase_start_is_refused_at_every_level(self, method: str, topic: str, message: str, expected_detail: str) -> None:+ assert _details(f"def load():\n log.{method}({message})\n", rule=LogCallRule.LOWERCASE_START) == [expected_detail], topic++ @pytest.mark.parametrize("method", EVERY_METHOD)+ @pytest.mark.parametrize(+ ("topic", "message", "expected_detail"),+ [+ ("a period", '"The library was loaded."', "the message ends with `.`"),+ ("an ellipsis of periods", '"Loading the library..."', "the message ends with `...`"),+ ("an ellipsis character", '"Loading the library…"', "the message ends with `…`"),+ ("a period before trailing whitespace", '"The library was loaded. "', "the message ends with `.`"),+ ],+ )+ def test_a_trailing_period_or_ellipsis_is_refused_at_every_level(self, method: str, topic: str, message: str, expected_detail: str) -> None:+ assert _details(f"def load():\n log.{method}({message})\n", rule=LogCallRule.TRAILING_PERIOD) == [expected_detail], topic++ @pytest.mark.parametrize("method", EVERY_METHOD)+ def test_a_backtick_is_refused_at_every_level(self, method: str) -> None:+ body = f'def load():\n log.{method}("The library was loaded with `strict` on")\n'+ assert _details(body, rule=LogCallRule.BACKTICK) == ["the message holds a backtick"]++ @pytest.mark.parametrize("method", EVERY_METHOD)+ @pytest.mark.parametrize(+ ("topic", "message"),+ [+ ("a capital start and no period", '"The library was loaded"'),+ ("a start that is no letter", '"3 pipes were loaded"'),+ ("a quoted start", "\"'strict' mode was turned on\""),+ ("a question mark", '"Was the library loaded?"'),+ ("a period inside the message", '"Version 1.2 of the library was loaded"'),+ ],+ )+ def test_a_message_worded_by_the_conventions_passes_at_every_level(self, method: str, topic: str, message: str) -> None:+ assert _offending(f"def load():\n log.{method}({message})\n") == [], topic++ @pytest.mark.parametrize("method", BELOW_INFO)+ @pytest.mark.parametrize(+ ("topic", "message"),+ [+ ("a start an f-string splices", 'f"{alias} was loaded"'),+ ("an end an f-string splices", 'f"Loaded the library at {alias}"'),+ ("a start a value concatenates", 'alias + " was loaded"'),+ ],+ )+ def test_a_start_or_an_end_the_guard_cannot_read_passes(self, method: str, topic: str, message: str) -> None:+ """A value spliced at the start or the end could be anything, so nothing tells the rule is broken."""+ assert _offending(f"def load(alias):\n log.{method}({message})\n") == [], topic++ @pytest.mark.parametrize("method", INFO_AND_ABOVE)+ @pytest.mark.parametrize(+ ("topic", "message", "expected_detail"),+ [+ ("a snake_case word", '"The needs_inference flag was turned off"', "the message holds the identifier `needs_inference`"),+ ("an environment variable", '"PIPELEX_API_KEY is not set"', "the message holds the identifier `PIPELEX_API_KEY`"),+ ("a leading underscore", '"A stuff name starts with _private"', "the message holds the identifier `_private`"),+ ("a call", '"The library was loaded before setup()"', "the message holds the call `setup()`"),+ ("a dotted call", '"Loader.load() was called twice"', "the message holds the call `Loader.load()`"),+ ],+ )+ def test_an_identifier_is_refused_at_info_and_above(self, method: str, topic: str, message: str, expected_detail: str) -> None:+ assert _details(f"def load():\n log.{method}({message})\n", rule=LogCallRule.IDENTIFIER) == [expected_detail], topic++ @pytest.mark.parametrize("method", INFO_AND_ABOVE)+ @pytest.mark.parametrize(+ ("topic", "message"),+ [+ ("a word of Pipelex's vocabulary", '"A PipeBatch ran with no items"'),+ ("a file name with no underscore", '"The METHODS.toml file was read"'),+ ("a plural in parentheses", '"The model(s) were loaded"'),+ ("a hyphenated word", '"A well-known backend was chosen"'),+ ],+ )+ def test_a_word_that_is_no_identifier_passes(self, method: str, topic: str, message: str) -> None:+ assert _offending(f"def load():\n log.{method}({message})\n") == [], topic++ @pytest.mark.parametrize("method", INFO_AND_ABOVE)+ def test_a_message_longer_than_the_bound_is_refused_at_info_and_above(self, method: str) -> None:+ too_long = "A" + "a" * MAX_MESSAGE_LENGTH+ at_the_bound = "A" + "a" * (MAX_MESSAGE_LENGTH - 1)+ assert _details(f'def load():\n log.{method}("{too_long}")\n', rule=LogCallRule.LENGTH) == [+ f"the message is {MAX_MESSAGE_LENGTH + 1} characters long, more than {MAX_MESSAGE_LENGTH}"+ ]+ assert _offending(f'def load():\n log.{method}("{at_the_bound}")\n') == []++ def test_the_length_is_read_on_the_folded_text(self) -> None:+ """Two literals joined by a `+` reach the console as one text, so their lengths add up."""+ half = "A" + "a" * (MAX_MESSAGE_LENGTH // 2)+ assert _details(f'def load():\n log.info("{half}" + "{half}")\n', rule=LogCallRule.LENGTH) == [+ f"the message is {2 * len(half)} characters long, more than {MAX_MESSAGE_LENGTH}"+ ]++ def test_the_length_of_an_f_string_counts_its_literal_text_alone(self) -> None:+ """A spliced value is at least empty, so a literal text past the bound is too long whatever the value."""+ literal_text = "A" + "a" * MAX_MESSAGE_LENGTH+ assert _details(f'def load(alias):\n log.info(f"{literal_text}{{alias}}")\n', rule=LogCallRule.LENGTH) == [+ f"the message is at least {MAX_MESSAGE_LENGTH + 1} characters long, more than {MAX_MESSAGE_LENGTH}"+ ]+ short_text = "A" + "a" * (MAX_MESSAGE_LENGTH - 10)+ assert _details(f'def load(alias):\n log.info(f"{short_text}{{alias}}")\n', rule=LogCallRule.LENGTH) == []++ @pytest.mark.parametrize("method", BELOW_INFO)+ @pytest.mark.parametrize(+ ("topic", "message"),+ [+ ("an identifier", '"The needs_inference flag was turned off"'),+ ("a call", '"The library was loaded before setup()"'),+ ("a long message", '"A' + "a" * MAX_MESSAGE_LENGTH + '"'),+ ],+ )+ def test_identifiers_and_length_are_not_held_below_info(self, method: str, topic: str, message: str) -> None:+ """A person at a terminal reads DEBUG and VERBOSE, where a message may name what the code names."""+ assert _offending(f"def load():\n log.{method}({message})\n") == [], topic++ @pytest.mark.parametrize(+ ("topic", "body", "expected_rules"),+ [+ (+ "a conditional between a good and a bad literal",+ 'log.debug("The library was loaded" if flag else "the library was skipped.")',+ [[LogCallRule.LOWERCASE_START, LogCallRule.TRAILING_PERIOD]],+ ),+ (+ "a name bound to a bad literal on one branch",+ 'msg = "The library was loaded"\n if flag:\n msg = "Loading the library..."\n log.info(msg)',+ [[LogCallRule.TRAILING_PERIOD]],+ ),+ ("a module constant", "log.warning(LOADED)", [[LogCallRule.LOWERCASE_START]]),+ ("a literal extended with +=", 'msg = "The library"\n msg += " was loaded."\n log.verbose(msg)', [[LogCallRule.TRAILING_PERIOD]]),+ ("an end folded across a +", 'log.debug("The library " + "was loaded.")', [[LogCallRule.TRAILING_PERIOD]]),+ ("a start folded across a +", 'log.debug("" + "loaded")', [[LogCallRule.LOWERCASE_START]]),+ ("a period before a value", 'log.debug("The library was loaded. " + str(flag))', []),+ ],+ )+ def test_every_text_a_message_can_reach_the_console_as_is_read(self, topic: str, body: str, expected_rules: list[list[LogCallRule]]) -> None:+ """A message is read through its bindings and its concatenations, and one text that breaks a rule is enough."""+ assert _rules(f'LOADED = "loaded the library"\n\ndef load(flag):\n {body}\n') == expected_rules, topic++ def test_a_concatenation_past_the_fold_bound_keeps_each_side_s_start_and_end_apart(self) -> None:+ """Past the bound, each left text keeps its start and each right text its end, and neither joins the other."""+ nb_alternatives = 17+ left = " if flag else ".join(f'"left{index_alternative}"' for index_alternative in range(nb_alternatives))+ right = " if flag else ".join(f'"right{index_alternative}."' for index_alternative in range(nb_alternatives))+ body = f"def load(flag):\n log.debug(({left}) + ({right}))\n"+ assert sorted(_details(body, rule=LogCallRule.LOWERCASE_START)) == sorted(+ f"the message starts with the lowercase `left{index_alternative}`" for index_alternative in range(nb_alternatives)+ )+ assert _details(body, rule=LogCallRule.TRAILING_PERIOD) == ["the message ends with `.`"]++ @pytest.mark.parametrize("keyword", ["title", "inline"])+ def test_a_title_is_worded_as_a_text_of_its_own(self, keyword: str) -> None:+ offending = _offending(f'def load():\n log.info("The library was loaded", {keyword}="the_library.")\n')+ assert [(breach.rule, breach.detail) for call in offending for breach in call.breaches] == [+ (LogCallRule.LOWERCASE_START, f"`{keyword}=` starts with the lowercase `the_library.`"),+ (LogCallRule.TRAILING_PERIOD, f"`{keyword}=` ends with `.`"),+ (LogCallRule.IDENTIFIER, f"`{keyword}=` holds the identifier `the_library`"),+ ]++ def test_a_wording_rule_is_named_in_the_signature(self) -> None:+ offending = _offending('def load():\n log.info("loaded the library.")\n')+ assert [call.signature for call in offending] == ["info: 'loaded the library.' [lowercase-start, trailing-period]"]++ def test_every_rule_names_a_remedy(self) -> None:+ assert all(rule.remedy for rule in LogCallRule)diff --git a/tests/unit/pipelex/cli/test_graph_render_cmd.py b/tests/unit/pipelex/cli/test_graph_render_cmd.pyindex 92923f15a..ca3f83725 100644--- a/tests/unit/pipelex/cli/test_graph_render_cmd.py+++ b/tests/unit/pipelex/cli/test_graph_render_cmd.py@@ -61,7 +61,7 @@ class TestGraphRenderFailure:# The log line is a fixed message and carries the path and the diagnosis as written, with no escape:# only the console print reads markup, and no sink reads a log message as markup.log_spy.error.assert_called_once()- assert log_spy.error.call_args.args == ("The graph spec was refused, so no graph was rendered",)+ assert log_spy.error.call_args.args == ("The graph spec was refused and no graph was rendered",)fields = log_spy.error.call_args.kwargs["fields"]assert fields["file.path"] == str(spec_file)assert fields["error.type"] == "GraphSpecValidationError"diff --git a/tests/unit/pipelex/cogt/inference/test_inference_call_summary.py b/tests/unit/pipelex/cogt/inference/test_inference_call_summary.pyindex eeb477b15..0e7aa3ae4 100644--- a/tests/unit/pipelex/cogt/inference/test_inference_call_summary.py+++ b/tests/unit/pipelex/cogt/inference/test_inference_call_summary.py@@ -685,8 +685,8 @@ class TestInferenceCallSummary:await _StandInLLMWorker(error=LLMCompletionError(message="provider refused")).gen_text(llm_job=_llm_job())succeeded, failed = _summaries(caplog)- assert rendered_text(record=succeeded).plain == "🧠: gpt-test chat · 1,200 → 300 tokens · $0.0018 · done in 1.25 s"- assert rendered_text(record=failed).plain == "🧠: gpt-test chat · failed after 1.25 s error.type=LLMCompletionError"+ assert rendered_text(record=succeeded).plain == "gpt-test chat · 1,200 → 300 tokens · $0.0018 · done in 1.25 s"+ assert rendered_text(record=failed).plain == "gpt-test chat · failed after 1.25 s error.type=LLMCompletionError"@pytest.mark.parametrize(("refuse_call", "refusal_type", "operation"), REFUSAL_CASES, ids=REFUSAL_IDS)@pytest.mark.asyncio@@ -738,7 +738,7 @@ class TestInferenceCallSummary:fields = _fields(record)assert (fields["outcome"], fields["duration_ms"]) == ("cancelled", DURATION_MS)assert "error.type" not in fields- assert rendered_text(record=record).plain == "🧠: gpt-test chat · cancelled after 1.25 s"+ assert rendered_text(record=record).plain == "gpt-test chat · cancelled after 1.25 s"@pytest.mark.parametrize("provider_error", [None, LLMCompletionError(message="provider refused")], ids=["the call succeeds", "the call fails"])@pytest.mark.asynciodiff --git a/tests/unit/pipelex/cogt/llm/test_llm_worker_constrained_job_params.py b/tests/unit/pipelex/cogt/llm/test_llm_worker_constrained_job_params.pyindex 0e1b274e0..681b9bad8 100644--- a/tests/unit/pipelex/cogt/llm/test_llm_worker_constrained_job_params.py+++ b/tests/unit/pipelex/cogt/llm/test_llm_worker_constrained_job_params.py@@ -23,7 +23,7 @@ if TYPE_CHECKING:from pipelex.cogt.llm.llm_job import LLMJobfrom pipelex.tools.typing.pydantic_utils import BaseModelTypeVar-FIXED_TEMPERATURE_WARNING = "The model takes a fixed temperature, so it is used in place of the requested one"+FIXED_TEMPERATURE_WARNING = "The model's fixed temperature was used in place of the requested one"def _make_model(diff --git a/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.py b/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.pyindex e43dd4d6d..88604a23e 100644--- a/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.py+++ b/tests/unit/pipelex/cogt/models/test_model_deck_ambiguous_bare_handle.py@@ -12,6 +12,7 @@ from pipelex.cogt.models.model_deck import ModelDeckfrom pipelex.cogt.models.model_reference import ModelReferenceKindfrom pipelex.cogt.usage.cost_category import CostCategoryfrom pipelex.system.runtime import ProblemReaction+from pipelex.tools.log.log_fields import USER_ACTION_FIELDdef _make_deck() -> ModelDeck:@@ -65,10 +66,12 @@ class TestModelDeckAmbiguousBareHandle:assert setting.model == "twin"warning.assert_called_once()+ assert warning.call_args.args == ("An ambiguous bare model name was read as a direct model handle",)assert warning.call_args.kwargs["fields"] == {"model_handle": "twin","model_type": ModelType.LLM,"matching_reference_kinds": [ModelReferenceKind.PRESET, ModelReferenceKind.ALIAS],+ USER_ACTION_FIELD: "Prefix the name with $ or preset: for a preset, @ or alias: for an alias, ~ or waterfall: for a waterfall",}def test_a_bare_name_that_names_nothing_else_is_not_warned_about(self, mocker: MockerFixture) -> None:diff --git a/tests/unit/pipelex/graph/test_graph_output_generation.py b/tests/unit/pipelex/graph/test_graph_output_generation.pyindex 6e7644ce3..e620bc8e1 100644--- a/tests/unit/pipelex/graph/test_graph_output_generation.py+++ b/tests/unit/pipelex/graph/test_graph_output_generation.py@@ -23,6 +23,7 @@ from tests.helpers.pipe_io_artifacts import make_pipe_io_artifactsfrom tests.unit.pipelex.graph.conftest import make_graph_config_T0 = datetime(2025, 7, 1, 12, 0, 0, tzinfo=UTC)+_REMOVAL_MESSAGE = "An I/O artifact an earlier run left beside the graphspec was removed"def _make_sequence_graphspec() -> GraphSpec:@@ -287,7 +288,7 @@ class TestGraphspecCompanions:assert set(saved) == {"graphspec_json"}assert {path.name for path in tmp_path.iterdir()} == {"graphspec.json"}- removed_paths = [Path(call.kwargs["fields"]["file.path"]) for call in warning_spy.call_args_list if "Removed" in str(call.args[0])]+ removed_paths = [Path(call.kwargs["fields"]["file.path"]) for call in warning_spy.call_args_list if call.args[0] == _REMOVAL_MESSAGE]assert {path.name for path in removed_paths} == {PIPE_IO_CONTRACTS_FILE_NAME,INPUT_FORM_FILE_NAME,@@ -306,7 +307,7 @@ class TestGraphspecCompanions:save_graph_outputs_to_dir(graph_outputs=outputs, output_dir=tmp_path)- assert not [call for call in warning_spy.call_args_list if "Removed" in str(call.args[0])]+ assert not [call for call in warning_spy.call_args_list if call.args[0] == _REMOVAL_MESSAGE]async def test_no_graphspec_leaves_the_directory_alone(self, tmp_path: Path) -> None:"""Only a written graphspec owns the companions beside it: a mermaid-only run touches nothing else."""diff --git a/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py b/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.pyindex ba5d428f3..65f83ebc4 100644--- a/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py+++ b/tests/unit/pipelex/graph/test_graph_tracer_manager_stale_key_healing.py@@ -24,8 +24,8 @@ _DATA_INCLUSION_OFF = DataInclusionConfig(_TRACER_KEY = "run_under_test"-_STALE_TRACER_MESSAGE = "Replacing a graph tracer left over by an interrupted execution whose cleanup never ran"-_STALE_TEARDOWN_MESSAGE = "The teardown of a stale graph tracer raised; replacing it anyway"+_STALE_TRACER_MESSAGE = "A graph tracer left over by an interrupted execution was replaced"+_STALE_TEARDOWN_MESSAGE = "The teardown of a stale graph tracer failed, and the tracer was replaced"def _records_with_message(*, caplog: pytest.LogCaptureFixture, message: str) -> list[logging.LogRecord]:diff --git a/tests/unit/pipelex/libraries/test_domain_library.py b/tests/unit/pipelex/libraries/test_domain_library.pyindex 4eada56d9..d224822cd 100644--- a/tests/unit/pipelex/libraries/test_domain_library.py+++ b/tests/unit/pipelex/libraries/test_domain_library.py@@ -5,7 +5,7 @@ import pytestfrom pipelex.core.domains.domain import Domainfrom pipelex.libraries.domain.domain_library import DomainLibrary-DOMAIN_FIELD_CONFLICT_MESSAGE = "Two declarations of one domain give one of its fields different values, so the first is kept"+DOMAIN_FIELD_CONFLICT_MESSAGE = "Two declarations of a domain disagree on a field, and the first value is kept"class TestDomainLibrary:diff --git a/tests/unit/pipelex/libraries/test_library_crate.py b/tests/unit/pipelex/libraries/test_library_crate.pyindex d26d5efbf..35598624b 100644--- a/tests/unit/pipelex/libraries/test_library_crate.py+++ b/tests/unit/pipelex/libraries/test_library_crate.py@@ -9,7 +9,7 @@ from pipelex.libraries.pipe.exceptions import PipeLibraryErrorfrom pipelex.mthds_parsing.pipelex_bundle_blueprint import PipelexBundleBlueprintfrom tests.unit.pipelex.libraries.test_library_crate_data import BlueprintSamples-DOMAIN_FIELD_CONFLICT_MESSAGE = "Two declarations of one domain give one of its fields different values, so the first is kept"+DOMAIN_FIELD_CONFLICT_MESSAGE = "Two declarations of a domain disagree on a field, and the first value is kept"class TestLibraryCrate:diff --git a/tests/unit/pipelex/libraries/test_mthds_version_warning.py b/tests/unit/pipelex/libraries/test_mthds_version_warning.pyindex c347b19cc..a40927359 100644--- a/tests/unit/pipelex/libraries/test_mthds_version_warning.py+++ b/tests/unit/pipelex/libraries/test_mthds_version_warning.py@@ -7,6 +7,7 @@ from pytest_mock import MockerFixturefrom pipelex.libraries.library_factory import LibraryFactoryfrom pipelex.libraries.library_manager import LibraryManagerfrom pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELD+from pipelex.tools.log.log_fields import USER_ACTION_FIELDclass TestMthdsVersionWarning:@@ -24,14 +25,14 @@ class TestMthdsVersionWarning:)mock_log.warning.assert_called_once()- assert mock_log.warning.call_args.args == (- "A package requires another MTHDS standard version than this runtime's; some features may not work correctly",- )- assert mock_log.warning.call_args.kwargs["fields"] == {+ assert mock_log.warning.call_args.args == ("A package requires another MTHDS standard version than this runtime's",)+ fields = mock_log.warning.call_args.kwargs["fields"]+ assert {name: fields[name] for name in ("package_address", "mthds_version_constraint", "mthds_standard_version")} == {"package_address": "github.com/org/pkg","mthds_version_constraint": "^2.0.0","mthds_standard_version": "1.0.0",}+ assert fields[USER_ACTION_FIELD]def test_no_warning_when_version_satisfied(self, mocker: MockerFixture) -> None:"""No warning emitted when current MTHDS standard version satisfies the constraint."""@@ -57,7 +58,7 @@ class TestMthdsVersionWarning:)mock_log.warning.assert_called_once()- assert mock_log.warning.call_args.args == ("The mthds_version constraint of a package could not be parsed",)+ assert mock_log.warning.call_args.args == ("The MTHDS version constraint of a package could not be parsed",)fields = mock_log.warning.call_args.kwargs["fields"]assert fields["package_address"] == "github.com/org/pkg"assert fields["mthds_version_constraint"] == ">>>garbage"diff --git a/tests/unit/pipelex/methods/test_fetch_on_miss.py b/tests/unit/pipelex/methods/test_fetch_on_miss.pyindex bb4227e51..a08d2e4b3 100644--- a/tests/unit/pipelex/methods/test_fetch_on_miss.py+++ b/tests/unit/pipelex/methods/test_fetch_on_miss.py@@ -19,6 +19,7 @@ from pipelex.methods.exceptions import (from pipelex.methods.fetch_on_miss import resolve_address_based_methodfrom pipelex.methods.fetching import FetchedMethodPackage, MethodProvenancefrom pipelex.methods.method_ref import parse_method_ref+from pipelex.tools.log.log_fields import USER_ACTION_FIELDif TYPE_CHECKING:from pathlib import Path@@ -224,10 +225,17 @@ class TestResolveAddressBasedMethod:resolved = resolve_address_based_method(full_address=FULL_ADDRESS)assert (resolved.path / "structures.py").is_file()- structures_warnings = [call for call in warning_spy.call_args_list if "hosted execution refuses them" in call.args[0]]+ structures_warnings = [+ call+ for call in warning_spy.call_args_list+ if call.args[0] == "A fetched method declares Python structure classes, which hosted runs refuse"+ ]assert len(structures_warnings) == 1- assert "declare these types as MTHDS concepts" in structures_warnings[0].args[0]- assert structures_warnings[0].kwargs["fields"] == {"package_address": FULL_ADDRESS, "structure_classes": "structures.py defines Invoice"}+ assert structures_warnings[0].kwargs["fields"] == {+ "package_address": FULL_ADDRESS,+ "structure_classes": "structures.py defines Invoice",+ USER_ACTION_FIELD: "Declare these types as MTHDS concepts with inline structures",+ }@pytest.mark.usefixtures("isolated_methods_dirs")def test_fetched_provenance_records_the_bare_address_fetch(self, tmp_path: Path, mocker: MockerFixture) -> None:diff --git a/tests/unit/pipelex/migration/test_runner.py b/tests/unit/pipelex/migration/test_runner.pyindex 19db06f46..c9030b734 100644--- a/tests/unit/pipelex/migration/test_runner.py+++ b/tests/unit/pipelex/migration/test_runner.py@@ -557,7 +557,7 @@ class TestMigrationRunner:assert stale_backup.exists()# The warning names the file and the backup just taken, and carries the system's reason alone, the paths being fields.warning_mock.assert_called_once_with(- "A change to a configuration file was backed up, but an older backup of the file could not be pruned",+ "An older backup of a configuration file could not be pruned",fields={"file.path": str(target),"backup_path": str(plan.backup_path),diff --git a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.py b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.pyindex 74d137f88..aa3802350 100644--- a/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.py+++ b/tests/unit/pipelex/pipe_controllers/batch/test_pipe_batch_large_batch_advisory.py@@ -3,38 +3,34 @@ from pytest_mock import MockerFixturefrom pipelex import logfrom pipelex.pipe_controllers.batch.pipe_batch import warn_of_large_batch+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.urls import URLsclass TestPipeBatchLargeBatchAdvisory:@pytest.mark.parametrize(- ("max_concurrency", "expected_message", "expected_fields"),- [- (- 8,- (- "A PipeBatch fans out over a large list with bounded fan-out, which is backpressure and not durable execution; "- "for a workload this size, consider a durable execution backend for rate-limited, resumable runs"- ),- {"pipe_code": "summarize_each", "item_count": 250, "max_concurrency": 8, "url.full": URLs.durable_execution},- ),- (- None,- (- "A PipeBatch fans out over a large list with unbounded fan-out, which is neither backpressure nor durable execution; "- "for a workload this size, consider a durable execution backend for rate-limited, resumable runs"- ),- {"pipe_code": "summarize_each", "item_count": 250, "url.full": URLs.durable_execution},- ),- ],+ ("max_concurrency", "expected_bound_fields"),+ [(8, {"max_concurrency": 8}), (None, {})],ids=["bounded", "unbounded"],)- def test_the_advisory_says_what_the_fan_out_is(- self, mocker: MockerFixture, max_concurrency: int | None, expected_message: str, expected_fields: dict[str, object]+ def test_the_advisory_is_one_event_whose_bound_is_a_field(+ self, mocker: MockerFixture, max_concurrency: int | None, expected_bound_fields: dict[str, object]) -> None:- """The advisory said "with bounded fan-out" even when the configuration's `"unbounded"` set no bound at all."""+ """The advisory said "with bounded fan-out" even when the configuration's `"unbounded"` set no bound at all.++ Bounded or not, the fan-out is one event under one message, its bound a field absent when there is none.+ """warning_spy = mocker.patch.object(log, "warning")warn_of_large_batch(pipe_code="summarize_each", item_count=250, max_concurrency=max_concurrency)- warning_spy.assert_called_once_with(expected_message, fields=expected_fields)+ warning_spy.assert_called_once_with(+ "A PipeBatch fans out over a large list without durable execution",+ fields={+ "pipe_code": "summarize_each",+ "item_count": 250,+ **expected_bound_fields,+ "url.full": URLs.durable_execution,+ USER_ACTION_FIELD: "Consider a durable execution backend for rate-limited, resumable runs",+ },+ )diff --git a/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.py b/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.pyindex e9835ef01..689578e2a 100644--- a/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.py+++ b/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_announcement.py@@ -38,7 +38,6 @@ from pipelex.tools.log.console_log_sink import ConsoleLogSinkfrom pipelex.tools.log.json_log_sink import MESSAGE_KEY, JsonLogSinkfrom pipelex.tools.log.log_config import HighlighterName, RichLogConfigfrom pipelex.tools.log.log_fields import LAYOUT_MARK-from pipelex.tools.log.log_formatter import EmojiLogFormatterfrom tests.helpers.console_log_rendering import package_log_configif TYPE_CHECKING:@@ -179,6 +178,7 @@ def _markup_reading_handler(*, config: RichLogConfig, buffer: io.StringIO) -> Riconsole=_colour_console(buffer=buffer),show_time=config.is_show_time,show_level=config.is_show_level,+ show_path=config.is_show_path,enable_link_path=config.is_link_path_enabled,highlighter=highlighter,markup=True,@@ -188,7 +188,7 @@ def _markup_reading_handler(*, config: RichLogConfig, buffer: io.StringIO) -> Ritracebacks_suppress=config.tracebacks_suppress,keywords=config.keywords_to_hilight,)- handler.setFormatter(EmojiLogFormatter())+ handler.setFormatter(logging.Formatter())return handlerdiff --git a/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_end.py b/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_end.pyindex 1740347c5..961b8678c 100644--- a/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_end.py+++ b/tests/unit/pipelex/pipe_machinery/test_live_run_pipe_end.py@@ -287,9 +287,9 @@ class TestLiveRunPipeEnd:lines = [rendered_text(record=record).plain for record in _records(caplog, message=PIPE_RUN_ENDS_MESSAGE)]assert lines == [- "🧠: ↳ EndingPipe: describe_company done in 1.25 s",- "🧠: EndingPipe: build_profile done in 1.25 s",- "🧠: EndingPipe: describe_company failed after 1.25 s error.type=PipeRunError",+ " ↳ EndingPipe: describe_company done in 1.25 s",+ "EndingPipe: build_profile done in 1.25 s",+ "EndingPipe: describe_company failed after 1.25 s error.type=PipeRunError",]async def test_the_json_sink_writes_the_duration_and_the_depth_as_numbers(self, caplog: pytest.LogCaptureFixture) -> None:@@ -370,4 +370,4 @@ class TestLiveRunPipeEnd:"duration_ms": DURATION_MS,"outcome": "cancelled",}- assert rendered_text(record=run_end).plain == "🧠: EndingPipe: describe_company cancelled after 1.25 s"+ assert rendered_text(record=run_end).plain == "EndingPipe: describe_company cancelled after 1.25 s"diff --git a/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.py b/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.pyindex 261306250..4067b12b3 100644--- a/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.py+++ b/tests/unit/pipelex/pipe_machinery/test_pipe_abstract_namespace_strip.py@@ -3,6 +3,7 @@ from pytest_mock import MockerFixturefrom pipelex import logfrom pipelex.pipe_machinery.pipe_abstract import PipeAbstract+from pipelex.tools.log.log_fields import USER_ACTION_FIELDclass TestPipeAbstractNamespaceStrip:@@ -28,8 +29,8 @@ class TestPipeAbstractNamespaceStrip:PipeAbstract.validate_pipe_code_syntax("domain.my_pipe")warning_spy.assert_called_once_with(- "A pipe code carries a namespace prefix, which was stripped: write the pipe code bare",- fields={"pipe_code": "my_pipe", "pipe_ref": "domain.my_pipe"},+ "A namespace prefix was stripped from a pipe code",+ fields={"pipe_code": "my_pipe", "pipe_ref": "domain.my_pipe", USER_ACTION_FIELD: "Write the pipe code bare"},)def test_validate_pipe_code_syntax_raises_for_invalid_after_strip(self) -> None:diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.pyindex de36c9f1f..c56b84233 100644--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py@@ -583,9 +583,7 @@ class TestDeliveryExecutor:assert result is Noneassert warn_spy.call_count == 0unknown_concept_calls = [- call- for call in debug_spy.call_args_list- if call.args[0] == "The delivered result's concept is not known here; the delivery renders it raw"+ call for call in debug_spy.call_args_list if call.args[0] == "A delivered result's concept is not known here and was rendered raw"]assert len(unknown_concept_calls) == 1assert unknown_concept_calls[0].kwargs["fields"] == {"concept_ref": "dynamic_test.Greeting"}@@ -603,7 +601,7 @@ class TestDeliveryExecutor:assert result is None(warning_call,) = warn_spy.call_args_list- assert warning_call.args[0] == "The delivered result could not be hydrated; the delivery renders it raw"+ assert warning_call.args[0] == "A delivered result could not be hydrated and was rendered raw"assert warning_call.kwargs["fields"]["error.type"] == "ValidationError"assert warning_call.kwargs["fields"]["error.message"].startswith("text: ")assert "secret-result-value" not in str(warning_call)diff --git a/tests/unit/pipelex/pipe_run/test_pipe_run.py b/tests/unit/pipelex/pipe_run/test_pipe_run.pyindex 044dc1e74..e3db674be 100644--- a/tests/unit/pipelex/pipe_run/test_pipe_run.py+++ b/tests/unit/pipelex/pipe_run/test_pipe_run.py@@ -137,7 +137,7 @@ class TestPipeRun:await PipeRun(pipe_router=mock_router).run(pipe_job=mock_job)(failure_record,) = [- record for record in caplog.records if record.name == pipe_run_module.__name__ and record.getMessage() == "Pipe execution failed"+ record for record in caplog.records if record.name == pipe_run_module.__name__ and record.getMessage() == "The execution of a pipe failed"]record_fields = vars(failure_record)assert record_fields["pipe_code"] == "describe_company"diff --git a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py b/tests/unit/pipelex/pipe_run/test_tracing_assembly.pyindex fd7e3207e..347c00a86 100644--- a/tests/unit/pipelex/pipe_run/test_tracing_assembly.py+++ b/tests/unit/pipelex/pipe_run/test_tracing_assembly.py@@ -189,7 +189,9 @@ class TestTracingAssembly:with caplog.at_level(logging.WARNING, logger=_MODULE):assemble_tracing(pipeline_run_id="plr-activity", assemble_graph=True, assemble_usage=True, run_metadata=run_metadata)- (record,) = [record for record in caplog.records if record.getMessage() == "Tracing assembly could not read the run's trace events"]+ (record,) = [+ record for record in caplog.records if record.getMessage() == "The trace events of a run could not be read for its tracing assembly"+ ]assert getattr(record, PIPELINE_RUN_ID_FIELD) == "plr-activity"assert getattr(record, REQUEST_ID_FIELD) == "req-activity"assert get_log_context() is None, "the binding is released when the assembly returns"diff --git a/tests/unit/pipelex/providers/google/test_google_factory_client_close.py b/tests/unit/pipelex/providers/google/test_google_factory_client_close.pynew file mode 100644index 000000000..55a3b53be--- /dev/null+++ b/tests/unit/pipelex/providers/google/test_google_factory_client_close.py@@ -0,0 +1,104 @@+import asyncio+import gc+import weakref+from collections.abc import Coroutine+from typing import Any++import pytest+from pytest_mock import MockerFixture++from pipelex.providers.google import google_factory+from pipelex.providers.google.google_factory import GoogleFactory+from pipelex.tools.log.error_fields import ERROR_MESSAGE_FIELD, ERROR_TYPE_FIELD+++async def _close_failing() -> None:+ await asyncio.sleep(0)+ msg = "connection reset"+ raise ConnectionError(msg)+++async def _close_succeeding() -> None:+ await asyncio.sleep(0)+++async def _close_never_finishing() -> None:+ # The event is reachable only from this coroutine, so nothing outside the task waiting on it holds that task+ await asyncio.Event().wait()+++def _schedule_and_find_close_task(*, close_coroutine: Coroutine[Any, Any, None]) -> "asyncio.Task[Any]":+ """Schedule a close on the running loop and return the task it created, which the scheduler does not return."""+ tasks_before = asyncio.all_tasks()+ GoogleFactory.schedule_client_close(event_loop=asyncio.get_running_loop(), close_coroutine=close_coroutine)+ (close_task,) = asyncio.all_tasks() - tasks_before+ return close_task+++class TestGoogleFactoryClientClose:+ """The background task a worker's teardown schedules to close its Google async client, and the done callback logging its failure."""++ @pytest.mark.asyncio+ async def test_a_pending_close_survives_garbage_collection_until_it_is_done(self) -> None:+ """The event loop holds a task only weakly, so a close task nothing else references would be collected mid-run."""+ close_task_ref = weakref.ref(_schedule_and_find_close_task(close_coroutine=_close_never_finishing()))+ await asyncio.sleep(0)+ gc.collect()++ pending_close_task = close_task_ref()+ assert pending_close_task is not None+ assert not pending_close_task.done()++ pending_close_task.cancel()+ await asyncio.wait([pending_close_task])+ del pending_close_task+ gc.collect()++ assert close_task_ref() is None++ @pytest.mark.asyncio+ async def test_a_scheduled_close_that_fails_is_logged_with_its_error_as_fields(self, mocker: MockerFixture) -> None:+ debug = mocker.patch.object(google_factory.log, "debug")+ close_task = _schedule_and_find_close_task(close_coroutine=_close_failing())+ await asyncio.wait([close_task])++ debug.assert_called_once_with(+ "A Google async client could not be closed",+ fields={ERROR_TYPE_FIELD: "ConnectionError", ERROR_MESSAGE_FIELD: "connection reset"},+ )++ @pytest.mark.asyncio+ async def test_a_failed_close_is_logged_with_its_error_as_fields(self, mocker: MockerFixture) -> None:+ debug = mocker.patch.object(google_factory.log, "debug")+ close_task = asyncio.create_task(_close_failing())+ await asyncio.wait([close_task])++ GoogleFactory.log_client_close_failure(close_task=close_task)++ debug.assert_called_once_with(+ "A Google async client could not be closed",+ fields={ERROR_TYPE_FIELD: "ConnectionError", ERROR_MESSAGE_FIELD: "connection reset"},+ )++ @pytest.mark.asyncio+ async def test_a_successful_close_logs_nothing(self, mocker: MockerFixture) -> None:+ debug = mocker.patch.object(google_factory.log, "debug")+ close_task = asyncio.create_task(_close_succeeding())+ await close_task++ GoogleFactory.log_client_close_failure(close_task=close_task)++ debug.assert_not_called()++ @pytest.mark.asyncio+ async def test_a_cancelled_close_logs_nothing_and_does_not_raise(self, mocker: MockerFixture) -> None:+ """A cancelled task's `exception()` raises `CancelledError`, which must not escape the callback."""+ debug = mocker.patch.object(google_factory.log, "debug")+ close_task = asyncio.create_task(_close_never_finishing())+ await asyncio.sleep(0)+ close_task.cancel()+ await asyncio.wait([close_task])++ GoogleFactory.log_client_close_failure(close_task=close_task)++ debug.assert_not_called()diff --git a/tests/unit/pipelex/reporting/test_emit_runner_fallback.py b/tests/unit/pipelex/reporting/test_emit_runner_fallback.pyindex 1d8aaf38a..155814924 100644--- a/tests/unit/pipelex/reporting/test_emit_runner_fallback.py+++ b/tests/unit/pipelex/reporting/test_emit_runner_fallback.py@@ -44,6 +44,8 @@ DATA_INCLUSION_OFF = DataInclusionConfig(error_stack_traces=False,)+_ENGAGED_MESSAGE = "Usage events are emitted through this process's activity event log"+def _make_llm_job(pipeline_run_id: str,@@ -326,7 +328,7 @@ class TestEmitRunnerFallback:mocker: MockerFixture,caplog: pytest.LogCaptureFixture,) -> None:- """The 'activity-side emission engaged' INFO log fires only on the first emission per process."""+ """The INFO line saying usage events go through the activity event log fires only on the first emission per process."""_enable_ndjson_tracing(mocker, tmp_path)manager = ReportingManager()@@ -337,7 +339,7 @@ class TestEmitRunnerFallback:for _ in range(100):manager.report_inference_job(_make_llm_job("run_abc", trace_context=trace_context))- engaged_records = [record for record in caplog.records if "activity-side usage event emission engaged" in record.message.lower()]+ engaged_records = [record for record in caplog.records if record.getMessage() == _ENGAGED_MESSAGE]assert len(engaged_records) == 1def test_engaged_log_emitted_once_even_with_multiple_managers(@@ -360,7 +362,7 @@ class TestEmitRunnerFallback:manager_b.setup()manager_b.report_inference_job(_make_llm_job("run_abc", trace_context=trace_context))- engaged_records = [record for record in caplog.records if "activity-side usage event emission engaged" in record.message.lower()]+ engaged_records = [record for record in caplog.records if record.getMessage() == _ENGAGED_MESSAGE]assert len(engaged_records) == 1def test_retried_activity_emits_duplicate_usage_event_documenting_r2(diff --git a/tests/unit/pipelex/system/configuration/test_boot_tolerance.py b/tests/unit/pipelex/system/configuration/test_boot_tolerance.pyindex 117a51c28..f24bdc4cc 100644--- a/tests/unit/pipelex/system/configuration/test_boot_tolerance.py+++ b/tests/unit/pipelex/system/configuration/test_boot_tolerance.py@@ -48,6 +48,7 @@ from pipelex.system.telemetry.exceptions import TelemetryConfigValidationErrorfrom pipelex.system.telemetry.telemetry_config import PostHogMode, TelemetryConfigfrom pipelex.system.telemetry.telemetry_loader import load_telemetry_configfrom pipelex.tools.log.log_dispatch import LogDispatch+from pipelex.tools.log.log_fields import USER_ACTION_FIELDfrom pipelex.tools.log.log_levels import LogLevelfrom pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider@@ -320,13 +321,14 @@ class TestWhatTheWarningSays:assert warning_spy.call_count == 2inside_call, outside_call = warning_spy.call_args_list- assert "run `pipelex migrate` to update it" in inside_call.args[0]- assert "`pipelex migrate` does not reach it, so update it where it lives" in outside_call.args[0]+ assert inside_call.args[0] == outside_call.args[0] == "A configuration file is out of date and was migrated in memory only"assert inside_call.kwargs["fields"] == {"file.path": str(inside_file),"migration_steps": ["Nest the flat telemetry settings under [custom_posthog]"],"has_blocked_steps": False,+ USER_ACTION_FIELD: "Run pipelex migrate to update it",}+ assert outside_call.kwargs["fields"][USER_ACTION_FIELD] == "Update it where it lives, since pipelex migrate does not reach it"assert outside_call.kwargs["fields"]["file.path"] == str(outside_file)for call in (inside_call, outside_call):assert str(tmp_path) not in call.args[0]@@ -334,22 +336,22 @@ class TestWhatTheWarningSays:@pytest.mark.parametrize(("topic", "is_reached_by_migrate", "has_blocked_steps", "expected_remedy"),[- ("in reach", True, False, "run `pipelex migrate` to update it"),- ("in reach, blocked", True, True, "run `pipelex migrate` to update it, and make by hand the changes it reports it cannot apply"),- ("out of reach", False, False, "`pipelex migrate` does not reach it, so update it where it lives"),+ ("in reach", True, False, "Run pipelex migrate to update it"),+ ("in reach, blocked", True, True, "Run pipelex migrate to update it, and make by hand the changes it reports it cannot apply"),+ ("out of reach", False, False, "Update it where it lives, since pipelex migrate does not reach it"),("out of reach, blocked",False,True,- "`pipelex migrate` does not reach it, so update it where it lives, including changes no migration can apply for you",+ "Update it where it lives, with the changes no migration can apply, since pipelex migrate does not reach it",),],)- def test_each_message_says_nothing_was_written_and_a_blocked_file_says_so(+ def test_every_file_is_one_event_and_its_advice_says_its_remedy(self, tmp_path: Path, mocker: MockerFixture, topic: str, is_reached_by_migrate: bool, has_blocked_steps: bool, expected_remedy: str) -> None:- """The warning used to be one text that said nothing was written, and that some of what a file needs cannot be applied for- the user, with `pipelex migrate` reporting it; a fixed message per file must keep saying both.+ """Whatever its remedy, a stale file is one event, so a log store counts it under one message: the message says the file+ was migrated in memory only, and the remedy, `pipelex migrate` or an edit where the file lives, is its advice."""stale_file = StaleConfigurationFile(file_path=tmp_path / "pipelex.toml",@@ -362,10 +364,8 @@ class TestWhatTheWarningSays:StaleConfigurationWarning(files=[stale_file]).emit()warning_spy.assert_called_once()- message = warning_spy.call_args.args[0]- assert message == (- f"A configuration file is out of date and was read as if it had been migrated, and nothing was written; {expected_remedy}"- ), topic+ assert warning_spy.call_args.args[0] == "A configuration file is out of date and was migrated in memory only", topic+ assert warning_spy.call_args.kwargs["fields"][USER_ACTION_FIELD] == expected_remedy, topicassert warning_spy.call_args.kwargs["fields"]["has_blocked_steps"] is has_blocked_stepsdef test_it_says_what_the_ledger_carried_and_nothing_read_from_the_file(self, tmp_path: Path) -> None:@@ -526,7 +526,7 @@ class TestTheTelemetryLoader:assert config.custom_posthog is not Noneassert stale.read_bytes() == before, "a tolerated boot writes nothing"- assert "pipelex migrate" in warning.call_args.args[0]+ assert "pipelex migrate" in warning.call_args.kwargs["fields"][USER_ACTION_FIELD]assert warning.call_args.kwargs["fields"]["file.path"] == str(stale)def test_a_file_the_ledger_cannot_explain_still_raises(diff --git a/tests/unit/pipelex/system/test_positive_int_env.py b/tests/unit/pipelex/system/test_positive_int_env.pyindex 189c192b6..9c1791b63 100644--- a/tests/unit/pipelex/system/test_positive_int_env.py+++ b/tests/unit/pipelex/system/test_positive_int_env.py@@ -19,7 +19,7 @@ class TestPositiveIntEnv:assert get_positive_int_env(env_var=ENV_VAR, default=256) == 256warning_spy.assert_called_once_with(- "An environment variable holds no positive integer, so its default applies",+ "An environment variable holding no positive integer was ignored for its default",fields={"env_var": ENV_VAR, "default_value": 256},)diff --git a/tests/unit/pipelex/tools/misc/test_tenacity_utils.py b/tests/unit/pipelex/tools/misc/test_tenacity_utils.pyindex 93611bb04..7ef0f7ac9 100644--- a/tests/unit/pipelex/tools/misc/test_tenacity_utils.py+++ b/tests/unit/pipelex/tools/misc/test_tenacity_utils.py@@ -5,6 +5,7 @@ import pytestfrom pytest_mock import MockerFixturefrom tenacity import Retrying, retry_base, retry_if_exception_type, retry_if_result, stop_after_attempt, wait_fixed+from pipelex.tools.log.error_fields import ERROR_TYPE_FIELDfrom pipelex.tools.misc import tenacity_utilsfrom pipelex.tools.misc.tenacity_utils import log_retry@@ -44,7 +45,7 @@ class TestLogRetry:"retry on an exception",_fail_once_with_value_error,retry_if_exception_type(ValueError),- {"attempt_number": 1, "wait_seconds": WAIT_SECONDS, "exception_type": "ValueError"},+ {"attempt_number": 1, "wait_seconds": WAIT_SECONDS, ERROR_TYPE_FIELD: "ValueError"},),("retry on a result",diff --git a/tests/unit/pipelex/tools/test_log_console_fields.py b/tests/unit/pipelex/tools/test_log_console_fields.pyindex 33655caf2..cd60e5212 100644--- a/tests/unit/pipelex/tools/test_log_console_fields.py+++ b/tests/unit/pipelex/tools/test_log_console_fields.py@@ -305,7 +305,7 @@ class TestConsoleFields:),)- assert text.plain == "🧠: Running pipe_code=compose_company output_concept=Company pipe_type=PipeLLM attempt=2"+ assert text.plain == "Running pipe_code=compose_company output_concept=Company pipe_type=PipeLLM attempt=2"assert styles_of(text=text, fragment="compose_company") == [FIELD_STYLES["pipe_code"]] == ["red"]assert styles_of(text=text, fragment="Company") == [FIELD_STYLES["output_concept"]] == ["bold green"]assert styles_of(text=text, fragment="PipeLLM") == [FIELD_STYLES["pipe_type"]] == ["white"]@@ -322,7 +322,7 @@ class TestConsoleFields:text = rendered_text(record=record)- assert text.plain == f"🧠: Running {COLLIDING_FIELD_PREFIX}pipe_code=compose_company"+ assert text.plain == f"Running {COLLIDING_FIELD_PREFIX}pipe_code=compose_company"assert styles_of(text=text, fragment="compose_company") == [FIELD_STYLES["pipe_code"]]def test_what_a_record_factory_or_the_runtime_stamped_is_not_shown(self) -> None:@@ -332,7 +332,7 @@ class TestConsoleFields:text = rendered_text(record=record)- assert text.plain == "🧠: Stamped files=7"+ assert text.plain == "Stamped files=7"assert FIELD_NAMES_MARK not in text.plaindef test_a_record_the_fields_channel_never_saw_renders_its_message_alone(self) -> None:diff --git a/tests/unit/pipelex/tools/test_log_console_layouts.py b/tests/unit/pipelex/tools/test_log_console_layouts.pyindex f60c01dde..5833d0c4d 100644--- a/tests/unit/pipelex/tools/test_log_console_layouts.py+++ b/tests/unit/pipelex/tools/test_log_console_layouts.py@@ -56,7 +56,7 @@ class TestConsoleLayouts:def test_the_pipe_run_layout_draws_the_tree_in_the_style_map_colours(self, overrides: dict[str, Any], expected: str) -> None:text = rendered_text(record=record_with_fields(message="Pipe run starts", extra={**PIPE_RUN_FIELDS, **overrides}, layout=LogLayout.PIPE_RUN))- assert text.plain == f"🧠: {expected}"+ assert text.plain == expectedassert styles_of(text=text, fragment="compose_company") == [FIELD_STYLES["pipe_code"]]assert styles_of(text=text, fragment="Company") == [FIELD_STYLES["output_concept"]]@@ -102,7 +102,7 @@ class TestConsoleLayouts:text = rendered_text(record=record_with_fields(message="Inference call ends", extra=fields, layout=LogLayout.INFERENCE_CALL_END))- assert text.plain == f"🧠: {expected}"+ assert text.plain == expected@pytest.mark.parametrize(("overrides", "expected"),@@ -119,7 +119,7 @@ class TestConsoleLayouts:text = rendered_text(record=record_with_fields(message="Pipe run ends", extra=fields, layout=LogLayout.PIPE_RUN_END))- assert text.plain == f"🧠: {expected}"+ assert text.plain == expectedassert styles_of(text=text, fragment="compose_company") == [FIELD_STYLES["pipe_code"]]@pytest.mark.parametrize(@@ -138,7 +138,7 @@ class TestConsoleLayouts:) -> None:text = rendered_text(record=record_with_fields(message="Work ends", extra={**fields, **overrides}, layout=layout))- assert text.plain.startswith("🧠: Work ends ")+ assert text.plain.startswith("Work ends ")assert expected_values in text.plaindef test_a_value_carrying_markup_or_an_emoji_code_prints_as_written_inside_a_layout(self) -> None:@@ -150,7 +150,7 @@ class TestConsoleLayouts:text = rendered_text(record=record)- assert text.plain == "🧠: PipeCompose: [red]x[/red] → :fire:"+ assert text.plain == "PipeCompose: [red]x[/red] → :fire:"assert styles_of(text=text, fragment="[red]x[/red]") == [FIELD_STYLES["pipe_code"]]def test_the_console_renders_a_layout_end_to_end_and_the_other_fields_follow_it(self, caplog: pytest.LogCaptureFixture) -> None:@@ -189,12 +189,12 @@ class TestConsoleLayouts:text = rendered_text(record=record)- assert text.plain == f"🧠: Pipe run starts pipe_type=PipeCompose pipe_code=compose_company output_concept=Company {expected_values}"+ assert text.plain == f"Pipe run starts pipe_type=PipeCompose pipe_code=compose_company output_concept=Company {expected_values}"def test_a_layout_that_cannot_be_filled_falls_back_to_the_message_and_every_field(self) -> None:text = rendered_text(record=record_with_fields(message="Pipe run starts", extra={"pipe_code": "compose_company"}, layout=LogLayout.PIPE_RUN))- assert text.plain == "🧠: Pipe run starts pipe_code=compose_company"+ assert text.plain == "Pipe run starts pipe_code=compose_company"def test_a_layout_that_raises_anything_at_all_costs_only_itself(self, mocker: MockerFixture) -> None:"""What a layout's derivation can raise is open-ended, and an error outside the ones the fallback named used to lose the line."""@@ -202,7 +202,7 @@ class TestConsoleLayouts:text = rendered_text(record=record_with_fields(message="Pipe run starts", extra={"pipe_code": "compose_company"}, layout=LogLayout.PIPE_RUN))- assert text.plain == "🧠: Pipe run starts pipe_code=compose_company"+ assert text.plain == "Pipe run starts pipe_code=compose_company"def test_a_record_carrying_structured_content_keeps_its_message_and_every_field_follows_it(self, caplog: pytest.LogCaptureFixture) -> None:"""The console never repeats ``data`` in the suffix because the message renders it, so a layout must not replace that message."""@@ -278,7 +278,7 @@ class TestConsoleLayouts:def test_a_layout_name_nobody_registered_renders_the_message(self) -> None:text = rendered_text(record=record_with_fields(message="Plain", extra={"files": 7}, layout="no_such_layout"))- assert text.plain == "🧠: Plain files=7"+ assert text.plain == "Plain files=7"def test_every_layout_a_call_can_name_is_registered(self) -> None:assert set(CONSOLE_LAYOUTS) == set(LogLayout)diff --git a/tests/unit/pipelex/tools/test_log_console_sink.py b/tests/unit/pipelex/tools/test_log_console_sink.pyindex aaaeea273..1d28d35a0 100644--- a/tests/unit/pipelex/tools/test_log_console_sink.py+++ b/tests/unit/pipelex/tools/test_log_console_sink.py@@ -1,10 +1,10 @@-"""The ``console`` sink renders byte for byte what a plain Rich handler renders, plus the fields.+"""The ``console`` sink renders byte for byte what a plain Rich handler renders, plus the fields and another library's name.-The reference is the handler ``log.configure`` used to build inline before the sink existed, reading no-message as markup as the console now does: a ``RichHandler`` fed every ``[runtime.log.rich_log]`` setting,-``markup=False`` and the emoji formatter. Both handlers are pointed at the same kind of non-terminal console-and handed the same fixed record set. A record whose call gave no field renders identically through both; a-record with fields renders the same line with the fields after the message.+The reference is a plain ``RichHandler`` fed every ``[runtime.log.rich_log]`` setting, reading no message as+markup as the console does, with the stdlib's plain formatter. Both handlers are pointed at the same kind of+non-terminal console and handed the same fixed record set. A Pipelex record whose call gave no field renders+identically through both; a record with fields renders the same line with the fields after the message, and a+record from another library the same line with that library's package name before it."""from __future__ import annotations@@ -20,11 +20,11 @@ from rich.logging import RichHandlerfrom pipelex.system.configuration.config_loader import ConfigLoaderfrom pipelex.system.console_target import ConsoleTarget+from pipelex.tools.log.console_fields import ADVICE_STYLE, one_line_textfrom pipelex.tools.log.console_layouts import LogLayoutfrom pipelex.tools.log.console_log_sink import ConsoleLogSinkfrom pipelex.tools.log.log_config import HighlighterName, LogConfig, RichLogConfig-from pipelex.tools.log.log_fields import RICH_MARKUP_ATTRIBUTE, attach_log_record_extra-from pipelex.tools.log.log_formatter import EmojiLogFormatter+from pipelex.tools.log.log_fields import RICH_MARKUP_ATTRIBUTE, USER_ACTION_FIELD, attach_log_record_extrafrom pipelex.tools.log.log_redaction import CYCLE_TEXTfrom pipelex.tools.misc.toml_utils import load_toml_from_pathfrom tests.helpers.console_log_rendering import (@@ -32,6 +32,9 @@ from tests.helpers.console_log_rendering import (console_sink_on_buffer,installed_log,package_rich_log_config_without_rich_tracebacks,+ record_with_fields,+ rendered_text,+ styles_of,)CONSOLE_WIDTH = 100@@ -43,7 +46,7 @@ def _package_rich_log_config() -> RichLogConfig:def _reference_handler(*, config: RichLogConfig) -> logging.Handler:- """The handler ``log.configure`` built before the sink seam, setting for setting, reading no message as markup."""+ """A plain Rich handler with the sink's settings, setting for setting, reading no message as markup."""highlighter: Highlightermatch config.highlighter_name:case HighlighterName.JSON:@@ -54,6 +57,7 @@ def _reference_handler(*, config: RichLogConfig) -> logging.Handler:console=Console(file=io.StringIO()),show_time=config.is_show_time,show_level=config.is_show_level,+ show_path=config.is_show_path,enable_link_path=config.is_link_path_enabled,highlighter=highlighter,markup=False,@@ -63,7 +67,7 @@ def _reference_handler(*, config: RichLogConfig) -> logging.Handler:tracebacks_suppress=config.tracebacks_suppress,keywords=config.keywords_to_hilight,)- handler.setFormatter(EmojiLogFormatter())+ handler.setFormatter(logging.Formatter())return handler@@ -92,7 +96,7 @@ def _fixed_record_set(*, is_with_call_fields: bool = True) -> list[logging.LogReexcept ValueError as exc:record(name="pipelex.pipeline.pipe_run", level=logging.ERROR, message="Failed", exc_info=(type(exc), exc, exc.__traceback__))record(name="openai._base_client", level=logging.INFO, message="Retrying request")- record(name="myapp.jobs.nightly", level=logging.INFO, message="A logger with no emoji")+ record(name="myapp.jobs.nightly", level=logging.INFO, message="A line from an application")return records@@ -121,13 +125,24 @@ def _render(handler: logging.Handler, *, is_with_call_fields: bool = True) -> streturn buffer.getvalue()+def _with_package_names(*, reference: str) -> str:+ """The reference rendering with each foreign line's package name before its message, taking the padding after it."""+ for package_name, message in (("openai", "Retrying request"), ("myapp", "A line from an application")):+ prefix = f"{package_name}: "+ assert f"{message}{' ' * len(prefix)}" in reference+ reference = reference.replace(f"{message}{' ' * len(prefix)}", f"{prefix}{message}")+ return reference++class TestConsoleLogSink:@pytest.mark.parametrize("is_rich_tracebacks", [True, False], ids=["rich tracebacks", "tracebacks as text"])- def test_output_is_byte_identical_to_the_handler_configure_used_to_build_when_no_call_gave_a_field(self, is_rich_tracebacks: bool) -> None:+ def test_output_is_byte_identical_to_a_plain_rich_handler_when_no_call_gave_a_field(self, is_rich_tracebacks: bool) -> None:"""The run identifier and the structured content's ``data`` are attached too, and neither adds anything to the line.- With Rich tracebacks off, the traceback reaches the handler as text after the message, which the sink- splits off and prints under the line: a traceback with nothing Rich would read as markup prints as it did.+ A Pipelex line carries no prefix, and a line from another library its package name alone, which takes the+ padding the message column had after the message. With Rich tracebacks off, the traceback reaches the+ handler as text after the message, which the sink splits off and prints under the line: a traceback with+ nothing Rich would read as markup prints as it did."""config = _package_rich_log_config().model_copy(update={"is_rich_tracebacks": is_rich_tracebacks})reference = _render(_reference_handler(config=config), is_with_call_fields=False)@@ -136,10 +151,10 @@ class TestConsoleLogSink:rendered = _render(sink.handler, is_with_call_fields=False)assert rendered- assert "🧠: Running the pipe" in rendered- assert "[myapp.jobs.nightly]: A logger with no emoji" in rendered+ assert "INFO Running the pipe" in rendered+ assert "myapp: A line from an application" in renderedassert "ValueError" in rendered- assert rendered == reference+ assert rendered == _with_package_names(reference=reference)def test_a_record_with_fields_gets_them_after_the_message_and_every_other_line_is_unchanged(self) -> None:config = _package_rich_log_config()@@ -148,22 +163,92 @@ class TestConsoleLogSink:rendered = _render(sink.handler)- assert "🧠: Slow backend files=7" in rendered+ assert "WARNING Slow backend files=7" in renderedassert "r1" not in rendered# The suffix takes the padding the message column had after the message, so the line keeps its width.suffix = " files=7"- assert rendered == reference.replace(f"🧠: Slow backend{' ' * len(suffix)}", f"🧠: Slow backend{suffix}")+ expected = reference.replace(f"Slow backend{' ' * len(suffix)}", f"Slow backend{suffix}")+ assert rendered == _with_package_names(reference=expected)- def test_the_prefix_stays_on_a_line_that_carries_a_traceback(self) -> None:- """The Rich handler renders such a line from ``formatMessage`` alone, and the emoji must survive that path too."""+ def test_the_package_name_stays_on_a_line_that_carries_a_traceback(self, caplog: pytest.LogCaptureFixture) -> None:+ """The Rich handler renders such a line from ``formatMessage`` alone, and the package name must survive that path too."""config = _package_rich_log_config()assert config.is_rich_tracebacks, "the shipped default is what the regression rode on"+ caplog.set_level(logging.INFO, logger="myapp.jobs.nightly")+ buffer = io.StringIO()+ with installed_log(sink=console_sink_on_buffer(buffer=buffer)):+ try:+ msg = "boom"+ raise ValueError(msg)+ except ValueError:+ logging.getLogger("myapp.jobs.nightly").exception("Failed")++ rendered = buffer.getvalue()+ assert "myapp: Failed" in rendered+ assert "ValueError: boom" in rendered++ @pytest.mark.parametrize(+ "logger_name",+ ["pipelex.pipe_operators.pipe_llm", "pipelex_api.security", "pipelex_temporal.worker", "root"],+ ids=["the runtime", "the API server", "a Pipelex plugin", "the root logger"],+ )+ def test_a_pipelex_line_and_a_root_line_carry_no_prefix(self, logger_name: str) -> None:+ text = rendered_text(record=record_with_fields(message="Loaded the library", logger_name=logger_name))++ assert text.plain == "Loaded the library"++ def test_a_line_from_another_library_starts_with_its_package_name_dimmed(self) -> None:+ text = rendered_text(record=record_with_fields(message="HTTP Request: POST", logger_name="httpx._client", extra={"attempt": 2}))++ assert text.plain == "httpx: HTTP Request: POST attempt=2"+ assert "dim" in styles_of(text=text, fragment="httpx: ")++ @pytest.mark.parametrize("is_show_path", [False, True], ids=["the default", "is_show_path"])+ def test_the_source_path_column_shows_only_when_the_setting_asks_for_it(self, is_show_path: bool) -> None:+ config = _package_rich_log_config().model_copy(update={"is_show_path": is_show_path, "is_link_path_enabled": False})sink = ConsoleLogSink(rich_log_config=config, target=ConsoleTarget.STDERR)rendered = _render(sink.handler)- assert "🧠: Failed" in rendered- assert "ValueError: boom" in rendered+ assert ("module.py:42" in rendered) is is_show_path++ def test_the_shipped_default_hides_the_source_path_column(self) -> None:+ assert _package_rich_log_config().is_show_path is False++ def test_the_advice_prints_on_a_line_of_its_own_under_the_record_and_never_in_the_suffix(self) -> None:+ text = rendered_text(+ record=record_with_fields(+ message="A configuration file is out of date", extra={"file.path": "pipelex.toml", USER_ACTION_FIELD: "Run pipelex migrate"}+ )+ )++ assert text.plain == "A configuration file is out of date file.path=pipelex.toml\n→ Run pipelex migrate"+ assert ADVICE_STYLE in styles_of(text=text, fragment="\n→ Run pipelex migrate")++ def test_the_advice_is_written_whole_and_on_one_line(self) -> None:+ advice = "Run pipelex migrate " + "then check the file " * 10 + "\x1b[31mred"++ text = rendered_text(record=record_with_fields(message="A configuration file is out of date", extra={USER_ACTION_FIELD: advice}))++ (advice_line,) = text.plain.splitlines()[1:]+ assert advice_line == f"→ {one_line_text(text=advice)}"+ assert "\x1b" not in text.plain++ def test_with_tracebacks_as_text_the_advice_comes_before_the_traceback(self, caplog: pytest.LogCaptureFixture) -> None:+ caplog.set_level(logging.INFO, logger=__name__)+ buffer = io.StringIO()+ sink = console_sink_on_buffer(buffer=buffer, rich_log_config=package_rich_log_config_without_rich_tracebacks())+ with installed_log(sink=sink) as fresh:+ try:+ msg = "boom"+ raise ValueError(msg)+ except ValueError:+ fresh.error("Pipe run failed", include_exception=True, fields={"attempt": 2, USER_ACTION_FIELD: "Check the backend"})++ lines = buffer.getvalue().splitlines()+ (index_line,) = [index for index, line in enumerate(lines) if "Pipe run failed attempt=2" in line]+ assert lines[index_line + 1].strip() == "→ Check the backend"+ assert any("Traceback (most recent call last):" in line for line in lines[index_line + 2 :])@pytest.mark.parametrize(("layout", "fields", "expected_line"),@@ -255,17 +340,18 @@ class TestConsoleLogSink:assert message in rendered- def test_a_logger_named_in_lowercase_keeps_its_channel_prefix(self, caplog: pytest.LogCaptureFixture) -> None:- """A logger with no emoji is prefixed with its name in brackets, which Rich read as a tag and removed when the name starts lowercase.+ def test_a_logger_named_in_lowercase_keeps_its_package_name(self, caplog: pytest.LogCaptureFixture) -> None:+ """A prefix written into the message as ``[name]: `` was read by Rich as a tag and removed when the name started lowercase.- The line printed as ``: Pipe run failed``, with nothing saying which library wrote it.+ The line printed as ``: Pipe run failed``, with nothing saying which library wrote it. The package name is+ styled text of its own, never markup, so it prints whatever it is spelled like."""caplog.set_level(logging.INFO, logger="myapp.jobs.nightly")buffer = io.StringIO()with installed_log(sink=console_sink_on_buffer(buffer=buffer)):logging.getLogger("myapp.jobs.nightly").error("Pipe run failed")- assert "[myapp.jobs.nightly]: Pipe run failed" in buffer.getvalue()+ assert "myapp: Pipe run failed" in buffer.getvalue()def test_a_circular_content_prints_its_cycle_marker(self, caplog: pytest.LogCaptureFixture) -> None:"""A content JSON refuses is rendered as its ``repr``, where the redaction cuts the cycle with ``[cycle]``.@@ -296,11 +382,11 @@ class TestConsoleLogSink:assert message not in rendered- def test_the_handler_is_a_rich_handler_with_the_emoji_formatter_and_the_same_object_on_every_read(self) -> None:+ def test_the_handler_is_a_rich_handler_with_the_plain_formatter_and_the_same_object_on_every_read(self) -> None:sink = ConsoleLogSink(rich_log_config=_package_rich_log_config(), target=ConsoleTarget.STDERR)handler = sink.handlerassert isinstance(handler, RichHandler)- assert isinstance(handler.formatter, EmojiLogFormatter)+ assert type(handler.formatter) is logging.Formatterassert sink.handler is handlerdiff --git a/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py b/tests/unit/pipelex/tools/test_log_console_sink_without_rich.pyindex 543ee8f4f..9b38dd21c 100644--- a/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py+++ b/tests/unit/pipelex/tools/test_log_console_sink_without_rich.py@@ -34,6 +34,7 @@ _GUARD_SCRIPT = textwrap.dedent(rich_log_config=RichLogConfig(is_show_time=False,is_show_level=True,+ is_show_path=False,is_link_path_enabled=True,highlighter_name=HighlighterName.JSON,is_rich_tracebacks=True,diff --git a/tests/unit/pipelex/tools/test_log_secondary_exceptions.py b/tests/unit/pipelex/tools/test_log_secondary_exceptions.pyindex 206f1046b..572c7580e 100644--- a/tests/unit/pipelex/tools/test_log_secondary_exceptions.py+++ b/tests/unit/pipelex/tools/test_log_secondary_exceptions.py@@ -102,7 +102,7 @@ class TestSecondaryExceptionsCarryNoPayload:raw = json_buffer.getvalue()assert _PAYLOAD not in raw(line,) = _lines_of(buffer=json_buffer, logger_name="pipelex.pipe_run.delivery_executor")- assert line[MESSAGE_KEY] == "The absence record of the main output is malformed, so the delivery has no result to render"+ assert line[MESSAGE_KEY] == "The absence record of the main output is malformed"assert line[ERROR_TYPE_FIELD] == "ValidationError"assert line[ERROR_MESSAGE_FIELD].startswith("kind: Input should be ")assert "reason: Input should be a valid string" in line[ERROR_MESSAGE_FIELD]