Skip to content

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

Keyword‑only enforcement (#991)

Louis Choquel3cea91be6182
diff --git a/.claude/hooks/check-keyword-only.sh b/.claude/hooks/check-keyword-only.sh
new file mode 100755
index 000000000..6bbd52516
--- /dev/null
+++ b/.claude/hooks/check-keyword-only.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# PostToolUse hook: enforce the keyword-only-arguments convention on the just-edited pipelex source file.
+#
+# Runs the stdlib-only AST guard (pipelex/cli/dev_cli/commands/keyword_only_guard.py) on the single
+# edited file — ~0.04s, because it is invoked by FILE PATH (not `python -m ...`), which skips importing
+# the `pipelex` package __init__ chain entirely. On a violation the guard prints the offending
+# signatures to stderr and exits 2, which Claude Code surfaces back to the agent as blocking feedback.
+#
+# Out-of-scope edits exit 0 fast: non-.py files are rejected here in bash (no Python launch), and the
+# precise "is it under pipelex/, not __pycache__" decision is made in Python (see relative_source_path).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+GUARD="$PROJECT_DIR/pipelex/cli/dev_cli/commands/keyword_only_guard.py"
+PYTHON="$PROJECT_DIR/.venv/bin/python"
+
+# Read the tool-call JSON from stdin and extract tool_input.file_path (pure bash, no jq — house style).
+# `|| true`: grep exits 1 when a payload carries no file_path, which under `set -o pipefail` would
+# abort the assignment before the empty-check below — we want a clean pass-through instead.
+input=$(cat)
+file_path=$(echo "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)
+
+# Fast, silent pass-through: no file, not a .py file, or a checkout without the venv / guard in place.
+if [ -z "$file_path" ]; then
+ exit 0
+fi
+case "$file_path" in
+ *.py) ;;
+ *) exit 0 ;;
+esac
+[ -x "$PYTHON" ] || exit 0
+[ -f "$GUARD" ] || exit 0
+
+# Run from the repo root so the guard's cwd-relative path resolution is deterministic, then hand off
+# (exec → the guard's exit code 0/2 and its stderr become this hook's, with no extra shell layer).
+cd "$PROJECT_DIR"
+exec "$PYTHON" "$GUARD" "$file_path"
diff --git a/.claude/settings.json b/.claude/settings.json
index c65924b97..9eead5f6c 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -40,6 +40,18 @@
}
]
}
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "Edit|Write|MultiEdit",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-keyword-only.sh",
+ "timeout": 10
+ }
+ ]
+ }
]
},
"enabledPlugins": {
diff --git a/.github/workflows/lint-check.yml b/.github/workflows/lint-check.yml
index 1e53e135f..ad102bf2f 100644
--- a/.github/workflows/lint-check.yml
+++ b/.github/workflows/lint-check.yml
@@ -79,12 +79,30 @@ jobs:
run: make check-config-sync
# --------------------------------------------------------------------------
-# 4. Aggregator job — the *single* required status check
+# 4. Keyword-only convention — single job, version-independent
+# --------------------------------------------------------------------------
+ lint-keyword-only:
+ name: Lint (keyword-only)
+ runs-on: [aca-runner-lint]
+ env:
+ VIRTUAL_ENV: ${{ github.workspace }}/.venv
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install dependencies
+ run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+
+ - name: Run keyword-only convention check
+ run: make check-keyword-only
+
+# --------------------------------------------------------------------------
+# 5. Aggregator job — the *single* required status check
# --------------------------------------------------------------------------
lint-all:
name: Lint (all)
runs-on: ubuntu-latest
- needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync]
+ needs: [lint-ruff-plxt, lint-typecheck, lint-config-sync, lint-keyword-only]
if: always()
steps:
@@ -92,7 +110,8 @@ jobs:
run: |
if [ "${{ needs.lint-ruff-plxt.result }}" != "success" ] || \
[ "${{ needs.lint-typecheck.result }}" != "success" ] || \
- [ "${{ needs.lint-config-sync.result }}" != "success" ]; then
+ [ "${{ needs.lint-config-sync.result }}" != "success" ] || \
+ [ "${{ needs.lint-keyword-only.result }}" != "success" ]; then
echo "::error::At least one lint job failed."
exit 1
fi
diff --git a/AGENTS.md b/AGENTS.md
index a57c7b2a5..5e73763fa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -275,6 +275,17 @@ When adding validation or fields, decide which layer they belong to. Language ru
- If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file `.pipelex/pipelex.toml`. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matching `pipelex/pipelex.toml`, even empty ones like `activity_queues = {}`) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden.
- The different `pipelex.toml` files and the python model `configs.py` must be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just run `make tb` which tests the boot sequence, which includes the config loading.
+### Keyword-only arguments
+
+Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+
+- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`) is always allowed and often preferable.
+- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+
+The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs (dunders, pydantic validators/serializers, Typer/Temporal/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net.
+
+The full specification — the two exceptions, the carve-out list, the symmetric-tuple allowlist, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
+
## Writing tests
### Unit test generalities
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8be2ce23c..feea3977e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,41 +4,60 @@
### Added
-- **Unit tests for CLI internal logic.** New offline test coverage for the pipelex-internal logic behind the CLI commands (the spec'd CLI *interface* remains owned by the conformance suite): the doctor diagnostic checks (config files, telemetry, backend credentials/files, deck sync, model checks, fix mode, health-report rendering), the `pipelex run` core execution and its sync wrapper (bundle/main_pipe resolution, inputs loading, output/graph/working-memory/CSV saving, error-handler dispatch), the `build structures|inputs|output|runner` codegen cores, the readiness gate, the `show`/`which` report logic, and the gateway/telemetry/signature error handlers.
-- **Unit tests for inference plumbing, core runtime, and tools/config internals.** Offline coverage for the layers around inference and execution that can break independently of any provider: the structured-output ↔ instructor mode mapping, backend-credentials error messages, model-deck reference checks (presets/aliases/waterfalls/handles with fuzzy suggestions), the per-provider image-gen argument factory (Flux/Qwen/SDXL/GPT-image taxonomies), the LLM and image-gen worker routing factories (SDK dispatch, client caching, missing-dependency errors), gateway completions request-shaping and extract-output parsing (Azure/Mistral/Deepseek/Linkup), and the Mistral factory (messages, OCR extract output, document prep/upload). Core runtime: the local observer JSONL sink, the output renderer's Anything-concept resolution, the bundle-level graph rendering dispatch, the builder bundle-spec validation/`to_blueprint()`/pretty rendering and inputs operations, and the pipeline runner's error paths and MTHDS protocol surfaces (`validate`/`models`/`version`). Tools: the TOML config-sync engine (structure/comment preservation, dry-run, idempotency), document/image format enums, PIL image conversion, and the storage config validators.
-- **Unit tests for the Temporal deploy-critical entry points.** Offline coverage for the operational surfaces that previously only failed inside a live cluster: the worker CLI (project resolution from pyproject, fast-fail task-queue validation before library load, worker-base library loading, forced `temporal.is_enabled`, full Typer arg wiring into the worker loop), the codec HTTP server for the Temporal Web UI (encode/decode round-trip over real HTTP, CORS preflight and origin gating, content-type/malformed-payload guards, storage-failure → HTTP status mapping), and the server connection logic (API-key resolution per secret method, TLS/RPC-metadata wiring, payload-codec converter selection, named server-config selection, SDK error wrapping).
-
-### Changed
-
-- **Canonical protocol validation report (breaking).** `PipelexValidationReport` is reworked into the canonical typed shape shared by every Pipelex backend and moved to `pipelex/pipeline/validation_report.py`: `bundle_blueprint` (the batch's primary blueprint — first declaring `main_pipe`, else first; replaces the untyped single-or-list `blueprint` dump), `pipe_io_contracts` keyed by namespaced `pipe_ref` with typed `PipeIOContract` entries (per-pipe input JSON Schemas + output concept/multiplicity — new module `pipelex/pipeline/pipe_io_contracts.py`, ported from the hosted API's route-local builder), `validated_pipes` (per-pipe sweep outcomes, the same entries as the agent-CLI envelope), plus the existing `pending_signatures` / `is_runnable` verdict. The report is assembled in exactly one place — `build_validation_report` — that every backend calls, and primary-blueprint selection is one shared rule (`select_primary_blueprint` in `pipelex/pipeline/blueprint_selection.py`, also folded into the Temporal validate activity).
-- **`validated_pipes` entry key `pipe_code` → `pipe_ref` (breaking).** The entry has always carried the namespaced `pipe_ref` (`domain.code`) under a key named for the wrong identity; the key now says what the value is. Applies to the agent-CLI / builder validate envelopes and the protocol report.
-- **Protocol `validate` now produces a best-effort `graph_spec` — the local runtime catches up with the hosted route.** When the validated batch declares a `main_pipe`, `PipelexMTHDSProtocol.validate` dry-runs it in-process via `dry_run_pipe_in_process` against the still-open validation library and ships the resulting `GraphSpec` on the report — the same single-library-load pattern and best-effort degrade contract as the Temporal validate activity, enforced by ONE shared implementation (`best_effort_graph_spec`) both backends call: a graph-arm domain failure (`PipelexError`, pydantic `ValidationError`, polyfactory `FactoryException`) yields `graph_spec=None` with validation still successful; no declared `main_pipe` means no graph. To make that wiring importable, `dry_run_pipe_in_process` moved to its own module `pipelex/pipe_run/dry_run_in_process.py`: its old home `dry_run_pipeline.py` imports the protocol runner, so sharing a module would have been an import cycle.
-- **The Temporal validate activity result carries the full worker-side artifact set.** `DryValidateResult` gains `pending_signatures` (the runnability verdict crosses the boundary at last) and `pipe_io_contracts` (typed `PipeIOContract` entries computed activity-side against the worker's loaded library — the API side never needs to re-acquire a library to render schemas). Both fields are required on the wire: a version-skewed worker that doesn't emit them fails loudly at deserialization instead of defaulting to a silently wrong runnability verdict. Breaking for the wire model; Temporal validate has never shipped to prod.
-- **`MTHDS_PROTOCOL_VERSION` is deleted (breaking).** The hardcoded duplicate of the protocol version is gone from `pipelex/pipeline/runner.py`; the SDK's `PROTOCOL_VERSION` (`mthds.protocol.protocol`) is the single source of truth and consumers (including the hosted API) import it directly.
-- **Additive multi-file library construction.** Merge-time rules now support building a same-domain `.mthds` library as separate, additive files (forward-declared headers + separate definitions), enabling parallel top-down method construction:
- - A `PipeSignature` and a concrete pipe with the same code reconcile — the concrete pipe satisfies the signature instead of raising a duplicate-code error. `PipeSignature` works like a forward declaration ("header"), its concrete pipe like the definition; their `inputs`/`output` contracts must match. Contracts are compared by *normalized concept identity*, so a header's bare `Brief` reconciles with a definition's domain-qualified `thisdomain.Brief` (and native `Text` with `native.Text`); multiplicity is compared structurally. Two concrete pipes with the same code, or two declarations with genuinely different contracts, remain errors.
- - Concept references resolve against the merged library instead of per file, so a concept declared once can be referenced by bare code from sibling files of the same domain — whether those files are loaded in the same directory batch or across separate load batches (e.g. a concept declared in a `-L` library directory referenced from a separately-loaded bundle). A concept declared twice remains a `ConceptLibraryError`, and a reference resolvable nowhere now surfaces as a structured validation error instead of a raw traceback.
- - Domain `description` / `system_prompt` now merge order-independently across same-domain files: a membership-only file that omits them defers to whichever file declares them, instead of warning and racing on filesystem load order. The root's header therefore always wins over siblings that carry only `domain = "..."`. Two files declaring *different* non-empty values still keep the first and warn — a genuine double-declaration to resolve.
- - **`pending_signatures` + `is_runnable` on the validate result.** A successful `validate bundle` (notably a lenient `--allow-signatures` run) now reports the library-wide set of pipes still declared as `PipeSignature` — the unimplemented headers left to satisfy. Surfaced as a `pending_signatures` array plus an `is_runnable` boolean on the agent-CLI / builder validate JSON envelope, and in markdown as an explicit runnability verdict: a complete bundle states it is runnable, while a bundle with pending signatures states it is not yet runnable immediately above the verbatim "Pending signatures" section — so a top-down build (and the LLM driving it) can see exactly what remains without inferring completeness from an absent section. The protocol-level `validate` (`PipelexMTHDSProtocol`) reports the same verdict: `pending_signatures` + `is_runnable` are now Pipelex extension fields on `PipelexValidationReport`, so a build driving the runtime through the MTHDS Protocol sees it too. (The hosted runner's `/validate` builds its own response envelope and needs its own change to surface the verdict — it does not inherit these fields.)
-- **`PipeSignature` evicted from the executable pipe taxonomy.** A signature is a contract, not a way of running, so it is no longer a `PipeType` / `PipeCategory` member: `PipeType.PIPE_SIGNATURE` and `PipeCategory.PIPE_SIGNATURE` are **removed** (breaking — any code matching on `PipeCategory.PIPE_SIGNATURE` must drop that arm). It stays a `PipeAbstract` subclass (the dry-run-only shim): a signature now carries `type = "PipeSignature"` with `pipe_category = None`, and `is_signature` is a class fact (base `False`, overridden to `True` on `PipeSignature` / `PipeSignatureBlueprint`) rather than an enum read. `signature_for` is retained for tooling; setting `signature_for = "PipeSignature"` is still rejected, now structurally (it is not a valid `PipeType`) rather than by a dedicated validator.
-
-### Fixed
-
-- **The protocol model deck no longer loses aliases to cross-category collisions.** `PipelexModelDeck.aliases`/`waterfalls` were flat maps built by `update()`-ing the per-category maps together — the same alias name in several categories (e.g. `default-small` for both llm and extract) silently kept only the last category's entry, dropping aliases from the unfiltered deck. Both extensions are now keyed by model category (`aliases: {category: {alias: model}}`), preserving every entry; the protocol's flat `models` list is unchanged (each entry already carries its category as `type`). Breaking for the deck's extension shape.
-- **JSON-Schema rendering failures on the validate surfaces are now structured errors.** A pydantic schema-generation failure while building `pipe_io_contracts` (an unschematizable structure-class field) surfaced as a raw third-party exception — which the Temporal error boundary would not convert, so Temporal retried a deterministic failure and the caller got an opaque infra error instead of a validation-shaped one. `build_pipe_io_contracts` now converts it to the new `PipeIOContractError` (with the offending pipe/input/concept named), non-retryable at the validate workflow tier like `ValidateBundleError`.
-- **Protocol `validate`'s library teardown can no longer mask the real error.** If the body failed mid-window and the validation library's teardown then also raised, the teardown error replaced the in-flight one — the caller's failure named teardown instead of the actual problem. The wrapper now suppresses a teardown raise while a body error is propagating (and still raises it when the body succeeded), and captures the validation library id once — right after `validate_bundle` leaves it current — so the graph arm and the teardown always target the same library. Mirrors the Temporal validate activity's existing guards.
-- **Empty `mthds_contents` rejected with a structured error.** `validate_bundle` (and therefore protocol `validate`) accepted an empty `mthds_contents` list — it slipped past the provided-params check and crashed the canonical report's primary-blueprint selection with a raw `IndexError`. It now raises a `ValidateBundleError` at entry, and `select_primary_blueprint` itself guards the empty batch with the same structured error. The main-pipe selection rule is also now genuinely single-implementation: the hand-rolled first-declaring-`main_pipe` loops in `execution_seams`, `dry_run_pipeline`, and `inputs_ops` were folded into `select_primary_blueprint`.
-- **Additive multi-file libraries: qualified same-domain pipe references resolve across files.** A controller could reference a pipe in its own domain by qualified name (e.g. `research.find_key_findings`) only when that pipe was declared in the *same* file — the bare form already resolved across sibling files. Qualified same-domain references are now deferred to the merged library like bare ones, so a header file can reference a pipe whose concrete definition lives in a sibling file. A reference that no file in the merged library declares is still rejected at load.
-- **Concepts-only loading validates concept references.** Loading a bundle with concepts only (the `pipelex structures` path / `load_concepts_only`) skipped the cross-file concept-reference check that the full load runs, so a structure field pointing at an undeclared concept (`concept_ref` / `item_concept_ref`) was silently accepted, leaving an invalid schema in the library. It is now validated on the concepts-only path too, matching the full load. The concepts-only library-directory loader batches all sibling files into one validation pass (like the directory loader already did), so a structure field referencing a concept declared in a sibling resolves regardless of file load order.
-- **Multi-file dependency packages reconcile signatures with their definitions.** A dependency package split across files — a `PipeSignature` header plus its concrete sibling — collided on the duplicate pipe code and silently dropped one declaration (which one depended on load order). Dependencies now go through the same additive merge as the main library: the signature and its concrete reconcile to the concrete, same-domain concept references are validated, and a genuine duplicate definition raises instead of being swallowed as a warning.
-- **OpenAI image moderation mapping was inverted.** `is_moderated = true` sent OpenAI's gpt-image `moderation="low"` (the LESS restrictive setting) and `false` sent `"auto"` (standard filtering) — the exact opposite of the documented "enable content moderation" intent. The mapping now matches the flag: enabled → `"auto"`, disabled → `"low"`. Alongside the mapping fix, `ImgGenSetting.is_moderated` now defaults to `None` ("no explicit choice") instead of `False`: workers omit the moderation/safety-checker parameter so the provider's own default applies (OpenAI's documented default is `auto`). Without this, model-deck alias/handle resolution — which builds settings without the field — would have started sending the less restrictive `low` by default once the mapping was corrected. For FAL models this also means `enable_safety_checker` is no longer explicitly disabled by default; the provider default applies there too.
-- **Storage config validation now covers every provider and requires a real `{hash}` replacement field in `uri_format`.** GCP's `lazy_validate` accepted any uri_format containing the bare substring `hash` (e.g. `assets/myhash/file`), which has no substitution slot and would render the same URI for every stored object — silent storage-wide overwrites; the local and in-memory configs had no validation at all, leaving the same misconfiguration uncaught. The check parses the format string: every placeholder must be a plain `{name}` (escaped `{{hash}}`, format specs like `{hash:.0}` or `{primary_id:.0}`, conversions, and attribute/index access are all rejected — on any field they render constant, colliding, or oversized keys, so the rule is enforced uniformly rather than only on `{hash}`), placeholders outside the supported set (`{primary_id}`, `{secondary_id}`, `{hash}`, `{extension}`) are rejected at config time instead of crashing with `KeyError` at content-store time, a `{hash}` placeholder is required, a test rendering catches anything parsing can't, and bucket configs must set a positive `signed_urls_lifespan_seconds` (or `"disabled"`) so signed URLs can't be born dead. Operator note: this validation runs when the storage provider is constructed at Pipelex boot — a misconfigured `uri_format` (including for the default local method) now fails fast at startup rather than at the first content store. The per-provider checks and the operator-facing error message now live on a shared config base (so the providers can no longer drift apart), the storage provider factory validates local/in-memory configs the same way it already did S3/GCP, and `StorageProviderConfig.storage_path` dispatches on the configured method instead of blaming a missing local config when the method is S3/GCP.
-- **Mistral chat requests now send the system message before the user message.** `MistralFactory.make_simple_messages` appended the system message after the user message, contradicting its own docstring and the OpenAI-typed sibling method.
-- **String concept values in bundle specs are now constructible and load correctly.** Validating a string against the `ConceptSpec | str` union crashed in a `mode="before"` validator that assumed dict input, and `to_blueprint()` mapped the string into the blueprint's `structure` field, where the concept loader rejects anything that isn't a registered structure class name. A string concept value now validates cleanly and passes through to the blueprint as the concept's description.
-- **LocalObserver JSONL records always carry the true lifecycle event name.** A payload carrying its own `event_type` key could silently overwrite the event name in the written record, breaking event-type-based filtering for JSONL consumers; the event name now wins the merge.
-- **Temporal worker startup no longer logs a misleading project name.** When the worker is started for the current project (no explicit project argument), the startup log said `Starting worker for current project 'None'`; it now omits the name instead of interpolating the unresolved value.
-- **Tests under `tests/**/build/` directories were silently skipped.** pytest's default `norecursedirs` includes `build`, so the whole `tests/unit/pipelex/cli/commands/build/` directory (mirroring the source layout) was never collected in full runs — including a pre-existing cross-package refines regression test. The pytest config now overrides `norecursedirs` to the defaults minus `build`, and sets `testpaths = ["tests"]` so bare `pytest` runs never scan outside the test tree.
-- **`Anything`-output option numbering is now deterministic.** The output renderer iterated a pipe-dependency set when collecting a `PipeCondition`'s possible outputs, so the user-facing `output_option_N` / `schema_option_N` numbering could vary between runs; dependencies are now sorted by pipe code.
+- **Structured `validation_errors` on the error wire**: `ErrorReport` gains a typed `validation_errors: list[ValidationErrorItem] | None` field. `ValidateBundleError.to_error_report()` flattens its per-error data onto it via a single shared builder (`pipelex/pipeline/validation_errors.py`), so the structured error report an HTTP API surfaces carries machine-mappable per-error diagnostics — `category`, `message`, identity fields, and a `source` (declaring file) for cross-file mapping — instead of only a `detail` string. The closed `ValidationErrorCategory` set is `blueprint_validation` / `pipe_factory` / `pipe_validation` / `dry_run`; a **residual dry-run failure** (`DryRunError` / `PipeRunError`, no structured locator) is projected as one `dry_run` item **only when no categorized error has data**, so an invalid verdict always carries a non-empty `validation_errors[]` (the structured-info invariant) rather than a bare message. The same builder feeds the agent CLI's `validation_errors` JSON array, so the CLI and API structured shapes cannot drift. The list is surfaced under STRICT disclosure (`_STRICT_KEPT_FIELDS`) because it describes the caller's own submitted bundle, not server internals.
+- **Changed — agent CLI `validation_errors` shape**: the `validate` commands' error envelope now omits null-valued keys per entry (`exclude_none`) and gains the previously-dropped `source`, `field_name`, and `concept_code` fields. Entries are guaranteed to carry `category` and `message`; all other keys are present only when populated, so consumers must treat them as optional rather than assume a fixed key set.
+- **Per-content `source` on the in-memory validate path**: `PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_source=...)` and `validate_bundle(mthds_sources=...)` let a caller attach a logical source to each in-memory bundle string, threaded into `blueprint.source`. A sourceless `mthds_contents` submission previously produced `source=None`, breaking cross-file diagnostics; a host (e.g. an HTTP API) can now pass per-item sources so the structured `validation_errors` carry a real owning file. The on-disk CLI path is unchanged (it already records real file paths).
+- **`dry_run` validation category**: `ValidationErrorCategory` gains a `dry_run` value. A dry-run residual failure that previously produced a bare-message `ValidateBundleError` with an empty `validation_errors[]` now surfaces one structured `dry_run` item carrying the message (graph-level, so typically no `source`) — closing the structured-info gap that drove consumers to fabricate a category.
+- **`is_valid` on the canonical validation report**: `PipelexValidationReport` gains `is_valid: Literal[True] = True`, the always-true discriminant of the valid arm of the hosted `/validate` response union (mirrored by pipelex-api's `InvalidReport`'s `Literal[False]`). It sits beside `is_runnable`: a sound bundle may still be not-yet-runnable.
+- **Keyword-only AST guard**: A custom AST-based linter (`pipelex-dev check-keyword-only` / `make cko`) that mechanically enforces the keyword-only argument convention across `pipelex/`, wired into `make check` and `make agent-check`.
+- **Keyword-only auto-fix**: A non-gating `--fix` mode (`pipelex-dev check-keyword-only --fix` / `make fix-keyword-only` / `make fko`) that rewrites every mechanically-fixable violation by inserting a bare `*` as far left as possible (after `self`/`cls`), re-parsing each rewrite before writing and reporting the shapes it can't fix mechanically. It runs early in `make agent-check`; the read-only check still runs last and owns the pass/fail gate.
+- **Claude Code hook**: A `PostToolUse` bash hook (`.claude/hooks/check-keyword-only.sh`) that runs the guard on edited files for immediate blocking feedback to AI agents.
+- **CI integration**: A dedicated `lint-keyword-only` job in the GitHub Actions linting workflow to block non-compliant signatures from merging.
+- **Convention documentation**: New `docs/contribute/keyword-only-arguments.md`, plus updates to `CLAUDE.md` and `AGENTS.md` establishing the keyword-only convention as a standing rule.
+- **Offline CLI unit tests**: Coverage for the pipelex-internal logic behind the CLI commands — `doctor` diagnostics, `run` execution and its sync wrapper, the `build` codegen cores, the readiness gate, `show`/`which`, and the gateway/telemetry/signature error handlers (the spec'd CLI interface stays owned by the conformance suite).
+- **Offline inference & runtime unit tests**: Coverage for layers that can break without a provider — structured-output↔instructor mode mapping, model-deck reference checks, the image-gen argument and worker-routing factories, gateway request-shaping and extract parsing, the Mistral factory, the local observer sink, the output renderer, builder spec validation / `to_blueprint()`, the pipeline runner's error paths, the TOML config-sync engine, and the storage config validators.
+- **Offline Temporal entry-point unit tests**: Coverage for operational surfaces that previously only failed inside a live cluster — the worker CLI, the codec HTTP server (encode/decode, CORS, error→status mapping), and the server connection logic (API-key resolution, TLS, codec selection).
+
+### Changed
+
+- **[BREAKING] Keyword-only public API**: Top-level public surfaces now require keyword arguments after the first parameter. A caller passing a second-or-later argument positionally must switch to keyword form — affected methods include `Pipelex.make(integration_mode, *, ...)`, `Pipelex.setup(integration_mode, *, ...)`, and `PipelexHub.setup_config(config_cls, *, ...)`. Downstream consumers to check: `pipelex-api`, `pipelex-worker`, `n8n-nodes-pipelex`, cookbook, starter.
+- **Codebase-wide keyword-only refactor**: The entire `pipelex/` tree (leaf tools, domain core, inference layer, execution path, framework-sensitive packages) now places a bare `*` after the subject parameter, requiring all later arguments to be named at the call site (e.g. `copy_file(src, target_path=dst, overwrite=False)`).
+- **Signature subject corrections**: Reordered parameters so the true semantic subject is the first positional argument, e.g. `parse_pipe_spec(spec_data, *, pipe_type)`, `hydrate_content(raw_content, *, concept)`, and `write_manifest(manifest, *, deck_dir)`. `parse_pipe_spec` is consumed by the hosted runner API (`pipelex-api`), updated in lockstep.
+- **[BREAKING] Canonical protocol validation report**: `PipelexValidationReport` is reworked into the canonical typed shape shared by every backend and moved to `pipelex/pipeline/validation_report.py` — a typed `bundle_blueprint` (replacing the untyped single-or-list `blueprint` dump), `pipe_io_contracts` keyed by namespaced `pipe_ref` (new `pipelex/pipeline/pipe_io_contracts.py`), `validated_pipes`, and the `pending_signatures` / `is_runnable` verdict. It is assembled in exactly one place (`build_validation_report`) with a single shared primary-blueprint rule (`select_primary_blueprint`).
+- **[BREAKING] `validated_pipes` key `pipe_code` → `pipe_ref`**: the entry has always carried the namespaced `pipe_ref` (`domain.code`) under a key named for the wrong identity; the key now says what the value is.
+- **Protocol `validate` now produces a best-effort `graph_spec`**: when the batch declares a `main_pipe`, the local runtime dry-runs it in-process and ships the resulting `GraphSpec`, via one shared implementation (`best_effort_graph_spec`) the Temporal validate activity also calls; a graph-arm domain failure degrades to `graph_spec=None` with validation still successful. (`dry_run_pipe_in_process` moved to `pipelex/pipe_run/dry_run_in_process.py` to break an import cycle.)
+- **[BREAKING] Temporal validate activity carries the full worker-side artifact set**: `DryValidateResult` gains required `pending_signatures` and `pipe_io_contracts` fields computed worker-side, so a version-skewed worker fails loudly at deserialization instead of defaulting to a silently wrong verdict. (Temporal validate has never shipped to prod.)
+- **[BREAKING] `MTHDS_PROTOCOL_VERSION` deleted**: the hardcoded duplicate is gone from `runner.py`; the SDK's `PROTOCOL_VERSION` (`mthds.protocol.protocol`) is the single source of truth, imported directly by consumers including the hosted API.
+- **Additive multi-file library construction**: Same-domain `.mthds` libraries can now be built as separate, additive files (forward-declared `PipeSignature` headers plus concrete definitions in sibling files), enabling parallel top-down construction. A `PipeSignature` and a same-code concrete pipe reconcile (contracts compared by normalized concept identity) instead of colliding; concept and qualified pipe references resolve against the merged library across sibling and separately-loaded files; domain `description` / `system_prompt` merge order-independently; and a successful `validate` reports library-wide `pending_signatures` plus an `is_runnable` verdict in both JSON and markdown.
+- **[BREAKING] `PipeSignature` evicted from the executable pipe taxonomy**: a signature is a contract, not a way of running, so `PipeType.PIPE_SIGNATURE` and `PipeCategory.PIPE_SIGNATURE` are removed (any code matching on them must drop that arm). It stays a `PipeAbstract` subclass with `pipe_category = None`, and `is_signature` is now a class fact rather than an enum read.
+- **[BREAKING] Signatures are never a validation error (signatures-as-data)**: the validator no longer raises when a pipe reaches an unimplemented `PipeSignature`. Strict and lenient modes return the **same** report body — the assembled library's outstanding signatures via `pending_signatures` and `is_runnable = not pending_signatures`. `allow_signatures` narrows to a sweep-mechanics flag (whether signature pipes are mock-run and listed in `validated_pipes`); it no longer changes the verdict. The "is this a failure?" decision moves to the consumer: the whole-bundle / whole-library surfaces (`pipelex validate`, `pipelex validate --all`, `pipelex-agent validate bundle` / `validate method` / `validate pipe --all`) derive the exit code from the library-wide runnability verdict — strict by default, exiting non-zero on `not is_runnable` unless `--allow-signatures`, while still emitting the success envelope (carrying `pending_signatures` + `is_runnable: false`). Single-pipe surfaces make no library-wide runnability claim and never gate: bare `validate pipe <code>`, and `validate bundle` / `validate method` invoked with `--pipe` (the slice can be fully implemented even when unrelated placeholders remain elsewhere). The **execute/run** path is unchanged — running a stub still raises `PipeSignatureNotExecutableError`.
+- **[BREAKING] Host-wiring guards reclassified to `PipelexUnexpectedError`**: `validate_bundle` / `load_concepts_only`'s "provide exactly one of `mthds_contents` / `mthds_file_path`" guards (and the existing `mthds_sources`-length-mismatch guard) now raise `PipelexUnexpectedError` (→ 500), not `ValidateBundleError` — a caller wiring bug is a programmer error, not a content verdict to be reported as an invalid bundle. The empty-`mthds_contents` guard stays caller-facing.
+
+### Fixed
+
+- **Protocol model deck no longer loses aliases to cross-category collisions**: `PipelexModelDeck.aliases` / `waterfalls` are now keyed by model category (`{category: {alias: model}}`) instead of being flattened with `update()`, which silently kept only the last category's entry for an alias name shared across categories. Breaking for the deck's extension shape.
+- **JSON-Schema rendering failures on the validate surfaces are now structured errors**: a pydantic schema-generation failure while building `pipe_io_contracts` now raises the new non-retryable `PipeIOContractError` (naming the offending pipe/input/concept) instead of a raw exception that the Temporal boundary would retry forever.
+- **Protocol `validate` teardown can no longer mask the real error**: a raising library teardown is suppressed while a body error is propagating, and the validation library id is captured once so the graph arm and the teardown always target the same library (mirrors the Temporal validate activity's guards).
+- **Empty `mthds_contents` is rejected with a structured error**: `validate_bundle` and `select_primary_blueprint` now raise `ValidateBundleError` instead of crashing primary-blueprint selection with a raw `IndexError`; the hand-rolled first-declaring-`main_pipe` loops in `execution_seams`, `dry_run_pipeline`, and `inputs_ops` are folded into the single `select_primary_blueprint`.
+- **Structured-info invariant is now total — parse-level failures carry a structured item**: a malformed `.mthds` file (a TOML-syntax error, an empty blueprint, or a bundle-elaborator failure) is raised with only a message and no categorized data, so an invalid verdict previously rode an **empty** `validation_errors[]` for the single most common failure mode. The shared builder (`build_validation_error_items`) gains a last-resort `fallback_message` residual: when no categorized error and no `dry_run` residual produced an item, it emits one `blueprint_validation` item carrying the message (no `source`, no `error_type` — the bundle could not become a blueprint at all). Both surfaces — `ValidateBundleError.to_error_report()` and the agent CLI's `extract_validation_errors()` — pass it, so every invalid verdict now carries a non-empty `validation_errors[]`, never a bare message.
+- **Qualified same-domain pipe references resolve across files**: a controller referencing a sibling-file pipe by qualified name (`research.find_key_findings`) is now deferred to the merged library like bare references; a reference no file declares is still rejected at load.
+- **Concepts-only loading validates concept references**: the `pipelex structures` / `load_concepts_only` path now runs the cross-file concept-reference check (batching sibling files into one pass) instead of silently accepting a structure field pointing at an undeclared concept.
+- **Multi-file dependency packages reconcile signatures with their definitions**: a dependency package split into a `PipeSignature` header plus its concrete sibling now goes through the same additive merge instead of colliding on the duplicate code and dropping one declaration by load order.
+- **OpenAI image moderation mapping was inverted**: `is_moderated=true` sent the *less* restrictive `moderation="low"` and `false` sent `"auto"` — the mapping now matches the flag (enabled → `"auto"`, disabled → `"low"`). `ImgGenSetting.is_moderated` also defaults to `None`, so workers omit the parameter and the provider's own default applies (which also stops force-disabling FAL's `enable_safety_checker`).
+- **Storage config validation now covers every provider and requires a real `{hash}` slot**: the `uri_format` check is enforced uniformly across local / in-memory / S3 / GCP — every placeholder must be a plain supported `{name}`, a `{hash}` slot is required (GCP previously accepted the bare substring `hash`, silently overwriting every stored object), and buckets must set a positive `signed_urls_lifespan_seconds`. A misconfigured format now fails fast at Pipelex boot instead of at the first content store.
+- **Mistral chat requests now send the system message before the user message**: `make_simple_messages` previously appended it after the user message, contradicting its own docstring and the OpenAI-typed sibling.
+- **String concept values in bundle specs are constructible again**: a bare string in the `ConceptSpec | str` union now validates (no longer crashing the `mode="before"` validator) and passes through to the blueprint as the concept's description instead of into `structure`, where the loader rejected it.
+- **LocalObserver JSONL records always carry the true lifecycle event name**: a payload's own `event_type` key can no longer overwrite the event name in the written record, which had broken event-type filtering for JSONL consumers.
+- **Temporal worker startup no longer logs a misleading project name**: starting for the current project (no explicit argument) now omits the name instead of logging `'None'`.
+- **Tests under `tests/**/build/` are no longer silently skipped**: pytest's default `norecursedirs` includes `build`, so the whole `tests/unit/pipelex/cli/commands/build/` tree was never collected; the config now overrides `norecursedirs` and sets `testpaths = ["tests"]`.
+- **`Anything`-output option numbering is now deterministic**: the output renderer sorts a `PipeCondition`'s possible outputs by pipe code instead of iterating a set, so `output_option_N` / `schema_option_N` numbering is stable across runs.
+- **Documentation examples**: Updated code snippets in `docs/under-the-hood/` to match the new keyword-only signatures.
+- **Test mock assertions**: Migrated mock assertions from `.call_args.args` to `.call_args.kwargs` to reflect keyword-only calls.
+
+### Removed
+
+- **[BREAKING] `SignaturesNotAllowedError` deleted**: with signatures no longer a validation error, the strict-mode signature pre-pass (`BundleValidator._signature_pre_pass`), the `signature_check_error` field on `ValidateBundleError`, the `handle_signatures_not_allowed_error` CLI renderer, and the `SignaturesNotAllowedError` exception class itself are removed. Code that caught `SignaturesNotAllowedError` on the validate path should read the report's `pending_signatures` / `is_runnable` instead; the execute path's `PipeSignatureNotExecutableError` is unaffected.
+- **Keyword-only migration scaffolding**: With the whole `pipelex/` tree converted, the temporary baseline file and the `pipelex-dev check-keyword-only --regen-baseline` flag are removed; the guard now hard-blocks on any new violation rather than burning one down.
## [v0.33.0] - 2026-06-11
diff --git a/CLAUDE.md b/CLAUDE.md
index 0a0b9f49a..bc13c4171 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -168,6 +168,17 @@ When adding validation or fields, decide which layer they belong to. Language ru
- If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file `.pipelex/pipelex.toml`. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matching `pipelex/pipelex.toml`, even empty ones like `activity_queues = {}`) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden.
- The different `pipelex.toml` files and the python model `configs.py` must be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just run `make tb` which tests the boot sequence, which includes the config loading.
+### Keyword-only arguments
+
+Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+
+- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`) is always allowed and often preferable.
+- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+
+The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs (dunders, pydantic validators/serializers, Typer/Temporal/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net.
+
+The full specification — the two exceptions, the carve-out list, the symmetric-tuple allowlist, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
+
## Writing Docs
We use Material for MkDocs. All markdown in our docs must be compatible with Material for MkDocs and done using best practices to get the best results with Material for MkDocs.
diff --git a/Makefile b/Makefile
index 7fc761306..a89540500 100644
--- a/Makefile
+++ b/Makefile
@@ -130,6 +130,8 @@ make ttm - Shorthand -> test-temporal
make check-unused-imports - Check for unused imports without fixing
make fix-unused-imports - Fix unused imports with ruff
make fui - Shorthand -> fix-unused-imports
+make fix-keyword-only - Auto-fix keyword-only-args violations (insert a bare *)
+make fko - Shorthand -> fix-keyword-only
make check-TODOs - Check for TODOs
make docs - Serve documentation locally with mkdocs
@@ -180,7 +182,7 @@ export HELP
.PHONY: \
all help env env-verbose check-uv check-uv-verbose lock install update build \
format lint ruff-format ruff-lint pyright mypy pylint plxt plxt-format plxt-lint \
- rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-rules check-urls cu insert-skeleton \
+ rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko check-rules check-urls cu insert-skeleton \
cleanderived cleanenv cleanall \
test test-xdist t test-quiet tq test-with-prints tp test-inference ti \
test-llm tl test-img-gen tg test-extract te test-temporal ttm codex-tests gha-tests \
@@ -316,6 +318,21 @@ check-config-sync: env
ccs: check-config-sync
@echo "> done: ccs = check-config-sync"
+check-keyword-only: env
+ $(call PRINT_TITLE,"Enforcing the keyword-only-arguments convention across pipelex/ source")
+ $(VENV_PIPELEX_DEV) check-keyword-only --quiet
+
+cko: check-keyword-only
+ @echo "> done: cko = check-keyword-only"
+
+fix-keyword-only: env
+ $(call PRINT_TITLE,"Auto-fixing keyword-only-arguments violations across pipelex/ source")
+ $(VENV_PIPELEX_DEV) check-keyword-only --fix --quiet
+ $(VENV_RUFF) format . --config pyproject.toml
+
+fko: fix-keyword-only
+ @echo "> done: fko = fix-keyword-only"
+
generate-mthds-schema: env
$(call PRINT_TITLE,"Generating MTHDS JSON Schema")
$(VENV_PIPELEX_DEV) generate-mthds-schema
@@ -1137,7 +1154,7 @@ trund: temporal-run-dry
### SHORTHANDS
##########################################################################################
-c: format lint pyright mypy
+c: check-keyword-only format lint pyright mypy
@echo "> done: c = check"
cc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet c
@@ -1146,10 +1163,10 @@ cc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update
up: generate-mthds-schema-quiet update-gateway-models-quiet up-kit-configs rules
@echo "> done: up = generate-mthds-schema update-gateway-models up-kit-configs rules"
-check: cc check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema pylint
+check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet update-gateway-models-quiet check-unused-imports check-config-sync check-rules check-urls check-gateway-models check-mthds-schema check-keyword-only format lint pyright mypy pylint
@echo "> done: check"
-agent-check: fix-unused-imports format lint pyright mypy
+agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-keyword-only
@echo "> done: agent-check"
v: validate
diff --git a/TODOS.md b/TODOS.md
index 606fbf36d..26be33d72 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,180 +1,374 @@
-# PR guide — additive multi-file MTHDS libraries (recursive design) + canonical MTHDS-protocol validate surface
+# Plan: CLI-or-API backend for MTHDS validation & graph rendering
-> **For reviewers.** This branch (`feature/Support-recursive-design`) carries two related bodies of work, in landing order:
+## Goal
+
+Today the VS Code extension validates `.mthds` bundles and renders method graphs exclusively by spawning the `pipelex-agent` Python CLI. Add a second backend that calls the **Pipelex API** (`pipelex-api`) over HTTP via the **`mthds-js`** typed client, selectable through a setting. The CLI backend stays the default and is preserved unchanged.
+
+This plan spans three repos plus the extension. The two upstream improvements — `pipelex` (expose structured validation errors over the API) and `mthds-js` (type and surface them) — are prerequisites for validation parity and are first-class phases here.
+
+## Decisions locked
+
+- **Expose structured validation errors over the API** — yes, make the `pipelex` runtime change. This is the gating prerequisite for validation parity.
+- **One call returns both** — when the extension needs validation details *and* the graph for the same file state, it must get both from a single backend call; no separate validate + graph round-trips. The API's `/v1/validate` already returns both. The CLI's `validate bundle --view --format json` must be extended to return both in one combined envelope (today it throws on invalid bundles instead of returning errors alongside a null graph).
+- **API target** — default local self-hosted `http://localhost:8081`, changeable in settings. Optional hosted `api.pipelex.com` via an API key. Key is picked up from the environment / VS Code SecretStorage — never stored as plaintext in settings.
+- **Multi-file bundles** — send every `.mthds` file in the saved file's directory as `mthds_contents[]` (mirrors the CLI's `--library-dir <dir>`).
+- **HTTP client** — use `mthds-js` (`MthdsApiClient`), not a hand-rolled fetch client.
+- **Default backend** — `cli` (zero-config preserved); `api` is opt-in.
+- **Per-pipe FAILURE as data** — it is acceptable for `/v1/validate` to report per-pipe dry-run FAILUREs as data on a 200 response (in `validated_pipes`) rather than always raising 422. The extension surfaces both the 422 `validation_errors` and any 200 `validated_pipes` FAILUREs as diagnostics. **Reality check (verified):** this is aspirational, not current behavior — the API response model and docstrings *allow* `FAILURE` entries in `validated_pipes`, but the current route raises 422 on *any* `ValidateBundleError`, so the 200-FAILURE channel never fires today. Keep the extension defensive (treat the channel as possibly-empty), but actually producing FAILURE-on-200 would require a deliberate behavior change in pipelex / pipelex-api that is **not** scoped in Phase 1 or 2 (which only confirm/document the boundary). Decide explicitly if that channel is needed.
+
+## Decisions locked in eng review (2026-06-15)
+
+These supersede or refine the items above where they conflict.
+
+- **Part B deferred.** Do NOT add a combined exit-0 `validate bundle --view --format json` envelope. Verified: `bundle_cmd.py` validates first and runs the `if view:` block only on success, so a single `--view` spawn already yields graph on exit 0 or `validation_errors` on non-zero exit. Phase 1 is **Part A only**. Part B moves to Out of scope.
+- **STRICT disclosure.** `validation_errors` IS surfaced on the untrusted external surface — add it to `_STRICT_KEPT_FIELDS` (`base_exceptions.py:54`), the documented single-decision contract for both STRICT branches. Rationale is NOT "like `caller_facing_message`" (that field is kept by separate branch logic, not this set) — cite the `_STRICT_KEPT_FIELDS` contract. They're the user's own submitted-bundle diagnostics, not server internals; redacting them would gut the hosted path.
+- **Conformance coverage added.** Add a `docs/specs/` ↔ `conformance/` pair for the `/v1/validate` **error** envelope (not covered today) and run `make check-spec-links`. The conformance test must assert the **real wire response**, not just the hand-maintained `pipelex-api.openapi.yaml` (which is a 4th place the shape lives — keep it in sync).
+- **MIN_AGENT_VERSION → 0.34.0.** Raise the CLI floor to the Part A version so the CLI's error JSON carries `source`/`field_name` and both backends use `source`. This IS a compatibility-floor break (older CLIs get a "too old" message) — state it explicitly; "CLI unchanged" refers to behavior, not the version requirement. Use the `bump-pipelex-version` skill to keep all floor references in sync.
+- **API `source` fix (load-bearing).** The validate request carries bundle text as nameless `mthds_contents: list[str]`, so the API sets `blueprint.source = None` (`interpreter.py:43`; `handle_pipe_errors.py:106,162` hard-code `source=None`) — cross-file diagnostics misfire on the API backend. Fix: add an **optional, additive per-item name** to the validate request (e.g. parallel `mthds_names` or `list[{name, content}]`, neutral/standard field names per the MTHDS brand boundary) and thread it into `blueprint.source` on the in-memory load path. Coordinate with the active MTHDS protocol-surface-alignment work. Spans pipelex Phase 1 + pipelex-api Phase 2 + mthds-js Phase 3.
+- **API transport-failure policy.** On a server-unreachable / non-`problem+json` / unparseable error (not a 422 validation failure): show an actionable notification ("Pipelex API unreachable at {baseUrl} — is pipelex-api running?"), set **no diagnostics**, **clear** any stale diagnostics, and do **not** auto-fall back to CLI. Applies to any non-validation API error, including HTML proxy pages / auth JSON / timeouts.
+- **Privacy confirmation timing.** Fire the non-localhost confirmation **before the first remote request**, and state that it sends the **whole directory's `.mthds` contents**, not just the active file.
+- **Multi-file gathering = disk read (v1).** Read siblings from disk to match CLI `--library-dir` semantics; verify the directory gather matches CLI bundle resolution (nested dirs, configured libraries, symlinks, ignored files, ordering) or document the divergence. Buffer-awareness is a follow-up TODO.
+- **Version-gate leniency (v1).** Parse `implementation_version` leniently — treat unparseable / prerelease / dev tags (`0.4.0-dev`, `latest`) as capable (warn-once, don't hard-block). Capability-probe redesign is a follow-up TODO.
+- **mthds-js runtime checklist.** Beyond "rollup bundles it": verify `fetch`, `AbortController`, proxy settings, TLS/cert handling, ESM/CJS interop on the VS Code extension-host Node runtime. Confirm SecretStorage→env token **precedence** actually overrides any native env read in `mthds-js`. Consider a file/workspace pin for `mthds` during dev while the npm publish is pending.
+
+## ▶ Resume point — current status (last updated 2026-06-16)
+
+**Strategy pivot (supersedes "release 0.34.0 to unblock Phase 2"):** we are NOT releasing pipelex first. We fix the **entire cross-repo train against an unreleased pipelex commit pin**, prove it end-to-end, and **cut pipelex 0.34.0 LAST**. This avoids a premature release PR and version juggling — the pipelex worktree stays at `0.33.0`, so pipelex-api's `==0.33.0` constraint keeps matching the pin throughout.
+
+**Pin mechanism ("both"):** pipelex-api pins pipelex with an **editable path** locally (`pipelex = { path = "../_calls", editable = true }` in `[tool.uv.sources]`) for a tight iteration loop, but the **committed** form must be the **git-rev SHA** (reproducible/CI). A comment block in `../pipelex-api/pyproject.toml` records the alternate line to restore. The pipelex-api Checkpoint-2 commit was made with the **git-rev form** at the pushed pipelex tip `0ab2cb8b` (so CI/build is reproducible); swap back to the editable line + re-`uv lock` for the next local iteration loop.
+
+> **⤳ SUPERSEDED by the validate/HTTP conformance plan (workspace `TODOS.md`, 2026-06): two T4-era divergences are now reversed.**
+> 1. **Conformance HTTP arm is BUILT** — the "conformance HTTP arm stays deferred (D5)" divergence (T4 below) no longer holds. `conformance/` now boots `pipelex-api` as a subprocess and asserts the **real wire** for `/validate`, `/models`, `/version`+`/health` (D-G), with the conformance CI installing the sibling (D-H). The spec's HTTP-section `<!-- unverified -->` markers were retired/narrowed accordingly. The `wip/conformance-http-arm.md` brief is marked revived/built.
+> 2. **`/validate` reframed to a 200-diagnostic endpoint** — the old "invalid bundle → 422 problem" contract this plan assumed (Decisions-locked "One call returns both" / "Per-pipe FAILURE as data") is replaced: **every produced verdict (valid OR invalid) rides a 200 discriminated on `is_valid`**; non-2xx is reserved for no-verdict conditions (request-shape 422, auth, 5xx). pipelex emits `is_valid` + the `dry_run` category + signatures-as-data; pipelex-api returns the `ValidReport | InvalidReport` union; the consumers (mthds-js typed `ValidationResult` union, the vscode backends) read `is_valid` off the body and the fabricated-`blueprint_validation` synthesis sites are deleted (vscode followup #10 closed). The structured-info invariant is now total (every invalid verdict carries a non-empty `validation_errors[]`). The `mthds_names`→`mthds_sources` rename also propagated to mthds-js. The 200-diagnostic contract landed in the MTHDS open standard (`mthds/`) too (D-F). **Release train unchanged:** still pipelex 0.34.0 LAST → pipelex-api re-pin `==0.34.0` + image → mthds-js publish → vscode re-pin + release.
+
+**DONE:**
+
+- **Phase 1 (pipelex)** — committed + **pushed**, branch `feature/Tweaks-for-validation-api` (version still `0.33.0`). See Checkpoint 1 below.
+- **Pipelex side of T3 (the enabling refactor)** — committed + **pushed**, tip **`0ab2cb8b`** (`refactor(validation): extract validate_bundles_in_process + thread mthds_names through temporal dry-validate`):
+ - NEW `pipelex/pipeline/validate_in_process.py::validate_bundles_in_process(*, mthds_contents, mthds_names=None, library_dirs=None, allow_signatures=False, log_context="validate")` — extracted the in-process validate orchestration out of `PipelexMTHDSProtocol.validate` (protocol signature untouched, delegates). Also corrected the protocol-path comment: that path carries nameless content so `source` stays `None`; the CLI populates `source` via the separate `validate_bundle(mthds_file_path=…)` disk entry point.
+ - `DryValidateArg.mthds_names` + `act_dry_validate` threads it to `validate_bundle`.
+ - Deferred follow-up #9 (library-window teardown hand-mirrored across `validate_in_process` + `act_dry_validate`) captured in `wip/dry-run-refactor/followup-dry-validate-hardening.md` — unify when `ApiRunner.validate` lands as the third consumer (now landed; revisit).
+- **Phase 2 / Checkpoint 2 (pipelex-api)** — **DONE + committed** on `feature/validation-errors-source`, commit **`2941daa`** (`feat(validate): structured validation_errors + optional mthds_names source threading`). Pinned pipelex git-rev `0ab2cb8b`, bumped **0.3.0 → 0.4.0**, `uv lock`+`uv sync --all-extras`, `make agent-check` + full `make agent-test` + `make openapi-check` GREEN against the git-rev install. See Checkpoint 2 below for as-built.
+- **Spec (T4)** — `docs/specs/pipelex-mthds-protocol.md` Error-contract section updated (validation_errors + mthds_names), committed on the workspace-root specs repo `dev` branch (**`a8b6b4b`**). `make check-spec-links` GREEN. **T4 divergence (deliberate):** the eng-review Issue 2 asked for a *conformance* test, but the conformance suite is CLI-only and the HTTP arm is **deferred (D5, `wip/conformance-http-arm.md`)** — so the real-wire 422 + `source` is verified in **pipelex-api's own suite** (`tests/unit/test_validate_errors.py`), referenced by the spec's `<!-- unverified -->` marker (the established pattern for HTTP-arm verification). No conformance HTTP harness was built.
+- **Phase 3 / Checkpoint 3 (mthds-js, T5)** — **DONE + committed** on `feature/typed-validation-report`, commit **`ad74bde`** (`feat(validate): typed PipelexValidationReport + structured validation errors`). `make check` (build + depcruise + full suite) GREEN. See Checkpoint 3 below for as-built. **Version stays 0.10.0** (NOT bumped to 0.11.0) and **npm publish deferred** to the release-LAST phase — consistent with pipelex staying at 0.33.0; the vscode extension pins mthds-js via a local file/workspace pin during dev.
+- **Phase 4 / Checkpoint 4 (vscode-pipelex, T6–T11)** — **DONE (uncommitted)** on branch `feature/Use-pipelex-api` in `../vscode-pipelex`. Backend abstraction (`ValidationBackend` + `CliValidationBackend` single-spawn exit-code discriminator + `ApiValidationBackend` over `MthdsApiClient`), settings, SecretStorage key commands, multi-file disk gather + per-item `mthds_names`, cross-file diagnostics via `source`, `MIN_AGENT_VERSION`→0.34.0, lenient API version gate, transport-failure policy, privacy confirm. `mthds` pinned `portal:../../../mthds-js`. Full vitest suite GREEN (141 tests, 37 new), `tsc` clean, node+browser+full builds green, bundle verified (no telemetry leak; `mthds` isolated to the API-backend chunk). See Checkpoint 4 below for as-built.
+
+**NEXT (resume here):** **Phase 5 — vscode-pipelex: docs polish, manual QA, release prep.** Core docs/CHANGELOG already landed with Phase 4 (see Checkpoint 4). Remaining: manual QA of both backends against a real `pipelex-api` (valid/invalid/multi-file/hosted-key), then the **release-LAST** train: cut pipelex 0.34.0 → re-pin pipelex-api `==0.34.0` + ship image → publish mthds-js 0.11.0 → re-pin vscode `mthds` to the published version + release the extension. The whole train still releases LAST.
+
+## Repos, paths, and current versions
+
+| Repo | Path | Version | Role in this plan |
+| --- | --- | --- | --- |
+| pipelex (worktree) | `../_calls` (branch `feature/Tweaks-for-validation-api`) | 0.33.0 | Expose `validation_errors` on the API error contract |
+| pipelex-api | `../pipelex-api` (branch `feature/validation-errors-source`) | 0.3.0 | Re-pin pipelex (done, editable), surface the field, bump `implementation_version` |
+| mthds-js | `../mthds-js` (branch `feature/typed-validation-report`) | 0.10.0 | Type the validation report + structured errors (DONE, commit `ad74bde`); 0.11.0 bump + publish deferred to release-LAST |
+| vscode-pipelex | `.` (this repo) | — | Backend abstraction, settings, consume `mthds-js` |
+
+> All `pipelex` edits land in the worktree `../_calls`, treated as repo root — not `../pipelex`.
>
-> 1. **Additive multi-file libraries** (Part I below): a same-domain `.mthds` library becomes buildable as **separate, additive files** instead of one monolithic file. That unblocks **parallel, top-down method construction**: a header file forward-declares the pipes (and the concepts they need), and definition files fill them in independently — no in-place overwrites, no transient collisions.
-> 2. **Canonical MTHDS-protocol validate surface** (Part II below): the runnability verdict from Part I is promoted onto the protocol level, and `PipelexMTHDSProtocol.validate`/`models` are reworked to produce ONE canonical, typed artifact shape that the hosted API (`pipelex-api`) and the Temporal worker arm reuse instead of re-implementing. Spec: workspace `docs/specs/pipelex-mthds-protocol.md`; plan + decision register: workspace `wip/mthds-protocol-surface-alignment.md` (decisions D1–D14).
+> **Doc vantage point.** Paths in this doc are written from the **vscode-pipelex** repo's perspective (`.` = vscode-pipelex, `../_calls` = the pipelex worktree). This copy of the doc currently lives in `../_calls`, so read the relative paths with that offset in mind.
>
-> This document describes *what changed and why* so the diff can be reviewed against intent.
+> **Current state (updated 2026-06-15 — see "▶ Resume point" above for the authoritative status).** Phase 1 is committed + pushed (`feature/Tweaks-for-validation-api`, tip `ec6e3a811`). The pipelex side of T3 (the `validate_bundles_in_process` extraction + temporal `mthds_names`) is implemented but uncommitted, live via the editable pin. `pipelex-api` (branch `feature/validation-errors-source`) has been **re-pointed off `0e32c8c02` to an editable pin on `../_calls`** (the committed form will be a git-rev SHA newer than `ec6e3a811`). No pipelex-api code changes yet.
+
+## Architecture overview — the seam
+
+The verified facts that shape the design:
+
+- **GraphSpec is already identical** on both paths. The CLI `--view` output and the API `graph_spec` field are the same `GraphSpec` model (`../_calls/pipelex/graph/graphspec.py`), serialized `by_alias=True`, and the webview's `@pipelex/mthds-ui` renderer mirrors it exactly. The only difference is the envelope key (`graphspec` from the CLI vs `graph_spec` inside the API's validation report) and that direction/layout is already client-side (ELK in the webview). No GraphSpec body transformation is needed.
+- **Validation errors regress today.** On an invalid bundle the API returns HTTP 422 RFC-7807 `problem+json` with a single `detail` string. The structured per-error list the extension maps to per-line diagnostics exists on the `ValidateBundleError` instance but is dropped at the exception→`ErrorReport` boundary. Phase 1 fixes this.
+- **One call must serve both.** When validation and graph are both wanted for a file, a single backend call returns them together. The API already does this (`/v1/validate` → report + `graph_spec`). The CLI does not yet — Phase 1 also makes `validate bundle --view --format json` return a combined envelope (validation details + best-effort graph).
+
+We introduce a single `ValidationBackend` abstraction in the extension with two implementations (CLI, API), selected by `pipelex.backend`. It exposes one `analyze(files, { withGraph })` method that returns both the validation outcome and (when requested) the graph, so the "no two calls" requirement is structural. Both backends produce the same normalized outcome types, keeping the diagnostics and graph webview code backend-agnostic.
---
-# Part I — additive multi-file MTHDS libraries
+## Phase 1 — pipelex (`../_calls`): structured `validation_errors` over the API + a single combined validate+view envelope
-## What "additive" means
+This phase has two parts: (A) get structured errors onto the API wire, and (B) make the CLI return validation details and the graph from one call.
-A library author can split a domain across files:
+### Part A — expose structured `validation_errors` over the API
-- a **root / header** file declares the domain header and forward-declares pipes as `PipeSignature` (a "header" with explicit `inputs`/`output` but no body), plus the concepts those contracts reference;
-- **definition** files supply the concrete pipes (and may declare more concepts), referencing sibling concepts by bare code.
+**Problem.** `ErrorReport` (`../_calls/pipelex/base_exceptions.py`, ~lines 233-266) is `frozen` / `extra="forbid"` and `PipelexError.to_error_report()` (~lines 482-508) copies only a fixed flat field set, so the three per-error lists on `ValidateBundleError` never reach the wire. The CLI dodges this by catching the exception itself and calling `extract_validation_errors(exc)` (`../_calls/pipelex/cli/agent_cli/commands/agent_output.py`, ~lines 409-473), which reads `pipelex_bundle_blueprint_validation_errors`, `pipe_factory_errors`, and `pipe_validation_errors`.
-Loading the whole set must produce the same library no matter the file order, with no spurious duplicate/undeclared errors. Three merge-time rules + one validate-surface addition make that work.
+**Changes.**
----
+1. **Promote a typed wire item.** Define a `ValidationErrorItem` Pydantic model carrying the *true* union of fields across the three error-data models. Verified against the current extractor (`extract_validation_errors`, `../_calls/pipelex/cli/agent_cli/commands/agent_output.py:410`) and the models (`PipeFactoryErrorData`, `PipesAndConceptValidationErrorData`, `PipelexBundleBlueprintValidationErrorData`), the union is: `category`, `error_type`, `pipe_code`, `concept_code`, `domain_code`, `source`, `field_path`, `field_name`, `variable_names`, `missing_concept_code`, `declared_concepts`, `message`. Place it next to the source error-data models (`../_calls/pipelex/core/exceptions.py`, `../_calls/pipelex/core/bundles/exceptions.py`). Corrections vs the field list this plan originally proposed:
-## The four changes
+ - **Keep `missing_concept_code` and `declared_concepts`.** The current CLI extractor emits both for `pipe_factory` errors (`agent_output.py:451-454`). Because the shared typed builder (item 2 below) becomes canonical for *both* the CLI and the API, dropping them would silently regress today's CLI output.
+ - **`field_name` is new, not "already emitted".** The extractor emits only `field_path` today; `field_name` exists on `PipesAndConceptValidationErrorData` but is never extracted. Adding it is fine, but `field_name` / `field_path` are a confusable pair — populate both intentionally.
+ - **Add `source` (the declaring file path).** Present on `PipesAndConceptValidationErrorData` and `PipelexBundleBlueprintValidationErrorData` (absent on `PipeFactoryErrorData`), and not extracted today. Threading it onto `ValidationErrorItem` hands the extension the owning file for those two categories directly, substantially de-risking Phase 4's cross-file diagnostic mapping. Surface it whenever present.
+2. **Extract a shared builder.** Move the `extract_validation_errors()` logic out of the CLI command module into a shared location (e.g. `../_calls/pipelex/pipeline/validation_errors.py`) and have it return `list[ValidationErrorItem]`. The CLI command and the new `to_error_report()` override both call it, so the CLI and API shapes can never drift.
+3. **Add the field to `ErrorReport`.** Declare `validation_errors: list[ValidationErrorItem] | None = None` on `ErrorReport`. Because `to_problem_document()` (~lines 315-357) already projects non-omitted payload fields onto the envelope, the field appears on the 422 body automatically once populated.
+4. **Override `ValidateBundleError.to_error_report()`** (`../_calls/pipelex/pipeline/exceptions.py`, ~lines 72-118) to call `super().to_error_report()` then attach `validation_errors` via the shared builder.
+5. **STRICT disclosure.** Add `validation_errors` to `_STRICT_KEPT_FIELDS` (`../_calls/pipelex/base_exceptions.py:54`) so the structured list survives STRICT error disclosure (production hosted). **Rationale (corrected):** that set is the documented single-decision contract for both STRICT branches — adding a top-level `ErrorReport` field there surfaces it on both branches. (NOT "like `caller_facing_message`" — that field is kept by separate branch logic at `base_exceptions.py:40-49`, not by this set.) Decision: surface them, because they describe the user's own submitted bundle, not server internals; redacting would gut hosted-path diagnostics. The test must assert retention on **both** STRICT branches (caller-facing + redacted).
-### 1. Pipe signature ↔ concrete reconciliation
+ **NEW (eng review, Issue 5 — API `source` fix):** thread an optional per-content name into `blueprint.source` on the in-memory (string) load path so the API populates `source` instead of `None` (`interpreter.py:43`, `handle_pipe_errors.py:106,162`). Keep the request field neutral/standard (MTHDS brand boundary). This makes cross-file diagnostics work on the API backend; the CLI path keeps real file paths.
+6. **(Optional, same boundary)** `PipelexInterpreterError.validation_errors` is lost the same way. Apply the same override if cheap; otherwise note as a follow-up.
-When two declarations of the same `pipe_ref` collide in the library merge:
+### Part B — single combined validate+view envelope (CLI) — ❌ DEFERRED (eng review 2026-06-15)
-| existing → incoming | result |
-| --- | --- |
-| concrete + concrete | **error** — genuine duplicate (unchanged) |
-| signature + concrete | **concrete wins** (definition satisfies the header) |
-| concrete + signature | **concrete wins** (header ignored) |
-| signature + signature | keep one via a deterministic, load-order-independent tie-break |
+> **DEFERRED to Out of scope.** A single `validate bundle --view --format json --allow-signatures` spawn already serves both channels today: `bundle_cmd.py` validates first and runs the `if view:` block only on success, so valid → exit 0 + `graphspec`, invalid → non-zero exit + `validation_errors` (the path the extension already parses). So "one call returns both" is satisfied without a CLI contract change. Phase 4's `CliValidationBackend` reads the exit code as the valid/invalid discriminator — see the rewritten Phase 4 note. The text below is retained for context only; do NOT implement it.
-Whenever at least one side is a signature, the two contracts **must agree**. Agreement is **normalized concept identity**, not raw-string equality: a header's bare `Brief` and a definition's `thisdomain.Brief` denote the same concept, as do `Text` and `native.Text`; structural multiplicity (`[]` vs `[1]`) stays distinct. Mismatched contracts are an error. Input *names* must match exactly (they are variable names, not concepts).
+**Problem.** Today the extension makes two CLI invocations when the graph is open: `validate bundle ...` for diagnostics (errors arrive on the exit-1 error path) and `validate bundle ... --view --format json` for the graph (success on exit 0). To satisfy "one call returns both", `validate bundle --view --format json` must return a single machine-readable envelope that carries both validation details and the best-effort graph, without throwing on an invalid bundle.
-Conceptually this is **a contract fulfilled by an implementation**, not a swap between two pipe *types*: after the taxonomy eviction (below), `PipeSignature` is not a `PipeType`, so reconciliation keys off `blueprint.is_signature` (a class fact) — never an enum tag. `contracts_match()` is unchanged.
+**Changes** (in `../_calls`, around the agent-CLI `validate bundle` command and `pipelex/graph/graph_rendering.py`'s `generate_view_for_bundle`):
-- `pipelex/libraries/library_crate_factory.py` — `_reconcile_pipe_collision` + the merge loop. Operates on a small `PipeDeclaration` (blueprint + source) record.
-- `pipelex/libraries/contract_match.py` — **NEW.** `contracts_match()` + `_canonical_concept_spec()`: normalization-for-identity only (NOT refinement substitutability — that stays the dry-run's job).
-- `pipelex/libraries/collision_messages.py` — **NEW.** `duplicate_ref_msg()`: shared same-file vs cross-file message for duplicate concept/pipe.
+7. In `--view --format json` mode, **do not raise on validation failure** — catch `ValidateBundleError` and emit a combined envelope on exit 0:
+ - valid bundle → `{ "success": true, "validated_pipes": [...], "pending_signatures": [...], "is_runnable": true, "graphspec": {...}, "pipe_code": "...", "direction": "..." }`
+ - invalid bundle → `{ "success": false, "validation_errors": [...], "graphspec": null }` (reusing the same shared `extract_validation_errors()` builder from Part A so the CLI's combined output and the API 422 stay identical).
+ This mirrors the API: errors and graph never coexist (an invalid bundle has no graph), but a single call always returns whichever applies.
+8. Leave the plain `validate bundle` path (no `--view`) untouched for the diagnostics-only / cheaper case — graph dry-run cost is only paid when `--view` is requested.
-### 2. Cross-file concept resolution
+**Tests** (`../_calls/tests/...`):
+- Part A: an invalid bundle's `ErrorReport` / problem document contains `validation_errors[]` with all fields populated; STRICT mode retains them; a parity test asserting the API-bound shape equals the CLI's `extract_validation_errors()` output.
+- Part B: `validate bundle --view --format json` on a valid bundle returns `graphspec` + `validated_pipes` with exit 0; on an invalid bundle returns `success:false` + `validation_errors` + `graphspec:null` with exit 0 (no throw).
-Concept references resolve against the **merged library** instead of per file, so a concept declared once is referenceable by bare code from sibling files of the same domain — within one load batch **or across separate batches** (e.g. a concept loaded via a `-L` directory, then a root file referencing it loaded separately). A concept declared twice still raises `ConceptLibraryError`.
+**Versioning & docs.** Bump pipelex 0.33.0 → 0.34.0 (new error-contract field + new combined `--view` output). Update CHANGELOG and the relevant `../_calls/docs/` pages (validate error envelope + the `--view --format json` output contract).
-The old per-file gate (`validate_local_concept_references` in `PipelexBundleBlueprint`) could not tell a typo from a valid cross-file ref, so it was removed; the check is reproduced where all declarations *and* the live library are visible — the loader.
+> **CHECKPOINT 1 — ✅ IMPLEMENTED (code + tests + docs), release pending.** The pipelex runtime now serializes structured `validation_errors` on `ValidateBundleError` problem documents (Part A). Part B was deferred (eng review), so the combined `--view` envelope is intentionally NOT built — the single `--view` spawn already serves both channels via exit code.
+>
+> **As-built (2026-06-15, branch `feature/Tweaks-for-validation-api`, uncommitted):**
+>
+> - `ValidationErrorItem` + `ValidationErrorCategory` live in `pipelex/base_exceptions.py` (next to `ErrorReport`, NOT in `core/exceptions.py` as the plan originally suggested — that would create a `base_exceptions ← core.exceptions` import cycle, since `ErrorReport` references the item as a typed field). The union fields match the plan: `category`, `message`, `error_type`, `pipe_code`, `concept_code`, `domain_code`, `source`, `field_path`, `field_name`, `variable_names`, `missing_concept_code`, `declared_concepts`.
+> - Shared builder `build_validation_error_items` in `pipelex/pipeline/validation_errors.py`. **Signature note:** it takes the three categorized error *lists* (keyword-only) rather than a `ValidateBundleError` instance — a `TYPE_CHECKING` back-reference to `ValidateBundleError` tripped pyright's `reportImportCycles` (it counts type-only imports). Both `ValidateBundleError.to_error_report()` and the CLI's `extract_validation_errors` call it.
+> - `ErrorReport.validation_errors: list[ValidationErrorItem] | None` added; `"validation_errors"` added to `_STRICT_KEPT_FIELDS` (surfaced on BOTH STRICT branches — caller's own bundle diagnostics).
+> - `ValidateBundleError.to_error_report()` override attaches the list; CLI `extract_validation_errors` is now a thin dump-adapter over the shared builder (and now also surfaces the previously-dropped `source` / `concept_code` / `field_name`).
+> - **Issue 5 / T1 source fix:** `make_pipelex_bundle_blueprint(mthds_name=...)` sets `blueprint.source` (and seeds `blueprint_dict["source"]` before validation so blueprint-validation errors carry it). `validate_bundle(mthds_names=...)` threads per-content names (length-mismatch → `ValidateBundleError`). The MTHDS protocol `validate` signature was deliberately NOT touched (cross-repo protocol change) — Phase 2's `ApiRunner.validate` will call `validate_bundle(mthds_names=...)` directly.
+> - Tests: `tests/unit/pipelex/pipeline/test_validation_errors.py`, `test_validate_bundle_error_report.py`, additions to `test_error_report_disclosure_mode.py` (STRICT both branches), `tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py`. `make agent-check` + full `make agent-test` GREEN.
+> - Docs: `docs/under-the-hood/error-model.md` (schema row + `validation_errors` subsection + File→Purpose). CHANGELOG entries under `[Unreleased]` (NOT bumped to 0.34.0 — versioning happens at release time).
+>
+> **Checkpoint 1 boundary — REVISED (strategy pivot, see "▶ Resume point").** We no longer cut the 0.34.0 release here. Phase 2 is unblocked by **pinning pipelex-api to the unreleased commit** (editable locally / git-rev SHA committed) instead of a release. The **pipelex 0.34.0 release is now the LAST step of the whole train** (after pipelex-api + mthds-js + vscode are all proven against the pin). When it's time: `/release` bumps `pyproject.toml`, finalizes `[Unreleased]` → `[0.34.0]`, opens PR to main; then re-point every consumer's pin from the git-rev SHA to `==0.34.0`. **Record the released version here once cut.**
+>
+> **Also done this session (T3 enabling refactor, uncommitted, live via editable pin):** `validate_bundles_in_process` extracted into `pipelex/pipeline/validate_in_process.py` (protocol `validate` signature untouched, delegates) + `DryValidateArg.mthds_names`. Full detail in "▶ Resume point". These pipelex commits must be pushed and the recorded pin SHA bumped past `ec6e3a811` before pipelex-api is committed with its git-rev form.
-- `pipelex/core/bundles/pipelex_bundle_blueprint.py` — removed the per-file same-domain concept gate (and the symmetric per-file *pipe* gate, which was the existing asymmetry — bare pipe refs were already deferred to library-level resolution). Reference **collectors** stay; `collect_concept_references()` is now public, mirroring `collect_pipe_references()`.
-- `pipelex/libraries/concept_reference_validation.py` — **NEW.** Pure `validate_concept_references_in_blueprints(blueprints, already_loaded_concept_refs=None)`: membership against `batch ∪ already-loaded ∪ native`; the error message lists only the batch's own declarations; every unresolved ref is accumulated and reported together.
-- `pipelex/libraries/library_manager.py` — calls the validator from `load_from_blueprints` *and* `load_concepts_only_from_blueprints` (batch ∪ live-library concepts). `load_from_crate` derives its pipe-factory bare-concept guard (`domain_concept_codes`) from the **live library**, not just the crate — the pipe-factory counterpart to the cross-batch check, so bare cross-batch refs resolve end-to-end (relaxing-only; no-op for self-contained crates incl. the Temporal path). Dependency loading now routes multi-file packages through `LibraryCrateFactory.make_from_blueprints`, so a dependency package can itself be additive (signature + concrete).
+---
-### 3. Order-independent domain-metadata merge
+## Phase 2 — pipelex-api (`../pipelex-api`): surface the field, version, docs
-Domain `description` / `system_prompt` merge order-independently across same-domain files. A membership-only sibling that declares only `domain = "..."` omits these — an omission contributes **no opinion** (it neither overrides nor warns), so whichever file declares the value wins regardless of filesystem load order. Two files declaring *different* non-empty values keep the first and **warn** (a real double-declaration). Same value → no warning.
+The route `validate_mthds` (`api/routes/pipelex/validate.py`) lets `ValidateBundleError` propagate to the global handler, so once Phase 1 ships the field flows onto the 422 with no route change.
-- `pipelex/libraries/domain/domain_metadata_merge.py` — **NEW.** `merge_domain_metadata_field()`, the single shared rule.
-- `pipelex/libraries/library_crate_factory.py` and `pipelex/libraries/domain/domain_library.py` — both wired to the shared helper (crate-merge path + runtime `DomainLibrary.add_domains`).
+**Changes.**
-### 4. `pending_signatures` on a successful validate
+1. **Re-pin pipelex** — ✅ DONE (editable path pin on `../_calls`; committed form will be a git-rev SHA newer than `ec6e3a811`). Branch `feature/validation-errors-source`, 253/253 tests green.
+1b. **Validate request gains optional per-item names (Issue 5).** — ✅ DONE. `ValidateRequest` (in `api/routes/pipelex/validate.py`, not `schemas/models.py` — it subclasses the shared `MthdsContentsRequest`) gained optional parallel `mthds_names: list[str] | None` + a `model_validator(mode="after")` length-match guard → 422. `ApiRunner.validate` threads it into `blueprint.source` (direct + temporal). Additive → old callers (n8n, app) keep working. `pipelex-api.openapi.yaml` regenerated via `make openapi-export`.
+2. **Contract docs.** Update `docs/openapi/pipelex-api.openapi.yaml` (error response schema gains `validation_errors`), `docs/error-responses.md`, and `docs/pipe-validate.md` with the structured-error shape and an example 422.
+3. **Version surface.** Bump pipelex-api 0.3.0 → 0.4.0 so `GET /v1/version` reports an `implementation_version` the extension can gate on.
+4. **Confirm 200-vs-422 boundary.** *Verified:* today the route raises 422 on any `ValidateBundleError` and never emits per-pipe `FAILURE` entries on a 200 — the response model supports them, the handler does not produce them. Document this as the actual contract. If the 200-FAILURE channel is wanted, scope it as an explicit behavior change here (out of scope as currently written); otherwise the extension's 200 `validated_pipes` FAILURE channel stays empty.
-A successful `validate bundle` (notably `--allow-signatures`) reports the library-wide set of pipes still declared as `PipeSignature` — so a top-down build sees exactly what remains to define.
+**Tests** (`../pipelex-api/tests/...`): `POST /v1/validate` with an invalid bundle returns 422 whose body contains `validation_errors[]`; `allow_signatures=true` still tolerates signature stubs.
-- `pipelex/pipeline/validate_bundle.py` — `build_pending_signatures()` + a `pending_signatures` field on the result.
-- `pipelex/builder/operations/validate_ops.py`, `pipelex/cli/agent_cli/commands/validate/_validate_core.py` — `pending_signatures` in the JSON envelope.
-- `pipelex/cli/agent_cli/commands/validate/_output_helpers.py` — a "Pending signatures" markdown section.
+**Conformance — DECIDED: add it (eng review Issue 2).** The `/v1/validate` error envelope is not covered by the `docs/specs/` ↔ `conformance/` pair today. Add a spec section + a verifying test for the structured-error contract (`validation_errors[]` incl. `source`), and run `make check-spec-links` in `conformance/`. The test must assert the **real wire response**, not just the hand-maintained `pipelex-api.openapi.yaml` — otherwise the Python model, the OpenAPI YAML, and the mthds-js types become three drifting contracts. Conformance is the single guard against cross-repo drift on this brand-new surface.
+
+> **CHECKPOINT 2 — ✅ REACHED (code + tests + docs + spec), release pending.** The Pipelex API emits structured `validation_errors` on 422 and advertises `implementation_version = 0.4.0`.
+>
+> **As-built (2026-06-16, branch `feature/validation-errors-source`, commit `2941daa`):**
+>
+> - **T3 — `mthds_names` request field + threading.** `ValidateRequest` (`api/routes/pipelex/validate.py`) gains optional `mthds_names: list[str] | None` + a `model_validator(mode="after")` length-match guard (mismatch → 422 via the custom `RequestValidationError`→problem+json handler, *before* the runtime, which would treat a mismatch as a 500). `ApiRunner.validate` (`api/routes/pipelex/pipeline.py`) gains the `mthds_names` param (additive over the protocol signature, `@override` LSP-safe): the in-process branch now calls `validate_bundles_in_process(mthds_names=…)` directly (not `super().validate`, which can't carry names); the Temporal branch threads names through `DryValidateArg` **and** the `make_pipelex_bundle_blueprint(mthds_name=…)` parse loop. Route passes `request_data.mthds_names`.
+> - **`validation_errors` rides automatically.** No route shaping — `ValidateBundleError.to_error_report()` (pinned pipelex) attaches the list; `to_problem_document()` projects it onto the 422 body. Default disclosure VERBOSE; retained under STRICT (`_STRICT_KEPT_FIELDS`).
+> - **Version + pin.** `pyproject.toml` 0.3.0 → 0.4.0; pinned pipelex git-rev `0ab2cb8b` (committed form). `/version`'s `implementation_version` reads `importlib.metadata.version("pipelex-api")` → 0.4.0.
+> - **Tests (real wire).** NEW `tests/unit/test_validate_errors.py::TestValidateErrors` — invalid bundle → 422 + `error_type=ValidateBundleError` + structured `validation_errors[]`; `mthds_names` → `validation_errors[].source` (blueprint-validation item) on the direct path AND `bundle_blueprint.source` on success; length mismatch → 422 request error; Temporal arm threads names through the dispatched `DryValidateArg` + onto `bundle_blueprint.source`. Added `INVALID_MAIN_PIPE_MTHDS` to `tests/unit/_constants.py`. Existing `test_validate_envelope.py` unchanged + green.
+> - **Docs.** Regenerated `docs/openapi/pipelex-api.openapi.yaml` (auto-export — `mthds_names` field + updated 422 description + `version: 0.4.0`; `make openapi-check` clean). `docs/error-responses.md` (new "Structured validation errors" section + field + updated 422 example). `docs/pipe-validate.md` ("Naming submitted files" section + `mthds_names` field + structured-error example). `CHANGELOG.md` `[Unreleased]` entries (NOT a `[v0.4.0]` header — finalized at release time).
+> - **Spec/conformance (T4).** `docs/specs/pipelex-mthds-protocol.md` Error-contract section documents `validation_errors[]` + `mthds_names`; `<!-- unverified -->` marker points at `pipelex-api/tests/unit/test_validate_errors.py` (real wire) — conformance HTTP arm stays deferred (D5). `make check-spec-links` GREEN. Committed on specs-repo `dev` (`a8b6b4b`).
+>
+> **Checkpoint 2 boundary — release deferred (strategy pivot).** No pipelex-api image is cut here. At release time: re-pin pipelex `==0.34.0` (once pipelex 0.34.0 is cut LAST), ship the image, bump `api_image_tag` in `pipelex-api-infra`. **Record the released image tag / version here once cut.**
---
-## Error surfacing
+## Phase 3 — mthds-js (`../mthds-js`): type the report and surface structured errors
-`ConceptLibraryError` / `PipeLibraryError` were reparented from `PipelexError` directly to `LibraryError`, so a single `except LibraryError` arm in `_translate_to_validate_bundle_error` turns an unresolved cross-file ref (and the pre-existing raw duplicate-concept/pipe errors) into a clean structured `ValidateBundleError` instead of a raw traceback. `PipeNotFoundError` (also a `PipeLibraryError`) keeps its dedicated `--pipe`-slice handler via an `except PipeNotFoundError: raise` placed *before* the `LibraryError` arm. `_load_mthds_files_into_library` gained a surgical `(ConceptLibraryError, PipeLibraryError)` file-context arm (kept narrow so `LibraryLoadingError`'s structured fields survive).
+`MthdsApiClient.validate()` currently returns an opaque `ValidationReport` and throws `ApiResponseError` on 422 with the body as raw text (`src/runners/api/client.ts`, ~lines 425-442; `src/runners/api/exceptions.ts`).
-- `pipelex/libraries/concept/exceptions.py`, `pipelex/libraries/pipe/exceptions.py` — reparenting (class names / `type_uri` / doc slugs unchanged).
-- `pipelex/pipeline/validate_bundle.py` — the translate arms.
+**Changes.**
----
+1. **Typed report.** Add a `PipelexValidationReport` interface (Pipelex-API extension over the protocol's extension-open `ValidationReport`) with the fields the runner returns: `bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`, `pending_signatures`, `is_runnable`, `success`, `message`. Keep neutral, standard-aligned field names (no `pipelex_` prefix on bundle/graph artifacts). Have `validate()` return this type.
+2. **Typed error item.** Add a `ValidationErrorItem` type mirroring the Phase 1 wire shape and export it.
+3. **Surface structured errors on 422.** In the error-construction path, when the problem+json body carries `validation_errors`, parse it into a typed `validationErrors?: ValidationErrorItem[]` property on `ApiResponseError`. Keep throw-on-422 semantics (an invalid bundle is still an `ApiResponseError`); the consumer catches and reads the typed field. Export the augmented error type.
+4. **graph_spec typing.** Keep `graph_spec` as opaque transport (`unknown`) in mthds-js to avoid duplicating the canonical GraphSpec schema that `@pipelex/mthds-ui` already owns; the extension casts it to the renderer's type. (Note the choice; revisit only if a shared graph type is wanted.)
+5. **Type `implementation_version` for gating.** *Verified:* `MthdsApiClient.version()` returns `VersionInfo`, which has typed `protocol_version` / `runner_version?` plus an open extension index signature — it has **no** typed `implementation_version`, even though `pipelex-api` populates one (`api/routes/version.py:43`). Add `implementation_version?: string` to `VersionInfo` (or a `PipelexVersionInfo` extension) so Phase 4 can gate on it without reading an untyped extension field. **Note (eng review F4):** this is cosmetic, not a gate — `install.ts:155` already reads `ver.implementation_version` via the index signature today, so it does not block Phase 4.
+6. **Send per-item names on `validate()` (Issue 5).** Extend the `validate()` signature to carry the optional per-content name alongside each content string (matching the Phase 2 request shape), so the extension's API path gets a real `source`. Keep `allowSignatures` semantics. Confirm SecretStorage→`MTHDS_API_KEY` token **precedence** in the client constructor (the wrapper must be able to override a native env read).
-## Part I test coverage (what proves it)
+**Tests** (`../mthds-js/...`): `validate()` returns the typed report on success; on 422 it throws `ApiResponseError` with a populated typed `validationErrors`; round-trips the Phase 2 example bodies.
-- `tests/unit/pipelex/libraries/test_library_crate.py` (+ `test_library_crate_data.py`) — signature/concrete reconciliation matrix (both orders, signature+signature match/mismatch, contract mismatch).
-- `tests/unit/pipelex/libraries/test_concept_reference_validation.py` — the pure validator, incl. the cross-batch (`already_loaded_concept_refs`) case and message format.
-- `tests/unit/pipelex/libraries/test_domain_library.py` — domain-metadata merge matrix (both orders, same-value, conflict; `description` + `system_prompt`; warnings asserted via `caplog`).
-- `tests/unit/pipelex/libraries/test_dependency_multi_file_reconciliation.py` — additive (signature + concrete) **dependency** packages.
-- `tests/unit/pipelex/cli/agent_cli/test_validate_output_helpers.py` — the "Pending signatures" markdown section.
-- `tests/unit/pipelex/core/.../test_pipelex_bundle_blueprint_concept_construction.py` — per-file construction smoke tests (replaces the relocated per-file validation tests).
-- `tests/integration/pipelex/libraries/test_additive_multi_file_library.py` — end-to-end `validate bundle <root> -L <dir>`: lenient passes with the signature, strict passes once the definition is present, concrete wins, cross-batch via `-L`, undeclared → clean `ValidateBundleError`.
-- `tests/integration/pipelex/libraries/test_cross_file_concept_references.py` — cross-batch + single-batch bare-ref resolve; undeclared → `ConceptLibraryError`.
-- `tests/integration/pipelex/pipeline/test_load_concepts_only.py` — concepts-only path incl. dangling `concept_ref`/`item_concept_ref` rejection and the **sibling cross-reference order-independence** regression test.
+**Versioning, docs, publish.** Bump 0.10.0 → 0.11.0; update `README.md` / `CLI.md` / `docs/architecture.md`; publish to npm so the extension can pin it.
-Verification: `make agent-check` clean (ruff, plxt, pyright 0 errors, mypy success); `make agent-test` full suite green.
+> **CHECKPOINT 3 — ✅ REACHED (code + tests + docs), publish deferred.** `mthds-js` exposes a typed validation report and typed structured errors. The extension can now consume the API path with full diagnostics parity (against a local file/workspace pin).
+>
+> **As-built (2026-06-16, branch `feature/typed-validation-report`, commit `ad74bde`):**
+>
+> - **Typed report (item 1).** `MthdsApiClient.validate()` returns `PipelexValidationReport` (in `src/runners/api/models.ts` — the Pipelex-API extension home next to `DictPipeOutput`, NOT `protocol/models.ts` which stays slim). Fields mirror the canonical pipelex `PipelexValidationReport` + the route's wire extras: `bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes` (`ValidatedPipeEntry {pipe_ref, status: DryRunStatus}`), `pending_signatures`, `is_runnable`, `success`, `message`, optional `mthds_contents` echo. `bundle_blueprint`/`pipe_io_contracts` are `Record<string, unknown>` and `graph_spec` is `unknown` — opaque transport (item 4), schemas owned by the runtime + `@pipelex/mthds-ui`.
+> - **Structured errors on 422 (items 2–3).** `ValidationErrorItem` (+ `ValidationErrorCategory`) mirrors the Phase 1 wire shape (union fields, `category`+`message` required). `parseErrorBody` (client.ts) now also extracts the problem envelope's **top-level** `validation_errors[]` (shallow `Array.isArray` guard) and `throwApiResponseError` threads it into the new `ApiResponseError.validationErrors?: ValidationErrorItem[]`. Throw-on-422 unchanged; `undefined` for non-validation errors. Generic across all endpoints (only the `ValidateBundleError` 422 populates it).
+> - **Named contents (item 6 / Issue 5).** `validate(mthdsContents, allowSignatures = false, mthdsNames?)` sends `mthds_names` only when provided (omission keeps the exact old body). **Protocol `MTHDSProtocol.validate` signature deliberately NOT changed** — `mthds_names` is a Pipelex-API extension, not protocol surface (brand boundary); the widened impl (extra optional param + covariant `PipelexValidationReport` return) stays assignable to the `Runner` interface, so `PipelexRunner` is untouched. **Token precedence confirmed** (item 6 tail): constructor `options.apiToken ?? process.env.MTHDS_API_KEY` — an explicit token (vscode SecretStorage) overrides the env read. No code change needed; documented.
+> - **`implementation_version` typed (item 5).** Added `implementation_version?: string` named optional to `VersionInfo` (`protocol/models.ts`); other extensions (`implementation`, `runtime_version`) still ride the index signature.
+> - **Exports.** `PipelexValidationReport`, `ValidatedPipeEntry`, `DryRunStatus`, `ValidationErrorItem`, `ValidationErrorCategory` exported from the barrel (`src/index.ts`).
+> - **Tests.** `tests/unit/client/client.test.ts` — typed report fields on 200, sends `mthds_names` parallel array, omits it when absent, structured `validation_errors[]` with threaded `source` on an invalid 422, `validationErrors` undefined on a plain (length-mismatch) 422, typed `implementation_version` on `version()`. Full `make check` GREEN (build + depcruise boundary intact + suite).
+> - **Docs.** README API-method table row, `docs/architecture.md` (module map + new "Typed Pipelex-API extensions over the validate surface" section incl. token precedence), `CHANGELOG.md` `[Unreleased]` `### Added` (CLI.md needs no change — its `validate` commands forward to the pipelex CLI and don't expose `mthds_names`).
+>
+> **Checkpoint 3 boundary — release deferred (strategy pivot).** Version stays **0.10.0**; the 0.11.0 bump + `npm publish` is step 3 of the release-LAST phase. During Phase 4 dev, vscode pins `mthds` via a local file/workspace pin (eng-review note). **Record the published version here once cut.**
---
-## Key design decisions
+## Phase 4 — vscode-pipelex: backend abstraction, settings, mthds-js integration
-- **Normalized identity at merge, substitutability at dry-run.** The merge runs at blueprint level (raw strings, before concepts resolve), so `contracts_match` normalizes *identity* (bare ≡ qualified, native spelling, multiplicity-as-text). Covariant-output / contravariant-input substitutability is deferred to the dry-run, which re-validates the parent against the concrete's real contract.
-- **Concept refs validate at the loader, not per file.** The one place holding both the raw blueprints (for messages + sources) and the live library (for already-loaded concepts). This makes `get_crate` and per-batch `load_from_blueprints` agree by construction.
-- **Reparent then catch once.** One `except LibraryError` arm covers the new undeclared-ref error and the pre-existing raw duplicate errors uniformly, rather than scattering catches.
-- **Per-file relaxation scope: concepts (and the already-deferred bare pipe refs).** Same-domain *qualified* cross-file refs are still not emitted by the recursive flow; not in scope.
-- **Exact-match contract requires explicit `inputs`/`output` on both header and definition.** `PipeLLM` does not infer `inputs` from prompt sigils, so a header with explicit `inputs` and a definition that omits them would mismatch — the additive flow must emit both explicitly (pinned by a test).
+**Dependency.** Add `mthds` (pinned to the Phase 3 version) to `editors/vscode/package.json`. **Verified:** the extension's *main* code is bundled by **rollup** (via `rollup-plugin-esbuild`); esbuild on its own only builds the webview bundle. Since `mthds` is imported by the backend code, verify it bundles cleanly under **rollup**, not esbuild. `mthds` is pure ESM (`"type": "module"`, `tsc`-only build, no internal bundler) — generally fine, but confirm the Node target, ESM interop, and that `fetch` is available on the VS Code Node runtime.
-See `wip/recursivity/` for the deeper records:
+**Backend abstraction** (new module under `editors/vscode/src/pipelex/validation/`):
-- [`recursive-followups.md`](wip/recursivity/recursive-followups.md) — `pending_signatures` + normalized contract conformance (both shipped).
-- [`domain-metadata-merge.md`](wip/recursivity/domain-metadata-merge.md) — the metadata-merge rule (shipped).
+- Define a single-call `ValidationBackend` interface:
+ - `analyze(files, { withGraph }): Promise<BundleAnalysis>` where `BundleAnalysis = { validation: { ok: true; report } | { ok: false; errors: ValidationErrorItem[] }; graph?: GraphSpec | null }`. `graph` is populated only when `withGraph` is true. This single method makes "no two calls" structural.
+ - `getBackendVersion(): Promise<...>` for gating/warnings.
+- `CliValidationBackend` — refactor the existing logic (`cliResolver.ts`, `processUtils.ts`, `extractJson`) behind this interface. **Single spawn per `analyze()` (Part B deferred):** `withGraph:false` → `validate bundle ... --allow-signatures` (diagnostics only, no graph cost). `withGraph:true` → one `validate bundle ... --allow-signatures --view --format json` spawn; **read the exit code as the discriminator** — exit 0 → parse `graphspec` (+ `validated_pipes`), non-zero → parse `validation_errors` from the structured error payload (the path the diagnostics-only flow already uses) and set `graph = null`. No double dry-run. Existing CLI diagnostics behavior stays identical.
+- `ApiValidationBackend` — wraps `MthdsApiClient`. One `client.validate(contents, /* allowSignatures */ true)` call: on success map the typed report into `validation` and read `graph_spec` into `graph`; on 422 map caught `ApiResponseError.validationErrors` into `validation`. **Transport / non-validation failures (Issue 4):** any server-unreachable, non-`problem+json`, HTML-proxy, auth, timeout, or otherwise-unparseable response → show an actionable notification ("Pipelex API unreachable at {baseUrl} — is pipelex-api running?"), set **no diagnostics**, **clear** stale diagnostics, and do **not** auto-fall back to CLI. Client constructed with `baseUrl` from settings and `apiToken` from SecretStorage→env (confirm the wrapper's token precedence actually overrides any native env read).
----
+**Dual-channel diagnostics.** The `{ ok:false; errors }` branch is fed by **two** sources that both map to diagnostics: the 422 `validation_errors` (hard failures) and any 200 `validated_pipes` entries with FAILURE status (per-pipe dry-run failures returned as data). The CLI combined envelope exposes the same two channels (`validation_errors` and `validated_pipes`). Normalize both into the `ValidationErrorItem[]` the diagnostics path already consumes.
+
+**One-call orchestration.** The on-save handler is the single orchestration point: it sets `withGraph = (graph panel is open for this doc)`, makes one `analyze` call, routes the validation outcome to the Problems panel via the existing `toDiagnostic()` / `locateError()` path, and — when `withGraph` — hands the returned graph to the panel instead of letting the panel make its own call. A fresh panel open (or the manual graph command) makes its own `analyze(withGraph:true)` call. Net effect: save-with-panel-open is one call serving both.
+
+**Wire the consumers** to go through the selected backend:
+
+- `pipelexValidator.ts` (`onSave`) — replace the direct `spawnCli(...)` validate call with the `analyze(...)` orchestration above.
+- `graph/methodGraphPanel.ts` — replace the `validate bundle --view` spawn with `backend.analyze(..., { withGraph:true })` and read `analysis.graph`. The canonical GraphSpec reaches the webview unchanged regardless of backend; direction stays a client-side `pipelex.graph.direction` concern.
+
+**Settings** (`contributes.configuration` in `editors/vscode/package.json`):
+
+- `pipelex.backend`: enum `["cli", "api"]`, default `"cli"` (preserve current zero-config behavior; `api` is opt-in).
+- `pipelex.api.baseUrl`: string, default `"http://localhost:8081"`.
+- **API key handling (best practice):** no plaintext key setting. The `ApiValidationBackend` resolves the token as SecretStorage → `MTHDS_API_KEY` env (which `mthds-js` reads natively). Add a command `Pipelex: Set Hosted API Key` that writes to `vscode.ExtensionContext.secrets`, and `Pipelex: Clear Hosted API Key`.
+
+**Multi-file gathering.** For a saved `.mthds` file, read every `*.mthds` in `path.dirname(file)` **from disk** (v1 — matches CLI `--library-dir`; buffer-awareness is a follow-up, see Out of scope) and build the contents array, mirroring `--library-dir <dir>`. **Verify the gather matches CLI bundle resolution** (nested dirs, configured libraries, symlinks, ignored files, deterministic ordering) or document the divergence. Keep a content-index → file-URI map for diagnostic placement. **For the API backend, also send the per-item name** (Issue 5) so the API can populate `source` — without it the API returns `source=None` and cross-file placement fails.
-## Deferred (intentionally out of scope)
+**Cross-file diagnostics.** Validation errors may reference pipes/concepts declared in sibling files. **Prefer the `source` field** (the declaring file path) added to `ValidationErrorItem` in Phase 1 — it is populated for pipe/concept-validation and blueprint-validation errors and gives the owning file directly. Fall back to mapping via `domain_code` / `pipe_code` → declaring file only for categories that lack `source` (e.g. `pipe_factory` errors). Set diagnostics on the owning file's URI using `sourceLocator.locateError()` against its text; errors that don't resolve fall back to the saved file or the output channel. This is the subtlest part of the API path — design it explicitly and cover it with tests.
-- **Partial-hierarchical same-domain typo skipped as external.** A ref like `legal.Foo` when the bundle domain is `legal.contracts` is treated as external (`QualifiedRef.is_external_to` uses exact-equality) and skipped, so the typo only fails later at resolution. Pre-existing — identical in the old per-file validator; fixing needs an ancestor/prefix notion of domain. Tracked in `wip/recursivity/`.
-- **P3 polish from the pre-landing `/review`** (docstring accuracy, an advisory-description silent-drop note, one low-confidence test-coverage gap) — none are bugs; recorded in [`review-followups.md`](wip/recursivity/review-followups.md).
+**Version gating (both backends).**
+- CLI: raise `MIN_AGENT_VERSION` (currently 0.31.0) to the Phase 1 version (0.34.0) that delivers the new `source`/`field_name` error fields, using the repo's `bump-pipelex-version` skill so all version-floor references stay in sync. **This is a compatibility-floor break** — older CLIs get a "too old" message; "CLI unchanged" refers to behavior, not the version requirement. State it explicitly in the changelog.
+- API: add a `MIN_API_IMPLEMENTATION_VERSION` constant (the Phase 2 version). On first API use, call `client.version()` and read `implementation_version` (typed in Phase 3 item 5; `pipelex-api` populates it at `version.py:43`), cache it, and if too old show an upgrade message — analogous to `agentCliVersion.ts`. **Parse leniently:** treat unparseable / prerelease / dev tags (`0.4.0-dev`, `latest`, git pins) as capable (warn-once, don't hard-block). Capability-probe is a follow-up (Out of scope).
+
+**Privacy.** The API backend sends file contents to `baseUrl` on every save. The localhost default keeps this local. Show the one-time confirmation **before the first remote request** (not lazily after a send has already happened), and state clearly that it sends the **whole directory's `.mthds` contents**, not just the active file.
+
+> **CHECKPOINT 4 — ✅ REACHED (code + tests + docs), uncommitted.** The extension validates and renders graphs through either backend, selected by `pipelex.backend`, with full diagnostics parity on the API path. CLI remains the default and behaviorally unchanged.
+>
+> **As-built (2026-06-16, `../vscode-pipelex` branch `feature/Use-pipelex-api`, UNCOMMITTED):**
+>
+> - **Backend seam** (`editors/vscode/src/pipelex/validation/`): `backend.ts` (`ValidationBackend` iface, flat `ValidationOutcome {ok, errors}` — discriminated union dropped because the extension tsconfig is `strict:false` and boolean-literal discriminants don't narrow there — `BundleAnalysis`, `BundleFile`, `BundleRequest`, `BackendError` taxonomy `{not-found|too-old|unreachable|infra|declined}`, `AnalyzeAbortError`, `GraphAnalysisSink`). `cliValidationBackend.ts` (single spawn; `--format json` always so BOTH streams are machine-readable — the agent CLI defaults error output to markdown, which the OLD on-save path silently mis-parsed; exit 0 → ok [+`graphspec` when `--view`]; exit 1 → parse `validation_errors`, OR synthesize one diagnostic from `message` when `error_domain==='input'` with no list, else infra/too-old). `apiValidationBackend.ts` (one `client.validate(contents, true, names)`; 422-with-`validationErrors` → ok:false; 422 `ValidateBundleError` no-list → synthetic; auth/5xx/unreachable/non-`problem+json`/timeout → `BackendError` notify-no-fallback; abort+timeout race around the uncancellable client call). `backendFactory.ts` (reads `pipelex.backend`/`pipelex.api.baseUrl` per call; owns shared `ApiVersionGate` + per-host remote-consent in globalState). `apiKey.ts` (SecretStorage→env token, Set/Clear commands). `apiVersionGate.ts` (`parseCleanRelease` lenient — prerelease/dev/non-semver = capable; warn-once below floor; never throws/blocks). `bundleGather.ts` (flat non-recursive `*.mthds`/`*.plx` disk gather = CLI `--library-dir` parity; primary first; documents the nested-dir/installed-lib/symlink divergence). `crossFileDiagnostics.ts` (owner = `source` → declaration scan `[pipe.X]`/`[concept.X]` → primary fallback; places diagnostics across sibling URIs).
+> - **Consumers refactored.** `pipelexValidator.ts` is the single on-save orchestrator: gathers files, `withGraph = panel.isShowingMthds(uri)`, ONE `analyze()`, cross-file diagnostics keyed per-directory (each save replaces that dir's diagnostic set), and feeds `graphSink.applyAnalysis()` (no 2nd call). `methodGraphPanel.ts` routes graph generation through the backend (`getBackend` injected; defaults to `CliValidationBackend` so its ~22 existing tests — which mock `spawnCli`/`resolveCli` — still pass); its `.mthds` save subscription self-refreshes ONLY when validation is disabled (else the validator drives). `pipelexExtension.ts` wires the factory, registers key commands, calls `validator.setGraphSink(panel)`.
+> - **T8 floor bump** via the `bump-pipelex-version` skill: `MIN_AGENT_VERSION` 0.31.0 → **0.34.0** (reason: structured `validation_errors[]` `source`/`field_name`); too-old message reason text updated; CHANGELOG `### Changed` records the **compatibility-floor break**.
+> - **Settings/commands** (`package.json`): `pipelex.backend` enum (default `cli`), `pipelex.api.baseUrl` (default `http://localhost:8081`), `pipelex.setApiKey`/`pipelex.clearApiKey`. **Dep:** `"mthds": "portal:../../../mthds-js"` (local pin; publish deferred).
+> - **Tests (T11):** 37 new across `crossFileDiagnostics`, `apiValidationBackend`, `cliValidationBackend`, `apiVersionGate`, `bundleGather` (`.test.ts`). Existing 104 still green (updated 1 mock to add `setGraphSink`). `yarn test` 141/141, `tsc --noEmit` clean (only pre-existing webview/LSP DOM-lib errors remain), `yarn build` (node + browser + webview) green. Bundle verified: no `posthog`/CLI deps leaked; `MthdsApiClient` lands only in the dynamically-imported `backendFactory` chunk.
+> - **Docs:** `docs/features/validation-backends.md` (CLI vs API, settings, self-hosting, key handling, privacy, cross-file, version gating); CHANGELOG `[Unreleased]` `### Added`/`### Changed`.
+>
+> **Deviations from the plan sketch (deliberate):** (1) `ValidationBackend` has NO `getBackendVersion()` — version gating folded into each backend (CLI throws `too-old`; API warns via the gate). (2) Diagnostic source label `pipelex-agent` → `pipelex` (either backend can produce them). (3) `ValidationOutcome` flat, not a discriminated union (`strict:false` narrowing). (4) The 200-`validated_pipes`-FAILURE channel stays unsynthesized (deferred per Out-of-scope). (5) Concept declaration-scan finds only `[concept.X]` table-style, not `[concept]` block-style — `source` is the primary mechanism, so this is a best-effort fallback only.
+>
+> **Checkpoint 4 boundary — UNCOMMITTED + release deferred.** Code is uncommitted on `feature/Use-pipelex-api`. The whole train releases LAST (pipelex 0.34.0 → pipelex-api `==0.34.0` → mthds-js 0.11.0 publish → re-pin vscode `mthds` to the published version → release extension). **Record the released extension version here once cut.**
+>
+> **Code review (2026-06-16, recall mode, 15 findings).** The three must-fix correctness items were **fixed** in `../vscode-pipelex` (still uncommitted on `feature/Use-pipelex-api`; 142 vitest GREEN incl. +1 new, `tsc` clean on changed files, node bundle builds): (1) open graph panel no longer goes stale on a non-success save — `GraphAnalysisSink` gained `applyBackendError`/`applySkipped`, driven from the validator's catch + LSP-skip paths; (2) the 0.34.0 CLI floor is now enforced **up front** in `CliValidationBackend.analyze` (a `[0.31.0,0.34.0)` CLI emits `source`-less errors and previously slipped through the lazy-only check); (3) the per-URI in-flight cancel now runs before the LSP-skip early return. The other 12 findings (loopback `0.0.0.0`/`[::1]` detection, `endsWith` cross-file mis-match, slow-server "unreachable" message, unbounded `/version` probe, runtime-toggle staleness, dir-keyed diagnostics race, two divergent `BackendError`→UX switches, `extractJson` brace-span, duplicated `blueprint_validation` synthesis, unconditional gather, dead `backendKind()`) are **deferred with justification** in `../vscode-pipelex/wip/api-backend-code-review-followups.md` — none are silent must-fixes; pick from there around Phase 5 QA. Brand boundary + docs conventions verified clean.
---
+## Phase 5 — vscode-pipelex: tests, docs, QA, release
+
+- **Tests (vitest):** `ApiValidationBackend` against a mocked `MthdsApiClient` (success report, 422 with `validationErrors`, transport error); multi-file gathering; cross-file diagnostic mapping; version gating; settings/secret resolution. Preserve all existing CLI-path tests.
+- **Docs:** add a backend page under `editors/vscode` docs (or this repo's `docs/`) covering CLI vs API, settings, key handling, and self-hosting `pipelex-api`; update CHANGELOG and README. Update `CLAUDE.md` if the backend seam introduces a new concept worth recording.
+- **Quality gate:** `make check` (fmt, plxt fmt, clippy `-D warnings`, crate tests, vitest, WASM check).
+- **Manual QA:** both backends against valid/invalid bundles, multi-file directories, graph rendering, and a hosted endpoint with a key in SecretStorage.
+
---
-# Part II — canonical MTHDS-protocol validate surface
+## Cross-repo release ordering
-The MTHDS Protocol (five routes: `execute`/`start`/`validate`/`models`/`version`) had **diverged between the local implementation and the hosted API**: same protocol operation, unrelated artifact shapes (the hosted `/validate` never called `PipelexMTHDSProtocol.validate` at all). This part makes pipelex the single owner of the canonical artifact shapes; the hosted `pipelex-api` rewires its routes through them in a companion branch (`pipelex-api@feature/Recursivity-and-protocols`). Principle: **backend overrides change backend, never shape; routes are thin wrappers adding wire-only extras** — exactly how `/execute`/`/start` already worked.
+**Strategy pivot (2026-06-15):** *build* against an unreleased pipelex commit pin, *release* in dependency order at the end. Concretely:
-## The canonical validation report
+- **Build/iterate phase (now):** pipelex-api → mthds-js → vscode are all developed against the pinned (editable / git-rev SHA) unreleased pipelex `0.33.0`. Prove the full path before any release.
+- **Release phase (last):** once the train is proven, ship in dependency order, re-pointing each consumer's pin from the git-rev SHA to the released version:
+ 1. **pipelex (`../_calls`)** — `/release` the `validation_errors` field as **0.34.0** (Checkpoint 1).
+ 2. **pipelex-api** — re-pin pipelex `==0.34.0`, release image + bumped `implementation_version` (Checkpoint 2).
+ 3. **mthds-js** — typed report + errors, publish to npm (Checkpoint 3).
+ 4. **vscode-pipelex** — pin the published `mthds`, gate the API backend on the min pipelex-api version, release the extension (Checkpoints 4–5).
-`PipelexValidationReport` moved to its own module `pipelex/pipeline/validation_report.py` and is now fully **typed** (no `Any` dumps — the typed schemas flow into pipelex-api's committed OpenAPI artifact):
+The graph-only API path could technically ship before 1–3 (GraphSpec already matches), but validation diagnostics would regress, so prefer shipping the whole feature together.
-- `bundle_blueprint: PipelexBundleBlueprint` — the batch's PRIMARY blueprint (first declaring `main_pipe`, else first). Renamed from the hosted side's `pipelex_bundle_blueprint`: blueprints are MTHDS-language artifacts, so no `pipelex_` prefix inside an already-Pipelex-branded envelope (the brand-boundaries principle in the workspace `CLAUDE.md`).
-- `pipe_io_contracts: dict[str, PipeIOContract]` — per-pipe IO contracts keyed by **namespaced `pipe_ref`** (`domain.code`), never bare code. The builder (`build_pipe_io_contracts`) is **ported from pipelex-api's route-local `_build_pipe_structures`** — it is runtime logic over `PipeAbstract`/`StuffSpec` the API repo should never have owned. New module `pipelex/pipeline/pipe_io_contracts.py` (`PipeIOContract`/`PipeInputContract`/`PipeOutputContract`, `IOMultiplicity = single|variable`); JSON-Schema rendering memoized per `(concept_ref, is_multiple)` within a call (deliberately not cross-call — stale-class hazard). A pydantic schema-generation failure raises a structured `PipeIOContractError` with pipe/input context (it must not cross the Temporal boundary as a raw retryable third-party error).
-- `graph_spec: GraphSpec | None` — **best-effort real graph on the local protocol too** (was always `None`): one shared `best_effort_graph_spec(pipe_ref, *, library_id, log_context)` in `pipelex/pipe_run/dry_run_in_process.py` runs `dry_run_pipe_in_process` against the **already-open validation library, before the lifecycle teardown** — the same single-load pattern as the Temporal activity, used by both backends. Degrade catch `(PipelexError, ValidationError, FactoryException)` → `None` with a warning.
-- `validated_pipes: list[ValidatedPipeEntry]` — per-pipe sweep outcomes, same entries as the agent-CLI envelope. **`ValidatedPipeEntry` key renamed `pipe_code` → `pipe_ref`** (the value always WAS the namespaced ref — a documented misnomer, fixed before the key gets canonized onto a protocol surface). `typing_extensions.TypedDict`, not `typing.TypedDict` (pydantic rejects the latter as a model field on Python < 3.12).
-- `pending_signatures: list[str]` + `is_runnable: bool` — the Part I runnability verdict, promoted onto the protocol report.
+## Risks & open questions
-One selection rule, one constructor, every backend: `select_primary_blueprint` (in its own `blueprint_selection.py`; also folds the previously-duplicated first-declaring-main_pipe loops in `execution_seams.py`, `dry_run_pipeline.py`, `inputs_ops.py`) and `build_validation_report(...)` (in `validation_report.py`) are the only way reports are assembled — `PipelexMTHDSProtocol.validate` locally, `ApiRunner.validate` hosted (companion branch).
+> **Eng review 2026-06-15 resolved several of these** — see "Decisions locked in eng review" above and the GSTACK REVIEW REPORT at the end. Newly resolved: API `source=None` (now fixed via per-item names, Issue 5), conformance coverage (added, Issue 2), `MIN_AGENT_VERSION` (→ 0.34.0), transport-failure policy, STRICT disclosure. New follow-ups captured in Out of scope.
-- `pipelex/pipeline/runner.py` — `validate` reworked: artifacts built inside the library window (the validation library id captured ONCE after `validate_bundle`; graph arm + `finally` target the same library; a teardown raise is suppressed while a body error propagates, mirroring the Temporal activity). Return annotations narrowed to the concrete `PipelexValidationReport`/`PipelexModelDeck` so typed consumers (ApiRunner, routes) get typed access. An empty `mthds_contents` list is a structured `ValidateBundleError`, not a raw `IndexError`.
+Decided (no longer open): default backend = `cli`; per-pipe FAILURE *may* be returned as data on a 200 and the extension surfaces it **if present** (verified: not produced today — see the locked decision and Phase 2 item 4); cross-file error→file mapping is the accepted main complexity of the directory-wide approach (eased by the `source` field — see Phase 1 item 1 and Phase 4).
-## Temporal wire (`DryValidateResult`)
+Remaining to verify during implementation:
-The worker computes everything with its already-loaded library and ships it across the boundary, so the API side never re-acquires a library: `DryValidateResult` gains `pending_signatures` and `pipe_io_contracts` as **required** wire fields (version-skewed workers fail loudly instead of silently yielding `is_runnable=True`). `PipeIOContractError` is non-retryable at the `wf_dry_validate` tier alongside `ValidateBundleError`. Integration test pins both fields crossing the in-process Temporal boundary. Size sanity-checked on a large structured bundle: `pipe_io_contracts` is an order of magnitude smaller than the `graph_spec` that already crossed the wire; the payload cap is far away.
+- **Cross-file diagnostics** — the error→file mapping (error references a pipe/concept declared in a sibling file) is the trickiest piece; needs explicit design and tests in Phase 4.
+- **`client.version()` shape** — *resolved:* `mthds-js` `VersionInfo` has no typed `implementation_version` (only `protocol_version` / `runner_version?` + an open index signature), though `pipelex-api` returns it (`version.py:43`). Phase 3 item 5 adds the typed field; until then it is only reachable via the untyped extension signature.
+- **Bundler for `mthds`** into the extension — *resolved:* the main extension bundles via **rollup** (esbuild only builds the webview). Verify the ESM `mthds` import bundles cleanly under rollup early in Phase 4.
+- **Conformance coverage** of the validate error envelope — *resolved:* not covered today; decide whether to *add* a spec section + test for the new `validation_errors` contract (not just "sync if covered").
+- **Secret UX** — final shape of the SecretStorage commands and env fallback.
-## Model deck
+## Out of scope (possible follow-ups)
-`PipelexModelDeck.aliases`/`waterfalls` are now **keyed by category** (`{category: {alias: model}}`): the old flat maps were built by `update()`-ing per-category maps and silently dropped cross-category alias collisions (e.g. `default-small`/`best-gpt` exist per category — proven against captured baselines). The protocol's flat `models` list is unchanged.
+- Pipeline **execution** via the API (`/v1/execute`, `/v1/start`, durable run lifecycle).
+- The build endpoints (`/v1/build/inputs|output|runner`, concept/pipe-spec) — separate features the extension doesn't use today.
+- Surfacing the richer report fields the API returns but the CLI on-save path ignores (`pipe_io_contracts`, `bundle_blueprint`, `pending_signatures`, `is_runnable`).
+- **Part B — combined exit-0 CLI validate+view envelope** (eng review 2026-06-15). Not needed: the single `--view` spawn already serves both channels via exit code. Revisit only if a cleaner exit-0 contract is wanted later (no functional gain).
+- **The 200-`validated_pipes`-FAILURE channel** (deliberate behavior change in pipelex / pipelex-api). When/if built, **split the diagnostic type** — a per-pipe dry-run FAILURE is pipe-level, not line-level, and must not be forced into `ValidationErrorItem` (which would fabricate code locations). (eng review TODO 2)
+- **Buffer-aware sibling gathering** — v1 reads siblings from disk (CLI parity). Follow-up: read unsaved editor buffers for fresher cross-file diagnostics, deliberately and with tests, on both backends. (eng review TODO 1)
+- **Capability probe for API gating** — replace the coarse `implementation_version` SemVer gate with a "does this server return `validation_errors`?" probe, robust for self-hosted/dev/prerelease servers. v1 ships the lenient version gate. (eng review TODO 3)
+- **`mthds_names` is an `MthdsApiClient`-only param, not on the `MTHDSProtocol`/`Runner` interface** (code-review finding, Phase 3 / `ad74bde`). **Deliberate** — `mthds_names` is a Pipelex-API extension, not protocol surface (MTHDS brand boundary), and Phase 4's `ApiValidationBackend` holds the concrete `MthdsApiClient` so it can pass names directly. Tradeoff: the cross-file-diagnostics capability is unreachable through a `Runner`-typed reference (a caller wiring names via the interface would need an `instanceof MthdsApiClient` downcast). Revisit IF/when the protocol surface formally adopts per-content names (coordinate with [[project_protocol_surface_alignment]]) — then promote it to `MTHDSProtocol.validate` as an optional 3rd arg (no-op on `PipelexRunner`). Do NOT reflexively add it to the interface now just to avoid the downcast; the brand boundary is the stronger constraint.
+- **`PipelexValidationReport.mthds_contents` typed optional but always present on the pipelex-api wire** (code-review finding). Minor under-promise (safe). The shallow `Array.isArray` cast on `validation_errors` + `JSON.parse as` on 200 bodies manufacture type guarantees the wire doesn't runtime-enforce — consistent with the client's pervasive `as`-cast style and the real server always sends well-formed data; harden to per-item validation only if a non-pipelex MTHDS runner ever feeds this client. The lone-named `VersionInfo.implementation_version` (vs `implementation`/`runtime_version` on the index signature) is a deliberate plan-scoped choice; type the cluster together if a second extension field ever needs gating.
+- **mthds-js agent/CLI surfaces don't yet consume the new typed fields** (code-review "noted-only" items — all in files Phase 3 `ad74bde` did NOT touch; capture, don't fix blind):
+ - **Agent `validate` envelope drops `validationErrors`.** `runProtocolValidate` (`src/agent/commands/api-commands.ts`) catches the 422 and emits `agentError(err.serverMessage ?? err.message, "ValidationError", …)`, discarding the now-typed `err.validationErrors`. Deliberate for Phase 3 (the VS Code extension is the intended consumer, the agent CLI surface wasn't scoped) — but if agents are ever meant to map per-error diagnostics, this is the wiring point. Splitting the diagnostic shape (per-pipe FAILURE ≠ line-level) interacts with the existing "200-`validated_pipes`-FAILURE channel" follow-up above.
+ - **Dead `success: true` literal.** `agentSuccess({ success: true, ...report })` (`api-commands.ts` `runProtocolValidate`) spreads a report that now carries its own `success`, so `...report` overrides the literal. Harmless today (server always sends `success: true` on 200) but misleading; drop the literal and rely on `report.success`, or drop `success` from the typed report. Same pattern lives near `cli/commands/validate.ts`.
+ - **`install.ts` renders "pipelex-api undefined".** `src/cli/commands/install.ts:155` builds `` `${ver.implementation} ${ver.implementation_version}` `` unguarded; a runner that omits `implementation_version` (now formally optional) prints a literal `undefined`. Pre-existing (the read predates Phase 3 via the index signature), but the field's new optional typing makes the unguarded read a flagged mismatch — guard with `?? ""` / a conditional join when touched.
-## Module moves (import-cycle breaks, mechanical)
+## GSTACK REVIEW REPORT
-- `dry_run_pipe_in_process` → NEW `pipelex/pipe_run/dry_run_in_process.py` (its old home `dry_run_pipeline.py` imports the runner; the runner importing the graph arm from it would close a cycle).
-- `dry_run_pipeline` → `pipelex/pipeline/dry_run_pipeline.py` (layering follow-up; importers + docs re-pointed).
-- `select_primary_blueprint` lives in its own `blueprint_selection.py`, NOT `validate_bundle.py` — importing from `validate_bundle` in `execution_seams` closed a cycle through `bundle_validator`. (Split out of `pipe_io_contracts.py`, where it had been parked: the contracts module is the heavy JSON-Schema builder, the selection rule is light and consumed by callers that never need the contracts.)
-- `MTHDS_PROTOCOL_VERSION` deleted: `version()` reports the SDK's `PROTOCOL_VERSION` directly ("single source of truth … runners do not get to override it"); the temporary re-export staged for pipelex-api's import was removed once the companion branch imports the SDK constant.
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | not run |
+| Codex Review | `/codex review` | Independent 2nd opinion | 1 | issues_found | outside-voice surfaced the API `source=None` blocker + hardening points |
+| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR | 5 issues + 3 TODOs, all resolved; 0 critical gaps |
+| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | n/a (editor diagnostics, no visual UI) |
+| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | not run |
-## Part II test coverage
+**CODEX:** ran (read-only, high effort). Confirmed D1/Q1, then found the load-bearing miss: the API request is nameless `mthds_contents: list[str]`, so `source=None` and cross-file diagnostics misfire on the API backend. Verified in code; resolved as Issue 5 (Option A: per-item names). Also folded: "one call" wording, transport stale-clear, privacy timing/directory-wide, non-`problem+json` handling, conformance-asserts-real-wire, mthds-js runtime checklist, compat-floor explicitness.
-- `tests/integration/pipelex/pipeline/test_pipe_io_contracts.py` — the D6 builder: `PipeSignature` pipes in lenient batches, multiplicity entry shapes, memoization, the `PipeIOContractError` wrap. `select_primary_blueprint` first-declaring / none / multiple is covered separately in `tests/unit/pipelex/pipeline/test_select_primary_blueprint.py`.
-- `tests/integration/pipelex/pipeline/test_protocol_validate.py` — the canonical report shape + lifecycle: graph populated on main-pipe bundles, graph-failure-mid-window degrades to `None` while restore/teardown holds (asserted WITHOUT mocks on the real-graph case), strict-raise, empty-contents guard.
-- `tests/integration/pipelex/temporal/` — both new `DryValidateResult` fields cross the boundary.
-- Downstream proof (not in this repo): pipelex-api's suite runs against this branch via an editable pin — local↔hosted byte-identity per fixture class is pinned by its `tests/unit/test_protocol_parity.py`; the conformance repo pins the agent-CLI envelope against workspace `docs/specs/pipelex-mthds-protocol.md`.
+**CROSS-MODEL:** One tension — my Issue 3 ("both backends use `source`") was infeasible as stated until Issue 5 fixed the API `source`. Resolved in the user's favor by adding per-item names. No remaining disagreement.
----
+**Scope decision (Step 0):** SCOPE_REDUCED then re-expanded for correctness — Part B deferred (D1), but Issue 5 added the API `source` contract change back because it is load-bearing for the headline goal. Net: leaner CLI surface, fuller API surface.
-## Downstream (separate effort, NOT in this PR)
+**What already exists (reused, not rebuilt):**
-The pipelex runtime support is complete here. The recursive **orchestrator** (`mthds-vibe`) + **worker** (`mthds-signature-expander`) + the `--allow-signatures` hook change live in the sibling `mthds-plugins` repo, prescribed by its `wip/recursive/design.md` (flipped to the additive model). Those artifacts don't exist yet; building them is a fresh effort and depends on the pipelex release carrying this branch.
+- GraphSpec is identical on both paths (`graphspec.py`, `by_alias=True`) — no body transform.
+- The extension's diagnostics pipe (`toDiagnostic`/`locateError`/`sourceLocator`/`extractJson`) and existing `ValidationErrorItem` shape — the API path feeds it, not a parallel one.
+- `extract_validation_errors()` (`agent_output.py:410`) — promoted to a shared builder, not rewritten.
+- The single `--view` spawn already serves both channels (exit-code discriminator) — no new CLI contract needed.
+- `graph_spec: unknown` opaque-transport pattern already established in `mthds-js` (`runs.ts`).
-On the protocol side (Part II), the companion consumers ship after this branch releases: `pipelex-api@feature/Recursivity-and-protocols` (routes through the canonical report; restores its PyPI pin at the release carrying this branch), `pipelex-app@feature/protocol-alignment` (renamed wire field + `pipe_ref` lookups), `conformance@feature/Pending-signatures` (envelope conformance tests — red against `dev` pipelex until this merges).
+**Failure modes (new codepaths):**
----
+| Failure | Test? | Error handling? | User sees? |
+|---|---|---|---|
+| API server unreachable | yes (T7/T11) | yes (Issue 4: notify, clear, no fallback) | clear actionable notification — not silent |
+| API returns non-`problem+json` (proxy/auth/timeout) | yes (T7) | yes (same policy) | notification, no garbage diagnostics |
+| Multi-file error, `source` unresolved | yes (T11) | yes (fallback to saved file/output channel) | diagnostic on saved file or channel, never lost |
+| STRICT redacts validation_errors (hosted) | yes (T11, both branches) | n/a | full diagnostics retained |
+| Old CLI (<0.34.0) selected | yes (T8) | yes (upgrade message) | clear "too old" message |
+| Dev/prerelease API tag false-fails gate | folded (lenient parse) | yes | warn-once, not hard-blocked |
-## CHANGELOG (under `[Unreleased]`)
+No critical gaps (no failure that is untested AND unhandled AND silent).
-The `[Unreleased]` entry in `CHANGELOG.md` covers the additive multi-file construction (reconciliation, cross-file concept resolution, domain-metadata merge, `pending_signatures`), the `PipeSignature` taxonomy eviction (removed `PipeType`/`PipeCategory.PIPE_SIGNATURE`), and the Part II protocol rework (canonical typed report, `pipe_ref` re-keying + D7 rename, graph arm, Temporal wire fields, category-keyed deck extensions, module moves). It also corrects the v0.33.0 entry's `protocol_version` claim (0.1.0 → 0.6.0, a factual error).
+**Worktree parallelization:** Largely SEQUENTIAL — the cross-repo release train is a hard dependency chain (pipelex → pipelex-api → mthds-js → vscode). Only meaningful parallelism: the extension's CLI-backend refactor (T6) can be built against pipelex 0.34.0 in parallel with the pipelex-api (T3/T4) and mthds-js (T5) releases, since it does not need the API path. All other extension work (T7–T10) shares `editors/vscode/src/pipelex/validation/` and is sequential.
----
+**Implementation Tasks** (also in `tasks-eng-review-*.jsonl` for /autoplan):
+
+- [x] **T1 (P1)** pipelex — thread per-item name into `blueprint.source` on the in-memory load path (Issue 5) — DONE (`make_pipelex_bundle_blueprint(mthds_name=)` + `validate_bundle(mthds_names=)`)
+- [x] **T2 (P1)** pipelex — Part A: ValidationErrorItem + shared builder + ErrorReport field + ValidateBundleError override + `_STRICT_KEPT_FIELDS` (Issues 1) — DONE
+- [x] **T2b (P1)** pipelex — T3 enabling refactor (this session, uncommitted/editable-live): extract `validate_bundles_in_process` (protocol `validate` signature untouched) + `DryValidateArg.mthds_names`; tests reconciled; `make agent-check` GREEN — DONE
+- [x] **T3 (P1)** pipelex-api — optional `mthds_names` on ValidateRequest (+ length validator → 422), threaded through `ApiRunner.validate` (direct→`validate_bundles_in_process`, temporal→`DryValidateArg`+blueprint loop) + route (Issue 5) — DONE (commit `2941daa`)
+- [x] **T4 (P2)** pipelex-api — spec Error-contract section documents `validation_errors`+`mthds_names`; real-wire verified in `pipelex-api/tests/unit/test_validate_errors.py` (Issue 2). **Divergence:** conformance HTTP arm stays deferred (D5) — verified in pipelex-api's own suite + spec `<!-- unverified -->` marker, NOT a new conformance test. `check-spec-links` GREEN. DONE (spec commit `a8b6b4b`)
+- [x] **T5 (P1)** mthds-js — typed report + `ApiResponseError.validationErrors` + named contents on `validate()` (Issue 5) — DONE (branch `feature/typed-validation-report`, commit `ad74bde`; version stays 0.10.0, publish deferred to release-LAST)
+- [x] **T6 (P1)** vscode — `CliValidationBackend` single-spawn exit-code discriminator (D1/Q1) — DONE (`cliValidationBackend.ts`; `--format json` always; exit-code discriminator; input-domain no-list → synthetic diagnostic)
+- [x] **T7 (P1)** vscode — `ApiValidationBackend` transport/non-problem+json policy: notify, clear stale, no fallback (Issue 4) — DONE (`apiValidationBackend.ts` + validator `handleBackendError` clears dir + `notifyOnce`)
+- [x] **T8 (P2)** vscode — raise `MIN_AGENT_VERSION`→0.34.0 (compat-floor break) + lenient API version parse (Issue 3) — DONE (via `bump-pipelex-version` skill; `apiVersionGate.parseCleanRelease`)
+- [x] **T9 (P2)** vscode — privacy confirm before first remote request, directory-wide wording — DONE (`backendFactory.confirmRemote` modal, per-host globalState, fired before first non-localhost send)
+- [x] **T10 (P2)** vscode — multi-file disk gather + CLI-resolution parity verify + send per-item names (TODO 1) — DONE (`bundleGather.ts` flat = `--library-dir` non-recursive glob verified in pipelex `bundle_cmd.py:103`; divergence documented; names threaded to API)
+- [x] **T11 (P1)** cross-repo — tests: STRICT both-branches, CLI==API parity, transport, cross-file mapping, conformance — DONE (vscode: 37 new tests across backends/gather/cross-file/version-gate; STRICT both-branches + real-wire 422 verified upstream in pipelex + pipelex-api suites; conformance HTTP arm deferred D5)
-## Pre-merge design change — DONE
+**VERDICT:** ENG CLEARED — ready to implement. CEO + Design reviews not required (backend/editor-diagnostics change, no product-direction or visual-UI scope).
-Review flagged that `PipeSignature` should not be a peer pipe type — it's a contract substrate of `PipeAbstract`, not a sibling of `PipeLLM`/`PipeSequence`. **Landed:** `PipeSignature` is evicted from the executable taxonomy. `PipeType.PIPE_SIGNATURE` and `PipeCategory.PIPE_SIGNATURE` are removed; `is_signature` is now a class fact (base returns `False`, `PipeSignature` / `PipeSignatureBlueprint` override to `True`) instead of an enum read; a signature carries `type = "PipeSignature"` with `pipe_category = None`, admitted by the shared validators via a `PIPE_SIGNATURE_TYPE_TAG` allowlist entry. It stays a `PipeAbstract` subclass (the dry-run shim) and keeps `signature_for` for mthds-plugins (its `reject_signature_for_pipe_signature` guards are gone — the rejection is now structural, since `PipeSignature` is no longer a `PipeType` the field can coerce). As-built plan: [`signature-taxonomy-refactor.md`](wip/recursivity/signature-taxonomy-refactor.md).
+NO UNRESOLVED DECISIONS
diff --git a/docs/building-methods/pipes/signature-pipes.md b/docs/building-methods/pipes/signature-pipes.md
index 872f93007..ce6dcce33 100644
--- a/docs/building-methods/pipes/signature-pipes.md
+++ b/docs/building-methods/pipes/signature-pipes.md
@@ -20,8 +20,8 @@ Signatures let an agent (or a human author) build a complete, dry-runnable bundl
| Mode | Behavior |
| ---- | -------- |
-| **Strict validation** (default) | A pipeline that reaches a signature through its dependency graph is rejected with a `SignaturesNotAllowedError`. The error names every reachable signature plus the controller chain that leads to it. |
-| **Lenient validation** (`--allow-signatures`) | Signatures are accepted. During dry-run, each signature mints a mock `Stuff` matching its declared `output` (including multiplicity). |
+| **Strict validation** (default) | Signatures are never a validation error: the bundle is valid, but a pipeline that reaches an unimplemented signature is reported as NOT yet runnable. The validation report lists the outstanding placeholders in `pending_signatures` and sets `is_runnable: false`; `validate` / `validate --all` / `validate bundle` / `validate method` then exit non-zero on that verdict (the runnability gate). In strict mode signature pipes are excluded from the dry-run sweep (not mock-run). |
+| **Lenient validation** (`--allow-signatures`) | The verdict is unchanged (`pending_signatures` / `is_runnable` are still reported), but the runnability gate is tolerated (exit 0) and signature pipes are mock-run during the sweep — each mints a mock `Stuff` matching its declared `output`, multiplicity included. |
| **Live execution** | Running a pipeline that hits a signature raises `PipeSignatureNotExecutableError` — a signature has no implementation to execute. |
## MTHDS Parameters
diff --git a/docs/contribute/keyword-only-arguments.md b/docs/contribute/keyword-only-arguments.md
new file mode 100644
index 000000000..0c6d0dc96
--- /dev/null
+++ b/docs/contribute/keyword-only-arguments.md
@@ -0,0 +1,202 @@
+# Keyword-only arguments convention
+
+This is the canonical convention for keyword-only function parameters across the `pipelex/` source tree (tests are out of scope). The goal is self-documenting call sites: when a function takes more than one meaningful argument, the caller must name them, so `do_thing(retries=3, timeout=30)` is forced over the unreadable `do_thing(3, 30)`. The convention is mechanically enforced by an AST guard (the `check-keyword-only` dev command, wired into both `make agent-check` and the `make check` family, and gated in CI). The `pipelex/` source tree is fully compliant, so the guard hard-blocks on **any** violation: new code must follow this convention or it fails the build. This document is the human-readable specification that guard implements.
+
+## The rule
+
+A function or method must place a bare `*` separator in its signature so that every parameter after the subject is keyword-only. The compliant shape is:
+
+```python
+def f(subject, *, opt1, opt2): ...
+```
+
+The first non-`self`/`cls` parameter — the subject — stays positional-or-keyword. We deliberately do NOT use the positional-only `/` separator anywhere; the subject is allowed to be passed positionally or by keyword, at the caller's discretion.
+
+A signature is a violation when, after dropping a leading `self`/`cls` and the single allowed subject parameter, any positional-or-keyword parameter that is not already keyword-only remains. In other words, a function needs the bare `*` as soon as it would otherwise expose a *second* bare positional argument to callers: only the subject may be passed positionally, and everything after it must be named. Making the subject keyword-only too is always allowed — see Exception 1.
+
+## The two exceptions
+
+These two exceptions are part of the rule itself — they describe signatures that are compliant without a bare `*`.
+
+### Exception 1 — the subject parameter
+
+The first parameter after `self`/`cls` — the subject — *may* stay positional-or-keyword. This is a permission, not a requirement, and it exists for the same reason Swift lets you drop the first argument label with `_`: when the function name already designates what it acts on, naming the subject at the call site adds nothing (`render(node)`, `parse_blueprint(bp)`). A function with only a subject is compliant, and so is `def f(subject, *, opt1, opt2)` where every parameter after the subject is keyword-only.
+
+Making the subject keyword-only too is always allowed and is frequently the better choice — `def f(*, source, target)` is fully compliant and often more readable than leaning on a positional subject. The exception only *permits* a positional subject; it never forces one. What the rule forbids is a *second* positional parameter: as soon as a non-subject parameter would be passed positionally, the bare `*` is required. So `def f(a, b)` and `def truncate(text, max_length=80)` are violations (`def f(a, *, b)`, `def truncate(text, *, max_length=80)`), while `def render(node)` and `def f(*, a, b)` are both fine.
+
+### Exception 2 — symmetric tuples (explicit allowlist only)
+
+A small set of functions take a short, conventionally-ordered tuple of arguments where positional calling is the universally-understood form and naming would be pure noise: `clamp(value, low, high)`, `Point(x, y)`, `replace(text, old, new)`, `lerp(a, b, t)`, `set_env(key, value)`. These are exempt ENTIRELY — the whole function, including any trailing options — but ONLY via an explicit allowlist keyed by qualified name and file. There is no pattern-based guessing: a function is symmetric-tuple-exempt if and only if it is listed in the allowlist. This keeps the carve-out auditable and prevents the exemption from quietly swallowing genuine subject-plus-options signatures, which are the main thing this refactor wants to fix.
+
+The curated allowlist is intentionally short. Each entry is a genuine ordered tuple under a well-known convention, not a subject followed by descriptive options.
+
+- `pipelex.system.environment.set_env` — `set_env(key: str, value: str)`. Canonical key/value pair mirroring dict assignment; naming them would be pure noise.
+- `pipelex.kit.single_file_agent_rules.unified_diff` — `unified_diff(before: str, after: str, path: str)`. `before`/`after` is the canonical ordered diff pair; `path` is the diff header. Reads as the universally-known diff convention.
+- `pipelex.tools.misc.diff.diff_files` — `diff_files(path1, path2)`. Symmetric two-operand comparison; the `1`/`2` suffixes self-label ordering and there is no old/new semantics that keywords could clarify.
+- `pipelex.tools.misc.diff.diff_dirs` — `diff_dirs(dir1, dir2)`. Same symmetric two-directory comparison; `dir1`/`dir2` is a self-labelling ordered pair.
+- `pipelex.tools.typing.class_utils.are_classes_equivalent` — `are_classes_equivalent(class_1, class_2)`. Symmetric structural-equivalence check; order is irrelevant (equivalence is commutative) and the `1`/`2` suffixes self-label the operands. No trailing options.
+
+The operating rule for two-operand functions — when only one of the operand-positional and the all-keyword form should win:
+
+- **A clean symmetric/ordered pair with NO trailing options** may go on the allowlist and stay fully positional (the entries above). Order is either irrelevant (`are_classes_equivalent`) or universally understood (`diff_files`'s `1`/`2`).
+- **A pair that also carries trailing options** is reshaped to fully keyword-only instead — the whole-function allowlist is all-or-nothing, so it cannot keep the pair positional while forcing the options keyword, and letting the options go positional is exactly the unreadable case this refactor targets. Examples now keyword-only: `copy_file(*, source_path, target_path, overwrite=True)`, `mirror_dir(*, source_dir, target_dir, …)`, `sync_toml_values(*, source_path, target_path, dry_run=False)`, `has_diff_dirs(*, dir1, dir2, exclude_files=None, exclude_dirs=None)`, `is_multiplicity_compatible(*, source_multiplicity, target_multiplicity)`, the graph tracer's `add_edge(*, source_node_id, target_node_id, edge_kind, …)`.
+
+This deliberately keeps the allowlist whole-function (no per-entry "leading positional count" machinery): the handful of pairs that would benefit from staying positional-with-keyword-options are rare enough that reshaping to all-keyword is the simpler, uniform answer.
+
+Adding to the allowlist is a deliberate act: the entry must name a genuine ordered tuple under a recognized convention (key/value, x/y, min/max/clamp, before/after, src/dst, geometric coordinates, interpolation operands) with no trailing options, justified in the same conservative spirit as the entries above. When in doubt, leave it off and let the function be keyword-only — that is the safe default.
+
+## Carve-outs (skipped entirely)
+
+Carve-outs are different from exceptions: a carved-out def is never inspected at all, regardless of its parameter shape. These are signatures the guard cannot or must not touch because some framework or the interpreter itself owns the calling convention.
+
+### Dunder and operator methods
+
+Any method whose name matches `^__[A-Za-z0-9_]+__$` (a leading and trailing double underscore around a real identifier body) is skipped. The interpreter and the data-model protocols invoke these positionally — `__init__`, `__eq__`, `__call__`, `__getitem__`, `__format__`, `__contains__`, `__enter__`, `__exit__`, and so on — and never by keyword, so forcing keyword-only would be both wrong and impossible to satisfy. The match is on the method NAME node only (not the source line), is a full-match (anchored), and requires a non-empty body between the underscore pairs so the degenerate `____` cannot match. This deliberately does NOT carve out name-mangled half-dunders (`__private` with no trailing `__`): those are ordinary methods we call ourselves, and they remain subject to the rule.
+
+### Pydantic validators and serializers
+
+A def decorated with any of these pydantic decorator names is skipped, because pydantic invokes the wrapped callable with a fixed positional protocol (`value`, `info`, `handler`, ...) that we do not control:
+
+- `field_validator`
+- `model_validator`
+- `field_serializer`
+- `model_serializer`
+- `validator` (pydantic v1 legacy)
+- `root_validator` (pydantic v1 legacy)
+
+Only `field_validator`, `model_validator`, and `model_serializer` are actually used in the source today; the v1 legacy names and `field_serializer` are included defensively so the guard stays correct if they are introduced later. Decorators may be call-form (`@field_validator("name", mode="before")`) or bare (`@model_serializer`); the guard handles both by unwrapping `ast.Call.func` when present and matching on the unqualified decorator name. The `parse_model_reference` helper referenced via `Annotated[..., BeforeValidator(parse_model_reference)]` is NOT a decorated def — it is a plain single-parameter module function, already compliant under the single-parameter rule, and needs no carve-out.
+
+### Framework entrypoints
+
+A def is skipped when it is registered with a framework whose calling convention is not ours to dictate. Matching is on the decorator's attribute suffix (the receiver name varies — `app`, `graph_app`, `show_app`, `kit_app`, `build_app`, ...), and on the Temporal and pytest decorators by their attribute/name:
+
+- Typer/click commands and callbacks — any decorator that is an attribute access ending in `.command` or `.callback`.
+- Temporal handlers — `activity.defn`, `workflow.run`, and defensively `workflow.signal`, `workflow.query`, `workflow.update` (none of the latter three are used yet, but they are part of the worker entrypoint surface). Note `workflow.defn` decorates classes, not functions, so it is irrelevant. The custom `@convert_pipelex_errors` decorator is stacked directly below `@activity.defn` and is NOT a framework decorator — the guard must scan the WHOLE decorator stack for a framework match, not just the innermost or outermost decorator.
+- pytest fixtures — `fixture`, matched on the bare decorator name so both `@pytest.fixture` and bare `@fixture` (`from pytest import fixture`) are covered (the only src-side fixtures live in the shipped `pipelex/test_extras/shared_pytest_plugins.py` plugin module).
+- Jinja2 filters/tests/globals — `pass_context`, `pass_environment`, `pass_eval_context`, matched on the bare decorator name (covers both `@pass_context` from `from jinja2 import pass_context` and the attributed `@jinja2.pass_context`). The Jinja2 engine invokes a filter POSITIONALLY from template syntax — `{{ value | tag("name") }}` calls `tag(context, value, "name")` — so the wrapped callable's arguments cannot be made keyword-only. This is the same framework-entrypoint category as Typer/Temporal/pytest. A multi-argument filter without one of these decorators (rare) is covered by the `# kw-only: ignore` escape hatch; single-argument filters (`escape_script_tag(value)`) are compliant under the single-parameter rule and need nothing.
+
+FastAPI is intentionally absent: there are no route handlers in `pipelex/` source — the FastAPI server lives in the separate `pipelex-api/` repo.
+
+Known coverage gap (documented, not silently ignored): some Typer commands are registered by call-style `app.command(name=...)(some_fn)` against functions defined in separate modules that carry NO decorator, so a decorator-keyed guard cannot see them via the framework carve-out. These target functions consistently type their parameters as `Annotated[T, typer.Argument(...)]` / `Annotated[T, typer.Option(...)]`. The guard treats a def as a framework entrypoint when any of its parameters carry `Argument`/`Option` metadata in their `Annotated[...]` annotation — matched on the trailing callee name, so both the qualified `typer.Option(...)` form and the bare `Option(...)` form (`from typer import Option`) are recognized — which closes the gap without resorting to a broad path-based exclusion of CLI modules.
+
+### Base / Protocol / ABC overrides
+
+A def decorated with `@override` (from `typing_extensions` / `typing`) is skipped. See the next section for why this single decorator is a complete and reliable signal in this codebase.
+
+## Override handling — decision
+
+DECISION: skip any def carrying an `@override` decorator. We do NOT introduce a dedicated `@kw_exempt` decorator for overrides, and we do NOT attempt base-aware (import-resolving / type-inferring) detection.
+
+Rationale. An overriding method cannot freely re-shape its signature — it must stay compatible with the base/Protocol it implements — so the correct place to apply the keyword-only convention is the base definition, after which implementations inherit the contract and pyright's `reportIncompatibleMethodOverride` keeps them in line. Skipping `@override` defs is consistent with fixing the base. Crucially, `@override` is a reliable AND complete signal here: `pyproject.toml` sets `reportImplicitOverride = true`, so any method overriding a nominal base MUST carry `@override` or `make agent-check` already fails before the keyword-only guard runs — the marker cannot silently rot. Protocol implementations are structural and not forced by that setting, but house style applies `@override` to them consistently too; the residual risk is a hypothetical future Protocol implementor that forgets `@override`, which is already a style deviation the team avoids and is covered by the inline escape hatch below. A `@kw_exempt` decorator would duplicate semantics `@override` already carries and add a second redundant annotation to dozens of override sites for no gain. Base-aware detection would require import resolution a pure-AST guard cannot do reliably, and the codebase has already solved the problem for us via `reportImplicitOverride`. The guard matches `@override` structurally: a decorator that is an `ast.Name` with `id == "override"` or an `ast.Attribute` with `attr == "override"`, covering both `override` and `typing_extensions.override` without resolving imports.
+
+## Inline escape hatch
+
+A `# kw-only: ignore` comment on the `def` line (or the `async def` line) suppresses exactly one violation for that function. This is the documented fallback for the rare legitimate case the carve-outs and allowlist do not cover — for example a Protocol implementor that genuinely lacks `@override`, or a one-off signature whose positional shape is justified and does not merit a permanent allowlist entry. The escape hatch is the exception, not the mechanism: the carve-outs and the `@override` skip are expected to handle the vast majority of legitimate non-compliant signatures, and a reviewer seeing `# kw-only: ignore` should expect a short justification nearby. The marker is matched against the comment text on the def line; it suppresses the single def it sits on, not a whole class or module.
+
+## Worked examples
+
+A subject plus options — the canonical thing this refactor fixes:
+
+```python
+# before — opaque at the call site: build_pipe(my_spec, True, 3, False)
+def build_pipe(spec, dry_run, retries, validate): ...
+
+# after — self-documenting: build_pipe(my_spec, dry_run=True, retries=3, validate=False)
+def build_pipe(spec, *, dry_run, retries, validate): ...
+```
+
+A single subject and nothing else — compliant; the subject may be passed positionally:
+
+```python
+def render(node): ... # render(my_node)
+```
+
+All parameters named, including the first — always compliant, and often the most readable choice:
+
+```python
+def copy_payload(*, source, target): ... # copy_payload(source=a, target=b)
+```
+
+Even a single defaulted option must be named — this is the common case the refactor fixes, not an exception to it:
+
+```python
+# before: truncate(text, 120) — what does 120 mean?
+def truncate(text, max_length=80): ...
+# after: truncate(text, max_length=120)
+def truncate(text, *, max_length=80): ...
+```
+
+A symmetric tuple on the allowlist — exempt entirely, stays positional:
+
+```python
+def set_env(key: str, value: str) -> None: ... # set_env("PIPELEX_ENV", "prod")
+```
+
+A directional pair with a trailing option — neither operand is "the object", and a whole-function allowlist exemption would let the option go positional too, so the whole signature becomes keyword-only:
+
+```python
+# before — copy_file(src, dst, True): what does True mean?
+def copy_file(source_path, target_path, overwrite=True): ...
+# after — copy_file(source_path=src, target_path=dst, overwrite=False); every argument is named
+def copy_file(*, source_path, target_path, overwrite=True): ...
+```
+
+A clean symmetric pair with no trailing options is the opposite case — it goes on the Exception 2 allowlist and stays fully positional (`are_classes_equivalent(class_1, class_2)`).
+
+An override — skipped because of `@override`; fix the base signature instead:
+
+```python
+@override
+def _store(self, data, *, key, content_type): ... # base StorageProviderAbstract._store defines the kw-only contract
+```
+
+A dunder — skipped by name; the interpreter owns the calling convention:
+
+```python
+def __format__(self, format_spec: str) -> str: ... # called positionally by format()/f-strings
+```
+
+A pydantic validator — skipped by decorator; pydantic owns the positional protocol:
+
+```python
+@field_validator("some_field", mode="before")
+def normalize(cls, value, info): ...
+```
+
+## Enforcement
+
+The entire `pipelex/` source tree is compliant, so the guard hard-blocks on **any** violation — there is no baseline and no tolerated debt. The guard runs at several gates:
+
+- A Claude Code `PostToolUse` hook (`.claude/hooks/check-keyword-only.sh`, wired in `.claude/settings.json`) — the tightest loop. After every `Edit`/`Write`/`MultiEdit` of a `pipelex/**/*.py` file it checks just that file and blocks with the offending signatures if it regressed, so an agent learns at edit time rather than at the end of the session. It runs the stdlib-only core by file path (no Typer/hub import), so it costs a few tens of milliseconds. The hook is check-only — it never rewrites a file mid-edit.
+- `make agent-check` — the fast everyday gate. It runs the **auto-fixing** variant (`fix-keyword-only`) early, right after `fix-unused-imports` and before `ruff format`, so a mechanically-fixable violation is corrected in place instead of failing the build. The fixer is **non-gating** — it reports the violations it can't mechanically fix but does not abort — so `format`, `lint`, `pyright`, and `mypy` all still run (you get keyword-only *and* type feedback in a single pass, and the tree is never left half-mutated and unformatted). The **read-only** `check-keyword-only` then runs **last** and is what actually blocks on any remaining violation.
+- `make check` — the heavy aggregate gate. It runs the **check-only** `check-keyword-only` (no rewriting), so CI-equivalent runs stay read-only.
+- CI — a dedicated lint job (`lint-keyword-only` in `.github/workflows/lint-check.yml`) gated by the required `Lint (all)` status check, so no non-compliant signature can merge. This is the hard guarantee; the hook and `make` gates are local conveniences layered on top.
+
+When you add or change a signature, place the bare `*` after the subject — or run `make fix-keyword-only` (alias `fko`) to insert it automatically. If the type checker is blind to how a function is called (a framework or the interpreter invokes it positionally — a Jinja2 filter, an `__import__` hook, an aiohttp route handler, a PostHog `on_error` callback), the guard cannot detect that statically; the carve-outs above cover the known cases, and a genuinely justified one-off uses the `# kw-only: ignore` escape hatch. `make agent-test` is the safety net for these dynamic call surfaces — pyright/mypy will pass a wrongly-keywordized callback that the suite then catches at runtime.
+
+## Auto-fix
+
+`pipelex-dev check-keyword-only --fix` (exposed as `make fix-keyword-only` / `fko`, and run automatically inside `make agent-check`) rewrites every *mechanically-fixable* violation by inserting a bare `*` as far left as possible — immediately after `self`/`cls` (and after any `/`) — so **every** non-`self`/`cls` parameter becomes keyword-only, not just the ones after the subject: `def f(a, b)` becomes `def f(*, a, b)`, `def m(self, a, b)` becomes `def m(self, *, a, b)`. (The exception that lets the subject stay positional is a permission, not a requirement — the fixer takes the always-allowed, more explicit form.) The raw insert lands on the def's original line(s); the `make fix-keyword-only` / `fko` target runs `ruff format` right after the rewrite, so the standalone path leaves a `ruff format`-clean tree (inside `agent-check` the later `format` step would normalize it anyway). The rewrite is idempotent and is re-parsed before being written — a rewrite that would not parse is discarded and the violation reported instead.
+
+A few shapes the guard flags cannot be fixed by a single bare-`*` insert, and are reported for a manual fix rather than rewritten:
+
+- a `*args` is present — the parameters before it cannot be made keyword-only by a bare `*`, and a bare `*` cannot coexist with `*args`;
+- a keyword-only section already exists (a bare `*` is already in the signature, with a positional parameter still ahead of it) — the existing `*` must be moved by hand, since a second one is a syntax error;
+- two or more positional-only parameters (before a `/`, excluding a leading `self`/`cls`) remain — a bare `*` cannot precede the `/`, so they stay positional and the single permitted positional subject is not enough to reach compliance. (A *single* positional-only subject is still auto-fixable: the `*` goes right after the `/`, e.g. `def f(a, /, b, c)` → `def f(a, /, *, b, c)`.)
+
+The `--fix` path is **non-gating**: it mutates and reports, but never exits non-zero on the violations it couldn't fix. The read-only `check-keyword-only` (no flag) owns the gating — it runs last in `agent-check` and is the variant `make check` / CI use. So `make fko` fixes what it can and prints the rest without failing your shell; run `make check-keyword-only` (alias `cko`) when you want the pass/fail gate. This split is deliberate: a tree-mutating step shouldn't also be the hard gate, or an abort could leave files rewritten-but-unformatted and mask the type-check phase.
+
+Auto-fix is not a substitute for review: the guard is blind to framework-positional callers (see the safety-net note above), so a signature it "fixes" might be one some framework invokes positionally. `make agent-test` remains the safety net — verify after a bulk auto-fix.
+
+Run the guard directly to see the full picture:
+
+```bash
+make check-keyword-only # alias: make cko — one line on pass, the full violation list on fail
+make fix-keyword-only # alias: make fko — auto-insert the bare `*`; reports any manual-fix cases
+.venv/bin/pipelex-dev check-keyword-only --report # full inventory grouped by package
+.venv/bin/pipelex-dev check-keyword-only --fix # auto-fix (what `make fko` runs)
+
+# Lean single-file check (what the PostToolUse hook runs): stdlib only, invoked by file path so it
+# skips the pipelex package import chain. Prints violations to stderr and exits 2, else exits 0.
+.venv/bin/python pipelex/cli/dev_cli/commands/keyword_only_guard.py pipelex/some/edited_file.py
+```
diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.md
index 41073dd3e..56ca6c96e 100644
--- a/docs/errors/authoring-and-language.md
+++ b/docs/errors/authoring-and-language.md
@@ -82,7 +82,6 @@ own page. Classes are grouped by subsystem.
## Pipe signatures
- [`PipeSignatureNotExecutableError`](pipe-signature-not-executable-error.md) — Pipe signature not executable
-- [`SignaturesNotAllowedError`](signatures-not-allowed-error.md) — Signatures not allowed
## Builder
diff --git a/docs/errors/signatures-not-allowed-error.md b/docs/errors/signatures-not-allowed-error.md
deleted file mode 100644
index 773043095..000000000
--- a/docs/errors/signatures-not-allowed-error.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: "Signatures not allowed"
-description: "Reference for the `SignaturesNotAllowedError` Pipelex error class."
----
-
-<!-- pipelex:generated -->
-
-# Signatures not allowed
-
-Raised in strict validation when one or more `PipeSignature` placeholders are reachable.
-
-| Field | Value |
-|---|---|
-| `error_type` | `SignaturesNotAllowedError` |
-| `title` | Signatures not allowed |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/signatures-not-allowed-error/` |
-| `error_domain` | `input` |
-| Defined in | `pipelex.pipe_signature.exceptions` |
-| Parent class | [`PipelexError`](pipelex-error.md) |
-
-[Back to Error Reference](index.md)
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index cab402d02..eb9908392 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -60,9 +60,31 @@ Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they att
| `model` | `str \| None` | Model handle, when the failure is attributable to one |
| `provider` | `str \| None` | Backend name, when attributable |
| `provider_metadata` | `ProviderErrorMetadata \| None` | SDK metadata — status code, request id, `retry_after` |
+| `validation_errors` | `list[ValidationErrorItem] \| None` | Structured per-error diagnostics on a bundle-validation failure (`ValidateBundleError` only) |
`PipelexError.to_error_report()` is the entry point. `to_dict()` serializes, dropping `None` fields; `from_dict()` is its strict inverse.
+### `validation_errors` — structured bundle-validation diagnostics
+
+A bundle-validation failure (`ValidateBundleError`) aggregates per-error data across stages and projects it onto `validation_errors` as a list of typed `ValidationErrorItem`s, so the structured error report an HTTP API surfaces carries machine-mappable diagnostics (not just a single `detail` string). Each item's `category` is one of the **closed** `ValidationErrorCategory` set:
+
+- `blueprint_validation` — interpreter / blueprint-validation faults. This also serves as the **last-resort residual**: a parse-level failure (a TOML-syntax error, an empty blueprint, a bundle-elaborator failure) is raised with only a message and no categorized data, so when *nothing else* produced an item the builder projects that message as one `blueprint_validation` item (no `error_type`, no `source` — the bundle could not become a blueprint at all).
+- `pipe_factory` — pipe-factory failures (e.g. a missing concept).
+- `pipe_validation` — pipe/concept validation (missing input variable, type mismatch).
+- `dry_run` — the **residual** dry-run failure (`DryRunError` / `PipeRunError`) with no structured locator. It is projected as one message-only item **only when no categorized error has data**. It is graph-level, so it typically carries **no `source`**.
+
+Together the two residuals make the **structured-info invariant total**: every invalid verdict carries a non-empty `validation_errors[]`, never a bare message. The builder tries the channels in order — categorized data, then the `dry_run` residual (the more specific channel), then the `blueprint_validation` fallback — and emits exactly one residual only when no earlier channel produced an item.
+
+Besides `category` and `message`, each item carries whatever identity fields its stage produced — `error_type`, `pipe_code`, `concept_code`, `domain_code`, `field_path`, `field_name`, `variable_names`, `missing_concept_code`, `declared_concepts`, and a `source` (the declaring file path, or the per-content source the in-memory load path was given) that hands a consumer the owning file for cross-file diagnostic placement.
+
+**Signatures are never an error.** An unimplemented `PipeSignature` reached during validation is a *runnability fact*, not a validation failure: the validator no longer raises on it. The assembled library's outstanding signatures ride the validation report's `pending_signatures`, and `is_runnable = not pending_signatures`. `allow_signatures` is a sweep-mechanics flag only (whether signature pipes are mock-run and listed in `validated_pipes`) — it does not change the verdict, so strict ≡ lenient in the report body. The "is this a failure?" decision moves to the consumer: the CLI exits non-zero on `not is_runnable` unless `--allow-signatures`; the HTTP caller reads `is_runnable`. (The **execute/run** path is different: running a stub still raises `PipeSignatureNotExecutableError`.)
+
+**Host-wiring guards are programmer errors, not content verdicts.** `validate_bundle` / `load_concepts_only`'s "provide exactly one of `mthds_contents` / `mthds_file_path`" and the `mthds_sources`-length-mismatch guards raise `PipelexUnexpectedError` (→ 500, redacted under STRICT), not `ValidateBundleError` — a caller wiring bug must not be reported as if the submitted bundle were invalid. The empty-`mthds_contents` guard stays caller-facing (it can legitimately reflect an end user submitting no bundles).
+
+`ValidationErrorItem` and the builder are the single source of truth across surfaces: `build_validation_error_items()` (`pipelex/pipeline/validation_errors.py`) is called by both `ValidateBundleError.to_error_report()` (the API path) and the agent CLI's `extract_validation_errors()` (the CLI JSON envelope), so the two structured shapes cannot drift. The item lives in `pipelex/base_exceptions.py` alongside `ErrorReport` — not next to the source error-data models — because `ErrorReport` references it as a typed field and the root exceptions module must not import the `pipelex.core` error modules.
+
+`validation_errors` is one of the fields kept under STRICT disclosure (it is in `_STRICT_KEPT_FIELDS`): the items describe the caller's *own* submitted bundle, not server internals, so redacting them would gut the hosted path's diagnostics.
+
```python
report = exc.to_error_report()
report.to_dict() # {"error_type": "LLMCompletionError", "message": "...", ...}
@@ -391,7 +413,8 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| File | Purpose |
|------|---------|
-| `pipelex/base_exceptions.py` | `PipelexError`, `ErrorReport`, `ErrorDomain`, `error_domain_to_http_status()` |
+| `pipelex/base_exceptions.py` | `PipelexError`, `ErrorReport`, `ErrorDomain`, `ValidationErrorItem`, `error_domain_to_http_status()` |
+| `pipelex/pipeline/validation_errors.py` | `build_validation_error_items()` — shared CLI/API structured bundle-validation builder |
| `pipelex/cogt/exceptions.py` | `CogtError`, `InferenceErrorCategory` |
| `pipelex/cogt/inference/error_classification.py` | Extract — `ProviderErrorMetadata`, `SDKErrorEnvelope`, `UserAction`, `UserActionKind`, per-provider `extract_*_metadata` functions, pure discriminators |
| `pipelex/cogt/inference/error_classify.py` | Classify — `classify_inference_error()`, `ClassificationResult` |
diff --git a/docs/under-the-hood/execution-graph-tracing.md b/docs/under-the-hood/execution-graph-tracing.md
index 4dadf6451..9d5b56549 100644
--- a/docs/under-the-hood/execution-graph-tracing.md
+++ b/docs/under-the-hood/execution-graph-tracing.md
@@ -375,7 +375,7 @@ from pipelex.graph.mermaidflow.mermaidflow_factory import MermaidflowFactory
mermaidflow = MermaidflowFactory.make_from_graphspec(
graph_spec,
- graph_config,
+ graph_config=graph_config,
direction=FlowchartDirection.TOP_DOWN,
include_subgraphs=True,
)
@@ -488,8 +488,8 @@ validate_graphspec(graph_spec)
| `GraphSpec.to_json()` | Serialize to JSON string |
| `GraphAnalysis.from_graphspec(g)` | Pre-compute analysis |
| `MermaidflowFactory.make_from_graphspec(...)` | Generate Mermaid |
-| `generate_reactflow_html(graphspec, config)` | Generate ReactFlow HTML |
-| `generate_graph_outputs(g, config, pipe_code)` | Generate all outputs |
+| `generate_reactflow_html(graphspec, config=...)` | Generate ReactFlow HTML |
+| `generate_graph_outputs(g, graph_config=..., pipe_code=...)` | Generate all outputs |
---
diff --git a/docs/under-the-hood/image-handling-in-llm-prompts.md b/docs/under-the-hood/image-handling-in-llm-prompts.md
index a6fed66f9..4e27c3a32 100644
--- a/docs/under-the-hood/image-handling-in-llm-prompts.md
+++ b/docs/under-the-hood/image-handling-in-llm-prompts.md
@@ -332,11 +332,11 @@ The `with_images` filter uses the `ImageRenderable` protocol to handle StuffArte
```python
# StuffArtefact implements ImageRenderable
if isinstance(value, ImageRenderable):
- return value.render_with_images(registry, text_format)
+ return value.render_with_images(registry, text_format=text_format)
# StuffArtefact.render_with_images() delegates to content
-def render_with_images(self, registry, text_format) -> str:
- return self._stuff.content.render_with_images(registry, text_format)
+def render_with_images(self, registry, *, text_format) -> str:
+ return self._stuff.content.render_with_images(registry, text_format=text_format)
```
!!! note "ImageRenderable Protocol"
diff --git a/docs/under-the-hood/stuffartefact-and-image-rendering.md b/docs/under-the-hood/stuffartefact-and-image-rendering.md
index fbfb77ec9..5aafea607 100644
--- a/docs/under-the-hood/stuffartefact-and-image-rendering.md
+++ b/docs/under-the-hood/stuffartefact-and-image-rendering.md
@@ -64,7 +64,7 @@ flowchart TB
subgraph FILTER["with_images Filter"]
direction TB
CHECK["isinstance(value, ImageRenderable)?"]
- CALL["value.render_with_images(registry, format)"]
+ CALL["value.render_with_images(registry, text_format=format)"]
CHECK --> CALL
end
@@ -134,7 +134,7 @@ StuffArtefact supports bracket notation and iteration:
| Method | Purpose |
|--------|---------|
| `artefact["field"]` | Bracket access (via `__getitem__`) |
-| `artefact.get("field", default)` | Safe access with default |
+| `artefact.get("field", default=...)` | Safe access with default |
| `"field" in artefact` | Membership test |
| `artefact.iter_keys()` | Iterate field names |
| `artefact.iter_items()` | Iterate (key, value) pairs |
@@ -156,6 +156,7 @@ class ImageRenderable(Protocol):
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat,
) -> str:
"""Render to string, registering images to the registry.
@@ -181,7 +182,7 @@ class ImageRenderable(Protocol):
Self-registers and returns a token:
```python
-def render_with_images(self, registry, text_format) -> str:
+def render_with_images(self, registry, *, text_format) -> str:
image_index = registry.register_image(self)
return f"[Image {image_index + 1}]"
```
@@ -191,11 +192,11 @@ def render_with_images(self, registry, text_format) -> str:
Iterates items, delegating to nested ImageRenderable objects:
```python
-def render_with_images(self, registry, text_format) -> str:
+def render_with_images(self, registry, *, text_format) -> str:
parts: list[str] = []
for item in self.items:
if isinstance(item, ImageRenderable):
- rendered = item.render_with_images(registry, text_format)
+ rendered = item.render_with_images(registry, text_format=text_format)
else:
rendered = str(item)
if rendered:
@@ -208,7 +209,7 @@ def render_with_images(self, registry, text_format) -> str:
Renders text first, then registers each image:
```python
-def render_with_images(self, registry, text_format) -> str:
+def render_with_images(self, registry, *, text_format) -> str:
parts: list[str] = []
if self.text:
parts.append(self.text.rendered_plain())
@@ -224,14 +225,14 @@ def render_with_images(self, registry, text_format) -> str:
Default implementation iterates Pydantic model fields:
```python
-def render_with_images(self, registry, text_format) -> str:
+def render_with_images(self, registry, *, text_format) -> str:
parts: list[str] = []
for field_name in type(self).model_fields:
field_value = getattr(self, field_name)
if field_value is None:
continue
if isinstance(field_value, ImageRenderable):
- rendered = field_value.render_with_images(registry, text_format)
+ rendered = field_value.render_with_images(registry, text_format=text_format)
else:
rendered = str(field_value)
if rendered:
@@ -287,7 +288,7 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
# 4. Protocol-based rendering
if isinstance(value, ImageRenderable):
- return value.render_with_images(registry, text_format)
+ return value.render_with_images(registry, text_format=text_format)
# 5. Handle plain sequences
if isinstance(value, (list, tuple)):
diff --git a/docs/under-the-hood/temporal-integration.md b/docs/under-the-hood/temporal-integration.md
index 9979016f5..1e451819a 100644
--- a/docs/under-the-hood/temporal-integration.md
+++ b/docs/under-the-hood/temporal-integration.md
@@ -223,7 +223,7 @@ Inside the activity everything is in-process and in-memory:
- The library is loaded once: the sweep half is `validate_bundle` itself (the same function the direct-mode route calls, so both backends share the categorized `ValidateBundleError` contract), which leaves the library loaded; the graph dry-run (`dry_run_pipe_in_process`) runs against that same library; teardown happens once in the activity's `finally`.
- ContextVar scopes pin the run in-process: `scoped_pipe_router` (nested controller sub-pipes resolve a local router, not the `TemporalPipeRouter`), `scoped_content_generator` (inference leaves resolve an inline dry generator, not `ContentGeneratorInWorkflow`), and `scoped_event_log` (the graph traces into a shared `InMemoryEventLog` — no NDJSON file, no DynamoDB round-trip; the `GraphSpec` rides back on the activity result). No usage/cost events are emitted.
- The graph is best-effort: an expected dry-run failure (the run-failure wrappers, or a mock-input mint failure) returns `graph_spec=None` with validation still successful; any other error propagates and fails the activity.
-- Validation failures cross the boundary as structured `ErrorReport`s via the activity error boundary — a strict-mode `SignaturesNotAllowedError` keeps its offending-pipe and signature refs, so the API can render a meaningful 422.
+- Validation failures cross the boundary as structured `ErrorReport`s via the activity error boundary — a `ValidateBundleError` keeps its categorized per-error data (blueprint/factory/pipe/dry-run), so the API can render meaningful diagnostics. Signatures are not a failure: an unsatisfied `PipeSignature` is a runnability fact carried on the report's `pending_signatures` / `is_runnable`, not an error that crosses the boundary.
Submitters call `dispatch_dry_validate` (`pipelex/temporal/tprl_pipe/dry_validate_dispatch.py`) for the whole round-trip. The wrapper workflow exists so the dispatch works on the current `temporalio` SDK; replacing it with a true standalone activity is a deferred optimization.
diff --git a/mkdocs.yml b/mkdocs.yml
index 46b6e589c..382b4c0c3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -317,6 +317,7 @@ plugins:
Project:
- contributing.md: "Contributing"
- contribute/configuration-defaults-and-overrides.md: "Configuration Internals"
+ - contribute/keyword-only-arguments.md: "Keyword-Only Arguments"
- changelog.md: "Changelog"
markdown_extensions:
@@ -563,6 +564,7 @@ nav:
- Project:
- Contributing: contributing.md
- Configuration Internals: contribute/configuration-defaults-and-overrides.md
+ - Keyword-Only Arguments: contribute/keyword-only-arguments.md
- Code of Conduct: CODE_OF_CONDUCT.md
- License: license.md
- Changelog: changelog.md
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index 212e13036..3e7a3f73b 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -1,7 +1,7 @@
from collections.abc import Iterator
from typing import Any, ClassVar
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction
from pipelex.tools.misc.string_utils import pascal_case_to_kebab, pascal_case_to_sentence
@@ -51,7 +51,25 @@ INTERNAL_ERROR_PLACEHOLDER = "An internal error occurred."
# Single source of truth for both STRICT branches. Adding a new top-level
# ``ErrorReport`` field is one decision: include it here to surface it on both
# branches, or leave it out to keep both branches consistently silent.
-_STRICT_KEPT_FIELDS: frozenset[str] = frozenset({"error_type", "title", "type_uri", "error_domain", "error_category", "retryable"})
+#
+# ``validation_errors`` IS surfaced: it describes the caller's own submitted
+# bundle (per-error diagnostics on a ``ValidateBundleError``), not server
+# internals, so redacting it would gut the hosted path's diagnostics. It only
+# ever rides a ``ValidateBundleError`` report (a caller-facing INPUT error), but
+# it is kept here — not by the caller-facing branch's bespoke logic — so the
+# decision lives in this one allowlist.
+#
+# Caveat — ``validation_errors[].source``: on the *in-memory* validate path
+# ``source`` is the caller-supplied logical source (e.g. ``api://bundle-0.mthds``),
+# which is the hosted/STRICT case and safe to surface. On the *on-disk* path it
+# is a real server filesystem path, and STRICT does NOT redact it (consistent
+# with ``DisclosureMode`` being a classification-projection, not a path-leak
+# shield — see its docstring). A hosted surface that validates from disk should
+# therefore use the in-memory path with logical sources rather than rely on STRICT
+# to scrub the path.
+_STRICT_KEPT_FIELDS: frozenset[str] = frozenset(
+ {"error_type", "title", "type_uri", "error_domain", "error_category", "retryable", "validation_errors"}
+)
# The curated subset of ``ProviderErrorMetadata`` that survives STRICT
# projection. ``status_code`` and ``retry_after_seconds`` are actionable client
@@ -230,6 +248,63 @@ def error_domain_is_input(error_domain: ErrorDomain | str | None) -> bool:
return False
+class ValidationErrorCategory(StrEnum):
+ """Which validation stage produced a :class:`ValidationErrorItem`.
+
+ Mirrors the categorized error-data lists aggregated by ``ValidateBundleError``:
+ blueprint validation (from the interpreter), pipe-factory failures (e.g. a
+ missing concept), pipe/concept validation (e.g. a missing input variable
+ or a type mismatch), and the ``dry_run`` residual — a dry-run failure with no
+ structured locator (graph-level), carried as a single message-only item so an
+ invalid verdict always surfaces a non-empty ``validation_errors[]`` (the
+ structured-info invariant) instead of a bare ``detail``.
+ """
+
+ BLUEPRINT_VALIDATION = "blueprint_validation"
+ PIPE_FACTORY = "pipe_factory"
+ PIPE_VALIDATION = "pipe_validation"
+ DRY_RUN = "dry_run"
+
+
+class ValidationErrorItem(BaseModel):
+ """One structured bundle-validation error, projected onto the error wire.
+
+ The typed wire item carried by :attr:`ErrorReport.validation_errors`. Its
+ fields are the *union* across the three ``ValidateBundleError`` error-data
+ models (``PipelexBundleBlueprintValidationErrorData``, ``PipeFactoryErrorData``,
+ ``PipesAndConceptValidationErrorData``); a given item only populates the
+ subset its :attr:`category` produces, and the unset fields drop out of the
+ ``exclude_none`` wire projection.
+
+ Built exclusively by ``pipelex.pipeline.validation_errors.build_validation_error_items``,
+ which both the agent CLI (``extract_validation_errors``) and the API path
+ (``ValidateBundleError.to_error_report``) call — so the CLI's structured
+ output and the API's 422 ``validation_errors`` can never drift.
+
+ ``source`` is the declaring file path (CLI) or the per-content source the API
+ threads onto the in-memory load path — it hands a consumer the owning file
+ for cross-file diagnostics. Lives here, alongside :class:`ErrorReport`,
+ rather than next to the source error-data models because ``ErrorReport``
+ references it as a typed field and ``base_exceptions`` must not import the
+ ``pipelex.core`` error modules (which import back into this module).
+ """
+
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ category: ValidationErrorCategory = Field(strict=False)
+ message: str
+ error_type: str | None = None
+ pipe_code: str | None = None
+ concept_code: str | None = None
+ domain_code: str | None = None
+ source: str | None = None
+ field_path: str | None = None
+ field_name: str | None = None
+ variable_names: list[str] | None = None
+ missing_concept_code: str | None = None
+ declared_concepts: list[str] | None = None
+
+
class ErrorReport(BaseModel):
"""Structured error report — single source of truth for all error serialization.
@@ -264,6 +339,13 @@ class ErrorReport(BaseModel):
# :class:`DisclosureMode`). Defaults to False so an unflagged report — and
# any payload that predates the field — is redacted, never leaked.
caller_facing_message: bool = False
+ # Structured per-error diagnostics on a bundle-validation failure. Populated
+ # only by ``ValidateBundleError.to_error_report`` (None on every other
+ # report), so the 422 problem document carries the same machine-mappable
+ # items the agent CLI emits. Surfaced under STRICT disclosure (see
+ # ``_STRICT_KEPT_FIELDS``): these describe the caller's own submitted bundle,
+ # not server internals.
+ validation_errors: list[ValidationErrorItem] | None = None
def to_dict(self, disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE) -> dict[str, Any]:
"""Return a dict with only non-None fields, projected through ``disclosure_mode``.
diff --git a/pipelex/builder/bundle_header_spec.py b/pipelex/builder/bundle_header_spec.py
index 6e07005fe..cb7498b00 100644
--- a/pipelex/builder/bundle_header_spec.py
+++ b/pipelex/builder/bundle_header_spec.py
@@ -18,7 +18,7 @@ class BundleHeaderSpec(StructuredContent):
main_pipe: str = Field(description="The main pipe of the domain.", examples=[MOCK_MAIN_PIPE_CODE])
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
bundle_group = Group()
if title:
bundle_group.renderables.append(Text(title, style="bold"))
diff --git a/pipelex/builder/bundle_spec.py b/pipelex/builder/bundle_spec.py
index 6cf218181..d1b412e05 100644
--- a/pipelex/builder/bundle_spec.py
+++ b/pipelex/builder/bundle_spec.py
@@ -121,7 +121,7 @@ class PipelexBundleSpec(StructuredContent):
raise PipelexBundleSpecBlueprintError(msg) from exc
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
bundle_group = Group()
# Bundle header info
diff --git a/pipelex/builder/concept/concept_spec.py b/pipelex/builder/concept/concept_spec.py
index bfe6419af..7dfef1132 100644
--- a/pipelex/builder/concept/concept_spec.py
+++ b/pipelex/builder/concept/concept_spec.py
@@ -175,19 +175,19 @@ class ConceptStructureSpec(StructuredContent):
match self.type:
case ConceptStructureSpecFieldType.TEXT:
if not isinstance(self.default_value, str):
- self._raise_type_mismatch_error("str", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("str", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.INTEGER:
if not isinstance(self.default_value, int):
- self._raise_type_mismatch_error("int", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("int", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.BOOLEAN:
if not isinstance(self.default_value, bool):
- self._raise_type_mismatch_error("bool", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("bool", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.NUMBER:
if not isinstance(self.default_value, (int, float)):
- self._raise_type_mismatch_error("number (int or float)", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("number (int or float)", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.DATE:
if not isinstance(self.default_value, datetime):
- self._raise_type_mismatch_error("date", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("date", actual_type_name=type(self.default_value).__name__)
case ConceptStructureSpecFieldType.CONCEPT:
# CONCEPT type cannot have default values, this is already validated in validate_structure_blueprint
pass
@@ -195,7 +195,7 @@ class ConceptStructureSpec(StructuredContent):
# LIST type cannot have default values, this is already validated in validate_structure_blueprint
pass
- def _raise_type_mismatch_error(self, expected_type_name: str, actual_type_name: str) -> None:
+ def _raise_type_mismatch_error(self, expected_type_name: str, *, actual_type_name: str) -> None:
msg = f"default_value type mismatch: expected {expected_type_name} for type '{self.type}', but got {actual_type_name}"
raise ValueError(msg)
@@ -355,7 +355,7 @@ class ConceptSpec(StructuredContent):
return field_spec.type
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
concept_group = Group()
if title:
concept_group.renderables.append(Text(title, style="bold"))
diff --git a/pipelex/builder/operations/inputs_ops.py b/pipelex/builder/operations/inputs_ops.py
index cfa65b540..ed729711e 100644
--- a/pipelex/builder/operations/inputs_ops.py
+++ b/pipelex/builder/operations/inputs_ops.py
@@ -22,6 +22,7 @@ if TYPE_CHECKING:
async def build_inputs_for_pipe(
pipe_code: str | None = None,
+ *,
mthds_contents: list[str] | None = None,
bundle_path: Path | None = None,
library_dirs: list[Path] | None = None,
diff --git a/pipelex/builder/operations/models_ops.py b/pipelex/builder/operations/models_ops.py
index de5b1d272..bb60d89f1 100644
--- a/pipelex/builder/operations/models_ops.py
+++ b/pipelex/builder/operations/models_ops.py
@@ -25,7 +25,7 @@ CATEGORY_TO_MODEL_TYPE: dict[ModelCategory, ModelType] = {
}
-def _should_include(category: ModelCategory, categories: list[ModelCategory] | None) -> bool:
+def _should_include(category: ModelCategory, *, categories: list[ModelCategory] | None) -> bool:
"""Check whether a category should be included given the filter list.
Returns True when no filter is set (None or empty) or when the category is in the filter list.
@@ -34,6 +34,7 @@ def _should_include(category: ModelCategory, categories: list[ModelCategory] | N
def _resolve_preset_backend(
+ *,
model_deck: ModelDeck,
model_handle: str,
model_type: ModelType,
@@ -44,6 +45,7 @@ def _resolve_preset_backend(
def _filter_presets_by_backend(
presets_list: list[dict[str, Any]],
+ *,
presets_dict: dict[str, Any],
model_deck: ModelDeck,
model_type: ModelType,
@@ -56,7 +58,7 @@ def _filter_presets_by_backend(
setting = presets_dict.get(preset_name)
if setting is None:
continue
- spec = _resolve_preset_backend(model_deck, setting.model, model_type)
+ spec = _resolve_preset_backend(model_deck=model_deck, model_handle=setting.model, model_type=model_type)
if spec is not None and spec.backend_name == backend:
filtered.append(preset_entry)
return filtered
@@ -64,6 +66,7 @@ def _filter_presets_by_backend(
def _filter_aliases_by_backend(
aliases: dict[str, str],
+ *,
model_deck: ModelDeck,
model_type: ModelType,
backend: str,
@@ -79,6 +82,7 @@ def _filter_aliases_by_backend(
def _filter_waterfalls_by_backend(
waterfalls: dict[str, list[str]],
+ *,
model_deck: ModelDeck,
model_type: ModelType,
backend: str,
@@ -95,6 +99,7 @@ def _filter_waterfalls_by_backend(
def _build_presets_for_category(
+ *,
model_deck: ModelDeck,
category: ModelCategory,
backend: str | None,
@@ -120,12 +125,15 @@ def _build_presets_for_category(
presets_list.append(entry)
if backend is not None:
- presets_list = _filter_presets_by_backend(presets_list, presets_dict, model_deck, model_type, backend)
+ presets_list = _filter_presets_by_backend(
+ presets_list, presets_dict=presets_dict, model_deck=model_deck, model_type=model_type, backend=backend
+ )
return presets_list
def _build_aliases_for_category(
+ *,
model_deck: ModelDeck,
category: ModelCategory,
backend: str | None,
@@ -144,12 +152,13 @@ def _build_aliases_for_category(
aliases = model_deck.search_aliases
if backend is not None:
- aliases = _filter_aliases_by_backend(aliases, model_deck, model_type, backend)
+ aliases = _filter_aliases_by_backend(aliases, model_deck=model_deck, model_type=model_type, backend=backend)
return aliases
def _build_waterfalls_for_category(
+ *,
model_deck: ModelDeck,
category: ModelCategory,
backend: str | None,
@@ -168,13 +177,14 @@ def _build_waterfalls_for_category(
waterfalls = model_deck.search_waterfalls
if backend is not None:
- waterfalls = _filter_waterfalls_by_backend(waterfalls, model_deck, model_type, backend)
+ waterfalls = _filter_waterfalls_by_backend(waterfalls, model_deck=model_deck, model_type=model_type, backend=backend)
return waterfalls
def list_models(
categories: list[ModelCategory] | None = None,
+ *,
backend: str | None = None,
) -> dict[str, Any]:
"""List available model presets, aliases, and waterfalls.
@@ -192,25 +202,25 @@ def list_models(
aliases: dict[str, dict[str, str]] = {}
waterfalls: dict[str, dict[str, list[str]]] = {}
- if _should_include(ModelCategory.LLM, categories):
- presets["llm"] = _build_presets_for_category(model_deck, ModelCategory.LLM, backend)
- aliases["llm"] = _build_aliases_for_category(model_deck, ModelCategory.LLM, backend)
- waterfalls["llm"] = _build_waterfalls_for_category(model_deck, ModelCategory.LLM, backend)
-
- if _should_include(ModelCategory.IMG_GEN, categories):
- presets["img_gen"] = _build_presets_for_category(model_deck, ModelCategory.IMG_GEN, backend)
- aliases["img_gen"] = _build_aliases_for_category(model_deck, ModelCategory.IMG_GEN, backend)
- waterfalls["img_gen"] = _build_waterfalls_for_category(model_deck, ModelCategory.IMG_GEN, backend)
-
- if _should_include(ModelCategory.EXTRACT, categories):
- presets["extract"] = _build_presets_for_category(model_deck, ModelCategory.EXTRACT, backend)
- aliases["extract"] = _build_aliases_for_category(model_deck, ModelCategory.EXTRACT, backend)
- waterfalls["extract"] = _build_waterfalls_for_category(model_deck, ModelCategory.EXTRACT, backend)
-
- if _should_include(ModelCategory.SEARCH, categories):
- presets["search"] = _build_presets_for_category(model_deck, ModelCategory.SEARCH, backend)
- aliases["search"] = _build_aliases_for_category(model_deck, ModelCategory.SEARCH, backend)
- waterfalls["search"] = _build_waterfalls_for_category(model_deck, ModelCategory.SEARCH, backend)
+ if _should_include(ModelCategory.LLM, categories=categories):
+ presets["llm"] = _build_presets_for_category(model_deck=model_deck, category=ModelCategory.LLM, backend=backend)
+ aliases["llm"] = _build_aliases_for_category(model_deck=model_deck, category=ModelCategory.LLM, backend=backend)
+ waterfalls["llm"] = _build_waterfalls_for_category(model_deck=model_deck, category=ModelCategory.LLM, backend=backend)
+
+ if _should_include(ModelCategory.IMG_GEN, categories=categories):
+ presets["img_gen"] = _build_presets_for_category(model_deck=model_deck, category=ModelCategory.IMG_GEN, backend=backend)
+ aliases["img_gen"] = _build_aliases_for_category(model_deck=model_deck, category=ModelCategory.IMG_GEN, backend=backend)
+ waterfalls["img_gen"] = _build_waterfalls_for_category(model_deck=model_deck, category=ModelCategory.IMG_GEN, backend=backend)
+
+ if _should_include(ModelCategory.EXTRACT, categories=categories):
+ presets["extract"] = _build_presets_for_category(model_deck=model_deck, category=ModelCategory.EXTRACT, backend=backend)
+ aliases["extract"] = _build_aliases_for_category(model_deck=model_deck, category=ModelCategory.EXTRACT, backend=backend)
+ waterfalls["extract"] = _build_waterfalls_for_category(model_deck=model_deck, category=ModelCategory.EXTRACT, backend=backend)
+
+ if _should_include(ModelCategory.SEARCH, categories=categories):
+ presets["search"] = _build_presets_for_category(model_deck=model_deck, category=ModelCategory.SEARCH, backend=backend)
+ aliases["search"] = _build_aliases_for_category(model_deck=model_deck, category=ModelCategory.SEARCH, backend=backend)
+ waterfalls["search"] = _build_waterfalls_for_category(model_deck=model_deck, category=ModelCategory.SEARCH, backend=backend)
return {
"presets": presets,
diff --git a/pipelex/builder/operations/output_ops.py b/pipelex/builder/operations/output_ops.py
index 56434ba4b..a9ca8066a 100644
--- a/pipelex/builder/operations/output_ops.py
+++ b/pipelex/builder/operations/output_ops.py
@@ -12,6 +12,7 @@ from pipelex.pipeline.validate_bundle import validate_bundle
async def build_output_for_pipe(
+ *,
mthds_contents: list[str],
pipe_code: str,
output_format: ConceptRepresentationFormat = ConceptRepresentationFormat.SCHEMA,
diff --git a/pipelex/builder/operations/pipe_ops.py b/pipelex/builder/operations/pipe_ops.py
index fa3c51cda..f87801047 100644
--- a/pipelex/builder/operations/pipe_ops.py
+++ b/pipelex/builder/operations/pipe_ops.py
@@ -44,7 +44,7 @@ def _normalize_sub_pipe_dict(data: dict[str, Any]) -> None:
data.pop("inputs", None)
-def _normalize_sub_pipe_list(raw_value: Any, field_name: str) -> list[dict[str, Any]]:
+def _normalize_sub_pipe_list(raw_value: Any, *, field_name: str) -> list[dict[str, Any]]:
"""Validate and normalize a raw ``steps`` / ``branches`` value into a list of step dicts.
Each entry is copied (to avoid mutating the caller's nested dicts) and passed
@@ -86,12 +86,12 @@ def _normalize_prompt_aliases(data: dict[str, Any]) -> None:
data.pop(alias)
-def parse_pipe_spec(pipe_type: str, spec_data: Any) -> PipeSpec:
+def parse_pipe_spec(spec_data: Any, *, pipe_type: str) -> PipeSpec:
"""Parse and validate a PipeSpec from JSON-like data.
Args:
- pipe_type: The type of pipe (e.g., "PipeLLM", "PipeSequence").
spec_data: Raw data for the pipe spec (untrusted JSON-like input).
+ pipe_type: The type of pipe (e.g., "PipeLLM", "PipeSequence").
Returns:
Validated PipeSpec instance of the correct type.
@@ -188,7 +188,7 @@ def parse_pipe_spec(pipe_type: str, spec_data: Any) -> PipeSpec:
return spec_class.model_validate(spec_data)
-def add_type_specific_fields(pipe_spec: PipeSpec, pipe_table: Table) -> None:
+def add_type_specific_fields(pipe_spec: PipeSpec, *, pipe_table: Table) -> None:
"""Add type-specific fields to the pipe TOML table.
Args:
@@ -329,7 +329,7 @@ def pipe_spec_to_toml(pipe_spec: PipeSpec) -> str:
pipe_item_table.add("output", pipe_spec.output)
# Add type-specific fields
- add_type_specific_fields(pipe_spec, pipe_item_table)
+ add_type_specific_fields(pipe_spec, pipe_table=pipe_item_table)
# Build the nested structure: [pipe.pipe_code]
pipe_section = tomlkit.table()
diff --git a/pipelex/builder/operations/runner_code_ops.py b/pipelex/builder/operations/runner_code_ops.py
index 0632810d9..1af0c0e2e 100644
--- a/pipelex/builder/operations/runner_code_ops.py
+++ b/pipelex/builder/operations/runner_code_ops.py
@@ -15,6 +15,7 @@ from pipelex.pipeline.bundle_validator import BundleValidator
async def build_runner_code_for_pipe(
+ *,
mthds_contents: list[str],
pipe_code: str,
) -> str:
diff --git a/pipelex/builder/operations/validate_ops.py b/pipelex/builder/operations/validate_ops.py
index 3c33ba7d3..9181971a3 100644
--- a/pipelex/builder/operations/validate_ops.py
+++ b/pipelex/builder/operations/validate_ops.py
@@ -45,6 +45,7 @@ async def validate_all(
# down before returning, so the set could not be computed post-hoc without reshaping a shared method.
return {
"success": True,
+ "is_valid": True,
"validated_pipes": build_validated_pipes(dry_run_results),
"total_pipes": len(dry_run_results),
}
@@ -52,6 +53,7 @@ async def validate_all(
async def validate_bundle_file(
bundle_path: Path,
+ *,
library_dirs: list[Path] | None = None,
) -> dict[str, Any]:
"""Validate a bundle file.
@@ -70,6 +72,7 @@ async def validate_bundle_file(
return {
"success": True,
+ "is_valid": True,
"bundle_path": str(bundle_path),
"validated_pipes": build_validated_pipes(result.dry_run_result),
"total_pipes": len(result.dry_run_result),
@@ -97,6 +100,7 @@ async def validate_bundle_content(
return {
"success": True,
+ "is_valid": True,
"mthds_contents": mthds_contents,
"pipelex_bundle_blueprint": [b.model_dump(mode="json") for b in blueprints],
"validated_pipes": build_validated_pipes(validate_bundle_result.dry_run_result),
@@ -108,6 +112,7 @@ async def validate_bundle_content(
async def validate_pipe(
pipe_code: str,
+ *,
library_dirs: list[Path] | None = None,
) -> dict[str, Any]:
"""Validate a single pipe.
@@ -139,6 +144,7 @@ async def validate_pipe(
return {
"success": True,
+ "is_valid": True,
"validated_pipes": build_validated_pipes(dry_run_results),
"total_pipes": len(dry_run_results),
}
@@ -156,6 +162,7 @@ async def validate_pipe(
async def validate_pipe_in_bundle(
+ *,
bundle_path: Path,
pipe_code: str,
library_dirs: list[Path] | None = None,
@@ -183,6 +190,7 @@ async def validate_pipe_in_bundle(
return {
"success": True,
+ "is_valid": True,
"bundle_path": str(bundle_path),
"validated_pipes": build_validated_pipes(result.dry_run_result),
"total_pipes": len(result.dry_run_result),
diff --git a/pipelex/builder/pipe/pipe_batch_spec.py b/pipelex/builder/pipe/pipe_batch_spec.py
index e853818d6..9efc050df 100644
--- a/pipelex/builder/pipe/pipe_batch_spec.py
+++ b/pipelex/builder/pipe/pipe_batch_spec.py
@@ -71,7 +71,7 @@ class PipeBatchSpec(PipeSpec):
return self
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_compose_spec.py b/pipelex/builder/pipe/pipe_compose_spec.py
index fe7e39354..22c2f206f 100644
--- a/pipelex/builder/pipe/pipe_compose_spec.py
+++ b/pipelex/builder/pipe/pipe_compose_spec.py
@@ -170,7 +170,7 @@ class PipeComposeSpec(PipeSpec):
return self
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_condition_spec.py b/pipelex/builder/pipe/pipe_condition_spec.py
index 87afeb99e..ea682a2ac 100644
--- a/pipelex/builder/pipe/pipe_condition_spec.py
+++ b/pipelex/builder/pipe/pipe_condition_spec.py
@@ -32,7 +32,7 @@ class PipeConditionSpec(PipeSpec):
default_outcome: str | SpecialOutcome = Field(description="The fallback outcome if the expression result does not match any key in outcome map.")
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_extract_spec.py b/pipelex/builder/pipe/pipe_extract_spec.py
index 93071d19e..1f9752820 100644
--- a/pipelex/builder/pipe/pipe_extract_spec.py
+++ b/pipelex/builder/pipe/pipe_extract_spec.py
@@ -69,7 +69,7 @@ class PipeExtractSpec(PipeSpec):
return inputs_value
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_func_spec.py b/pipelex/builder/pipe/pipe_func_spec.py
index efa474bca..dfddab4aa 100644
--- a/pipelex/builder/pipe/pipe_func_spec.py
+++ b/pipelex/builder/pipe/pipe_func_spec.py
@@ -19,7 +19,7 @@ class PipeFuncSpec(PipeSpec):
function_name: str = Field(description="The name of the function to call.")
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_img_gen_spec.py b/pipelex/builder/pipe/pipe_img_gen_spec.py
index 1d406ed77..7c521bb68 100644
--- a/pipelex/builder/pipe/pipe_img_gen_spec.py
+++ b/pipelex/builder/pipe/pipe_img_gen_spec.py
@@ -41,7 +41,7 @@ class PipeImgGenSpec(PipeSpec):
return value
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_llm_spec.py b/pipelex/builder/pipe/pipe_llm_spec.py
index 1c4effca9..31f86e16e 100644
--- a/pipelex/builder/pipe/pipe_llm_spec.py
+++ b/pipelex/builder/pipe/pipe_llm_spec.py
@@ -74,7 +74,7 @@ So, don't have to write a bullet-list of all the attributes definitions yourself
return value
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_parallel_spec.py b/pipelex/builder/pipe/pipe_parallel_spec.py
index 6890bc16d..90084c46f 100644
--- a/pipelex/builder/pipe/pipe_parallel_spec.py
+++ b/pipelex/builder/pipe/pipe_parallel_spec.py
@@ -58,7 +58,7 @@ class PipeParallelSpec(PipeSpec):
return self
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_search_spec.py b/pipelex/builder/pipe/pipe_search_spec.py
index 394208d6a..6ce5aa49b 100644
--- a/pipelex/builder/pipe/pipe_search_spec.py
+++ b/pipelex/builder/pipe/pipe_search_spec.py
@@ -79,7 +79,7 @@ class PipeSearchSpec(PipeSpec):
return date_value
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_sequence_spec.py b/pipelex/builder/pipe/pipe_sequence_spec.py
index 7bf19d980..88369efea 100644
--- a/pipelex/builder/pipe/pipe_sequence_spec.py
+++ b/pipelex/builder/pipe/pipe_sequence_spec.py
@@ -26,7 +26,7 @@ class PipeSequenceSpec(PipeSpec):
)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Get base pipe information from parent
base_group = super().rendered_pretty(title=title, depth=depth)
diff --git a/pipelex/builder/pipe/pipe_signature_spec.py b/pipelex/builder/pipe/pipe_signature_spec.py
index 227a7a317..54e742aa0 100644
--- a/pipelex/builder/pipe/pipe_signature_spec.py
+++ b/pipelex/builder/pipe/pipe_signature_spec.py
@@ -65,7 +65,7 @@ class PipeSignatureSpec(PipeSpec):
)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
pipe_group = Group()
if title:
pipe_group.renderables.append(Text(title, style="bold"))
diff --git a/pipelex/builder/pipe/pipe_spec.py b/pipelex/builder/pipe/pipe_spec.py
index 7b51bcc10..b11768d44 100644
--- a/pipelex/builder/pipe/pipe_spec.py
+++ b/pipelex/builder/pipe/pipe_spec.py
@@ -161,7 +161,7 @@ class PipeSpec(StructuredContent):
)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
pipe_group = Group()
if title:
pipe_group.renderables.append(Text(title, style="bold"))
diff --git a/pipelex/builder/pipe/pipe_structure_spec.py b/pipelex/builder/pipe/pipe_structure_spec.py
index 5236999aa..1e852b12a 100644
--- a/pipelex/builder/pipe/pipe_structure_spec.py
+++ b/pipelex/builder/pipe/pipe_structure_spec.py
@@ -40,7 +40,7 @@ class PipeStructureSpec(PipeSpec):
return value
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
base_group = super().rendered_pretty(title=title, depth=depth)
structure_group = Group()
diff --git a/pipelex/builder/runner_code.py b/pipelex/builder/runner_code.py
index 4309fbc30..1fbdcfa04 100644
--- a/pipelex/builder/runner_code.py
+++ b/pipelex/builder/runner_code.py
@@ -62,7 +62,7 @@ def _is_multiple(multiplicity: VariableMultiplicity | None) -> bool:
return multiplicity > 1
-def _format_representation_as_python(representation: dict[str, Any], is_multiple: bool = False) -> str:
+def _format_representation_as_python(representation: dict[str, Any], *, is_multiple: bool = False) -> str:
"""Format a representation dict as Python code.
Args:
@@ -140,7 +140,7 @@ def _collect_imports_for_inputs(inputs: InputStuffSpecs) -> tuple[set[str], dict
# Get imports from the representation generator
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- generator.generate_representation(concept.concept_ref, structure_class)
+ generator.generate_representation(concept.concept_ref, structure_class=structure_class)
for class_name in generator.imports_needed:
if NativeConceptCode.is_native_structure_class(class_name):
@@ -155,7 +155,7 @@ def _collect_imports_for_inputs(inputs: InputStuffSpecs) -> tuple[set[str], dict
return native_classes, custom_classes
-def generate_runner_code(pipe: PipeAbstract, output_multiplicity: bool = False, library_dir: str | None = None) -> str:
+def generate_runner_code(pipe: PipeAbstract, *, output_multiplicity: bool = False, library_dir: str | None = None) -> str:
"""Generate the complete Python runner code for a pipe.
This generates a runnable Python script with:
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index ff924c6ff..8039a2183 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -16,7 +16,7 @@ Only the error format is backed by a module-level `ContextVar` in `agent_output.
Markdown structure per command:
- `run`: `# Pipeline run complete`, a `## Result` section (the rendered `main_stuff` markdown with `--with-memory`, otherwise the concept JSON in a fenced block), and output / graph file paths. Cost is machine-first: on the local runner, when costs are on (`--costs`, the default) and the run did reportable work (any tokens or any cost), a best-effort `cost_report` object (`{total_cost, by_model: [...]}`, real USD) rides the JSON `--with-memory` envelope — there is **no** Rich cost table on stderr (unlike the human `pipelex run` CLI). The markdown renderer ignores the `cost_report` key, so it is JSON-only. A free/zero-price model still reports its token usage (with `total_cost` 0). The `cost_report` is **absent** when the run did no reportable work (dry runs), when `--no-costs` is passed, on the API-runner path (which does not assemble local usage), or if cost-summary aggregation fails (caught and skipped so it never fails an otherwise-successful run) — so consumers must treat it as optional.
-- `validate`: `# Validation passed`, the bundle path when relevant, and a list of validated pipes with their status. Every entry in `validated_pipes` (markdown and JSON) identifies its pipe by the namespaced `pipe_ref` (`domain.code`) — the same unambiguous identity across `validate all`, `validate bundle`, and `validate pipe`, so the same pipe is never reported under two identifiers. `validate bundle` additionally carries `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), namespaced by `pipe_ref` — a non-blocking nudge on a successful lenient (`--allow-signatures`) run, rendered as a "Pending signatures" section in markdown. It also carries a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown adds an explicit plain-English runnability verdict on the bundle surfaces: a complete bundle states it is runnable, while one with pending signatures states it is NOT yet runnable immediately above the verbatim "Pending signatures" heading. Both `is_runnable` and the verdict line are scoped to the bundle surfaces (which compute `pending_signatures`); `validate all` / `validate pipe` omit the key and emit no verdict.
+- `validate`: `# Validation passed`, the bundle path when relevant, and a list of validated pipes with their status. Every entry in `validated_pipes` (markdown and JSON) identifies its pipe by the namespaced `pipe_ref` (`domain.code`) — the same unambiguous identity across `validate all`, `validate bundle`, and `validate pipe`, so the same pipe is never reported under two identifiers. `validate bundle`, `validate method`, and `validate all` carry `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), namespaced by `pipe_ref` — rendered as a "Pending signatures" section in markdown. They also carry a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown adds an explicit plain-English runnability verdict on those surfaces: a complete bundle/library states it is runnable, while one with pending signatures states it is NOT yet runnable immediately above the verbatim "Pending signatures" heading. These whole-bundle/whole-library surfaces are **strict by default**: they exit non-zero on `not is_runnable` unless `--allow-signatures` is passed (which both tolerates the placeholders for the exit code and mock-runs the signature pipes in the sweep). Single-pipe surfaces make no library-wide runnability claim and never gate the exit code on it: bare `validate pipe <code>` omits the key and emits no verdict, while `validate bundle`/`validate method` with `--pipe` still surface the library-wide `pending_signatures` for information but do not gate on it (the requested slice can be fully implemented even when unrelated placeholders remain elsewhere).
- `init`: `# Pipelex initialized` with target directory, enabled backends, and routing profile.
- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.
diff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.py
index cccef8254..bd8d7b0a5 100644
--- a/pipelex/cli/agent_cli/_agent_cli.py
+++ b/pipelex/cli/agent_cli/_agent_cli.py
@@ -56,7 +56,7 @@ class PipelexAgentCLI(TyperGroup):
valid_commands = super().list_commands(ctx)
agent_error(
f"Unknown command: {cmd_name}",
- "UnknownCommandError",
+ error_type="UnknownCommandError",
valid_commands=valid_commands,
)
return cmd
@@ -126,7 +126,7 @@ def app_callback(
valid_values = ", ".join(runner_type.value for runner_type in RunnerType)
agent_error(
f"Invalid runner '{runner}'. Valid values: {valid_values}",
- "ArgumentError",
+ error_type="ArgumentError",
)
diff --git a/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py b/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py
index ec9869f7f..a1fc43811 100644
--- a/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py
+++ b/pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py
@@ -35,6 +35,6 @@ def agent_accept_gateway_terms_cmd() -> None:
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
agent_error(
f"Failed to accept gateway terms: {exc}",
- type(exc).__name__,
+ error_type=type(exc).__name__,
cause=exc,
)
diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
index 632f836d6..1aadf7efb 100644
--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py
+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
@@ -162,6 +162,7 @@ def apply_agent_cli_output_discipline() -> None:
def make_pipelex_for_agent_cli(
library_dirs: list[str] | list[Path] | None = None,
+ *,
needs_inference: bool = True,
needs_model_specs: bool | None = None,
) -> Pipelex:
@@ -236,21 +237,21 @@ def make_pipelex_for_agent_cli(
)
raise typer.Exit(0) from None
except TelemetryConfigValidationError as exc:
- agent_error(exc.message, "TelemetryConfigValidationError", cause=exc)
+ agent_error(exc.message, error_type="TelemetryConfigValidationError", cause=exc)
except GatewayTermsNotAcceptedError as exc:
- agent_error(exc.message, "GatewayTermsNotAcceptedError", cause=exc)
+ agent_error(exc.message, error_type="GatewayTermsNotAcceptedError", cause=exc)
except GatewayApiKeyMissingError as exc:
- agent_error(exc.message, "GatewayApiKeyMissingError", cause=exc)
+ agent_error(exc.message, error_type="GatewayApiKeyMissingError", cause=exc)
except GatewayDoNotTrackConflictError as exc:
- agent_error(exc.message, "GatewayDoNotTrackConflictError", cause=exc)
+ agent_error(exc.message, error_type="GatewayDoNotTrackConflictError", cause=exc)
except RemoteConfigUnavailableError as exc:
- agent_error(exc.message, "RemoteConfigUnavailableError", cause=exc)
+ agent_error(exc.message, error_type="RemoteConfigUnavailableError", cause=exc)
except RemoteConfigValidationError as exc:
- agent_error(exc.message, "RemoteConfigValidationError", cause=exc)
+ agent_error(exc.message, error_type="RemoteConfigValidationError", cause=exc)
except GatewayUnknownModelError as exc:
agent_error(
exc.message,
- "GatewayUnknownModelError",
+ error_type="GatewayUnknownModelError",
cause=exc,
model_name=exc.model_name,
source=exc.source,
@@ -258,7 +259,7 @@ def make_pipelex_for_agent_cli(
except ModelDeckPresetValidatonError as exc:
agent_error(
exc.message,
- "ModelDeckPresetValidatonError",
+ error_type="ModelDeckPresetValidatonError",
cause=exc,
preset_id=exc.preset_id,
model_type=str(exc.model_type),
@@ -269,7 +270,7 @@ def make_pipelex_for_agent_cli(
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
agent_error(
f"Pipelex initialization failed: {exc}",
- type(exc).__name__,
+ error_type=type(exc).__name__,
cause=exc,
hint="Initialization failed. Run 'pipelex-agent doctor' to diagnose, or 'pipelex init config' to reset configuration",
)
diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.py
index 22c3980a0..b0a14d1cd 100644
--- a/pipelex/cli/agent_cli/commands/agent_output.py
+++ b/pipelex/cli/agent_cli/commands/agent_output.py
@@ -28,6 +28,7 @@ import typer
from pipelex.base_exceptions import PipelexError, iter_cause_chain
from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validation_errors import build_validation_error_items
from pipelex.tools.misc.json_utils import clean_json_dumps
from pipelex.types import StrEnum
@@ -106,10 +107,6 @@ AGENT_ERROR_HINTS: dict[str, str] = {
),
# Validation errors
"PipeValidationError": "Check pipe inputs, outputs, and concept references for consistency",
- "SignaturesNotAllowedError": (
- "This pipeline reaches a PipeSignature placeholder that has no implementation. Replace each signature with a real "
- "pipe, or re-run with --allow-signatures to validate the partial pipeline."
- ),
# Execution errors
"PipeExecutionError": "A pipe input validation failed during pipeline execution. Check the error message for the failing model and field.",
# File/input errors
@@ -160,8 +157,6 @@ AGENT_ERROR_DOMAINS: dict[str, str] = {
# input = agent can fix (bad .mthds, wrong args, bad JSON)
"ModelChoiceNotFoundError": "input",
"PipeValidationError": "input",
- # SignaturesNotAllowedError intentionally absent: it carries a class-level error_domain = INPUT,
- # so the report is its single source of truth (enforced by test_agent_output_drift).
"FileNotFoundError": "input",
"JSONDecodeError": "input",
"JsonTypeError": "input",
@@ -215,7 +210,7 @@ def _build_error_source(exc: BaseException) -> list[str]:
return sources
-def _assemble_error_payload(message: str, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> dict[str, Any]:
+def _assemble_error_payload(message: str, *, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> dict[str, Any]:
"""Build the structured error payload shared by the JSON and markdown renderers.
Sources ``hint`` / ``retryable`` / ``error_domain`` / ``error_category`` /
@@ -308,14 +303,14 @@ def _render_error_markdown(payload: dict[str, Any]) -> str:
return "\n".join(lines)
-def _agent_error_json(message: str, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> NoReturn:
+def _agent_error_json(message: str, *, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> NoReturn:
"""Print a structured JSON error to stderr and exit with code 1."""
- payload = _assemble_error_payload(message, error_type, cause, extra)
+ payload = _assemble_error_payload(message, error_type=error_type, cause=cause, extra=extra)
print(clean_json_dumps(payload, indent=2), file=sys.stderr)
raise typer.Exit(1) from cause
-def agent_error_markdown(message: str, error_type: str, cause: BaseException | None = None, **extra: Any) -> NoReturn:
+def agent_error_markdown(message: str, *, error_type: str, cause: BaseException | None = None, **extra: Any) -> NoReturn:
"""Print a markdown-rendered error to stderr and exit with code 1.
The markdown sibling of :func:`agent_error`'s JSON path: an error-type
@@ -330,12 +325,12 @@ def agent_error_markdown(message: str, error_type: str, cause: BaseException | N
cause: Optional exception to chain with ``raise ... from``.
**extra: Additional fields merged into the payload.
"""
- payload = _assemble_error_payload(message, error_type, cause, extra)
+ payload = _assemble_error_payload(message, error_type=error_type, cause=cause, extra=extra)
print(_render_error_markdown(payload), file=sys.stderr)
raise typer.Exit(1) from cause
-def agent_error(message: str, error_type: str, cause: BaseException | None = None, **extra: Any) -> NoReturn:
+def agent_error(message: str, *, error_type: str, cause: BaseException | None = None, **extra: Any) -> NoReturn:
"""Emit a structured error to stderr and exit with code 1.
Dispatches on the active error format (see :func:`set_agent_cli_error_format`):
@@ -353,9 +348,9 @@ def agent_error(message: str, error_type: str, cause: BaseException | None = Non
"""
match get_agent_cli_error_format():
case CliOutputFormat.JSON:
- _agent_error_json(message, error_type, cause, extra)
+ _agent_error_json(message, error_type=error_type, cause=cause, extra=extra)
case CliOutputFormat.MARKDOWN:
- agent_error_markdown(message, error_type, cause, **extra)
+ agent_error_markdown(message, error_type=error_type, cause=cause, **extra)
def agent_success(result: dict[str, Any]) -> None:
@@ -381,6 +376,7 @@ def agent_success(result: dict[str, Any]) -> None:
def agent_success_formatted(
result: dict[str, Any],
+ *,
markdown_renderer: Callable[[dict[str, Any]], str],
output_format: CliOutputFormat,
) -> None:
@@ -407,67 +403,33 @@ def agent_success_formatted(
def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]:
- """Extract all validation error categories from a ValidateBundleError into a flat list.
-
- Covers all 4 error sources:
- - Blueprint validation errors (from interpreter)
- - Pipe factory errors (e.g., missing concepts)
- - Pipe validation errors (e.g., missing inputs, type mismatches)
- - Pipe/concept instantiation errors (from Pydantic validation during factory)
-
- Each entry includes a ``category`` field identifying its source.
+ """Project a ``ValidateBundleError`` into the CLI ``validation_errors`` JSON array.
+
+ Thin adapter over the shared ``build_validation_error_items`` builder — the
+ same one feeding the API 422's ``ErrorReport.validation_errors`` — so the CLI
+ and API structured shapes can never drift. Each typed item is dumped to a
+ plain dict with unset fields dropped (``exclude_none``), matching the
+ machine-first agent-CLI envelope; the entries carry ``category``,
+ ``error_type``, ``message``, and whatever identity / ``source`` fields the
+ underlying error populated. Two residuals make the invariant total: a dry-run
+ failure with no structured locator becomes one ``dry_run``-category item, and
+ a parse-level failure (TOML syntax, an empty blueprint, a bundle elaborator)
+ that carries only a message becomes one ``blueprint_validation`` residual
+ (``fallback_message=exc.message``). So the envelope's ``validation_errors[]``
+ is non-empty on every invalid verdict (the structured-info invariant) — never
+ a bare message.
Args:
exc: The ValidateBundleError to extract errors from.
Returns:
- List of dicts, each with at minimum ``category``, ``error_type``, and ``message``.
+ List of dicts, each with at minimum ``category`` and ``message``.
"""
- validation_errors: list[dict[str, Any]] = []
-
- for blueprint_error in exc.pipelex_bundle_blueprint_validation_errors:
- entry: dict[str, Any] = {
- "category": "blueprint_validation",
- "error_type": str(blueprint_error.error_type) if blueprint_error.error_type else None,
- "pipe_code": blueprint_error.pipe_code,
- "message": blueprint_error.message,
- }
- if blueprint_error.domain_code:
- entry["domain_code"] = blueprint_error.domain_code
- if blueprint_error.variable_names:
- entry["variable_names"] = blueprint_error.variable_names
- validation_errors.append(entry)
-
- for factory_error in exc.pipe_factory_errors:
- entry = {
- "category": "pipe_factory",
- "error_type": str(factory_error.error_type),
- "pipe_code": factory_error.pipe_code,
- "message": factory_error.message,
- }
- if factory_error.domain_code:
- entry["domain_code"] = factory_error.domain_code
- if factory_error.missing_concept_code:
- entry["missing_concept_code"] = factory_error.missing_concept_code
- if factory_error.declared_concepts:
- entry["declared_concepts"] = factory_error.declared_concepts
- validation_errors.append(entry)
-
- for pipe_error in exc.pipe_validation_errors:
- entry = {
- "category": "pipe_validation",
- "error_type": str(pipe_error.error_type),
- "pipe_code": pipe_error.pipe_code,
- "message": pipe_error.message,
- }
- if pipe_error.domain_code:
- entry["domain_code"] = pipe_error.domain_code
- if pipe_error.concept_code:
- entry["concept_code"] = pipe_error.concept_code
- if pipe_error.field_path:
- entry["field_path"] = pipe_error.field_path
- if pipe_error.variable_names:
- entry["variable_names"] = pipe_error.variable_names
- validation_errors.append(entry)
-
- return validation_errors
+ items = build_validation_error_items(
+ blueprint_errors=exc.pipelex_bundle_blueprint_validation_errors,
+ factory_errors=exc.pipe_factory_errors,
+ pipe_validation_errors=exc.pipe_validation_error_data,
+ dry_run_error_message=exc.dry_run_error_message,
+ fallback_message=exc.message,
+ )
+ return [item.model_dump(mode="json", exclude_none=True) for item in items]
diff --git a/pipelex/cli/agent_cli/commands/check_model_cmd.py b/pipelex/cli/agent_cli/commands/check_model_cmd.py
index 3fd652ca3..33ae58d4a 100644
--- a/pipelex/cli/agent_cli/commands/check_model_cmd.py
+++ b/pipelex/cli/agent_cli/commands/check_model_cmd.py
@@ -82,7 +82,7 @@ def agent_check_model_cmd(
ref = ModelReference.parse(name)
resolved_model_type = CATEGORY_TO_MODEL_TYPE[model_type]
- candidates = get_collection_keys(model_deck, resolved_model_type, ref.kind)
+ candidates = get_collection_keys(model_deck, model_type=resolved_model_type, kind=ref.kind)
is_valid = ref.name in candidates
result: dict[str, Any] = {
@@ -94,7 +94,9 @@ def agent_check_model_cmd(
}
if not is_valid:
- suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(model_deck, resolved_model_type, ref.name, ref.kind)
+ suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(
+ model_deck, model_type=resolved_model_type, name=ref.name, kind=ref.kind
+ )
result["suggestions"] = suggestions
result["wrong_sigil_hints"] = wrong_sigil_hints
result["cross_collection_suggestions"] = cross_suggestions
@@ -107,9 +109,9 @@ def agent_check_model_cmd(
except SystemExit:
raise
except ModelReferenceParseError as exc:
- agent_error(f"Invalid model reference: {exc}", "ArgumentError", cause=exc)
+ agent_error(f"Invalid model reference: {exc}", error_type="ArgumentError", cause=exc)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(f"Failed to check model: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Failed to check model: {exc}", error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/concept_cmd.py b/pipelex/cli/agent_cli/commands/concept_cmd.py
index bac38faef..518d291b5 100644
--- a/pipelex/cli/agent_cli/commands/concept_cmd.py
+++ b/pipelex/cli/agent_cli/commands/concept_cmd.py
@@ -97,10 +97,10 @@ def concept_cmd(
"""
# Validate that exactly one of spec or spec_file is provided
if spec is None and spec_file is None:
- agent_error("Either --spec or --spec-file must be provided", "ArgumentError")
+ agent_error("Either --spec or --spec-file must be provided", error_type="ArgumentError")
if spec is not None and spec_file is not None:
- agent_error("Cannot use both --spec and --spec-file", "ArgumentError")
+ agent_error("Cannot use both --spec and --spec-file", error_type="ArgumentError")
# Load spec data
spec_data: dict[str, Any]
@@ -111,9 +111,9 @@ def concept_cmd(
else:
spec_data = json.loads(spec) # type: ignore[arg-type]
except FileNotFoundError as exc:
- agent_error(f"Spec file not found: {spec_file}", "FileNotFoundError", cause=exc)
+ agent_error(f"Spec file not found: {spec_file}", error_type="FileNotFoundError", cause=exc)
except json.JSONDecodeError as exc:
- agent_error(f"Invalid JSON: {exc.msg}", "JSONDecodeError", cause=exc)
+ agent_error(f"Invalid JSON: {exc.msg}", error_type="JSONDecodeError", cause=exc)
# Validate and convert spec
try:
@@ -124,11 +124,11 @@ def concept_cmd(
except ValidationError as exc:
message, details = format_pydantic_validation_error_for_agent(exc)
- agent_error(message, "ValidationError", cause=exc, validation_details=details)
+ agent_error(message, error_type="ValidationError", cause=exc, validation_details=details)
except ValueError as exc:
- agent_error(str(exc), "ValueError", cause=exc)
+ agent_error(str(exc), error_type="ValueError", cause=exc)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
diff --git a/pipelex/cli/agent_cli/commands/doctor_cmd.py b/pipelex/cli/agent_cli/commands/doctor_cmd.py
index 870e1b469..216372c41 100644
--- a/pipelex/cli/agent_cli/commands/doctor_cmd.py
+++ b/pipelex/cli/agent_cli/commands/doctor_cmd.py
@@ -194,7 +194,7 @@ def agent_doctor_cmd(
# Agent CLI command boundary: agent_error() (NoReturn) converts any genuinely
# unexpected failure into the structured error payload. PipelexConfigError is
# handled by the inner arm above and never reaches here.
- agent_error(f"Health check failed unexpectedly: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Health check failed unexpectedly: {exc}", error_type=type(exc).__name__, cause=exc)
# Pin stdout discipline regardless of bootstrap path (broken-config branch never
# installed a hub or configured log — the helper guards both internally).
diff --git a/pipelex/cli/agent_cli/commands/fmt_cmd.py b/pipelex/cli/agent_cli/commands/fmt_cmd.py
index cac78e3fc..97d6fb6c3 100644
--- a/pipelex/cli/agent_cli/commands/fmt_cmd.py
+++ b/pipelex/cli/agent_cli/commands/fmt_cmd.py
@@ -18,4 +18,4 @@ def fmt_cmd(
This is a thin wrapper around ``plxt fmt`` that eliminates the need
for agents to call the plxt binary directly.
"""
- run_plxt("fmt", file_path)
+ run_plxt("fmt", file_path=file_path)
diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.py
index 9d036ff13..c1e186758 100644
--- a/pipelex/cli/agent_cli/commands/init_cmd.py
+++ b/pipelex/cli/agent_cli/commands/init_cmd.py
@@ -48,18 +48,18 @@ def _parse_config_arg(config_arg: str | None) -> dict[str, Any]:
result: dict[str, Any] = json.loads(config_arg)
return result
except json.JSONDecodeError as exc:
- agent_error(f"Failed to parse inline JSON config: {exc}", "JSONDecodeError", cause=exc)
+ agent_error(f"Failed to parse inline JSON config: {exc}", error_type="JSONDecodeError", cause=exc)
else:
try:
with open(config_arg, encoding="utf-8") as file:
loaded: Any = json.load(file)
if not isinstance(loaded, dict):
- agent_error(f"Config file must contain a JSON object, got {type(loaded).__name__}", "JSONDecodeError")
+ agent_error(f"Config file must contain a JSON object, got {type(loaded).__name__}", error_type="JSONDecodeError")
return cast("dict[str, Any]", loaded)
except FileNotFoundError as exc:
- agent_error(f"Config file not found: {config_arg}", "FileNotFoundError", cause=exc)
+ agent_error(f"Config file not found: {config_arg}", error_type="FileNotFoundError", cause=exc)
except json.JSONDecodeError as exc:
- agent_error(f"Failed to parse config file JSON: {exc}", "JSONDecodeError", cause=exc)
+ agent_error(f"Failed to parse config file JSON: {exc}", error_type="JSONDecodeError", cause=exc)
return {}
@@ -102,7 +102,7 @@ def _resolve_target_dir(global_: bool) -> Path:
agent_error(
"No project root found (no .git, pyproject.toml, etc. in parent directories). "
"Use --global/-g to target the global ~/.pipelex/ directory.",
- "ArgumentError",
+ error_type="ArgumentError",
)
return project_root / ".pipelex"
@@ -142,7 +142,7 @@ def _copy_inference_templates(target_dir: Path) -> None:
if deck_file.suffix == ".toml":
shutil.copy2(deck_file, target_deck_dir / deck_file.name)
- write_manifest(target_deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=target_deck_dir)
# Copy routing_profiles.toml
template_routing_path = template_inference_dir / "routing_profiles.toml"
@@ -150,7 +150,7 @@ def _copy_inference_templates(target_dir: Path) -> None:
shutil.copy2(template_routing_path, target_inference_dir / "routing_profiles.toml")
-def _copy_telemetry_template(target_dir: Path, for_project: bool) -> None:
+def _copy_telemetry_template(target_dir: Path, *, for_project: bool) -> None:
"""Copy the appropriate telemetry template to the target directory.
The global template (`telemetry.toml`) carries active defaults. The project
@@ -171,6 +171,7 @@ def _copy_telemetry_template(target_dir: Path, for_project: bool) -> None:
def _configure_backends(
+ *,
config: dict[str, Any],
backends_toml_path: Path,
template_backends_path: Path,
@@ -186,7 +187,7 @@ def _configure_backends(
List of enabled backend keys.
"""
if not backends_toml_path.exists():
- agent_error("backends.toml not found after config initialization", "InitConfigError")
+ agent_error("backends.toml not found after config initialization", error_type="InitConfigError")
requested_backends: list[str] | None = config.get("backends")
@@ -195,14 +196,14 @@ def _configure_backends(
return get_selected_backend_keys(backends_toml_path)
# Validate requested backend keys
- backend_options = get_backend_options_from_toml(template_backends_path, backends_toml_path)
+ backend_options = get_backend_options_from_toml(template_backends_path, existing_path=backends_toml_path)
available_keys = [key for key, _ in backend_options]
for backend_key in requested_backends:
if backend_key not in available_keys:
agent_error(
f"Unknown backend: {backend_key}. Available: {', '.join(available_keys)}",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Build selected indices from requested backend keys
@@ -211,8 +212,8 @@ def _configure_backends(
# Update backends.toml
toml_doc = load_toml_with_tomlkit(backends_toml_path)
- update_backends_in_toml(toml_doc, selected_indices, backend_options)
- save_toml_to_path(toml_doc, backends_toml_path)
+ update_backends_in_toml(toml_doc, selected_indices=selected_indices, backend_options=backend_options)
+ save_toml_to_path(toml_doc, path=backends_toml_path)
# Handle pipelex_gateway terms acceptance (only when explicitly provided)
if PipelexBackend.GATEWAY in requested_backends:
@@ -224,7 +225,7 @@ def _configure_backends(
return requested_backends
-def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any], target_dir: Path) -> str:
+def _configure_routing(selected_backend_keys: list[str], *, config: dict[str, Any], target_dir: Path) -> str:
"""Configure routing profile based on selected backends and config.
Args:
@@ -238,14 +239,14 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],
routing_profiles_toml_path = target_dir / "inference" / "routing_profiles.toml"
if not routing_profiles_toml_path.exists():
- agent_error("routing_profiles.toml not found after config initialization", "InitConfigError")
+ agent_error("routing_profiles.toml not found after config initialization", error_type="InitConfigError")
toml_doc = load_toml_with_tomlkit(routing_profiles_toml_path)
# Case 1: pipelex_gateway is enabled → use all_pipelex_gateway
if PipelexBackend.GATEWAY in selected_backend_keys:
toml_doc["active"] = PipelexRoutingProfile.ALL_PIPELEX_GATEWAY
- save_toml_to_path(toml_doc, routing_profiles_toml_path)
+ save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
return PipelexRoutingProfile.ALL_PIPELEX_GATEWAY
# Case 2: Only one backend → use all_{backend_key}
@@ -265,7 +266,7 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],
toml_doc["profiles"][profile_name] = profile_data # type: ignore[index]
toml_doc["active"] = profile_name
- save_toml_to_path(toml_doc, routing_profiles_toml_path)
+ save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
return profile_name
# Case 3: Multiple backends (no pipelex_gateway) → need primary_backend
@@ -275,13 +276,13 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],
agent_error(
f"primary_backend is required when multiple backends are selected ({', '.join(selected_backend_keys)}) "
"and pipelex_gateway is not among them",
- "ArgumentError",
+ error_type="ArgumentError",
)
if primary_backend not in selected_backend_keys:
agent_error(
f"primary_backend '{primary_backend}' is not in the selected backends: {', '.join(selected_backend_keys)}",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Build custom_routing profile
@@ -309,7 +310,7 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],
toml_doc["profiles"] = new_profiles # type: ignore[assignment]
toml_doc["active"] = "custom_routing"
- save_toml_to_path(toml_doc, routing_profiles_toml_path)
+ save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
return "custom_routing"
@@ -395,10 +396,12 @@ def agent_init_cmd(
# Step 2: Configure backends
template_backends_path = Path(str(get_kit_configs_dir() / "inference" / "backends.toml"))
backends_toml_path = target_dir / "inference" / "backends.toml"
- backends_enabled = _configure_backends(parsed_config, backends_toml_path, template_backends_path)
+ backends_enabled = _configure_backends(
+ config=parsed_config, backends_toml_path=backends_toml_path, template_backends_path=template_backends_path
+ )
# Step 3: Configure routing
- routing_profile = _configure_routing(backends_enabled, parsed_config, target_dir)
+ routing_profile = _configure_routing(backends_enabled, config=parsed_config, target_dir=target_dir)
# Step 4: Mark inference setup as completed
update_inference_setup_completed(completed=True, config_dir=config_manager.global_config_dir)
@@ -422,10 +425,10 @@ def agent_init_cmd(
result_payload["cache_priming_error"] = priming_result.error_message
# Output result
- agent_success_formatted(result_payload, _format_init_markdown, output_format)
+ agent_success_formatted(result_payload, markdown_renderer=_format_init_markdown, output_format=output_format)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(f"Initialization failed: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Initialization failed: {exc}", error_type=type(exc).__name__, cause=exc)
diff --git a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
index 53ec068b1..b64c4ace7 100644
--- a/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
+++ b/pipelex/cli/agent_cli/commands/inputs/_inputs_core.py
@@ -12,6 +12,7 @@ if TYPE_CHECKING:
async def inputs_core(
pipe_code: str | None = None,
+ *,
bundle_path: Path | None = None,
library_dirs: list[Path] | None = None,
) -> dict[str, Any]:
diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
index f1bad131a..4f4ff5583 100644
--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
@@ -55,13 +55,13 @@ def inputs_bundle_cmd(
else:
mthds_files = list(target_path.glob(f"*{MTHDS_EXTENSION}"))
if len(mthds_files) == 0:
- agent_error(f"No .mthds bundle file found in directory '{path}'", "FileNotFoundError")
+ agent_error(f"No .mthds bundle file found in directory '{path}'", error_type="FileNotFoundError")
if len(mthds_files) > 1:
mthds_names = ", ".join(mthds_file.name for mthds_file in mthds_files)
agent_error(
f"Multiple .mthds files found in '{path}' ({mthds_names}) and no '{DEFAULT_BUNDLE_FILE_NAME}'. "
f"Pass the .mthds file directly instead.",
- "ArgumentError",
+ error_type="ArgumentError",
)
bundle_path = str(mthds_files[0])
@@ -78,7 +78,7 @@ def inputs_bundle_cmd(
agent_error(
f"'{path}' is not a .mthds file or directory. "
f"Use 'inputs pipe <code>' for pipe codes, or 'inputs bundle <path>' for .mthds files/directories.",
- "ArgumentError",
+ error_type="ArgumentError",
)
pipe_code: str | None = pipe
@@ -90,14 +90,14 @@ def inputs_bundle_cmd(
agent_success(result)
except FileNotFoundError as exc:
- agent_error(f"Bundle file not found: {bundle_path}", "FileNotFoundError", cause=exc)
+ agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
validation_errors = extract_validation_errors(exc)
extra: dict[str, Any] = {"validation_errors": validation_errors}
if exc.dry_run_error_message:
extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **extra)
+ agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
except NoInputsRequiredError as exc:
agent_success(
@@ -112,7 +112,7 @@ def inputs_bundle_cmd(
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -128,14 +128,14 @@ def inputs_bundle_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
index 4a6f1ec04..223f50c3e 100644
--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
@@ -62,14 +62,14 @@ def inputs_method_cmd(
agent_success(result)
except FileNotFoundError as exc:
- agent_error(f"Bundle file not found: {bundle_path}", "FileNotFoundError", cause=exc)
+ agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
validation_errors = extract_validation_errors(exc)
extra: dict[str, Any] = {"validation_errors": validation_errors}
if exc.dry_run_error_message:
extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **extra)
+ agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
except NoInputsRequiredError as exc:
agent_success(
@@ -84,7 +84,7 @@ def inputs_method_cmd(
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -100,11 +100,11 @@ def inputs_method_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
index 19342254b..a37b251dc 100644
--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
@@ -44,7 +44,7 @@ def inputs_pipe_cmd(
agent_error(
f"'{pipe_code}' looks like a file path or directory. "
f"Use 'inputs bundle {pipe_code}' for bundles/directories, or 'inputs pipe <code>' for pipe codes.",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Check installed methods' exports for additional library dirs
@@ -53,7 +53,7 @@ def inputs_pipe_cmd(
except ValueError as exc:
agent_error(
f"Ambiguous pipe code '{pipe_code}': {exc}",
- "ArgumentError",
+ error_type="ArgumentError",
cause=exc,
)
if export_dirs:
@@ -70,14 +70,14 @@ def inputs_pipe_cmd(
agent_success(result)
except FileNotFoundError as exc:
- agent_error(f"File not found: {exc}", "FileNotFoundError", cause=exc)
+ agent_error(f"File not found: {exc}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
validation_errors = extract_validation_errors(exc)
extra: dict[str, Any] = {"validation_errors": validation_errors}
if exc.dry_run_error_message:
extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **extra)
+ agent_error(exc.message, error_type="ValidateBundleError", cause=exc, **extra)
except NoInputsRequiredError as exc:
# Not really an error - just a pipe with no inputs
@@ -93,7 +93,7 @@ def inputs_pipe_cmd(
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -109,14 +109,14 @@ def inputs_pipe_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/lint_cmd.py b/pipelex/cli/agent_cli/commands/lint_cmd.py
index e7f07fbf3..91ad9cb4d 100644
--- a/pipelex/cli/agent_cli/commands/lint_cmd.py
+++ b/pipelex/cli/agent_cli/commands/lint_cmd.py
@@ -18,4 +18,4 @@ def lint_cmd(
This is a thin wrapper around ``plxt lint`` that eliminates the need
for agents to call the plxt binary directly.
"""
- run_plxt("lint", file_path)
+ run_plxt("lint", file_path=file_path)
diff --git a/pipelex/cli/agent_cli/commands/models_cmd.py b/pipelex/cli/agent_cli/commands/models_cmd.py
index e39285827..90d30128f 100644
--- a/pipelex/cli/agent_cli/commands/models_cmd.py
+++ b/pipelex/cli/agent_cli/commands/models_cmd.py
@@ -49,6 +49,6 @@ def agent_models_cmd(
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(f"Failed to list models: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Failed to list models: {exc}", error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/pipe_cmd.py b/pipelex/cli/agent_cli/commands/pipe_cmd.py
index 182968a85..4fe131965 100644
--- a/pipelex/cli/agent_cli/commands/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/pipe_cmd.py
@@ -62,7 +62,7 @@ def _pipe_spec_to_toml(pipe_spec: PipeSpec) -> str:
pipe_item_table.add("output", pipe_spec.output)
# Add type-specific fields
- _add_type_specific_fields(pipe_spec, pipe_item_table)
+ _add_type_specific_fields(pipe_spec, pipe_table=pipe_item_table)
# Build the nested structure: [pipe.pipe_code]
pipe_section = tomlkit.table()
@@ -71,7 +71,7 @@ def _pipe_spec_to_toml(pipe_spec: PipeSpec) -> str:
return tomlkit.dumps(doc)
-def _add_type_specific_fields(pipe_spec: PipeSpec, pipe_table: tomlkit.TOMLDocument | tomlkit.items.Table) -> None: # type: ignore[name-defined]
+def _add_type_specific_fields(pipe_spec: PipeSpec, *, pipe_table: tomlkit.TOMLDocument | tomlkit.items.Table) -> None: # type: ignore[name-defined]
"""Add type-specific fields to the pipe TOML table.
Args:
@@ -234,10 +234,10 @@ def pipe_cmd(
"""
# Validate that exactly one of spec or spec_file is provided
if spec is None and spec_file is None:
- agent_error("Either --spec or --spec-file must be provided", "ArgumentError")
+ agent_error("Either --spec or --spec-file must be provided", error_type="ArgumentError")
if spec is not None and spec_file is not None:
- agent_error("Cannot use both --spec and --spec-file", "ArgumentError")
+ agent_error("Cannot use both --spec and --spec-file", error_type="ArgumentError")
# Load spec data
spec_data: dict[str, Any]
@@ -248,9 +248,9 @@ def pipe_cmd(
else:
spec_data = json.loads(spec) # type: ignore[arg-type]
except FileNotFoundError as exc:
- agent_error(f"Spec file not found: {spec_file}", "FileNotFoundError", cause=exc)
+ agent_error(f"Spec file not found: {spec_file}", error_type="FileNotFoundError", cause=exc)
except json.JSONDecodeError as exc:
- agent_error(f"Invalid JSON: {exc.msg}", "JSONDecodeError", cause=exc)
+ agent_error(f"Invalid JSON: {exc.msg}", error_type="JSONDecodeError", cause=exc)
# Accept "pipe_type" as an alias for "type" in the JSON spec
if "pipe_type" in spec_data and "type" not in spec_data:
@@ -265,22 +265,22 @@ def pipe_cmd(
elif "type" in spec_data:
resolved_pipe_type = spec_data.pop("type")
else:
- agent_error("Pipe type must be provided either via --type or as 'type' in the JSON spec", "ArgumentError")
+ agent_error("Pipe type must be provided either via --type or as 'type' in the JSON spec", error_type="ArgumentError")
# Validate and convert spec
try:
- pipe_spec = parse_pipe_spec(resolved_pipe_type, spec_data)
+ pipe_spec = parse_pipe_spec(spec_data, pipe_type=resolved_pipe_type)
toml_content = _pipe_spec_to_toml(pipe_spec)
print(toml_content, end="" if toml_content.endswith("\n") else "\n")
except ValidationError as exc:
message, details = format_pydantic_validation_error_for_agent(exc)
- agent_error(message, "ValidationError", cause=exc, validation_details=details)
+ agent_error(message, error_type="ValidationError", cause=exc, validation_details=details)
except ValueError as exc:
- agent_error(str(exc), "ValueError", cause=exc)
+ agent_error(str(exc), error_type="ValueError", cause=exc)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
diff --git a/pipelex/cli/agent_cli/commands/plxt_passthrough.py b/pipelex/cli/agent_cli/commands/plxt_passthrough.py
index dc8474e1f..22a4666db 100644
--- a/pipelex/cli/agent_cli/commands/plxt_passthrough.py
+++ b/pipelex/cli/agent_cli/commands/plxt_passthrough.py
@@ -8,7 +8,7 @@ import typer
from pipelex.cli.agent_cli.commands.agent_output import agent_error
-def run_plxt(subcommand: str, file_path: str) -> None:
+def run_plxt(subcommand: str, *, file_path: str) -> None:
"""Execute a plxt subcommand with full stdin/stdout/stderr passthrough.
Locates the plxt binary, runs ``plxt <subcommand> <file_path>``,
diff --git a/pipelex/cli/agent_cli/commands/run/_output_helpers.py b/pipelex/cli/agent_cli/commands/run/_output_helpers.py
index 3fc529d47..40ed1700e 100644
--- a/pipelex/cli/agent_cli/commands/run/_output_helpers.py
+++ b/pipelex/cli/agent_cli/commands/run/_output_helpers.py
@@ -12,6 +12,7 @@ from pipelex.tools.misc.json_utils import clean_json_dumps
def build_run_output(
+ *,
with_memory: bool,
main_stuff_json: dict[str, Any],
working_memory_dump: dict[str, Any],
@@ -65,7 +66,7 @@ def _render_json_payload_lines(result_payload: Any) -> list[str]:
return ["## Result", "", "```json", clean_json_dumps(result_payload, indent=2), "```"]
-def format_run_markdown(result: dict[str, Any], with_memory: bool) -> str:
+def format_run_markdown(result: dict[str, Any], *, with_memory: bool) -> str:
"""Render a pipeline-run result dict as agent-readable markdown.
Handles both shapes ``build_run_output()`` produces, disambiguated by the
diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.py
index 8124a434d..68963c095 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_core.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py
@@ -20,6 +20,7 @@ from pipelex.tools.misc.json_utils import clean_json_dumps
async def run_pipeline_core(
pipe_code: str,
+ *,
mthds_contents: list[str] | None = None,
bundle_uris: list[str] | None = None,
inputs: dict[str, Any] | None = None,
diff --git a/pipelex/cli/agent_cli/commands/run/_run_core_api.py b/pipelex/cli/agent_cli/commands/run/_run_core_api.py
index 041b7f18a..dc607800a 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_core_api.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_core_api.py
@@ -16,6 +16,7 @@ from pipelex.cli.agent_cli.commands.run._output_helpers import build_run_output
async def run_pipeline_core_api(
pipe_code: str,
+ *,
mthds_contents: list[str] | None = None,
inputs: dict[str, Any] | None = None,
with_memory: bool = False,
diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
index efd71117f..3624891d5 100644
--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
@@ -89,7 +89,7 @@ def run_bundle_cmd(
# Validate --mock-inputs requires --dry-run
if mock_inputs and not dry_run:
- agent_error("--mock-inputs requires --dry-run", "ArgumentError")
+ agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")
pipe_code: str | None = pipe
bundle_path: str | None = None
@@ -104,13 +104,13 @@ def run_bundle_cmd(
else:
mthds_files = list(target_path.glob(f"*{MTHDS_EXTENSION}"))
if len(mthds_files) == 0:
- agent_error(f"No .mthds bundle file found in directory '{path}'", "FileNotFoundError")
+ agent_error(f"No .mthds bundle file found in directory '{path}'", error_type="FileNotFoundError")
if len(mthds_files) > 1:
mthds_names = ", ".join(mthds_file.name for mthds_file in mthds_files)
agent_error(
f"Multiple .mthds files found in '{path}' ({mthds_names}) and no '{DEFAULT_BUNDLE_FILE_NAME}'. "
f"Pass the .mthds file directly instead.",
- "ArgumentError",
+ error_type="ArgumentError",
)
bundle_path = str(mthds_files[0])
@@ -130,7 +130,7 @@ def run_bundle_cmd(
else:
agent_error(
f"'{path}' is not a .mthds file or directory. Use 'run pipe <code>' for pipe codes, or 'run bundle <path>' for .mthds files/directories.",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Load MTHDS content from bundle
@@ -144,15 +144,15 @@ def run_bundle_cmd(
if not main_pipe_code:
agent_error(
f"Bundle '{bundle_path}' does not declare a main_pipe. Specify a pipe code with --pipe.",
- "BundleError",
+ error_type="BundleError",
)
pipe_code = main_pipe_code
except FileNotFoundError as exc:
- agent_error(f"Bundle file not found: {bundle_path}", "FileNotFoundError", cause=exc)
+ agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except (OSError, UnicodeDecodeError) as exc:
- agent_error(f"Failed to read bundle file '{bundle_path}': {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Failed to read bundle file '{bundle_path}': {exc}", error_type=type(exc).__name__, cause=exc)
except PipelexInterpreterError as exc:
- agent_error(f"Failed to parse bundle '{bundle_path}': {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Failed to parse bundle '{bundle_path}': {exc}", error_type=type(exc).__name__, cause=exc)
# Load inputs: --inputs flag takes priority, then stdin fallback, then auto-detected
pipeline_inputs: dict[str, Any] | None = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True, auto_inputs_path=auto_inputs_path)
@@ -163,9 +163,9 @@ def run_bundle_cmd(
case RunnerType.API:
# Validate unsupported flags for API runner
if dry_run:
- agent_error("--dry-run is not supported with --runner api", "ArgumentError")
+ agent_error("--dry-run is not supported with --runner api", error_type="ArgumentError")
if mock_inputs:
- agent_error("--mock-inputs is not supported with --runner api", "ArgumentError")
+ agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")
from mthds.protocol.exceptions import PipelineRequestError # noqa: PLC0415
from mthds.runners.api.exceptions import ClientAuthenticationError # noqa: PLC0415
@@ -179,17 +179,19 @@ def run_bundle_cmd(
with_memory=with_memory,
)
)
- agent_success_formatted(result, functools.partial(format_run_markdown, with_memory=with_memory), output_format)
+ agent_success_formatted(
+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format
+ )
except ClientAuthenticationError as exc:
- agent_error(str(exc), "ClientAuthenticationError", cause=exc)
+ agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)
except PipelineRequestError as exc:
- agent_error(str(exc), "PipelineRequestError", cause=exc)
+ agent_error(str(exc), error_type="PipelineRequestError", cause=exc)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
case RunnerType.PIPELEX:
make_pipelex_for_agent_cli(needs_inference=not dry_run, needs_model_specs=True)
@@ -209,7 +211,9 @@ def run_bundle_cmd(
with_memory=with_memory,
)
)
- agent_success_formatted(result, functools.partial(format_run_markdown, with_memory=with_memory), output_format)
+ agent_success_formatted(
+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format
+ )
except PipelineExecutionError as exc:
extra_fields: dict[str, Any] = {
@@ -219,12 +223,12 @@ def run_bundle_cmd(
if exc.__cause__:
extra_fields["cause_type"] = type(exc.__cause__).__name__
extra_fields["cause_message"] = str(exc.__cause__)
- agent_error(exc.message, "PipelineExecutionError", cause=exc, **extra_fields)
+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **extra_fields)
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -240,11 +244,11 @@ def run_bundle_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.py
index dbc9e7fcb..a96033ba8 100644
--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py
@@ -86,7 +86,7 @@ def run_method_cmd(
# Validate --mock-inputs requires --dry-run
if mock_inputs and not dry_run:
- agent_error("--mock-inputs requires --dry-run", "ArgumentError")
+ agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")
pipe_code, method_library_dirs, method = resolve_method_target(
method_name=name,
@@ -120,9 +120,9 @@ def run_method_cmd(
case RunnerType.API:
# Validate unsupported flags for API runner
if dry_run:
- agent_error("--dry-run is not supported with --runner api", "ArgumentError")
+ agent_error("--dry-run is not supported with --runner api", error_type="ArgumentError")
if mock_inputs:
- agent_error("--mock-inputs is not supported with --runner api", "ArgumentError")
+ agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")
from mthds.protocol.exceptions import PipelineRequestError # noqa: PLC0415
from mthds.runners.api.exceptions import ClientAuthenticationError # noqa: PLC0415
@@ -136,17 +136,19 @@ def run_method_cmd(
with_memory=with_memory,
)
)
- agent_success_formatted(result, functools.partial(format_run_markdown, with_memory=with_memory), output_format)
+ agent_success_formatted(
+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format
+ )
except ClientAuthenticationError as exc:
- agent_error(str(exc), "ClientAuthenticationError", cause=exc)
+ agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)
except PipelineRequestError as exc:
- agent_error(str(exc), "PipelineRequestError", cause=exc)
+ agent_error(str(exc), error_type="PipelineRequestError", cause=exc)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
case RunnerType.PIPELEX:
make_pipelex_for_agent_cli(needs_inference=not dry_run, needs_model_specs=True)
@@ -166,7 +168,9 @@ def run_method_cmd(
with_memory=with_memory,
)
)
- agent_success_formatted(result, functools.partial(format_run_markdown, with_memory=with_memory), output_format)
+ agent_success_formatted(
+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format
+ )
except PipelineExecutionError as exc:
extra_fields: dict[str, Any] = {
@@ -176,12 +180,12 @@ def run_method_cmd(
if exc.__cause__:
extra_fields["cause_type"] = type(exc.__cause__).__name__
extra_fields["cause_message"] = str(exc.__cause__)
- agent_error(exc.message, "PipelineExecutionError", cause=exc, **extra_fields)
+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **extra_fields)
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -197,11 +201,11 @@ def run_method_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
index b4e0d6e2e..99d89b9d4 100644
--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
@@ -87,12 +87,12 @@ def run_pipe_cmd(
agent_error(
f"'{pipe_code}' looks like a file path or directory. "
f"Use 'run bundle {pipe_code}' for bundles/directories, or 'run pipe <code>' for pipe codes.",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Validate --mock-inputs requires --dry-run
if mock_inputs and not dry_run:
- agent_error("--mock-inputs requires --dry-run", "ArgumentError")
+ agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")
# Check installed methods' exports for additional library dirs
try:
@@ -100,7 +100,7 @@ def run_pipe_cmd(
except ValueError as exc:
agent_error(
f"Ambiguous pipe code '{pipe_code}': {exc}",
- "ArgumentError",
+ error_type="ArgumentError",
cause=exc,
)
if export_dirs:
@@ -118,9 +118,9 @@ def run_pipe_cmd(
case RunnerType.API:
# Validate unsupported flags for API runner
if dry_run:
- agent_error("--dry-run is not supported with --runner api", "ArgumentError")
+ agent_error("--dry-run is not supported with --runner api", error_type="ArgumentError")
if mock_inputs:
- agent_error("--mock-inputs is not supported with --runner api", "ArgumentError")
+ agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")
from mthds.protocol.exceptions import PipelineRequestError # noqa: PLC0415
from mthds.runners.api.exceptions import ClientAuthenticationError # noqa: PLC0415
@@ -133,17 +133,19 @@ def run_pipe_cmd(
with_memory=with_memory,
)
)
- agent_success_formatted(result, functools.partial(format_run_markdown, with_memory=with_memory), output_format)
+ agent_success_formatted(
+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format
+ )
except ClientAuthenticationError as exc:
- agent_error(str(exc), "ClientAuthenticationError", cause=exc)
+ agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)
except PipelineRequestError as exc:
- agent_error(str(exc), "PipelineRequestError", cause=exc)
+ agent_error(str(exc), error_type="PipelineRequestError", cause=exc)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
case RunnerType.PIPELEX:
make_pipelex_for_agent_cli(needs_inference=not dry_run, needs_model_specs=True)
@@ -161,7 +163,9 @@ def run_pipe_cmd(
with_memory=with_memory,
)
)
- agent_success_formatted(result, functools.partial(format_run_markdown, with_memory=with_memory), output_format)
+ agent_success_formatted(
+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format
+ )
except PipelineExecutionError as exc:
extra_fields: dict[str, Any] = {
@@ -171,12 +175,12 @@ def run_pipe_cmd(
if exc.__cause__:
extra_fields["cause_type"] = type(exc.__cause__).__name__
extra_fields["cause_message"] = str(exc.__cause__)
- agent_error(exc.message, "PipelineExecutionError", cause=exc, **extra_fields)
+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **extra_fields)
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -192,11 +196,11 @@ def run_pipe_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
index 36664ccbf..d702d6c09 100644
--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py
@@ -77,12 +77,12 @@ def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]:
working_memory_raw: Any = stdin_data[WORKING_MEMORY_KEY]
if not isinstance(working_memory_raw, dict):
- agent_error("stdin envelope has invalid 'working_memory': expected a dict", "JSONDecodeError")
+ agent_error("stdin envelope has invalid 'working_memory': expected a dict", error_type="JSONDecodeError")
working_memory = cast("dict[str, Any]", working_memory_raw)
root_raw: Any = working_memory.get("root", {})
if not isinstance(root_raw, dict):
- agent_error("stdin envelope has invalid 'working_memory.root': expected a dict", "JSONDecodeError")
+ agent_error("stdin envelope has invalid 'working_memory.root': expected a dict", error_type="JSONDecodeError")
root = cast("dict[str, Any]", root_raw)
aliases_raw: Any = working_memory.get("aliases", {})
@@ -115,6 +115,7 @@ def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]:
def parse_cli_inputs(
inputs_arg: str | None,
+ *,
stdin_fallback: bool = True,
auto_inputs_path: str | None = None,
) -> dict[str, Any] | None:
@@ -165,17 +166,17 @@ def _parse_inputs_arg(inputs_arg: str) -> dict[str, Any] | None:
result: dict[str, Any] = json.loads(inputs_arg)
return result
except json.JSONDecodeError as exc:
- agent_error(f"Failed to parse inline JSON inputs: {exc}", "JSONDecodeError", cause=exc)
+ agent_error(f"Failed to parse inline JSON inputs: {exc}", error_type="JSONDecodeError", cause=exc)
else:
try:
loaded = load_json_dict_from_path(Path(inputs_arg))
# Resolve relative url paths against the inputs file's parent directory
base_dir = Path(inputs_arg).parent.resolve()
- return resolve_inputs_paths(loaded, base_dir)
+ return resolve_inputs_paths(loaded, base_dir=base_dir)
except FileNotFoundError as exc:
- agent_error(f"Input file not found: {inputs_arg}", "FileNotFoundError", cause=exc)
+ agent_error(f"Input file not found: {inputs_arg}", error_type="FileNotFoundError", cause=exc)
except JsonTypeError as exc:
- agent_error(f"Input file must be a valid JSON dictionary: {inputs_arg}", "JsonTypeError", cause=exc)
+ agent_error(f"Input file must be a valid JSON dictionary: {inputs_arg}", error_type="JsonTypeError", cause=exc)
return None
@@ -196,10 +197,10 @@ def _read_stdin_inputs() -> dict[str, Any] | None:
try:
parsed: Any = json.loads(stdin_raw)
except json.JSONDecodeError as exc:
- agent_error(f"Failed to parse stdin JSON: {exc}", "JSONDecodeError", cause=exc)
+ agent_error(f"Failed to parse stdin JSON: {exc}", error_type="JSONDecodeError", cause=exc)
if not isinstance(parsed, dict):
- agent_error("stdin JSON must be a dictionary, got " + type(parsed).__name__, "JSONDecodeError")
+ agent_error("stdin JSON must be a dictionary, got " + type(parsed).__name__, error_type="JSONDecodeError")
parsed_dict = cast("dict[str, Any]", parsed)
return resolve_stdin_inputs(parsed_dict)
diff --git a/pipelex/cli/agent_cli/commands/validate/_validate_core.py b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
index caed29298..9bead12fe 100644
--- a/pipelex/cli/agent_cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/agent_cli/commands/validate/_validate_core.py
@@ -8,12 +8,14 @@ from pipelex.hub import (
clear_current_library,
get_current_library_id_or_none,
get_library_manager,
+ get_pipe_library,
get_required_pipe,
resolve_library_dirs,
set_current_library,
)
from pipelex.pipeline.bundle_validator import BundleValidator
-from pipelex.pipeline.validate_bundle import build_validated_pipes, validate_bundle
+from pipelex.pipeline.execution_seams import acquire_library
+from pipelex.pipeline.validate_bundle import build_pending_signatures, build_validated_pipes, validate_bundle
if TYPE_CHECKING:
from pathlib import Path
@@ -21,6 +23,7 @@ if TYPE_CHECKING:
async def validate_all_core(
library_dirs: list[Path] | None = None,
+ *,
allow_signatures: bool = False,
) -> dict[str, Any]:
"""Validate all pipes in all libraries.
@@ -36,25 +39,45 @@ async def validate_all_core(
Raises:
ValidateBundleError: If validation fails.
"""
- # acquire_and_validate opens a fresh library, loads the resolved dirs, sweeps every loaded pipe
- # (filtering signatures in strict mode), and tears the library down — the standalone validate-all
- # lifecycle (D6). The returned map is keyed by namespaced pipe_ref.
- dry_run_results = await BundleValidator().acquire_and_validate(
+ # This mirrors BundleValidator.acquire_and_validate's lifecycle (acquire → sweep → restore +
+ # teardown) inline rather than calling it, because `validate all` is strict-by-default on
+ # signatures and must read the LIBRARY-WIDE pending set BEFORE teardown — acquire_and_validate
+ # returns only the per-pipe status map and tears the library down before we could compute it.
+ prev_library_id = get_current_library_id_or_none()
+ acquired_id, _ = acquire_library(
+ library_id="",
library_dirs=[str(library_dir) for library_dir in library_dirs] if library_dirs else None,
- allow_signatures=allow_signatures,
)
-
- # No `pending_signatures` here by design — see validate_all in builder/operations/validate_ops.py:
- # it is a per-bundle top-down-build nudge surfaced only by `validate bundle`, not the whole-library sweep.
- return {
- "success": True,
- "validated_pipes": build_validated_pipes(dry_run_results),
- "total_pipes": len(dry_run_results),
- }
+ try:
+ # acquire_library left the freshly-acquired library current, so the inner sweep targets it
+ # (it filters signatures in strict mode itself). The returned map is keyed by namespaced pipe_ref.
+ dry_run_results = await BundleValidator().validate_current_library(allow_signatures=allow_signatures)
+
+ # pending_signatures is the library-wide set of still-unimplemented forward declarations;
+ # is_runnable = not pending. `validate all` now makes a strict runnability claim (the consumer
+ # gates the exit code on it unless --allow-signatures), so both keys ride the envelope.
+ pending_signatures = build_pending_signatures(get_pipe_library().get_pipes_dict())
+ return {
+ "success": True,
+ "is_valid": True,
+ "validated_pipes": build_validated_pipes(dry_run_results),
+ "total_pipes": len(dry_run_results),
+ "pending_signatures": pending_signatures,
+ "is_runnable": not pending_signatures,
+ }
+ finally:
+ # Restore the caller's outer current-library FIRST (so the guarantee survives a teardown
+ # raise), then tear the acquired library down — mirroring acquire_and_validate / validate_pipe_core.
+ if prev_library_id is not None:
+ set_current_library(library_id=prev_library_id)
+ else:
+ clear_current_library()
+ get_library_manager().teardown(library_id=acquired_id)
async def validate_bundle_core(
bundle_path: Path,
+ *,
library_dirs: list[Path] | None = None,
allow_signatures: bool = False,
) -> dict[str, Any]:
@@ -84,6 +107,7 @@ async def validate_bundle_core(
# successful lenient (--allow-signatures) run.
return {
"success": True,
+ "is_valid": True,
"bundle_path": str(bundle_path),
"validated_pipes": build_validated_pipes(result.dry_run_result),
"total_pipes": len(result.dry_run_result),
@@ -94,6 +118,7 @@ async def validate_bundle_core(
async def validate_pipe_core(
pipe_code: str,
+ *,
library_dirs: list[Path] | None = None,
allow_signatures: bool = False,
) -> dict[str, Any]:
@@ -128,6 +153,7 @@ async def validate_pipe_core(
return {
"success": True,
+ "is_valid": True,
"validated_pipes": build_validated_pipes(dry_run_results),
"total_pipes": len(dry_run_results),
}
@@ -145,6 +171,7 @@ async def validate_pipe_core(
async def validate_pipe_in_bundle_core(
+ *,
bundle_path: Path,
pipe_code: str,
library_dirs: list[Path] | None = None,
@@ -155,8 +182,11 @@ async def validate_pipe_in_bundle_core(
Loads the bundle's pipes into the library (so the requested pipe's dependencies resolve),
then dry-runs ONLY the requested pipe. Unrelated pipes — including unimplemented
`PipeSignature` placeholders — are loaded but not dry-run, so they do not block validating
- an implemented slice of a partially stubbed bundle. Strict mode is still enforced on the
- requested pipe: if it reaches a signature, validation fails.
+ an implemented slice of a partially stubbed bundle. Signatures are never an error (D-B): if the
+ requested pipe reaches one, it dry-runs trivially (the placeholder mints a mock); the unsatisfied
+ set is reported library-wide via `pending_signatures` / `is_runnable`, never raised. The caller
+ (`validate bundle`/`validate method` with `--pipe`) makes no library-wide runnability claim — it
+ surfaces `pending_signatures` for information but does not gate its exit code on it.
Args:
bundle_path: Path to the bundle file.
@@ -184,6 +214,7 @@ async def validate_pipe_in_bundle_core(
# library-wide set of still-unimplemented forward declarations.
return {
"success": True,
+ "is_valid": True,
"bundle_path": str(bundle_path),
"validated_pipes": build_validated_pipes(result.dry_run_result),
"total_pipes": len(result.dry_run_result),
diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
index a42bd5d36..33bf861b6 100644
--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
@@ -102,13 +102,13 @@ def validate_bundle_cmd(
else:
mthds_files = list(target_path.glob(f"*{MTHDS_EXTENSION}"))
if len(mthds_files) == 0:
- agent_error(f"No .mthds bundle file found in directory '{path}'", "FileNotFoundError")
+ agent_error(f"No .mthds bundle file found in directory '{path}'", error_type="FileNotFoundError")
if len(mthds_files) > 1:
mthds_names = ", ".join(mthds_file.name for mthds_file in mthds_files)
agent_error(
f"Multiple .mthds files found in '{path}' ({mthds_names}) and no '{DEFAULT_BUNDLE_FILE_NAME}'. "
f"Pass the .mthds file directly instead.",
- "ArgumentError",
+ error_type="ArgumentError",
)
bundle_path = str(mthds_files[0])
@@ -125,7 +125,7 @@ def validate_bundle_cmd(
agent_error(
f"'{path}' is not a .mthds file or directory. "
f"Use 'validate pipe <code>' for pipe codes, or 'validate bundle <path>' for .mthds files/directories.",
- "ArgumentError",
+ error_type="ArgumentError",
)
library_dirs = [Path(lib_dir) for lib_dir in library_dir] if library_dir else None
@@ -169,14 +169,14 @@ def validate_bundle_cmd(
if exc.__cause__:
graph_extra["cause_type"] = type(exc.__cause__).__name__
graph_extra["cause_message"] = str(exc.__cause__)
- agent_error(f"Graph generation failed: {exc.message}", "PipelineExecutionError", cause=exc, **graph_extra)
+ agent_error(f"Graph generation failed: {exc.message}", error_type="PipelineExecutionError", cause=exc, **graph_extra)
except PipelexInterpreterError as exc:
- agent_error(f"Graph generation failed: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Graph generation failed: {exc}", error_type=type(exc).__name__, cause=exc)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(f"Graph generation failed: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"Graph generation failed: {exc}", error_type=type(exc).__name__, cause=exc)
# Generate view (GraphSpec JSON) if requested and validation succeeded
if view:
@@ -197,34 +197,54 @@ def validate_bundle_cmd(
if exc.__cause__:
view_extra["cause_type"] = type(exc.__cause__).__name__
view_extra["cause_message"] = str(exc.__cause__)
- agent_error(f"View generation failed: {exc.message}", "PipelineExecutionError", cause=exc, **view_extra)
+ agent_error(f"View generation failed: {exc.message}", error_type="PipelineExecutionError", cause=exc, **view_extra)
except PipelexInterpreterError as exc:
- agent_error(f"View generation failed: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"View generation failed: {exc}", error_type=type(exc).__name__, cause=exc)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(f"View generation failed: {exc}", type(exc).__name__, cause=exc)
+ agent_error(f"View generation failed: {exc}", error_type=type(exc).__name__, cause=exc)
- agent_success_formatted(result, format_validate_markdown, output_format)
+ agent_success_formatted(result, markdown_renderer=format_validate_markdown, output_format=output_format)
+
+ # Gate-from-report (D-B consumer-decides): the bundle is valid, but unsatisfied PipeSignature
+ # placeholders make it NOT runnable. The success envelope (carrying pending_signatures +
+ # is_runnable) is already emitted above; the exit code — not a fabricated error item — reflects
+ # the gate. --allow-signatures tolerates the placeholders (exit 0). Re-raised by the
+ # `except typer.Exit` arm below so teardown still runs.
+ #
+ # Only the whole-bundle path gates: with --pipe, `result` is the slice envelope whose
+ # is_runnable derives from LIBRARY-WIDE pending_signatures, so gating there would fail a
+ # fully-implemented slice for unrelated placeholders elsewhere in the bundle. The slice makes
+ # no library-wide runnability claim (mirroring `validate pipe`), so it is not gated.
+ if not pipe and not allow_signatures and not result.get("is_runnable", True):
+ raise typer.Exit(1)
except PipeNotFoundError as exc:
- agent_error(str(exc), "PipeNotFoundError", cause=exc)
+ agent_error(str(exc), error_type="PipeNotFoundError", cause=exc)
except FileNotFoundError as exc:
- agent_error(f"Bundle file not found: {bundle_path}", "FileNotFoundError", cause=exc)
+ agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **extra)
+ # Invalid verdict: emit the structured failure envelope. validation_errors[] is the shared
+ # builder's output — non-empty on every invalid verdict (a residual dry-run failure rides one
+ # dry_run item, not a separate field). is_valid:false is the discriminant mirroring the success
+ # envelope; signatures never reach here (they are a runnability fact, gated above).
+ agent_error(
+ exc.message,
+ error_type="ValidateBundleError",
+ cause=exc,
+ is_valid=False,
+ bundle_path=str(bundle_path),
+ validation_errors=extract_validation_errors(exc),
+ )
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -240,14 +260,14 @@ def validate_bundle_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/validate/method_cmd.py b/pipelex/cli/agent_cli/commands/validate/method_cmd.py
index b2772474d..e7411dbcb 100644
--- a/pipelex/cli/agent_cli/commands/validate/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/method_cmd.py
@@ -76,7 +76,7 @@ def validate_method_cmd(
library_dirs=library_dir,
)
if not method.mthds_files:
- agent_error(f"Method '{name}' has no .mthds bundle files.", "MethodError")
+ agent_error(f"Method '{name}' has no .mthds bundle files.", error_type="MethodError")
bundle_path = method.mthds_files[0]
@@ -99,22 +99,39 @@ def validate_method_cmd(
# Validate the entire bundle
result = asyncio.run(validate_bundle_core(bundle_path=bundle_path, library_dirs=library_dirs_paths, allow_signatures=allow_signatures))
- agent_success_formatted(result, format_validate_markdown, output_format)
+ agent_success_formatted(result, markdown_renderer=format_validate_markdown, output_format=output_format)
+
+ # Gate-from-report (D-B consumer-decides): valid but NOT runnable when unsatisfied PipeSignature
+ # placeholders remain. The success envelope (with pending_signatures + is_runnable) is emitted
+ # above; the exit code reflects the gate. --allow-signatures tolerates them. Re-raised by the
+ # `except typer.Exit` arm below so teardown still runs.
+ #
+ # Only the whole-method path gates: with --pipe, `result` is the slice envelope whose
+ # is_runnable derives from LIBRARY-WIDE pending_signatures, so gating there would fail a
+ # fully-implemented slice for unrelated placeholders. The slice makes no library-wide
+ # runnability claim (mirroring `validate pipe`), so it is not gated.
+ if not pipe and not allow_signatures and not result.get("is_runnable", True):
+ raise typer.Exit(1)
except FileNotFoundError as exc:
- agent_error(f"Bundle file not found: {bundle_path}", "FileNotFoundError", cause=exc)
+ agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **extra)
+ # Invalid verdict (see bundle_cmd): structured failure envelope; validation_errors[] is the
+ # shared builder's output (a residual dry-run failure rides one dry_run item).
+ agent_error(
+ exc.message,
+ error_type="ValidateBundleError",
+ cause=exc,
+ is_valid=False,
+ bundle_path=str(bundle_path),
+ validation_errors=extract_validation_errors(exc),
+ )
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -130,11 +147,16 @@ def validate_method_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+
+ except typer.Exit:
+ # The runnability gate raises typer.Exit(1) after emitting the success envelope; let it
+ # propagate (exit code) rather than be reshaped into an agent_error by the broad handler below.
+ raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
index 6e64800be..0385bdfb6 100644
--- a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
@@ -75,25 +75,38 @@ def validate_pipe_cmd(
# Handle --all flag
if validate_all:
if pipe_code:
- agent_error("--all cannot be used with a pipe code", "ArgumentError")
+ agent_error("--all cannot be used with a pipe code", error_type="ArgumentError")
make_pipelex_for_agent_cli(library_dirs=library_dirs, needs_inference=False, needs_model_specs=True)
try:
result = asyncio.run(validate_all_core(library_dirs=library_dirs, allow_signatures=allow_signatures))
- agent_success_formatted(result, format_validate_markdown, output_format)
+ agent_success_formatted(result, markdown_renderer=format_validate_markdown, output_format=output_format)
+
+ # Gate-from-report (D-B consumer-decides): `validate all` is strict by default — the
+ # library is valid but NOT runnable while unsatisfied PipeSignature placeholders remain.
+ # The success envelope (carrying library-wide pending_signatures + is_runnable) is emitted
+ # above; the exit code reflects the gate. --allow-signatures tolerates them. Re-raised by
+ # the `except typer.Exit` arm below so teardown still runs.
+ if not allow_signatures and not result.get("is_runnable", True):
+ raise typer.Exit(1)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- validate_all_extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- validate_all_extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **validate_all_extra)
+ # Invalid verdict: structured failure envelope. validation_errors[] is the shared builder's
+ # output (a residual dry-run failure rides one dry_run item). Signatures are a runnability
+ # fact (pending_signatures + the gate above), not an error, so they never reach this arm.
+ agent_error(
+ exc.message,
+ error_type="ValidateBundleError",
+ cause=exc,
+ is_valid=False,
+ validation_errors=extract_validation_errors(exc),
+ )
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -103,15 +116,20 @@ def validate_pipe_cmd(
except PipeOperatorModelAvailabilityError as exc:
agent_error(
str(exc),
- "PipeOperatorModelAvailabilityError",
+ error_type="PipeOperatorModelAvailabilityError",
cause=exc,
pipe_code=exc.pipe_code,
model_handle=exc.model_handle,
)
+ except typer.Exit:
+ # The runnability gate raises typer.Exit(1) after emitting the success envelope; let it
+ # propagate (exit code) rather than be reshaped into an agent_error by the broad handler below.
+ raise
+
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
@@ -120,7 +138,7 @@ def validate_pipe_cmd(
if not pipe_code:
agent_error(
"No pipe code specified. Use --all to validate all pipes, or use 'validate bundle <path>' for bundle files.",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Helpful error if the user passes a path instead of a pipe code
@@ -129,7 +147,7 @@ def validate_pipe_cmd(
agent_error(
f"'{pipe_code}' looks like a file path or directory. "
f"Use 'validate bundle {pipe_code}' for bundles/directories, or 'validate pipe <code>' for pipe codes.",
- "ArgumentError",
+ error_type="ArgumentError",
)
# Check installed methods' exports for additional library dirs
@@ -138,7 +156,7 @@ def validate_pipe_cmd(
except ValueError as exc:
agent_error(
f"Ambiguous pipe code '{pipe_code}': {exc}",
- "ArgumentError",
+ error_type="ArgumentError",
cause=exc,
)
if export_dirs:
@@ -152,25 +170,29 @@ def validate_pipe_cmd(
try:
result = asyncio.run(validate_pipe_core(pipe_code=pipe_code, library_dirs=library_dirs, allow_signatures=allow_signatures))
- agent_success_formatted(result, format_validate_markdown, output_format)
+ agent_success_formatted(result, markdown_renderer=format_validate_markdown, output_format=output_format)
except PipeNotFoundError as exc:
error_message = str(exc)
if pipe_code == "all":
error_message += " Did you mean '--all'?"
- agent_error(error_message, "PipeNotFoundError", cause=exc)
+ agent_error(error_message, error_type="PipeNotFoundError", cause=exc)
except ValidateBundleError as exc:
- validation_errors = extract_validation_errors(exc)
- extra: dict[str, Any] = {"validation_errors": validation_errors}
- if exc.dry_run_error_message:
- extra["dry_run_error"] = exc.dry_run_error_message
- agent_error(exc.message, "ValidateBundleError", cause=exc, **extra)
+ # Invalid verdict (see the --all arm): structured failure envelope; validation_errors[] is the
+ # shared builder's output (a residual dry-run failure rides one dry_run item).
+ agent_error(
+ exc.message,
+ error_type="ValidateBundleError",
+ cause=exc,
+ is_valid=False,
+ validation_errors=extract_validation_errors(exc),
+ )
except PipeOperatorModelChoiceError as exc:
agent_error(
exc.message,
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=exc,
pipe_code=exc.pipe_code,
model_type=str(exc.model_type),
@@ -186,14 +208,14 @@ def validate_pipe_cmd(
availability_extra["fallback_list"] = exc.fallback_list
if exc.pipe_stack:
availability_extra["pipe_stack"] = exc.pipe_stack
- agent_error(exc.message, "PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)
except typer.Exit:
raise
except Exception as exc: # noqa: BLE001
# Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.
- agent_error(str(exc), type(exc).__name__, cause=exc)
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc)
finally:
Pipelex.teardown_if_needed()
diff --git a/pipelex/cli/cli_factory.py b/pipelex/cli/cli_factory.py
index 3b8650929..13d5d095b 100644
--- a/pipelex/cli/cli_factory.py
+++ b/pipelex/cli/cli_factory.py
@@ -29,6 +29,7 @@ from pipelex.system.telemetry.exceptions import TelemetryConfigValidationError
def make_pipelex_for_cli(
+ *,
context: ErrorContext,
library_dirs: list[str] | list[Path] | None = None,
needs_inference: bool = True,
diff --git a/pipelex/cli/commands/build/inputs/_inputs_core.py b/pipelex/cli/commands/build/inputs/_inputs_core.py
index 5abe52805..3f1e18c72 100644
--- a/pipelex/cli/commands/build/inputs/_inputs_core.py
+++ b/pipelex/cli/commands/build/inputs/_inputs_core.py
@@ -34,6 +34,7 @@ SUB_COMMAND_INPUTS = "inputs"
async def _generate_inputs_core(
pipe_code: str | None = None,
+ *,
bundle_path: Path | None = None,
output_path: Path | None = None,
library_dir: list[str] | None = None,
@@ -114,6 +115,7 @@ async def _generate_inputs_core(
def execute_generate_inputs(
pipe_code: str | None,
+ *,
bundle_path: Path | None,
output_path: Path | None,
library_dir: list[str] | None = None,
diff --git a/pipelex/cli/commands/build/output/_output_core.py b/pipelex/cli/commands/build/output/_output_core.py
index cd9e67226..2984fb243 100644
--- a/pipelex/cli/commands/build/output/_output_core.py
+++ b/pipelex/cli/commands/build/output/_output_core.py
@@ -34,6 +34,7 @@ SUB_COMMAND_OUTPUT = "output"
async def _generate_output_core(
pipe_code: str | None = None,
+ *,
bundle_path: Path | None = None,
output_path: Path | None = None,
output_format: ConceptRepresentationFormat = ConceptRepresentationFormat.JSON,
@@ -128,6 +129,7 @@ async def _generate_output_core(
def execute_generate_output(
pipe_code: str | None,
+ *,
bundle_path: Path | None,
output_path: Path | None,
output_format: ConceptRepresentationFormat,
diff --git a/pipelex/cli/commands/build/runner/_runner_core.py b/pipelex/cli/commands/build/runner/_runner_core.py
index 85996c552..24eac0587 100644
--- a/pipelex/cli/commands/build/runner/_runner_core.py
+++ b/pipelex/cli/commands/build/runner/_runner_core.py
@@ -51,6 +51,7 @@ SUB_COMMAND_RUNNER = "runner"
async def _prepare_runner_core(
pipe_code: str | None = None,
+ *,
bundle_path: Path | None = None,
output_path: Path | None = None,
library_dirs: list[Path] | None = None,
@@ -173,6 +174,7 @@ async def _prepare_runner_core(
def execute_prepare_runner(
pipe_code: str | None,
+ *,
bundle_path: Path | None,
output_path: Path | None,
library_dirs: list[Path] | None = None,
diff --git a/pipelex/cli/commands/build/structures_cmd.py b/pipelex/cli/commands/build/structures_cmd.py
index 3f8296aa0..f5cc6c0df 100644
--- a/pipelex/cli/commands/build/structures_cmd.py
+++ b/pipelex/cli/commands/build/structures_cmd.py
@@ -49,6 +49,7 @@ def _compute_relative_path_from_output_dir(output_directory: Path) -> Path | Non
def _build_concept_ref_to_class_info(
blueprints: list["PipelexBundleBlueprint"],
+ *,
output_directory: Path,
) -> dict[str, ConceptClassInfo]:
"""Build a mapping from concept refs to their class info including module paths.
@@ -78,9 +79,9 @@ def _build_concept_ref_to_class_info(
# concept_code (i.e. no user-supplied structure class reference), qualify
# it with the domain so cross-class imports/types match the qualified
# class definitions emitted below.
- raw_class_name = get_structure_class_name_from_blueprint(concept_blueprint, concept_code)
+ raw_class_name = get_structure_class_name_from_blueprint(concept_blueprint, concept_ref_or_code=concept_code)
if raw_class_name == concept_code:
- class_name = make_qualified_structure_class_name(blueprint.domain, concept_code)
+ class_name = make_qualified_structure_class_name(domain_code=blueprint.domain, concept_code=concept_code)
file_stem_snake_case = pascal_case_to_snake_case(concept_code)
else:
class_name = raw_class_name
@@ -103,6 +104,7 @@ def _build_concept_ref_to_class_info(
def generate_structures_from_blueprints(
blueprints: list["PipelexBundleBlueprint"],
+ *,
output_directory: Path,
target_path: Path | None = None,
skip_existing_check: bool = False,
@@ -123,7 +125,7 @@ def generate_structures_from_blueprints(
output_directory.mkdir(parents=True, exist_ok=True)
# Build concept_ref_to_class_info mapping for all concepts
- concept_ref_to_class_info = _build_concept_ref_to_class_info(blueprints, output_directory)
+ concept_ref_to_class_info = _build_concept_ref_to_class_info(blueprints, output_directory=output_directory)
class_registry = get_class_registry()
# Only check for existing classes if we're not skipping and have a target path
@@ -167,7 +169,7 @@ def generate_structures_from_blueprints(
generated_code, _ = StructureGenerator(
concept_ref_to_class_info=concept_ref_to_class_info, local_domain=blueprint.domain
).generate_from_structure_blueprint(
- class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),
+ class_name=make_qualified_structure_class_name(domain_code=blueprint.domain, concept_code=concept_code),
structure_blueprint={},
base_class_name=TextContent.__name__,
description=concept_blueprint,
@@ -197,7 +199,7 @@ def generate_structures_from_blueprints(
concept_ref_to_class_info=concept_ref_to_class_info,
local_domain=blueprint.domain,
).generate_from_structure_blueprint(
- class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),
+ class_name=make_qualified_structure_class_name(domain_code=blueprint.domain, concept_code=concept_code),
structure_blueprint=normalized_structure,
description=concept_blueprint.description,
)
@@ -231,7 +233,9 @@ def generate_structures_from_blueprints(
refined_structure_class_name = refined_concept_code + "Content"
else:
refined_domain_code = refined_ref.domain_path or blueprint.domain
- refined_structure_class_name = make_qualified_structure_class_name(refined_domain_code, refined_concept_code)
+ refined_structure_class_name = make_qualified_structure_class_name(
+ domain_code=refined_domain_code, concept_code=refined_concept_code
+ )
else:
refined_structure_class_name = TextContent.__name__
@@ -240,7 +244,7 @@ def generate_structures_from_blueprints(
concept_ref_to_class_info=concept_ref_to_class_info,
local_domain=blueprint.domain,
).generate_from_structure_blueprint(
- class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),
+ class_name=make_qualified_structure_class_name(domain_code=blueprint.domain, concept_code=concept_code),
structure_blueprint={},
base_class_name=refined_structure_class_name,
description=concept_blueprint.description,
@@ -271,7 +275,7 @@ def generate_structures_from_blueprints(
concept_ref_to_class_info=concept_ref_to_class_info,
local_domain=blueprint.domain,
).generate_from_structure_blueprint(
- class_name=make_qualified_structure_class_name(blueprint.domain, concept_code),
+ class_name=make_qualified_structure_class_name(domain_code=blueprint.domain, concept_code=concept_code),
structure_blueprint={},
base_class_name=TextContent.__name__,
description=concept_blueprint.description,
diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.py
index 087f2b350..bcc4dcef7 100644
--- a/pipelex/cli/commands/doctor_cmd.py
+++ b/pipelex/cli/commands/doctor_cmd.py
@@ -288,7 +288,7 @@ def check_kit_template_exists(backend_name: str) -> bool:
return False
-def replace_backend_file(backend_name: str, dry_run: bool = False, config_dir: Path | None = None) -> bool:
+def replace_backend_file(backend_name: str, *, dry_run: bool = False, config_dir: Path | None = None) -> bool:
"""Replace a backend configuration file with the kit template.
Args:
@@ -436,6 +436,7 @@ def check_backend_files(config_dir: Path | None = None) -> tuple[bool, dict[str,
def display_health_report(
+ *,
config_healthy: bool,
config_message: str,
config_missing_count: int,
@@ -739,6 +740,7 @@ def check_deck_sync(config_dir: Path | None = None) -> tuple[bool, DeckSyncRepor
def setup_doctor_runtime(
log_config_overrides: Mapping[str, Any] | None = None,
+ *,
config_dir: Path | None = None,
) -> None:
"""Spin up a fresh PipelexHub and configure logging for doctor checks.
@@ -785,7 +787,7 @@ def setup_doctor_runtime(
log_config = get_config().pipelex.log_config
if log_config_overrides is not None:
merged = log_config.model_dump()
- deep_update(merged, log_config_overrides)
+ deep_update(merged, updates=log_config_overrides)
log_config = LogConfig.model_validate(merged)
pipelex_hub.set_console_print_target(target=log_config.console_print_target)
log.configure_if_unset(log_config=log_config)
diff --git a/pipelex/cli/commands/graph_cmd.py b/pipelex/cli/commands/graph_cmd.py
index bdff1e2bb..4363d3b93 100644
--- a/pipelex/cli/commands/graph_cmd.py
+++ b/pipelex/cli/commands/graph_cmd.py
@@ -37,6 +37,7 @@ graph_app = typer.Typer(no_args_is_help=True)
def _do_graph_render(
input_file: Path,
+ *,
out: str | None,
direction: FlowchartDirection | None,
mermaidflow: bool,
diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.py
index 634ab6746..2bf4234bb 100644
--- a/pipelex/cli/commands/init/backends.py
+++ b/pipelex/cli/commands/init/backends.py
@@ -28,7 +28,7 @@ from pipelex.system.pipelex_service.pipelex_service_agreement import update_serv
from pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_with_tomlkit, save_toml_to_path
-def update_backends_in_toml(toml_doc: Any, selected_indices: list[int], backend_options: list[tuple[str, str]]) -> None:
+def update_backends_in_toml(toml_doc: Any, *, selected_indices: list[int], backend_options: list[tuple[str, str]]) -> None:
"""Update the backends.toml document with selected backends.
Args:
@@ -86,10 +86,10 @@ def disable_gateway_backend(backends_toml_path: Path) -> None:
if PipelexBackend.GATEWAY in toml_doc:
toml_doc[PipelexBackend.GATEWAY]["enabled"] = False # type: ignore[index]
- save_toml_to_path(toml_doc, backends_toml_path)
+ save_toml_to_path(toml_doc, path=backends_toml_path)
-def customize_backends_config(is_first_time_setup: bool = False, target_config_dir: Path | None = None) -> None:
+def customize_backends_config(*, is_first_time_setup: bool = False, target_config_dir: Path | None = None) -> None:
"""Interactively customize which inference backends are enabled in backends.toml.
Args:
@@ -108,10 +108,10 @@ def customize_backends_config(is_first_time_setup: bool = False, target_config_d
try:
# Get backend options from template and existing config
existing_path = backends_toml_path if backends_toml_path.exists() else None
- backend_options = get_backend_options_from_toml(template_backends_path, existing_path)
+ backend_options = get_backend_options_from_toml(template_backends_path, existing_path=existing_path)
# Get currently enabled backends to show user their current selection
- currently_enabled = get_currently_enabled_backends(backends_toml_path, backend_options)
+ currently_enabled = get_currently_enabled_backends(backends_toml_path, backend_options=backend_options)
# If this is first-time setup, ignore what's in the template (all enabled)
# and use only pipelex_gateway as the default
@@ -123,7 +123,7 @@ def customize_backends_config(is_first_time_setup: bool = False, target_config_d
console.print()
# UI: Display panel and get user selection
- console.print(build_backend_selection_panel(backend_options, currently_enabled, is_first_time_setup))
+ console.print(build_backend_selection_panel(backend_options, currently_enabled=currently_enabled, is_first_time_setup=is_first_time_setup))
selected_indices, selected_backends = prompt_backend_select(
console=console,
backend_options=backend_options,
@@ -154,11 +154,11 @@ def customize_backends_config(is_first_time_setup: bool = False, target_config_d
selected_indices = [idx for idx in selected_indices if backend_options[idx][0] != PipelexBackend.GATEWAY]
# Business logic: Update and save backends.toml first (local operation)
- update_backends_in_toml(toml_doc, selected_indices, backend_options)
- save_toml_to_path(toml_doc, backends_toml_path)
+ update_backends_in_toml(toml_doc, selected_indices=selected_indices, backend_options=backend_options)
+ save_toml_to_path(toml_doc, path=backends_toml_path)
# UI: Display confirmation
- display_selected_backends(console, selected_indices, backend_options)
+ display_selected_backends(console=console, selected_indices=selected_indices, backend_options=backend_options)
# Save gateway terms acceptance to global config (separate from backends save)
if gateway_terms_accepted is not None:
diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.py
index db95bbc30..488d5b447 100644
--- a/pipelex/cli/commands/init/command.py
+++ b/pipelex/cli/commands/init/command.py
@@ -126,7 +126,7 @@ def attempt_prime_remote_config_cache(target_config_dir: Path | None = None) ->
return CachePrimingResult(primed=True)
-def prime_remote_config_cache(console: Console, target_config_dir: Path | None = None) -> None:
+def prime_remote_config_cache(console: Console, *, target_config_dir: Path | None = None) -> None:
"""Interactive-surface wrapper around :func:`attempt_prime_remote_config_cache`.
Prints a yellow warning to the console when a fetch was attempted and failed; otherwise
@@ -141,7 +141,7 @@ def prime_remote_config_cache(console: Console, target_config_dir: Path | None =
console.print("[dim]Re-run 'pipelex init' while online to prime the cache for offline dry-runs.[/dim]")
-def _check_gateway_terms_if_needed(console: Console, backends_toml_path: Path) -> None:
+def _check_gateway_terms_if_needed(console: Console, *, backends_toml_path: Path) -> None:
"""Check if gateway is enabled and terms not yet accepted, then prompt for acceptance.
This is called after init_config() to ensure users who have gateway enabled
@@ -180,6 +180,7 @@ def _check_gateway_terms_if_needed(console: Console, backends_toml_path: Path) -
def determine_needs(
+ *,
reset: bool,
check_config: bool,
check_inference: bool,
@@ -217,6 +218,7 @@ def determine_needs(
def confirm_initialization(
console: Console,
+ *,
needs_config: bool,
needs_inference: bool,
needs_routing: bool,
@@ -244,7 +246,16 @@ def confirm_initialization(
typer.Exit: If user cancels initialization.
"""
console.print()
- console.print(build_initialization_panel(needs_config, needs_inference, needs_routing, needs_telemetry, reset, check_credentials))
+ console.print(
+ build_initialization_panel(
+ needs_config,
+ needs_inference=needs_inference,
+ needs_routing=needs_routing,
+ needs_telemetry=needs_telemetry,
+ reset=reset,
+ check_credentials=check_credentials,
+ )
+ )
if not Confirm.ask("[bold]Continue with initialization?[/bold]", default=True):
console.print("\n[yellow]Initialization cancelled.[/yellow]")
@@ -265,6 +276,7 @@ def confirm_initialization(
def execute_initialization(
console: Console,
+ *,
needs_config: bool,
needs_inference: bool,
needs_routing: bool,
@@ -317,7 +329,7 @@ def execute_initialization(
# If we're NOT going to run customize_backends_config (which handles gateway terms),
# we need to check if gateway is enabled and terms not accepted
if not needs_inference and backends_existed_before:
- _check_gateway_terms_if_needed(console, backends_toml_path)
+ _check_gateway_terms_if_needed(console, backends_toml_path=backends_toml_path)
# Determine if this is truly a first-time setup
first_time_setup = is_first_time_backends_setup
@@ -357,7 +369,7 @@ def execute_initialization(
# Stamp the deck manifest so future updates can detect drift and
# `pipelex update` knows the exact kit version this install came from.
- write_manifest(target_deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=target_deck_dir)
# Reset routing_profiles.toml
template_routing_path = template_inference_dir / "routing_profiles.toml"
@@ -378,7 +390,7 @@ def execute_initialization(
# Step 2.5: Prompt for missing credentials
if check_credentials:
- prompt_credentials(console, backends_toml_path)
+ prompt_credentials(console, backends_toml_path=backends_toml_path)
# Step 3: Set up routing profile if specifically requested
if needs_routing:
@@ -401,7 +413,7 @@ def execute_initialization(
# Step 4: Set up telemetry if needed
if needs_telemetry:
- setup_telemetry(console, telemetry_config_path, for_project=for_project)
+ setup_telemetry(console=console, telemetry_config_path=telemetry_config_path, for_project=for_project)
# Step 5: Prime the remote-config cache so dry-runs and validate can fall back offline.
# No-op when gateway is disabled or terms have not been accepted. We forward
@@ -465,6 +477,7 @@ def _init_agreement(console: Console) -> None:
def init_cmd(
focus: InitFocus = InitFocus.ALL,
+ *,
skip_confirmation: bool = False,
local: bool = False,
):
@@ -493,7 +506,7 @@ def init_cmd(
console.print("[yellow]No backends.toml found. Please run 'pipelex init' first.[/yellow]")
console.print()
return
- prompt_credentials(console, backends_toml_path)
+ prompt_credentials(console, backends_toml_path=backends_toml_path)
console.print()
return
diff --git a/pipelex/cli/commands/init/config_files.py b/pipelex/cli/commands/init/config_files.py
index 9a4b8f339..32ce95971 100644
--- a/pipelex/cli/commands/init/config_files.py
+++ b/pipelex/cli/commands/init/config_files.py
@@ -17,7 +17,7 @@ INIT_SKIP_FILES: frozenset[str] = GIT_IGNORED_CONFIG_FILES | {TELEMETRY_CONFIG_F
INIT_SKIP_DIRS: frozenset[str] = frozenset({"inference"})
-def init_config(reset: bool = False, dry_run: bool = False, target_dir: Path | None = None) -> int:
+def init_config(reset: bool = False, *, dry_run: bool = False, target_dir: Path | None = None) -> int:
"""Initialize pipelex configuration in the .pipelex directory. Does not install telemetry, just the main config and inference backends.
Args:
@@ -37,7 +37,7 @@ def init_config(reset: bool = False, dry_run: bool = False, target_dir: Path | N
copied_files: list[str] = []
existing_files: list[str] = []
- def copy_directory_structure(src_dir: Path, dst_dir: Path, relative_path: Path | None = None, dry_run: bool = False) -> None:
+ def copy_directory_structure(*, src_dir: Path, dst_dir: Path, relative_path: Path | None = None, dry_run: bool = False) -> None:
"""Recursively copy directory structure, handling existing files."""
for src_item in src_dir.iterdir():
item = src_item.name
@@ -53,7 +53,7 @@ def init_config(reset: bool = False, dry_run: bool = False, target_dir: Path | N
continue
if not dry_run:
dst_item.mkdir(parents=True, exist_ok=True)
- copy_directory_structure(src_item, dst_item, relative_item, dry_run)
+ copy_directory_structure(src_dir=src_item, dst_dir=dst_item, relative_path=relative_item, dry_run=dry_run)
elif dst_item.exists() and not reset:
existing_files.append(relative_item.as_posix())
else:
diff --git a/pipelex/cli/commands/init/credentials.py b/pipelex/cli/commands/init/credentials.py
index 33ddd46c6..c7ab5b57a 100644
--- a/pipelex/cli/commands/init/credentials.py
+++ b/pipelex/cli/commands/init/credentials.py
@@ -45,7 +45,7 @@ def read_env_file(env_path: Path) -> dict[str, str]:
return entries
-def write_env_file(env_path: Path, entries: dict[str, str]) -> None:
+def write_env_file(env_path: Path, *, entries: dict[str, str]) -> None:
"""Write key-value pairs to a .env file with a header comment.
Creates parent directories if needed. Sets file permissions to 0600 (user-only).
@@ -101,7 +101,7 @@ def get_required_vars_for_enabled_backends(backends_toml_path: Path) -> dict[str
return var_to_backends
-def prompt_credentials(console: Console, backends_toml_path: Path) -> None:
+def prompt_credentials(console: Console, *, backends_toml_path: Path) -> None:
"""Prompt the user for missing credentials and persist them to ~/.pipelex/.env.
Reads the backends.toml to find which env vars are needed by enabled backends,
@@ -146,7 +146,7 @@ def prompt_credentials(console: Console, backends_toml_path: Path) -> None:
collected_count += 1
if collected_count > 0:
- write_env_file(global_env_path, entries)
+ write_env_file(global_env_path, entries=entries)
console.print()
console.print(f"[green]Saved {collected_count} credential(s) to {global_env_path}[/green]")
else:
diff --git a/pipelex/cli/commands/init/ide_extension.py b/pipelex/cli/commands/init/ide_extension.py
index eade2cf62..91a0a9424 100644
--- a/pipelex/cli/commands/init/ide_extension.py
+++ b/pipelex/cli/commands/init/ide_extension.py
@@ -53,7 +53,7 @@ def _get_available_ide_commands() -> dict[str, dict[str, str]]:
return {ide_name: info for ide_name, info in _IDE_INFO.items() if shutil.which(info["cmd"]) is not None}
-def _install_extension(ide_name: str, cmd: str, console: Console) -> bool:
+def _install_extension(ide_name: str, *, cmd: str, console: Console) -> bool:
"""Install the Pipelex extension for a given IDE.
Args:
@@ -114,6 +114,6 @@ def suggest_extension_install_if_needed(console: Console) -> None:
if install:
for ide_name, info in ides_needing_install.items():
- _install_extension(ide_name, info["cmd"], console)
+ _install_extension(ide_name, cmd=info["cmd"], console=console)
else:
console.print("[dim]You can install it later from the IDE marketplace or the links above.[/dim]")
diff --git a/pipelex/cli/commands/init/routing.py b/pipelex/cli/commands/init/routing.py
index bfe377dda..3962b2f06 100644
--- a/pipelex/cli/commands/init/routing.py
+++ b/pipelex/cli/commands/init/routing.py
@@ -23,7 +23,7 @@ from pipelex.system.configuration.config_loader import config_manager
from pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path
-def customize_routing_profile(selected_backend_keys: list[str], target_config_dir: Path | None = None) -> None:
+def customize_routing_profile(selected_backend_keys: list[str], *, target_config_dir: Path | None = None) -> None:
"""Interactively customize routing profile based on selected backends.
Args:
@@ -49,13 +49,13 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_di
# Get backend options for display names
template_backends_path = Path(str(get_kit_configs_dir() / "inference" / "backends.toml"))
- backend_options = get_backend_options_from_toml(template_backends_path, backends_toml_path)
+ backend_options = get_backend_options_from_toml(template_backends_path, existing_path=backends_toml_path)
# Case 1: pipelex_gateway is enabled - use all_pipelex_gateway
if PipelexBackend.GATEWAY in selected_backend_keys:
toml_doc["active"] = PipelexRoutingProfile.ALL_PIPELEX_GATEWAY
- save_toml_to_path(toml_doc, routing_profiles_toml_path)
- display_routing_profile_result(console, PipelexRoutingProfile.ALL_PIPELEX_GATEWAY, created=False)
+ save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
+ display_routing_profile_result(console, profile_name=PipelexRoutingProfile.ALL_PIPELEX_GATEWAY, created=False)
return
# Case 2: Only one backend selected - use all_{backend_key} profile
@@ -88,8 +88,8 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_di
# Set as active profile
toml_doc["active"] = profile_name
- save_toml_to_path(toml_doc, routing_profiles_toml_path)
- display_routing_profile_result(console, profile_name, created=not profile_exists)
+ save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
+ display_routing_profile_result(console, profile_name=profile_name, created=not profile_exists)
return
# Case 3: Multiple backends (no pipelex_gateway) - create/update custom_routing profile
@@ -98,8 +98,8 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_di
console.print()
# Show panel and prompt for primary backend
- console.print(build_primary_backend_panel(selected_backend_keys, backend_options))
- primary_backend = prompt_primary_backend(console, selected_backend_keys)
+ console.print(build_primary_backend_panel(selected_backend_keys, backend_options=backend_options))
+ primary_backend = prompt_primary_backend(console=console, backend_keys=selected_backend_keys)
# Prompt for fallback order if there are 2+ remaining backends
remaining_backends = [b for b in selected_backend_keys if b != primary_backend]
@@ -107,9 +107,9 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_di
if len(remaining_backends) >= 2:
console.print()
- console.print(build_fallback_order_panel(remaining_backends, backend_options))
+ console.print(build_fallback_order_panel(remaining_backends, backend_options=backend_options))
# Get the ordered remaining backends from user (default keeps current order)
- ordered_remaining = prompt_fallback_order(console, remaining_backends, backend_options)
+ ordered_remaining = prompt_fallback_order(console, remaining_backends=remaining_backends, backend_options=backend_options)
fallback_order = [primary_backend, *ordered_remaining]
elif len(remaining_backends) == 1:
# Only one remaining backend - set fallback_order with primary first
@@ -144,8 +144,8 @@ def customize_routing_profile(selected_backend_keys: list[str], target_config_di
toml_doc["profiles"] = new_profiles # type: ignore[assignment]
toml_doc["active"] = "custom_routing"
- save_toml_to_path(toml_doc, routing_profiles_toml_path)
- display_routing_profile_result(console, "custom_routing", created=True)
+ save_toml_to_path(toml_doc, path=routing_profiles_toml_path)
+ display_routing_profile_result(console, profile_name="custom_routing", created=True)
# Inform user about customization options
console.print("[dim]You can find your custom routing profile in:[/dim]")
diff --git a/pipelex/cli/commands/init/telemetry.py b/pipelex/cli/commands/init/telemetry.py
index 716975f55..da0c79bdf 100644
--- a/pipelex/cli/commands/init/telemetry.py
+++ b/pipelex/cli/commands/init/telemetry.py
@@ -9,7 +9,7 @@ from pipelex.kit.paths import get_kit_configs_dir
from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TELEMETRY_PROJECT_TEMPLATE_FILE_NAME
-def setup_telemetry(console: Console, telemetry_config_path: Path, for_project: bool) -> None:
+def setup_telemetry(*, console: Console, telemetry_config_path: Path, for_project: bool) -> None:
"""Set up telemetry configuration by copying the appropriate kit template.
The global template (`telemetry.toml`) carries active defaults and seeds
diff --git a/pipelex/cli/commands/init/ui/backends_ui.py b/pipelex/cli/commands/init/ui/backends_ui.py
index 46803096a..81ea68fe4 100644
--- a/pipelex/cli/commands/init/ui/backends_ui.py
+++ b/pipelex/cli/commands/init/ui/backends_ui.py
@@ -14,7 +14,7 @@ from pipelex.tools.misc.string_utils import snake_to_capitalize_first_letter
from pipelex.tools.misc.toml_utils import load_toml_from_path
-def get_backend_options_from_toml(template_path: Path, existing_path: Path | None = None) -> list[tuple[str, str]]:
+def get_backend_options_from_toml(template_path: Path, *, existing_path: Path | None = None) -> list[tuple[str, str]]:
"""Get backend options dynamically from TOML files.
Args:
@@ -58,7 +58,7 @@ def get_backend_options_from_toml(template_path: Path, existing_path: Path | Non
return backend_options
-def get_currently_enabled_backends(backends_toml_path: Path, backend_options: list[tuple[str, str]]) -> list[int]:
+def get_currently_enabled_backends(backends_toml_path: Path, *, backend_options: list[tuple[str, str]]) -> list[int]:
"""Get list of currently enabled backend indices from existing backends.toml.
Args:
@@ -95,7 +95,7 @@ def get_currently_enabled_backends(backends_toml_path: Path, backend_options: li
def build_backend_selection_panel(
- backend_options: list[tuple[str, str]], currently_enabled: list[int] | None = None, is_first_time_setup: bool = False
+ backend_options: list[tuple[str, str]], *, currently_enabled: list[int] | None = None, is_first_time_setup: bool = False
) -> Panel:
"""Create a Rich Panel for backend selection with options table.
@@ -154,6 +154,7 @@ def build_backend_selection_panel(
def prompt_backend_select(
console: Console,
+ *,
backend_options: list[tuple[str, str]],
currently_enabled: list[int] | None = None,
is_first_time_setup: bool = False,
@@ -236,7 +237,7 @@ def prompt_backend_select(
return selected_indices, selected_backend_keys
-def display_selected_backends(console: Console, selected_indices: list[int], backend_options: list[tuple[str, str]]) -> None:
+def display_selected_backends(*, console: Console, selected_indices: list[int], backend_options: list[tuple[str, str]]) -> None:
"""Display confirmation of selected backends.
Args:
diff --git a/pipelex/cli/commands/init/ui/general_ui.py b/pipelex/cli/commands/init/ui/general_ui.py
index bd321187a..80a86feb9 100644
--- a/pipelex/cli/commands/init/ui/general_ui.py
+++ b/pipelex/cli/commands/init/ui/general_ui.py
@@ -5,6 +5,7 @@ from rich.panel import Panel
def build_initialization_panel(
needs_config: bool,
+ *,
needs_inference: bool,
needs_routing: bool,
needs_telemetry: bool,
diff --git a/pipelex/cli/commands/init/ui/routing_ui.py b/pipelex/cli/commands/init/ui/routing_ui.py
index 1f083293a..9efa7dbeb 100644
--- a/pipelex/cli/commands/init/ui/routing_ui.py
+++ b/pipelex/cli/commands/init/ui/routing_ui.py
@@ -10,7 +10,7 @@ from rich.text import Text
from pipelex.tools.misc.string_utils import snake_to_capitalize_first_letter
-def build_primary_backend_panel(backend_keys: list[str], backend_options: list[tuple[str, str]]) -> Panel:
+def build_primary_backend_panel(backend_keys: list[str], *, backend_options: list[tuple[str, str]]) -> Panel:
"""Build a panel for selecting a primary backend from enabled backends.
Args:
@@ -45,7 +45,7 @@ def build_primary_backend_panel(backend_keys: list[str], backend_options: list[t
)
-def prompt_primary_backend(console: Console, backend_keys: list[str]) -> str:
+def prompt_primary_backend(*, console: Console, backend_keys: list[str]) -> str:
"""Prompt user to select a primary backend from enabled backends.
Args:
@@ -88,7 +88,7 @@ def prompt_primary_backend(console: Console, backend_keys: list[str]) -> str:
return selected_backend
-def build_fallback_order_panel(remaining_backends: list[str], backend_options: list[tuple[str, str]]) -> Panel:
+def build_fallback_order_panel(remaining_backends: list[str], *, backend_options: list[tuple[str, str]]) -> Panel:
"""Build a panel explaining fallback order configuration.
Args:
@@ -124,7 +124,7 @@ def build_fallback_order_panel(remaining_backends: list[str], backend_options: l
)
-def prompt_fallback_order(console: Console, remaining_backends: list[str], backend_options: list[tuple[str, str]]) -> list[str]:
+def prompt_fallback_order(console: Console, *, remaining_backends: list[str], backend_options: list[tuple[str, str]]) -> list[str]:
"""Prompt user to order the remaining backends for fallback.
Args:
@@ -195,7 +195,7 @@ def prompt_fallback_order(console: Console, remaining_backends: list[str], backe
return fallback_order
-def display_routing_profile_result(console: Console, profile_name: str, created: bool = False) -> None:
+def display_routing_profile_result(console: Console, *, profile_name: str, created: bool = False) -> None:
"""Display confirmation of routing profile configuration.
Args:
diff --git a/pipelex/cli/commands/login/command.py b/pipelex/cli/commands/login/command.py
index 43b99facd..9c9ebbc91 100644
--- a/pipelex/cli/commands/login/command.py
+++ b/pipelex/cli/commands/login/command.py
@@ -84,7 +84,7 @@ def login_cmd() -> None:
webbrowser.open(auth_url)
server.timeout = LOGIN_TIMEOUT_SECONDS
- server_thread = threading.Thread(target=serve_until_callback, args=(server, result), daemon=True)
+ server_thread = threading.Thread(target=serve_until_callback, args=(server,), kwargs={"result": result}, daemon=True)
server_thread.start()
server_thread.join(timeout=LOGIN_TIMEOUT_SECONDS)
@@ -102,7 +102,7 @@ def login_cmd() -> None:
raise SystemExit(1)
-def serve_until_callback(server: HTTPServer, result: dict[str, str | None]) -> None:
+def serve_until_callback(server: HTTPServer, *, result: dict[str, str | None]) -> None:
"""Handle requests until we get the API key or timeout."""
try:
while result["api_key"] is None:
@@ -117,4 +117,4 @@ def save_api_key(api_key: str) -> None:
env_path = get_global_env_path()
entries = read_env_file(env_path)
entries[PIPELEX_GATEWAY_API_KEY_VAR] = api_key
- write_env_file(env_path, entries)
+ write_env_file(env_path, entries=entries)
diff --git a/pipelex/cli/commands/run/_inputs_path_resolver.py b/pipelex/cli/commands/run/_inputs_path_resolver.py
index 38c0e3c85..b212e9f98 100644
--- a/pipelex/cli/commands/run/_inputs_path_resolver.py
+++ b/pipelex/cli/commands/run/_inputs_path_resolver.py
@@ -42,7 +42,7 @@ def is_relative_local_path(uri: str) -> bool:
return not Path(resolved.path).is_absolute()
-def resolve_url_in_value(value: Any, base_dir: Path) -> Any:
+def resolve_url_in_value(value: Any, *, base_dir: Path) -> Any:
"""Recursively walk a JSON-like value and resolve relative ``url`` fields.
When a ``dict`` contains a ``"url"`` key whose value is a relative local
@@ -62,17 +62,17 @@ def resolve_url_in_value(value: Any, base_dir: Path) -> Any:
if key == "url" and isinstance(val, str) and is_relative_local_path(val):
result[key] = str(base_dir / val)
else:
- result[key] = resolve_url_in_value(val, base_dir)
+ result[key] = resolve_url_in_value(val, base_dir=base_dir)
return result
if isinstance(value, list):
value_list = cast("list[Any]", value)
- return [resolve_url_in_value(item, base_dir) for item in value_list]
+ return [resolve_url_in_value(item, base_dir=base_dir) for item in value_list]
return value
-def resolve_inputs_paths(inputs_dict: dict[str, Any], base_dir: Path) -> dict[str, Any]:
+def resolve_inputs_paths(inputs_dict: dict[str, Any], *, base_dir: Path) -> dict[str, Any]:
"""Resolve relative ``url`` paths in a pipeline inputs dict.
Entry point that applies :func:`resolve_url_in_value` to each top-level
@@ -88,5 +88,5 @@ def resolve_inputs_paths(inputs_dict: dict[str, Any], base_dir: Path) -> dict[st
"""
resolved: dict[str, Any] = {}
for key, value in inputs_dict.items():
- resolved[key] = resolve_url_in_value(value, base_dir)
+ resolved[key] = resolve_url_in_value(value, base_dir=base_dir)
return resolved
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
index 6791a6b44..b96ce69ab 100644
--- a/pipelex/cli/commands/run/_run_core.py
+++ b/pipelex/cli/commands/run/_run_core.py
@@ -73,6 +73,7 @@ def validate_run_flag_combination(*, dry_run: bool, mock_usage: bool, mock_input
async def _execute_run(
pipe_code: str | None,
+ *,
bundle_path: str | None,
inputs: str | None,
save_working_memory: bool,
@@ -88,7 +89,6 @@ async def _execute_run(
library_dir: list[str] | None,
costs: bool | None = None,
dynamic_output_concept_ref: str | None = None,
- *,
save_csv: str | None = None,
) -> None:
"""Core async execution logic for running a pipe.
@@ -152,7 +152,7 @@ async def _execute_run(
pipeline_inputs = load_json_dict_from_path(Path(inputs))
# Resolve relative url paths against the inputs file's parent directory
base_dir = Path(inputs).parent.resolve()
- pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir)
+ pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=base_dir)
typer.echo(f"Loaded inputs from: {inputs}")
except FileNotFoundError as file_not_found_exc:
print_traceback_if_requested(get_console())
@@ -343,6 +343,7 @@ async def _execute_run(
def execute_run(
pipe_code: str | None,
+ *,
bundle_path: str | None,
inputs: str | None,
save_working_memory: bool,
@@ -360,7 +361,6 @@ def execute_run(
telemetry_command_label: str = COMMAND,
temporal: bool | None = None,
dynamic_output_concept_ref: str | None = None,
- *,
save_csv: str | None = None,
) -> None:
"""Synchronous entry point that wraps the async execution with Pipelex setup/teardown.
diff --git a/pipelex/cli/commands/update_cmd.py b/pipelex/cli/commands/update_cmd.py
index d488a0469..0b64586c3 100644
--- a/pipelex/cli/commands/update_cmd.py
+++ b/pipelex/cli/commands/update_cmd.py
@@ -33,6 +33,7 @@ from pipelex.system.configuration.config_loader import config_manager
def update_cmd(
local: bool = False,
+ *,
yes: bool = False,
dry_run: bool = False,
no_backup: bool = False,
@@ -54,7 +55,7 @@ def update_cmd(
sys.exit(1)
report = compute_deck_sync_report(deck_dir)
- _print_status_table(report, deck_dir)
+ _print_status_table(report, deck_dir=deck_dir)
if report.is_clean():
console.print(_summary_panel("Model deck is up to date.", style="green"))
@@ -80,7 +81,7 @@ def update_cmd(
return
actions_applied = _apply_updates(deck_dir=deck_dir, report=report, no_backup=no_backup)
- write_manifest(deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=deck_dir)
console.print()
console.print(_summary_panel(f"Model deck updated ({actions_applied} file change(s) applied).", style="green"))
@@ -98,7 +99,7 @@ def _resolve_deck_dir(local: bool) -> Path:
return config_manager.model_decks_dir_path
-def _print_status_table(report: DeckSyncReport, deck_dir: Path) -> None:
+def _print_status_table(report: DeckSyncReport, *, deck_dir: Path) -> None:
"""Render the per-file sync status as a Rich table."""
table = Table(title="Pipelex Model Deck — Update Plan", show_lines=False)
table.add_column("File", style="cyan", no_wrap=True)
@@ -134,7 +135,7 @@ def _action_description(status: DeckFileStatus) -> str:
return "back up + overwrite from kit"
-def _apply_updates(deck_dir: Path, report: DeckSyncReport, no_backup: bool) -> int:
+def _apply_updates(deck_dir: Path, *, report: DeckSyncReport, no_backup: bool) -> int:
"""Apply the per-file actions described by ``report``. Returns the count of files changed."""
kit_dir = kit_deck_dir()
timestamp = datetime.now(tz=timezone.utc).strftime("%Y%m%dT%H%M%SZ")
diff --git a/pipelex/cli/commands/validate/_validate_core.py b/pipelex/cli/commands/validate/_validate_core.py
index f73357992..d025c77f2 100644
--- a/pipelex/cli/commands/validate/_validate_core.py
+++ b/pipelex/cli/commands/validate/_validate_core.py
@@ -12,13 +12,13 @@ from pipelex.cli.error_handlers import (
ErrorContext,
handle_model_availability_error,
handle_model_choice_error,
- handle_signatures_not_allowed_error,
handle_validate_bundle_error,
)
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.hub import (
get_console,
get_library_manager,
+ get_pipe_library,
get_pipes,
get_required_pipe,
get_telemetry_manager,
@@ -27,13 +27,12 @@ from pipelex.hub import (
)
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipe_signature.signature_walk import collect_signature_refs
from pipelex.pipelex import Pipelex
from pipelex.pipeline.bundle_validator import BundleValidator
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.execution_seams import load_libraries_and_activate
-from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.pipeline.validate_bundle import build_pending_signatures, validate_bundle
from pipelex.system.runtime import IntegrationMode
from pipelex.system.telemetry.events import EventProperty
from pipelex.tools.misc.package_utils import get_package_version
@@ -58,6 +57,7 @@ def _format_signatures_summary_suffix(signature_count: int) -> str:
def do_validate_all_libraries_and_dry_run(
library_dirs: list[Path] | None = None,
+ *,
allow_signatures: bool = False,
) -> None:
try:
@@ -71,24 +71,37 @@ def do_validate_all_libraries_and_dry_run(
# teardown. No teardown on success here: the caller (validate_pipe_cmd) owns Pipelex teardown.
load_libraries_and_activate(library_dirs)
- # The pipe list is needed only to render the "Validating N" line and the signature-count
- # suffix; validate_current_library re-derives it (with the same strict-mode signature filter)
- # from the current library for the sweep itself.
+ # The pipe list is needed only to render the "Validating N" line; validate_current_library
+ # re-derives its own sweep candidates from the current library (validate_pipes excludes
+ # signature pipes in strict mode). The count line mirrors that strict-mode exclusion.
all_pipes = get_pipes()
pipes = all_pipes if allow_signatures else [pipe for pipe in all_pipes if not pipe.is_signature]
if library_dirs:
dirs_str = ", ".join(f'"{lib_dir}"' for lib_dir in library_dirs)
typer.echo(f"Validating {len(pipes)} pipe(s) from: {dirs_str}")
- # validate_current_library owns the static wiring pass, the strict signature pre-pass, and the
- # single PIPE_DRY_RUN telemetry event — sweeping the library we just loaded, without teardown.
+ # validate_current_library owns the static wiring pass and the single PIPE_DRY_RUN telemetry
+ # event — sweeping the library we just loaded, without teardown.
asyncio.run(BundleValidator().validate_current_library(allow_signatures=allow_signatures))
- signature_count = sum(1 for pipe in pipes if pipe.is_signature)
+
+ # Gate-from-report (D-B consumer-decides): signatures are never a validation error, but a
+ # library with unsatisfied PipeSignature placeholders is valid yet NOT runnable. `validate
+ # --all` is strict by default — it exits non-zero on pending signatures unless
+ # --allow-signatures tolerates them. The library is still loaded here (no teardown), so the
+ # library-wide pending set is read directly off it.
+ pending_signatures = build_pending_signatures(get_pipe_library().get_pipes_dict())
+ if pending_signatures and not allow_signatures:
+ pending = ", ".join(pending_signatures)
+ typer.secho(
+ f"Libraries are valid but NOT yet runnable — unimplemented PipeSignature placeholder(s): {pending}\n"
+ "Implement them, or re-run with --allow-signatures to accept placeholders.",
+ fg=typer.colors.RED,
+ err=True,
+ )
+ raise typer.Exit(1)
+
+ signature_count = sum(1 for pipe in all_pipes if pipe.is_signature)
typer.echo(f"Setup sequence passed OK, config and pipelines are validated.{_format_signatures_summary_suffix(signature_count)}")
- except SignaturesNotAllowedError as sig_error:
- # A non-signature pipe in the library reaches a PipeSignature. Render it as a friendly
- # CLI error (matching the bundle/pipe paths) instead of bubbling a raw traceback.
- handle_signatures_not_allowed_error(sig_error, context=ErrorContext.VALIDATION)
except PipeOperatorModelAvailabilityError as exc:
handle_model_availability_error(exc, context=ErrorContext.VALIDATION)
except PipeOperatorModelChoiceError as exc:
@@ -97,6 +110,7 @@ def do_validate_all_libraries_and_dry_run(
async def _validate_pipe_or_bundle(
pipe_code: str | None = None,
+ *,
bundle_path: Path | None = None,
library_dirs: list[Path] | None = None,
allow_signatures: bool = False,
@@ -109,6 +123,18 @@ async def _validate_pipe_or_bundle(
library_dirs=library_dirs,
allow_signatures=allow_signatures,
)
+ # Gate-from-report (D-B consumer-decides): signatures are never a validation error, but a
+ # bundle with unsatisfied PipeSignature placeholders is valid yet NOT runnable. The CLI
+ # exits non-zero on `not is_runnable` unless --allow-signatures tolerates the placeholders.
+ if bundle_result.pending_signatures and not allow_signatures:
+ pending = ", ".join(bundle_result.pending_signatures)
+ typer.secho(
+ f"Bundle '{bundle_path}' is valid but NOT yet runnable — unimplemented PipeSignature placeholder(s): {pending}\n"
+ "Implement them, or re-run with --allow-signatures to accept placeholders.",
+ fg=typer.colors.RED,
+ err=True,
+ )
+ raise typer.Exit(1)
signature_count = sum(1 for pipe in bundle_result.pipes if pipe.is_signature)
typer.secho(
f"Successfully validated bundle '{bundle_path}'{_format_signatures_summary_suffix(signature_count)}",
@@ -135,14 +161,14 @@ async def _validate_pipe_or_bundle(
pipe = get_required_pipe(pipe_code=pipe_code)
typer.echo(f"Validating pipe '{pipe_code}'...")
- try:
- await BundleValidator().validate_pipes(
- pipes=[pipe],
- library_id=library_id,
- allow_signatures=allow_signatures,
- )
- except SignaturesNotAllowedError as sig_error:
- handle_signatures_not_allowed_error(sig_error, context=ErrorContext.VALIDATION)
+ # Signatures are never an error (D-B): a single-pipe validation reaching a PipeSignature
+ # dry-runs trivially (the placeholder mints a mock). validate pipe makes no library-wide
+ # runnability claim — pending_signatures is a bundle-surface fact — so there is no gate here.
+ await BundleValidator().validate_pipes(
+ pipes=[pipe],
+ library_id=library_id,
+ allow_signatures=allow_signatures,
+ )
signature_count = len(collect_signature_refs(pipe=pipe))
typer.secho(
f"Successfully validated pipe '{pipe_code}'{_format_signatures_summary_suffix(signature_count)}",
@@ -159,6 +185,7 @@ async def _validate_pipe_or_bundle(
def execute_validate(
pipe_code: str | None,
+ *,
bundle_path: Path | None,
library_dirs: list[Path] | None,
telemetry_command_label: str = COMMAND,
diff --git a/pipelex/cli/commands/which_cmd.py b/pipelex/cli/commands/which_cmd.py
index 93c2b72d0..539c70852 100644
--- a/pipelex/cli/commands/which_cmd.py
+++ b/pipelex/cli/commands/which_cmd.py
@@ -30,7 +30,7 @@ if TYPE_CHECKING:
COMMAND = "which"
-def do_which_pipe(pipe_code: str, library_dirs: list[Path], source_label: str) -> bool:
+def do_which_pipe(pipe_code: str, *, library_dirs: list[Path], source_label: str) -> bool:
"""Locate where a pipe is defined."""
console = get_console()
diff --git a/pipelex/cli/dev_cli/_dev_cli.py b/pipelex/cli/dev_cli/_dev_cli.py
index c895224e2..7d5fe151e 100644
--- a/pipelex/cli/dev_cli/_dev_cli.py
+++ b/pipelex/cli/dev_cli/_dev_cli.py
@@ -12,6 +12,7 @@ from typing_extensions import override
from pipelex.cli.dev_cli.commands.check_config_sync_cmd import LeadingConfig, check_config_sync_cmd
from pipelex.cli.dev_cli.commands.check_gateway_models_cmd import check_gateway_models_cmd
+from pipelex.cli.dev_cli.commands.check_keyword_only_cmd import check_keyword_only_cmd
from pipelex.cli.dev_cli.commands.check_mthds_schema_cmd import check_mthds_schema_cmd
from pipelex.cli.dev_cli.commands.check_rules_sync_cmd import check_rules_sync_cmd
from pipelex.cli.dev_cli.commands.check_urls_cmd import DEFAULT_TIMEOUT, check_urls_cmd
@@ -36,6 +37,7 @@ class PipelexDevCLI(TyperGroup):
return [
"check-config-sync",
"check-gateway-models",
+ "check-keyword-only",
"check-mthds-schema",
"check-rules",
"check-urls",
@@ -246,6 +248,39 @@ def check_mthds_schema_command(
sys.exit(1)
[email protected](name="check-keyword-only", help="Enforce the keyword-only-arguments convention across pipelex/ source")
+def check_keyword_only_command(
+ report: Annotated[bool, typer.Option("--report", help="Print the full violation inventory grouped by package")] = False,
+ fix: Annotated[
+ bool,
+ typer.Option(
+ "--fix",
+ help=(
+ "Auto-fix by inserting a bare `*` as far left as possible "
+ "(every non-self/cls parameter becomes keyword-only); reports any that need a manual fix"
+ ),
+ ),
+ ] = False,
+ quiet: Annotated[
+ bool, typer.Option("--quiet", "-q", help="Light output on success (single line); the full violation list still prints on failure")
+ ] = False,
+) -> None:
+ """Enforce the keyword-only-arguments convention across pipelex/ source."""
+ try:
+ check_keyword_only_cmd(report=report, fix=fix, quiet=quiet)
+ except (typer.Exit, typer.Abort):
+ # Typer control-flow exits carry an intended exit code — not a failure. Let them through.
+ raise
+ except Exception: # noqa: BLE001
+ # Dev CLI command root: print a traceback for any unexpected failure and exit non-zero.
+ console = get_console()
+ console.print()
+ console.print("[bold red]Unexpected error occurred[/bold red]")
+ console.print()
+ console.print(Traceback())
+ sys.exit(1)
+
+
@app.command(name="sync-main-config", help="Sync main config values to kit and project configs")
def sync_main_config_command(
target: Annotated[
diff --git a/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py b/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
index e9cb554c2..6bd556e4d 100644
--- a/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_config_sync_cmd.py
@@ -23,6 +23,7 @@ class LeadingConfig(StrEnum):
def check_config_sync_cmd(
show_diff: bool = True,
+ *,
leading: LeadingConfig = LeadingConfig.INSTALLED,
quiet: bool = False,
) -> None:
@@ -75,7 +76,7 @@ def check_config_sync_cmd(
# Check for differences (excluding files and directories that intentionally differ)
try:
- has_diff = has_diff_dirs(left_dir, right_dir, exclude_files=CONFIG_SYNC_EXCLUDED_FILES, exclude_dirs=GIT_IGNORED_CONFIG_DIRS)
+ has_diff = has_diff_dirs(dir1=left_dir, dir2=right_dir, exclude_files=CONFIG_SYNC_EXCLUDED_FILES, exclude_dirs=GIT_IGNORED_CONFIG_DIRS)
except OSError as exc:
# Handle race condition where directories are deleted/modified after existence checks
if quiet:
@@ -119,7 +120,9 @@ def check_config_sync_cmd(
if show_diff:
console.print()
- pretty_diff = make_diff_dirs_pretty(left_dir, right_dir, exclude_files=CONFIG_SYNC_EXCLUDED_FILES, exclude_dirs=GIT_IGNORED_CONFIG_DIRS)
+ pretty_diff = make_diff_dirs_pretty(
+ dir1=left_dir, dir2=right_dir, exclude_files=CONFIG_SYNC_EXCLUDED_FILES, exclude_dirs=GIT_IGNORED_CONFIG_DIRS
+ )
console.print(pretty_diff)
console.print()
diff --git a/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py b/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
index 2502f5c92..2cfa7d698 100644
--- a/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py
@@ -25,7 +25,7 @@ if TYPE_CHECKING:
from rich.console import Console
-def check_gateway_models_cmd(show_diff: bool = True, quiet: bool = False) -> None:
+def check_gateway_models_cmd(show_diff: bool = True, *, quiet: bool = False) -> None:
"""Verify that the Pipelex Gateway models reference files are up-to-date.
Compares the existing reference files — both the .pipelex/ copies and the
@@ -164,7 +164,7 @@ def check_gateway_models_cmd(show_diff: bool = True, quiet: bool = False) -> Non
if show_diff:
for path_str, existing_content, expected_content in pending_diffs:
console.print(f"[bold]Differences in {path_str}:[/bold]")
- _display_diff(existing_content, expected_content, console)
+ _display_diff(existing=existing_content, expected=expected_content, console=console)
console.print("[bold yellow]Recommended Action:[/bold yellow]")
console.print(" Run: [cyan]make update-gateway-models[/cyan] or [cyan]make ugm[/cyan]")
@@ -173,7 +173,7 @@ def check_gateway_models_cmd(show_diff: bool = True, quiet: bool = False) -> Non
sys.exit(1)
-def _display_diff(existing: str, expected: str, console: Console) -> None:
+def _display_diff(*, existing: str, expected: str, console: Console) -> None:
"""Display a simplified diff between existing and expected content.
Args:
diff --git a/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py b/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
new file mode 100644
index 000000000..ddeaa9239
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py
@@ -0,0 +1,200 @@
+"""Command enforcing the keyword-only-arguments convention across ``pipelex/`` source.
+
+Non-subject function parameters must be keyword-only so call sites are self-documenting:
+``do_thing(retries=3, timeout=30)`` is forced over the opaque ``do_thing(3, 30)``.
+
+The canonical human-readable specification lives in ``docs/contribute/keyword-only-arguments.md``.
+The pure-AST collection logic lives in the stdlib-only ``keyword_only_guard`` module; this module
+is the ``rich``/``pipelex.hub`` presentation layer wired into the ``pipelex-dev`` Typer app
+(``make check-keyword-only`` / ``make agent-check`` / CI). The ``pipelex/`` source tree is fully
+compliant, so the guard hard-blocks on ANY violation (a bare ``*`` after the subject, or a
+``# kw-only: ignore`` escape hatch with a justification, is required).
+
+The read-only check (``check-keyword-only``, no flag) is the gate; ``--fix`` only mutates and reports.
+``--fix`` never exits non-zero on remaining violations, so ``agent-check`` runs it early (fixing before
+``ruff format``) without masking the ``pyright``/``mypy`` phase, then runs the read-only check last to
+enforce. ``make check`` / CI gate with the read-only check and never mutate.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rich.markup import escape
+from rich.panel import Panel
+
+from pipelex.cli.dev_cli.commands.keyword_only_guard import SOURCE_ROOT, Violation, collect_all_violations, fix_all_violations
+from pipelex.hub import get_console
+
+# --------------------------------------------------------------------------------------
+# Command entrypoint
+# --------------------------------------------------------------------------------------
+
+
+def _print_report(violations: list[Violation]) -> None:
+ """Print the full inventory grouped by top-level package."""
+ console = get_console()
+ grouped: dict[str, list[Violation]] = {}
+ for violation in violations:
+ package = violation.relative_path.split("/")[1] if "/" in violation.relative_path else violation.relative_path
+ grouped.setdefault(package, []).append(violation)
+ console.print()
+ console.print("[bold]Keyword-only convention — full inventory[/bold]")
+ console.print()
+ for package in sorted(grouped):
+ package_violations = grouped[package]
+ console.print(f"[bold cyan]{escape(package)}[/bold cyan] ([dim]{len(package_violations)}[/dim])")
+ for violation in package_violations:
+ console.print(f" {escape(violation.relative_path)}:{violation.lineno} [dim]{escape(violation.qualified_name)}[/dim]")
+ console.print()
+ console.print(f"[bold]Total:[/bold] {len(violations)}")
+ console.print()
+
+
+def check_keyword_only_cmd(*, report: bool = False, fix: bool = False, quiet: bool = False) -> None:
+ """Enforce the keyword-only-arguments convention across ``pipelex/`` source.
+
+ The source tree is fully compliant, so the guard hard-blocks on ANY violation. The only
+ sanctioned non-compliant signatures are the explicit carve-outs and the ``# kw-only: ignore``
+ escape hatch (see ``docs/contribute/keyword-only-arguments.md``).
+
+ Args:
+ report: If True, print the full inventory grouped by package (no pass/fail gating).
+ fix: If True, auto-fix every mechanically-fixable violation by inserting a bare ``*`` as far
+ left as possible (right after ``self``/``cls``) so every other parameter becomes keyword-only,
+ then report what was fixed and what still needs a manual fix. Non-gating — it reports the
+ unfixable ones but exits 0; the read-only check (run last in ``agent-check`` and in
+ ``make check`` / CI) enforces compliance. Takes precedence over ``report``.
+ quiet: If True, keep the success output to a single line (for Make targets / CI). Quiet
+ only trims the happy path — a failure still prints the full actionable violation list.
+ """
+ console = get_console()
+
+ if not SOURCE_ROOT.exists():
+ # An error is always loud — quiet only trims success output, never failures.
+ console.print("[red]✗ Keyword-only check: FAILED[/red] - source root [cyan]pipelex/[/cyan] does not exist")
+ sys.exit(1)
+
+ if fix:
+ _run_fix(quiet=quiet)
+ return
+
+ violations = collect_all_violations(SOURCE_ROOT)
+
+ if report:
+ _print_report(violations)
+ return
+
+ if not violations:
+ # Success is the only thing quiet trims: one line in quiet mode, a panel otherwise.
+ if quiet:
+ console.print("[green]✓ Keyword-only check: PASSED[/green]")
+ else:
+ _print_success_panel()
+ return
+
+ # Failure is always actionable: list the offending signatures so no re-run is needed —
+ # in quiet mode too, since the Make targets and CI invoke the guard quietly.
+ if quiet:
+ _print_failure_quiet(violations=violations)
+ else:
+ _print_failure_panel(violations=violations)
+ sys.exit(1)
+
+
+def _run_fix(*, quiet: bool) -> None:
+ """Auto-fix path: insert a bare ``*`` for every fixable violation, then report the outcome.
+
+ Non-gating by design: it mutates and reports but never exits non-zero on remaining (unfixable)
+ violations. That lets it run early in ``make agent-check`` — fixing before ``ruff format`` without
+ aborting the pipeline mid-mutation or masking the ``pyright``/``mypy`` phase. The read-only
+ ``check-keyword-only`` gate (run last in ``agent-check``, and in ``make check`` / CI) is what
+ enforces compliance and fails on the unfixable ones. A genuine error (e.g. a missing source root)
+ still exits non-zero — that is handled by the caller, not here.
+ """
+ console = get_console()
+ fixed, unfixable = fix_all_violations(SOURCE_ROOT)
+
+ if fixed:
+ # Files changed — always surface this, even in quiet mode.
+ console.print(
+ f"[green]✓ Auto-fixed {len(fixed)} keyword-only violation(s)[/green] "
+ "(inserted a bare `*` after self/cls so every other parameter is keyword-only):"
+ )
+ _print_violation_lines(fixed)
+ console.print(
+ "[dim]Verify with `make agent-test` — the guard can't see framework-positional callers, "
+ "so a wrongly keyword-only'd call site only fails at runtime.[/dim]"
+ )
+
+ if unfixable:
+ # Reported, not gated here — the read-only `check-keyword-only` (last in agent-check / CI) fails on these.
+ console.print(
+ f"[red]✗ {len(unfixable)} violation(s) need a manual fix[/red] "
+ "(e.g. `*args` present, an existing keyword-only section, or two+ positional-only params):"
+ )
+ _print_violation_lines(unfixable)
+ console.print(
+ "[dim]Place the bare `*` by hand, or add `# kw-only: ignore` on the def line if justified — "
+ "`make check-keyword-only` (and CI) will fail until then. See docs/contribute/keyword-only-arguments.md[/dim]"
+ )
+
+ if not fixed and not unfixable:
+ # Nothing needed fixing — quiet trims this happy path to one line.
+ if quiet:
+ console.print("[green]✓ Keyword-only auto-fix: nothing to fix[/green]")
+ else:
+ _print_success_panel()
+
+
+def _print_success_panel() -> None:
+ """Verbose success output (no violations)."""
+ console = get_console()
+ console.print()
+ console.print(
+ Panel(
+ "[green]✓[/green] No keyword-only violations.",
+ title="[bold green]Keyword-only Check: PASSED[/bold green]",
+ border_style="green",
+ padding=(1, 2),
+ )
+ )
+ console.print()
+
+
+def _print_failure_panel(*, violations: list[Violation]) -> None:
+ """Verbose failure output with a per-violation file:line list."""
+ console = get_console()
+ console.print()
+ console.print(
+ Panel(
+ f"[red]✗[/red] {len(violations)} keyword-only violation(s) found.\n\n"
+ "[dim]Non-subject parameters must be keyword-only — place a bare `*` before them, "
+ "or add `# kw-only: ignore` on the def line if genuinely justified.[/dim]",
+ title="[bold red]Keyword-only Check: FAILED[/bold red]",
+ border_style="red",
+ padding=(1, 2),
+ )
+ )
+ console.print()
+ console.print("[bold]Violations:[/bold]")
+ _print_violation_lines(violations)
+ console.print()
+
+
+def _print_failure_quiet(*, violations: list[Violation]) -> None:
+ """Compact failure output for quiet mode: a status line, the actionable file:line list, one remedy hint."""
+ console = get_console()
+ console.print(f"[red]✗ Keyword-only check: FAILED[/red] - {len(violations)} violation(s):")
+ _print_violation_lines(violations)
+ console.print(
+ "[dim]Place a bare `*` so non-subject parameters are keyword-only (or run `make fix-keyword-only`), "
+ "or add `# kw-only: ignore` if justified — see docs/contribute/keyword-only-arguments.md[/dim]"
+ )
+
+
+def _print_violation_lines(violations: list[Violation]) -> None:
+ """Print one ``file:line qualified_name`` row per violation."""
+ console = get_console()
+ for violation in violations:
+ console.print(f" [red]{escape(violation.relative_path)}:{violation.lineno}[/red] [dim]{escape(violation.qualified_name)}[/dim]")
diff --git a/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py b/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
index 76015b549..37a9cd261 100644
--- a/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py
@@ -18,7 +18,7 @@ if TYPE_CHECKING:
from rich.console import Console
-def check_mthds_schema_cmd(show_diff: bool = True, quiet: bool = False) -> None:
+def check_mthds_schema_cmd(show_diff: bool = True, *, quiet: bool = False) -> None:
"""Verify that the MTHDS JSON Schema file is up-to-date.
Regenerates the schema in memory and compares it against the on-disk file.
@@ -117,7 +117,7 @@ def check_mthds_schema_cmd(show_diff: bool = True, quiet: bool = False) -> None:
console.print()
if show_diff:
- _display_diff(existing_content, expected_content, console)
+ _display_diff(existing=existing_content, expected=expected_content, console=console)
console.print("[bold yellow]Recommended Action:[/bold yellow]")
console.print(" Run: [cyan]make generate-mthds-schema[/cyan] or [cyan]make gms[/cyan]")
@@ -126,7 +126,7 @@ def check_mthds_schema_cmd(show_diff: bool = True, quiet: bool = False) -> None:
sys.exit(1)
-def _display_diff(existing: str, expected: str, console: Console) -> None:
+def _display_diff(*, existing: str, expected: str, console: Console) -> None:
"""Display a simplified diff between existing and expected content.
Args:
diff --git a/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py b/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
index 8c9c29a92..c430903e4 100644
--- a/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py
@@ -37,7 +37,7 @@ def _get_preferred_targets_from_toml() -> list[AgentTarget]:
return parsed_targets or _DEFAULT_TARGETS
-def check_rules_sync_cmd(show_diff: bool = True, quiet: bool = False) -> None:
+def check_rules_sync_cmd(show_diff: bool = True, *, quiet: bool = False) -> None:
"""Verify that installed agent rules match kit templates.
Args:
@@ -79,7 +79,7 @@ def check_rules_sync_cmd(show_diff: bool = True, quiet: bool = False) -> None:
target_file_list = target.sets[agent_set]
# Build merged rules for this specific target (with override if applicable)
- merged_rules = build_merged_rules(kit_index, agent_set=agent_set, file_list=target_file_list)
+ merged_rules = build_merged_rules(kit_index=kit_index, agent_set=agent_set, file_list=target_file_list)
# Expected content is heading + merged rules
expected_content = f"# Pipelex Coding Rules\n\n{merged_rules}"
diff --git a/pipelex/cli/dev_cli/commands/check_urls_cmd.py b/pipelex/cli/dev_cli/commands/check_urls_cmd.py
index 83b2f9ce5..c46c184f9 100644
--- a/pipelex/cli/dev_cli/commands/check_urls_cmd.py
+++ b/pipelex/cli/dev_cli/commands/check_urls_cmd.py
@@ -62,6 +62,7 @@ def get_all_urls_from_class() -> list[tuple[str, str]]:
async def check_single_url_async(
client: httpx.AsyncClient,
+ *,
name: str,
url: str,
) -> URLCheckResult:
@@ -116,6 +117,7 @@ async def check_single_url_async(
async def check_all_urls_async(
url_pairs: list[tuple[str, str]],
+ *,
request_timeout: int,
) -> list[URLCheckResult]:
"""Check all URLs concurrently with connection pooling.
@@ -135,12 +137,12 @@ async def check_all_urls_async(
timeout=request_timeout,
limits=HTTP_LIMITS,
) as client:
- tasks = [check_single_url_async(client, name, url) for name, url in url_pairs]
+ tasks = [check_single_url_async(client, name=name, url=url) for name, url in url_pairs]
results = await asyncio.gather(*tasks)
return list(results)
-def check_urls_cmd(quiet: bool = False, timeout: int = DEFAULT_TIMEOUT) -> None:
+def check_urls_cmd(quiet: bool = False, *, timeout: int = DEFAULT_TIMEOUT) -> None:
"""Check all URLs defined in pipelex/urls.py for broken links.
Args:
diff --git a/pipelex/cli/dev_cli/commands/gateway_models_generator.py b/pipelex/cli/dev_cli/commands/gateway_models_generator.py
index 8b818cf9a..5f93d8876 100644
--- a/pipelex/cli/dev_cli/commands/gateway_models_generator.py
+++ b/pipelex/cli/dev_cli/commands/gateway_models_generator.py
@@ -123,14 +123,14 @@ def generate_pure_markdown_list(models: list[dict[str, Any]]) -> str:
outputs: list[str] = model.get("outputs", [])
# Sort inputs and outputs using preferred order
- def sort_by_preferred(items: list[str], preferred: list[str]) -> list[str]:
+ def sort_by_preferred(items: list[str], *, preferred: list[str]) -> list[str]:
item_set = set(items)
ordered = [col for col in preferred if col in item_set]
remaining = sorted(item_set - set(preferred))
return ordered + remaining
- sorted_inputs = sort_by_preferred(inputs, PREFERRED_INPUT_ORDER)
- sorted_outputs = sort_by_preferred(outputs, PREFERRED_OUTPUT_ORDER)
+ sorted_inputs = sort_by_preferred(inputs, preferred=PREFERRED_INPUT_ORDER)
+ sorted_outputs = sort_by_preferred(outputs, preferred=PREFERRED_OUTPUT_ORDER)
inputs_str = ", ".join(sorted_inputs) if sorted_inputs else "none"
outputs_str = ", ".join(sorted_outputs) if sorted_outputs else "none"
@@ -162,13 +162,13 @@ def generate_markdown_table(models: list[dict[str, Any]]) -> str:
all_outputs.update(model.get("outputs", []))
# Sort columns using preferred order, with any unlisted columns appended alphabetically
- def sort_by_preferred(items: set[str], preferred: list[str]) -> list[str]:
+ def sort_by_preferred(items: set[str], *, preferred: list[str]) -> list[str]:
ordered = [col for col in preferred if col in items]
remaining = sorted(items - set(preferred))
return ordered + remaining
- input_cols = sort_by_preferred(all_inputs, PREFERRED_INPUT_ORDER)
- output_cols = sort_by_preferred(all_outputs, PREFERRED_OUTPUT_ORDER)
+ input_cols = sort_by_preferred(all_inputs, preferred=PREFERRED_INPUT_ORDER)
+ output_cols = sort_by_preferred(all_outputs, preferred=PREFERRED_OUTPUT_ORDER)
# Background colors for visual separation (semi-transparent for dark/light mode compatibility)
input_bg = "background-color:rgba(33,150,243,0.15)" # Semi-transparent blue
diff --git a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
index e91cdd21e..90a4a46e0 100644
--- a/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py
@@ -13,7 +13,7 @@ from pipelex.pipelex import Pipelex
ERROR_PAGES_DIR = Path("docs/errors")
-def generate_error_pages_cmd(output: Path | None = None, quiet: bool = False) -> None:
+def generate_error_pages_cmd(output: Path | None = None, *, quiet: bool = False) -> None:
"""Generate per-class error documentation pages.
Bootstraps Pipelex with ``needs_inference=False`` (kept for parity with other
diff --git a/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py b/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
index 6a65c94e5..b9a1af012 100644
--- a/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py
@@ -15,7 +15,7 @@ from pipelex.language.mthds_schema_generator import generate_mthds_schema
MTHDS_SCHEMA_PATH = Path("derived/mthds_schema.json")
-def generate_mthds_schema_cmd(output: Path | None = None, quiet: bool = False) -> None:
+def generate_mthds_schema_cmd(output: Path | None = None, *, quiet: bool = False) -> None:
"""Generate a Taplo-compatible JSON Schema for .mthds files.
Generates the schema from PipelexBundleBlueprint and writes it as JSON.
diff --git a/pipelex/cli/dev_cli/commands/keyword_only_guard.py b/pipelex/cli/dev_cli/commands/keyword_only_guard.py
new file mode 100644
index 000000000..d4dc21a8f
--- /dev/null
+++ b/pipelex/cli/dev_cli/commands/keyword_only_guard.py
@@ -0,0 +1,615 @@
+"""Pure-stdlib AST core for the keyword-only-arguments convention guard.
+
+Non-subject function parameters must be keyword-only so call sites are self-documenting:
+``do_thing(retries=3, timeout=30)`` is forced over the opaque ``do_thing(3, 30)``. The canonical
+human-readable specification lives in ``docs/contribute/keyword-only-arguments.md``.
+
+This module holds the AST collection logic that mechanically enforces the convention. It depends
+on **stdlib only** (``ast``/``re``/``pathlib``) — no ``rich``, ``pipelex.hub``, or ``typer`` — so it
+can be loaded in two cold-start budgets:
+
+- The full-tree command (``pipelex-dev check-keyword-only``) imports from here and adds the
+ ``rich``/``pipelex.hub`` presentation layer (see ``check_keyword_only_cmd.py``).
+- The lean single-file entry below, invoked **by file path** (``python
+ pipelex/cli/dev_cli/commands/keyword_only_guard.py <file>``), skips the whole Typer/hub import
+ graph so a ``PostToolUse`` hook can check just the edited file in a few tens of milliseconds. Run
+ by file path, not ``python -m ...`` — the ``-m`` form would import the ``pipelex`` package chain
+ (``pipelex/__init__.py`` → ``rich``), defeating the cold-start budget.
+
+Single-file results are an exact subset of the full scan: ``relative_path``/``module_qname`` are
+computed identically (see ``collect_violations_for_files``), so the carve-out allowlist matches.
+
+The module also exposes an auto-fix surface (``fix_source`` / ``fix_all_violations``) backing the
+``--fix`` flag: it inserts a bare ``*`` as far left as possible (right after ``self``/``cls``) so every
+non-``self``/``cls`` parameter becomes keyword-only, for the mechanically fixable violations, and reports
+the rest for a manual fix. See ``docs/contribute/keyword-only-arguments.md`` (the Auto-fix section) for the
+fixable/unfixable shapes.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, NamedTuple
+
+from typing_extensions import override
+
+if TYPE_CHECKING:
+ from collections.abc import Iterable, Iterator
+
+# --------------------------------------------------------------------------------------
+# Configuration / carve-out data
+# --------------------------------------------------------------------------------------
+
+#: Source root scanned by the guard (relative to the repo root / cwd).
+SOURCE_ROOT = Path("pipelex")
+
+#: The line breaks ``ast``/CPython counts toward ``node.lineno`` — and ONLY these.
+#: ``str.splitlines()`` additionally splits on form-feed, vertical tab, NEL, file/group/record/unit
+#: separators and the Unicode line/paragraph separators, so a single such character before a violation
+#: would shift every subsequent ``lineno``-based index off by one. The capturing group keeps the
+#: separators in the split output so :func:`_split_source_lines` can reconstruct the file byte-for-byte.
+_LINE_BREAK_RE = re.compile(r"(\r\n|\r|\n)")
+
+#: Inline comment that suppresses a single violation on the def line it sits on.
+ESCAPE_HATCH_MARKER = "# kw-only: ignore"
+
+#: Anchored full-match against the function NAME node (not the source line).
+#: The ``+`` quantifier guarantees a non-empty body so the degenerate ``____`` cannot match.
+DUNDER_PATTERN = re.compile(r"__[A-Za-z0-9_]+__")
+
+#: pydantic decorator names whose wrapped callables follow a fixed positional protocol.
+PYDANTIC_DECORATOR_NAMES = frozenset(
+ {
+ "field_validator",
+ "model_validator",
+ "field_serializer",
+ "model_serializer",
+ "validator",
+ "root_validator",
+ }
+)
+
+#: Typer/click decorator attribute suffixes (receiver varies: app/graph_app/show_app/...).
+TYPER_DECORATOR_ATTRS = frozenset({"command", "callback"})
+
+#: Framework decorators matched on their bare name, so both ``@receiver.name`` and bare ``@name`` forms hit.
+#: pytest's ``fixture`` is written both as ``@pytest.fixture`` and as bare ``@fixture`` (``from pytest import fixture``).
+#: Jinja2's ``pass_context`` / ``pass_environment`` / ``pass_eval_context`` mark a filter/test/global whose
+#: wrapped callable is invoked POSITIONALLY by the Jinja2 engine (``{{ x|filter(arg) }}``), so its arguments
+#: cannot be made keyword-only — same framework-entrypoint category as Typer/Temporal/pytest. Written bare
+#: (``@pass_context``, ``from jinja2 import pass_context``) or attributed (``@jinja2.pass_context``).
+BARE_FRAMEWORK_DECORATOR_NAMES = frozenset({"fixture", "pass_context", "pass_environment", "pass_eval_context"})
+
+#: Temporal handler decorators matched on their trailing two attribute segments.
+TEMPORAL_DECORATOR_TAILS = frozenset(
+ {
+ ("activity", "defn"),
+ ("workflow", "run"),
+ ("workflow", "signal"),
+ ("workflow", "query"),
+ ("workflow", "update"),
+ }
+)
+
+#: Typer parameter-annotation metadata callables that mark a call-style CLI entrypoint.
+TYPER_ANNOTATION_ATTRS = frozenset({"Argument", "Option"})
+
+#: Curated symmetric-tuple allowlist — exempt ENTIRELY, keyed by (qualified_name, relative_path).
+#: There is no pattern guessing; both the dotted name and the file path must match exactly.
+SYMMETRIC_ALLOWLIST: frozenset[tuple[str, str]] = frozenset(
+ {
+ ("pipelex.system.environment.set_env", "pipelex/system/environment.py"),
+ ("pipelex.kit.single_file_agent_rules.unified_diff", "pipelex/kit/single_file_agent_rules.py"),
+ ("pipelex.tools.misc.diff.diff_files", "pipelex/tools/misc/diff.py"),
+ ("pipelex.tools.misc.diff.diff_dirs", "pipelex/tools/misc/diff.py"),
+ ("pipelex.tools.typing.class_utils.are_classes_equivalent", "pipelex/tools/typing/class_utils.py"),
+ }
+)
+
+
+class Violation(NamedTuple):
+ """A single keyword-only convention violation.
+
+ Attributes:
+ relative_path: The source file path relative to the repo root.
+ qualified_name: Module-relative dotted path (package.module + class chain + function name).
+ lineno: 1-based line of the ``def`` for human display only — never part of the stable key.
+ """
+
+ relative_path: str
+ qualified_name: str
+ lineno: int
+
+ @property
+ def key(self) -> str:
+ """Stable identity key for sorting/dedup: ``<relative_path>::<qualified_function_name>`` (no line number)."""
+ return f"{self.relative_path}::{self.qualified_name}"
+
+
+# --------------------------------------------------------------------------------------
+# Carve-out detection (pure AST, no import resolution)
+# --------------------------------------------------------------------------------------
+
+
+def _attribute_tail(node: ast.expr) -> tuple[str, ...]:
+ """Return the trailing attribute segments of a dotted expression (e.g. ``a.b.c`` -> ``(a, b, c)``)."""
+ segments: list[str] = []
+ current: ast.expr = node
+ while isinstance(current, ast.Attribute):
+ segments.append(current.attr)
+ current = current.value
+ if isinstance(current, ast.Name):
+ segments.append(current.id)
+ segments.reverse()
+ return tuple(segments)
+
+
+def _decorator_matches_carveout(decorator: ast.expr) -> bool:
+ """Whether a single decorator expression matches any framework / pydantic carve-out."""
+ target: ast.expr = decorator.func if isinstance(decorator, ast.Call) else decorator
+
+ bare_name: str | None = None
+ if isinstance(target, ast.Name):
+ bare_name = target.id
+ elif isinstance(target, ast.Attribute):
+ bare_name = target.attr
+
+ # Bare-name matches — valid whether the decorator is written bare (`@name`) or attributed (`@receiver.name`).
+ if bare_name is not None:
+ if bare_name in PYDANTIC_DECORATOR_NAMES:
+ return True
+ if bare_name in BARE_FRAMEWORK_DECORATOR_NAMES:
+ return True
+ if bare_name == "override":
+ return True
+ # Attribute-only matches — these framework decorators are always written as `receiver.attr`, never bare.
+ if isinstance(target, ast.Attribute):
+ if target.attr in TYPER_DECORATOR_ATTRS:
+ return True
+ tail = _attribute_tail(target)
+ if len(tail) >= 2 and tail[-2:] in TEMPORAL_DECORATOR_TAILS:
+ return True
+ return False
+
+
+def _has_carveout_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+ """Scan the WHOLE decorator stack for a carve-out match (e.g. @activity.defn above @convert_pipelex_errors)."""
+ return any(_decorator_matches_carveout(decorator) for decorator in node.decorator_list)
+
+
+def _iter_subscript_metadata(annotation: ast.expr) -> Iterator[ast.expr]:
+ """Yield the metadata elements of an ``Annotated[...]`` subscript (everything after the first slice element)."""
+ if not isinstance(annotation, ast.Subscript):
+ return
+ slice_value = annotation.slice
+ if isinstance(slice_value, ast.Tuple):
+ yield from slice_value.elts[1:]
+
+
+def _callee_name(func: ast.expr) -> str | None:
+ """The trailing name of a call target: ``typer.Option`` -> ``Option``, bare ``Option`` -> ``Option``."""
+ if isinstance(func, ast.Attribute):
+ return func.attr
+ if isinstance(func, ast.Name):
+ return func.id
+ return None
+
+
+def _annotation_has_typer_metadata(annotation: ast.expr | None) -> bool:
+ """Whether an ``Annotated[...]`` annotation carries ``Argument(...)`` / ``Option(...)`` metadata.
+
+ Matches the qualified ``typer.Argument(...)`` form and the bare ``Argument(...)`` form alike
+ (``from typer import Argument``), so call-style CLI entrypoints are detected either way.
+ """
+ if annotation is None:
+ return False
+ for metadata in _iter_subscript_metadata(annotation):
+ for sub_node in ast.walk(metadata):
+ if isinstance(sub_node, ast.Call) and _callee_name(sub_node.func) in TYPER_ANNOTATION_ATTRS:
+ return True
+ return False
+
+
+def _has_typer_param_annotation(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+ """Detect call-style Typer entrypoints registered without a decorator (closes the decorator-blind gap)."""
+ all_args = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]
+ return any(_annotation_has_typer_metadata(arg.annotation) for arg in all_args)
+
+
+# --------------------------------------------------------------------------------------
+# Rule evaluation
+# --------------------------------------------------------------------------------------
+
+
+def _positional_or_keyword_count(node: ast.FunctionDef | ast.AsyncFunctionDef, *, is_method: bool) -> int:
+ """Count positional-or-keyword params after dropping self/cls and the allowed subject.
+
+ Keyword-only params (already compliant) and ``*args``/``**kwargs`` are not counted.
+ """
+ params = [*node.args.posonlyargs, *node.args.args]
+ if is_method and params and params[0].arg in {"self", "cls"}:
+ params = params[1:]
+ # Drop the single allowed subject under Exception 1.
+ params = params[1:]
+ return len(params)
+
+
+def _is_dunder(name: str) -> bool:
+ """Whether a function name is a reserved dunder (anchored full-match on the NAME only)."""
+ return DUNDER_PATTERN.fullmatch(name) is not None
+
+
+def _def_line_has_escape_hatch(node: ast.FunctionDef | ast.AsyncFunctionDef, *, source_lines: list[str]) -> bool:
+ """Whether the ``# kw-only: ignore`` marker is present on the physical def header line."""
+ index = node.lineno - 1
+ if 0 <= index < len(source_lines):
+ return ESCAPE_HATCH_MARKER in source_lines[index]
+ return False
+
+
+def _qualify(name: str, *, class_stack: tuple[str, ...], func_stack: tuple[str, ...]) -> str:
+ """Build the module-relative dotted qualified name from the enclosing class/function stack."""
+ return ".".join((*class_stack, *func_stack, name))
+
+
+def _evaluate_def(
+ node: ast.FunctionDef | ast.AsyncFunctionDef,
+ *,
+ module_qname: str,
+ relative_path: str,
+ class_stack: tuple[str, ...],
+ func_stack: tuple[str, ...],
+ is_method: bool,
+ source_lines: list[str],
+) -> Violation | None:
+ """Apply the carve-outs then the rule to a single def; return a Violation or None."""
+ # Carve-outs first — any match => skip entirely.
+ if _is_dunder(node.name):
+ return None
+ if _def_line_has_escape_hatch(node, source_lines=source_lines):
+ return None
+ if _has_carveout_decorator(node):
+ return None
+ if _has_typer_param_annotation(node):
+ return None
+
+ local_qname = _qualify(node.name, class_stack=class_stack, func_stack=func_stack)
+ dotted_qname = f"{module_qname}.{local_qname}"
+ if (dotted_qname, relative_path) in SYMMETRIC_ALLOWLIST:
+ return None
+
+ # Rule: a bare `*` is required once two or more positional-or-keyword params remain
+ # after dropping self/cls — i.e. at least one non-subject positional-or-keyword param.
+ if _positional_or_keyword_count(node, is_method=is_method) >= 1:
+ return Violation(relative_path=relative_path, qualified_name=local_qname, lineno=node.lineno)
+ return None
+
+
+def _fix_insertion_point(node: ast.FunctionDef | ast.AsyncFunctionDef, *, is_method: bool) -> tuple[int, int] | None:
+ """Locate where a bare ``*`` must be inserted to fix a violation, or None if not mechanically fixable.
+
+ The ``*`` is placed as far left as possible — immediately after ``self``/``cls`` (and after any ``/``)
+ — so EVERY non-``self``/``cls`` parameter becomes keyword-only, not just the params after the subject:
+ ``def f(a, b)`` is fixed to ``def f(*, a, b)`` and ``def m(self, a, b)`` to ``def m(self, *, a, b)``.
+ The convention permits the subject to stay positional, but making it keyword-only too is always allowed
+ and is preferred here (see ``docs/contribute/keyword-only-arguments.md``).
+
+ Returns the ``(lineno, col_offset)`` of the parameter the bare ``*`` must immediately precede — the
+ first positional-or-keyword parameter that is not ``self``/``cls``. The ``col_offset`` is a UTF-8 byte
+ offset, matching ``ast`` (see :func:`fix_source` for how it is used).
+
+ Returns None for the signatures a simple bare-``*`` insert cannot fix — these need human judgement:
+
+ - a ``*args`` is present (``node.args.vararg``): a bare ``*`` cannot coexist with ``*args``;
+ - a keyword-only section already exists (``node.args.kwonlyargs`` while ``vararg`` is None means a bare
+ ``*`` is already in the signature): a second bare ``*`` is a syntax error, so the existing one must be
+ moved by hand;
+ - two or more positional-only parameters (before a ``/``, excluding a leading ``self``/``cls``) remain:
+ a bare ``*`` cannot precede the ``/``, so they stay positional and the single allowed subject is not
+ enough to reach compliance.
+ """
+ if node.args.vararg is not None or node.args.kwonlyargs:
+ return None
+ args = node.args.args
+ # self/cls (when it leads the positional-or-keyword params) stays positional; the `*` goes right after it.
+ skip = 1 if (is_method and args and args[0].arg in {"self", "cls"}) else 0
+ if skip >= len(args):
+ return None # nothing after self/cls in the positional-or-keyword section to make keyword-only
+ # A bare `*` cannot precede a `/`, so positional-only params can't be made keyword-only. After the
+ # insert, only the positional-only params (plus a leading self/cls) stay positional; mirror
+ # `_positional_or_keyword_count` on that residue — the convention allows exactly one (the subject), so
+ # two or more leftover positional-or-keyword params mean a bare `*` can't reach compliance.
+ residual_positional = [*node.args.posonlyargs, *args[:skip]]
+ if is_method and residual_positional and residual_positional[0].arg in {"self", "cls"}:
+ residual_positional = residual_positional[1:]
+ if len(residual_positional) > 1:
+ return None
+ target = args[skip]
+ return (target.lineno, target.col_offset)
+
+
+class _FixRecord(NamedTuple):
+ """A violation paired with where to insert the bare ``*`` (or None when it needs a manual fix)."""
+
+ violation: Violation
+ insertion: tuple[int, int] | None
+
+
+class _Collector(ast.NodeVisitor):
+ """Walks the module, tracking the enclosing class/function scope to qualify defs."""
+
+ def __init__(self, *, module_qname: str, relative_path: str, source_lines: list[str], collect_fixes: bool = False) -> None:
+ self.module_qname = module_qname
+ self.relative_path = relative_path
+ self.source_lines = source_lines
+ self.collect_fixes = collect_fixes
+ self.violations: list[Violation] = []
+ self.fix_records: list[_FixRecord] = []
+ self._class_stack: tuple[str, ...] = ()
+ self._func_stack: tuple[str, ...] = ()
+ self._in_class_body: tuple[bool, ...] = ()
+
+ @override
+ def visit_ClassDef(self, node: ast.ClassDef) -> None: # ast visitor naming
+ self._class_stack = (*self._class_stack, node.name)
+ self._in_class_body = (*self._in_class_body, True)
+ self.generic_visit(node)
+ self._class_stack = self._class_stack[:-1]
+ self._in_class_body = self._in_class_body[:-1]
+
+ def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+ is_method = bool(self._in_class_body) and self._in_class_body[-1]
+ violation = _evaluate_def(
+ node,
+ module_qname=self.module_qname,
+ relative_path=self.relative_path,
+ class_stack=self._class_stack,
+ func_stack=self._func_stack,
+ is_method=is_method,
+ source_lines=self.source_lines,
+ )
+ if violation is not None:
+ self.violations.append(violation)
+ if self.collect_fixes:
+ insertion = _fix_insertion_point(node, is_method=is_method)
+ self.fix_records.append(_FixRecord(violation=violation, insertion=insertion))
+ # Descend into the function body; nested defs are NOT methods of the enclosing class.
+ self._func_stack = (*self._func_stack, node.name)
+ self._in_class_body = (*self._in_class_body, False)
+ self.generic_visit(node)
+ self._func_stack = self._func_stack[:-1]
+ self._in_class_body = self._in_class_body[:-1]
+
+ @override
+ def visit_FunctionDef(self, node: ast.FunctionDef) -> None: # ast visitor naming
+ self._visit_function(node)
+
+ @override
+ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None: # ast visitor naming
+ self._visit_function(node)
+
+
+def _split_source_lines(source: str) -> list[str]:
+ """Split ``source`` into content lines indexable by ``ast`` line number (``node.lineno - 1``).
+
+ Unlike ``str.splitlines()``, this splits ONLY on the tokenizer's newline set (see :data:`_LINE_BREAK_RE`),
+ so an exotic-whitespace character earlier in the file never shifts a ``lineno``-based index. The content
+ lines are the even-indexed elements of the capturing split (odd indices are the separators).
+ """
+ return _LINE_BREAK_RE.split(source)[::2]
+
+
+def find_violations_in_source(source: str, *, module_qname: str, relative_path: str) -> list[Violation]:
+ """Find all keyword-only convention violations in a single Python source string.
+
+ Args:
+ source: The Python source text to scan.
+ module_qname: The dotted module path used to qualify each def (e.g. ``pipelex.builder.foo``).
+ relative_path: The source file path relative to the repo root (used in the violation's sort/identity key).
+
+ Returns:
+ The violations found, in source order.
+ """
+ tree = ast.parse(source)
+ collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source))
+ collector.visit(tree)
+ return collector.violations
+
+
+# --------------------------------------------------------------------------------------
+# Auto-fix (insert a bare `*` before the first non-self/cls positional-or-keyword param)
+# --------------------------------------------------------------------------------------
+
+
+def _find_fix_records_in_source(source: str, *, module_qname: str, relative_path: str) -> list[_FixRecord]:
+ """Collect a fix record (violation + insertion point) for every violation in a single source string."""
+ tree = ast.parse(source)
+ collector = _Collector(module_qname=module_qname, relative_path=relative_path, source_lines=_split_source_lines(source), collect_fixes=True)
+ collector.visit(tree)
+ return collector.fix_records
+
+
+def fix_source(source: str, *, module_qname: str, relative_path: str) -> tuple[str, list[Violation], list[Violation]]:
+ """Insert a bare ``*`` for every mechanically-fixable violation in a single source string.
+
+ Returns ``(new_source, fixed, unfixable)``: the rewritten text, the violations that were auto-fixed,
+ and the violations that need a manual fix (see :func:`_fix_insertion_point` for which shapes those are).
+ If the rewrite somehow fails to re-parse, the original source is returned unchanged and every violation
+ is reported as unfixable — a rewrite that breaks the file is never written.
+
+ Args:
+ source: The Python source text to fix.
+ module_qname: The dotted module path used to qualify each def (e.g. ``pipelex.builder.foo``).
+ relative_path: The source file path relative to the repo root (used in each violation's key).
+ """
+ records = _find_fix_records_in_source(source, module_qname=module_qname, relative_path=relative_path)
+ fixable = [(record.violation, record.insertion) for record in records if record.insertion is not None]
+ unfixable = [record.violation for record in records if record.insertion is None]
+ if not fixable:
+ return source, [], unfixable
+
+ # Split keeping separators so the file rebuilds byte-for-byte. Content of `ast` line N is the
+ # even-indexed element at `(N - 1) * 2`; odd indices are the separators (see _LINE_BREAK_RE).
+ parts = _LINE_BREAK_RE.split(source)
+ # Apply bottom-up so an earlier insertion never shifts a not-yet-applied byte offset.
+ for lineno, col in sorted((insertion for _, insertion in fixable), reverse=True):
+ content_index = (lineno - 1) * 2
+ line_bytes = parts[content_index].encode("utf-8")
+ parts[content_index] = (line_bytes[:col] + b"*, " + line_bytes[col:]).decode("utf-8")
+ new_source = "".join(parts)
+
+ try:
+ ast.parse(new_source)
+ except SyntaxError:
+ return source, [], [record.violation for record in records]
+ return new_source, [violation for violation, _ in fixable], unfixable
+
+
+# --------------------------------------------------------------------------------------
+# Filesystem walking
+# --------------------------------------------------------------------------------------
+
+
+def _module_qname_for(path: Path) -> str:
+ """Compute the dotted module name for a ``.py`` file under the source root."""
+ parts = list(path.with_suffix("").parts)
+ if parts and parts[-1] == "__init__":
+ parts = parts[:-1]
+ return ".".join(parts)
+
+
+def iter_source_files(root: Path) -> Iterator[Path]:
+ """Yield every ``.py`` file under ``root``, excluding ``__pycache__``."""
+ for path in sorted(root.rglob("*.py")):
+ if "__pycache__" in path.parts:
+ continue
+ yield path
+
+
+def collect_all_violations(root: Path) -> list[Violation]:
+ """Scan every source file under ``root`` and return all violations, sorted by key."""
+ violations: list[Violation] = []
+ for path in iter_source_files(root):
+ relative_path = path.as_posix()
+ module_qname = _module_qname_for(path)
+ source = path.read_text(encoding="utf-8")
+ violations.extend(find_violations_in_source(source, module_qname=module_qname, relative_path=relative_path))
+ return sorted(violations, key=lambda violation: violation.key)
+
+
+def fix_all_violations(root: Path) -> tuple[list[Violation], list[Violation]]:
+ """Rewrite every mechanically-fixable violation under ``root`` in place.
+
+ Returns ``(fixed, unfixable)``, each sorted by key: the violations auto-fixed by inserting a bare
+ ``*`` as far left as possible (right after ``self``/``cls``), and those that still need a manual fix.
+ Only files whose content actually changed are rewritten. Inserted text stays on the def's original
+ line(s); a subsequent ``ruff format`` (the next step in ``make agent-check``) normalizes the layout.
+ """
+ fixed_all: list[Violation] = []
+ unfixable_all: list[Violation] = []
+ for path in iter_source_files(root):
+ source = path.read_text(encoding="utf-8")
+ new_source, fixed, unfixable = fix_source(source, module_qname=_module_qname_for(path), relative_path=path.as_posix())
+ if new_source != source:
+ path.write_text(new_source, encoding="utf-8")
+ fixed_all.extend(fixed)
+ unfixable_all.extend(unfixable)
+ return sorted(fixed_all, key=lambda violation: violation.key), sorted(unfixable_all, key=lambda violation: violation.key)
+
+
+# --------------------------------------------------------------------------------------
+# Single-file scanning (lean hot path for the PostToolUse hook)
+# --------------------------------------------------------------------------------------
+
+
+def relative_source_path(path: Path, *, root: Path | None = None) -> Path | None:
+ """Return ``path`` as a repo-root-relative ``Path`` iff it is an in-scope ``pipelex/`` source file.
+
+ In-scope means: a ``.py`` file under ``SOURCE_ROOT`` (``pipelex/``), not inside ``__pycache__``.
+ Anything else (out-of-tree path, non-``.py``, a sibling repo, a test file) returns ``None`` so the
+ caller can pass any edited path and let this self-filter.
+
+ Args:
+ path: The edited path, absolute or relative to ``root``.
+ root: The repo root; defaults to the current working directory (the hook runs from there).
+ """
+ base = root or Path.cwd()
+ resolved = path if path.is_absolute() else base / path
+ try:
+ relative = resolved.resolve().relative_to(base.resolve())
+ except ValueError:
+ return None # outside the repo
+ if relative.suffix != ".py":
+ return None
+ if "__pycache__" in relative.parts:
+ return None
+ if not relative.parts or relative.parts[0] != SOURCE_ROOT.name:
+ return None
+ return relative
+
+
+def collect_violations_for_files(paths: Iterable[Path], *, root: Path | None = None) -> list[Violation]:
+ """Find violations across the given files; out-of-scope, missing, or unparseable files are skipped.
+
+ Results are an exact subset of :func:`collect_all_violations`: ``relative_path`` and ``module_qname``
+ are computed identically (the carve-out allowlist keys on both), so a single-file scan agrees with
+ the full-tree scan for that file.
+
+ A file that does not parse yet (``SyntaxError``) is skipped rather than reported — a mid-edit file
+ is not a keyword-only violation, and the hook must never block on a transient syntax error.
+
+ Args:
+ paths: Edited paths, absolute or relative to ``root``.
+ root: The repo root; defaults to the current working directory.
+ """
+ base = root or Path.cwd()
+ violations: list[Violation] = []
+ for path in paths:
+ relative = relative_source_path(path, root=base)
+ if relative is None:
+ continue
+ try:
+ source = (base / relative).read_text(encoding="utf-8")
+ except OSError:
+ continue # file vanished between the edit and the hook — nothing to check
+ try:
+ file_violations = find_violations_in_source(
+ source,
+ module_qname=_module_qname_for(relative),
+ relative_path=relative.as_posix(),
+ )
+ except SyntaxError:
+ continue # not-yet-parseable mid-edit file is not a violation
+ violations.extend(file_violations)
+ return sorted(violations, key=lambda violation: violation.key)
+
+
+def main(argv: list[str]) -> int:
+ """Lean single-file entrypoint for the ``PostToolUse`` hook — stdlib only, no Typer/rich/hub.
+
+ Usage (by file path, not ``-m`` — see the module docstring): ``python
+ pipelex/cli/dev_cli/commands/keyword_only_guard.py <file> [<file> ...]``
+
+ Prints any violations to ``stderr`` and returns ``2`` (so a hook blocks and feeds the list back to
+ the agent); returns ``0`` when the in-scope files are clean or none are in scope. Plain ``print`` to
+ stderr is intentional here — pulling in ``pipelex.log``/``rich`` would defeat the cold-start budget.
+ """
+ violations = collect_violations_for_files([Path(arg) for arg in argv])
+ if not violations:
+ return 0
+ print("✗ Keyword-only violation(s) in edited pipelex source:", file=sys.stderr)
+ for violation in violations:
+ print(f" {violation.relative_path}:{violation.lineno} {violation.qualified_name}", file=sys.stderr)
+ print(
+ "Place a bare `*` so the non-subject parameters are keyword-only (or run `make fix-keyword-only`), "
+ "or add `# kw-only: ignore` on the def line if justified — see docs/contribute/keyword-only-arguments.md",
+ file=sys.stderr,
+ )
+ return 2
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv[1:]))
diff --git a/pipelex/cli/dev_cli/commands/kit_cmd.py b/pipelex/cli/dev_cli/commands/kit_cmd.py
index c0ee9a09a..2a0c20d37 100644
--- a/pipelex/cli/dev_cli/commands/kit_cmd.py
+++ b/pipelex/cli/dev_cli/commands/kit_cmd.py
@@ -30,6 +30,7 @@ kit_app = typer.Typer(no_args_is_help=True)
def _sync_agent_rules(
repo_root: Path | None,
+ *,
agent_set: str | None,
cleanup: bool,
kit_index: KitIndex | None = None,
@@ -55,7 +56,7 @@ def _sync_agent_rules(
# so a simple membership check is enough to pick the branch.
if AgentTarget.CURSOR in targets_to_update:
typer.echo("Updating Cursor rules...")
- update_cursor_rules(resolved_repo_root, loaded_kit_index, agent_set=agent_set)
+ update_cursor_rules(resolved_repo_root, kit_index=loaded_kit_index, agent_set=agent_set)
else:
all_targets = loaded_kit_index.agent_rules.targets
filtered_targets: dict[str, Target] = {}
@@ -89,6 +90,7 @@ def _sync_agent_rules(
def _cleanup_other_targets(
repo_root: Path,
+ *,
kit_index: KitIndex,
preferred_targets: list[AgentTarget],
) -> None:
diff --git a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py
index 63fb33f51..dbaafa7fb 100644
--- a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py
@@ -214,7 +214,7 @@ def _load_merged_profiles_config() -> dict[str, Any]:
# Merge override file if it exists
if TEST_PROFILES_OVERRIDE_PATH.exists():
override_config = load_toml_from_path(str(TEST_PROFILES_OVERRIDE_PATH))
- deep_update(config, override_config)
+ deep_update(config, updates=override_config)
return dict(config)
@@ -246,6 +246,7 @@ def _load_test_profile(profile_name: str) -> dict[str, Any]:
def _process_collections_from_toml(
collections_raw: Any, # pyright: ignore[reportExplicitAny]
+ *,
collections: dict[str, dict[str, list[str]]],
) -> None:
"""Process raw TOML collections data into typed collections dict.
@@ -283,13 +284,14 @@ def _load_collections() -> dict[str, dict[str, list[str]]]:
return {}
# Process TOML collections (untyped data at boundary)
- _process_collections_from_toml(collections_raw, collections)
+ _process_collections_from_toml(collections_raw, collections=collections)
return collections
def _resolve_model_list(
raw_list: list[str],
+ *,
collections: dict[str, list[str]],
backend_models: dict[str, list[str]],
all_known_models: list[str],
@@ -364,6 +366,7 @@ def _resolve_model_list(
def _filter_models_by_profile(
availability: dict[str, Any],
+ *,
profile: dict[str, Any],
collections: dict[str, dict[str, list[str]]],
) -> dict[str, list[tuple[str, str]]]:
@@ -494,6 +497,7 @@ def _filter_models_by_profile(
def _generate_fixtures_python(
combo_pairs: dict[str, list[tuple[str, str]]],
+ *,
profile_name: str,
) -> str:
"""Generate Python module content with pre-computed model/backend pairs.
@@ -556,6 +560,7 @@ def _generate_fixtures_python(
def _display_summary(
availability: dict[str, Any],
+ *,
combo_pairs: dict[str, list[tuple[str, str]]],
profile_name: str,
console: Console,
@@ -605,6 +610,7 @@ def _display_summary(
def preprocess_test_models_cmd(
profile: str = "dev",
+ *,
generate_fixtures: bool = False,
output_json: bool = False,
quiet: bool = False,
@@ -784,11 +790,11 @@ def preprocess_test_models_cmd(
sys.exit(1)
collections = _load_collections()
- combo_pairs = _filter_models_by_profile(availability, test_profile, collections)
+ combo_pairs = _filter_models_by_profile(availability, profile=test_profile, collections=collections)
# Generate fixtures if requested
if generate_fixtures:
- fixtures_content = _generate_fixtures_python(combo_pairs, profile)
+ fixtures_content = _generate_fixtures_python(combo_pairs, profile_name=profile)
GENERATED_FIXTURES_PATH.parent.mkdir(parents=True, exist_ok=True)
GENERATED_FIXTURES_PATH.write_text(fixtures_content, encoding="utf-8")
@@ -798,7 +804,7 @@ def preprocess_test_models_cmd(
# Display summary
if not quiet:
console.print()
- _display_summary(availability, combo_pairs, profile, console)
+ _display_summary(availability, combo_pairs=combo_pairs, profile_name=profile, console=console)
console.print()
# Show profile info
diff --git a/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py b/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
index 5d495bb06..718ac3f4a 100644
--- a/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
+++ b/pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py
@@ -83,7 +83,7 @@ ELKJS = CDNAsset(
'''
-def _validate_version(name: str, value: str) -> str:
+def _validate_version(name: str, *, value: str) -> str:
if not _VERSION_PATTERN.fullmatch(value):
msg = f"Invalid {name} version {value!r}: expected a SemVer string like 1.2.3 or 1.2.3-rc.1"
raise PipelexCLIError(msg)
@@ -103,7 +103,7 @@ def _validate_sri(value: str) -> str:
return value
-def _fetch(url: str, timeout: float = 30.0) -> bytes:
+def _fetch(url: str, *, timeout: float = 30.0) -> bytes:
"""Fetch the full body at `url`. Raises if the URL is not on the allowlist or the request fails."""
if not any(url.startswith(prefix) and url.endswith(suffix) for prefix, suffix in _ALLOWED_URL_SHAPES):
msg = f"Refusing to fetch {url}: only the jsDelivr graph viewer URLs are allowed"
@@ -147,6 +147,7 @@ def _render_module_source(
def refresh_graph_ui_sri_cmd(
mthds_ui_version: str | None = None,
+ *,
elkjs_version: str | None = None,
output_path: Path | None = None,
quiet: bool = False,
@@ -162,11 +163,11 @@ def refresh_graph_ui_sri_cmd(
# `is None` (not falsy) so an explicit empty-string argument fails validation rather than silently falling back to the default.
target_mthds_ui_version = _validate_version(
"mthds-ui",
- current_pins.MTHDS_UI_VERSION if mthds_ui_version is None else mthds_ui_version,
+ value=current_pins.MTHDS_UI_VERSION if mthds_ui_version is None else mthds_ui_version,
)
target_elkjs_version = _validate_version(
"elkjs",
- current_pins.ELKJS_VERSION if elkjs_version is None else elkjs_version,
+ value=current_pins.ELKJS_VERSION if elkjs_version is None else elkjs_version,
)
target_path = output_path or _DEFAULT_OUTPUT_PATH
diff --git a/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py b/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
index e10234acb..711b877c0 100644
--- a/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
+++ b/pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py
@@ -17,7 +17,7 @@ PIPELEX_DIR = ".pipelex"
KIT_CONFIGS_DIR = "pipelex/kit/configs"
-def _display_result(result: MirrorDirResult, quiet: bool) -> None:
+def _display_result(result: MirrorDirResult, *, quiet: bool) -> None:
"""Display the outcome of the kit config sync."""
console = get_console()
prefix = "(dry run) " if result.dry_run else ""
@@ -83,7 +83,7 @@ def _display_result(result: MirrorDirResult, quiet: bool) -> None:
console.print()
-def sync_kit_configs_cmd(quiet: bool = False, dry_run: bool = False) -> None:
+def sync_kit_configs_cmd(quiet: bool = False, *, dry_run: bool = False) -> None:
"""Mirror the .pipelex/ directory into pipelex/kit/configs/.
Copies new and changed files and deletes files absent from .pipelex/, using
diff --git a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
index 0ec259a61..f4b4da25c 100644
--- a/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
+++ b/pipelex/cli/dev_cli/commands/sync_main_config_cmd.py
@@ -37,6 +37,7 @@ def _format_value(value: object) -> str:
def _display_sync_result(
result: TomlSyncResult,
+ *,
target_label: str,
show_diff: bool,
quiet: bool,
@@ -75,6 +76,7 @@ def _display_sync_result(
def sync_main_config_cmd(
target: SyncTarget = SyncTarget.ALL,
+ *,
dry_run: bool = False,
quiet: bool = False,
show_diff: bool = True,
@@ -116,7 +118,7 @@ def sync_main_config_cmd(
if sync_kit:
if KIT_CONFIG_PATH.exists():
try:
- kit_result = sync_toml_values(MAIN_CONFIG_PATH, KIT_CONFIG_PATH, dry_run=dry_run)
+ kit_result = sync_toml_values(source_path=MAIN_CONFIG_PATH, target_path=KIT_CONFIG_PATH, dry_run=dry_run)
results.append(("kit", kit_result, KIT_CONFIG_PATH))
except OSError as exc:
# Handle race condition where file is deleted/modified after exists() check
@@ -134,7 +136,7 @@ def sync_main_config_cmd(
if sync_project:
if PROJECT_CONFIG_PATH.exists():
try:
- project_result = sync_toml_values(MAIN_CONFIG_PATH, PROJECT_CONFIG_PATH, dry_run=dry_run)
+ project_result = sync_toml_values(source_path=MAIN_CONFIG_PATH, target_path=PROJECT_CONFIG_PATH, dry_run=dry_run)
results.append(("project", project_result, PROJECT_CONFIG_PATH))
except OSError as exc:
# Handle race condition where file is deleted/modified after exists() check
@@ -152,7 +154,7 @@ def sync_main_config_cmd(
total_updated = 0
for label, result, path in results:
if result is not None:
- _display_sync_result(result, f"{label} ({path})", show_diff=show_diff, quiet=quiet)
+ _display_sync_result(result, target_label=f"{label} ({path})", show_diff=show_diff, quiet=quiet)
total_updated += result.updated_count
if not quiet:
diff --git a/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py b/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
index 3a8ab66ba..ea38c2a3d 100644
--- a/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
+++ b/pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py
@@ -40,6 +40,7 @@ def gateway_models_reference_files() -> list[tuple[Path, Path]]:
def _all_references_up_to_date(
reference_files: list[tuple[Path, Path]],
+ *,
expected_html: str,
expected_plain: str,
) -> bool:
@@ -121,7 +122,7 @@ def update_gateway_models_cmd(quiet: bool = False) -> None:
# Skip writing if every reference file is already current (ignoring the
# timestamp line) — avoids noisy diffs in PRs.
- if _all_references_up_to_date(reference_files, markdown_content, plain_markdown_content):
+ if _all_references_up_to_date(reference_files, expected_html=markdown_content, expected_plain=plain_markdown_content):
if quiet:
console.print(f"[green]✓ Gateway models update: UP-TO-DATE[/green] ({model_count} models, no changes)")
else:
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index c58716f03..5d8d7645d 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -12,7 +12,6 @@ from pipelex.cogt.exceptions import GatewayUnknownModelError, ModelDeckPresetVal
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.hub import get_console
from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.system.pipelex_service.exceptions import (
GatewayApiKeyMissingError,
@@ -122,7 +121,7 @@ def display_error_panel(
console.print()
-def handle_model_choice_error(exc: PipeOperatorModelChoiceError, context: ErrorContext) -> NoReturn:
+def handle_model_choice_error(exc: PipeOperatorModelChoiceError, *, context: ErrorContext) -> NoReturn:
"""Handle and display PipeOperatorModelChoiceError with formatted output.
Args:
@@ -153,7 +152,7 @@ def handle_model_choice_error(exc: PipeOperatorModelChoiceError, context: ErrorC
raise typer.Exit(1) from exc
-def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, context: ErrorContext) -> NoReturn:
+def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *, context: ErrorContext) -> NoReturn:
"""Handle and display PipeOperatorModelAvailabilityError with formatted output.
Args:
@@ -190,7 +189,7 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, con
raise typer.Exit(1) from exc
-def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, context: ErrorContext) -> NoReturn:
+def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, *, context: ErrorContext) -> NoReturn:
"""Handle and display ModelDeckPresetValidatonError with formatted output.
Args:
@@ -245,7 +244,7 @@ def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, context:
raise typer.Exit(1) from exc
-def _display_validation_error_details(console: Console, exc: ValidateBundleError) -> None:
+def _display_validation_error_details(console: Console, *, exc: ValidateBundleError) -> None:
"""Display the detailed validation error information from a ValidateBundleError.
Args:
@@ -316,31 +315,8 @@ def _display_validation_error_details(console: Console, exc: ValidateBundleError
console.print("[bold cyan]Dry Run Error:[/bold cyan]\n")
console.print(f"[yellow]{escape(exc.dry_run_error_message)}[/yellow]\n")
- # Display signature pre-check error (strict mode refused due to PipeSignature placeholders)
- if exc.signature_check_error is not None:
- console.print("[bold cyan]Unimplemented Signatures:[/bold cyan]\n")
- console.print(f"[yellow]{escape(str(exc.signature_check_error))}[/yellow]\n")
-
-def handle_signatures_not_allowed_error(exc: SignaturesNotAllowedError, *, context: ErrorContext) -> NoReturn:
- """Render `SignaturesNotAllowedError` as a Rich CLI error and exit.
-
- Mirrors the bundle-path treatment so the single-pipe validation path also produces a
- friendly error message instead of an unhandled traceback (issue #6 / greptile).
- """
- console = get_console()
- print_traceback_if_requested(console)
- console.print(f"\n[bold red]❌ {context} failed because of unimplemented PipeSignature placeholders[/bold red]\n")
- console.print(f"[yellow]{escape(str(exc))}[/yellow]\n")
- console.print(
- "[bold green]💡 Tip:[/bold green] Replace each placeholder with a real implementation, or re-run with [cyan]--allow-signatures[/cyan]."
- )
- console.print(f"[dim]Learn more: {URLs.documentation}[/dim]")
- console.print(f"[dim]Join our Discord for help: {URLs.discord}[/dim]\n")
- raise typer.Exit(1) from exc
-
-
-def handle_validate_bundle_error(exc: ValidateBundleError, bundle_path: Path | None = None) -> NoReturn:
+def handle_validate_bundle_error(exc: ValidateBundleError, *, bundle_path: Path | None = None) -> NoReturn:
"""Handle and display ValidateBundleError with formatted output.
Args:
diff --git a/pipelex/cli/installed_methods.py b/pipelex/cli/installed_methods.py
index 9b7cd4d51..8284ebf7b 100644
--- a/pipelex/cli/installed_methods.py
+++ b/pipelex/cli/installed_methods.py
@@ -42,6 +42,7 @@ class InstalledMethod(BaseModel):
def discover_installed_methods(
include_global: bool = True,
+ *,
include_project: bool = True,
extra_search_dirs: list[Path] | None = None,
) -> list[InstalledMethod]:
@@ -108,7 +109,7 @@ def discover_installed_methods(
return methods
-def discover_method_at(method_dir: Path, seen_dirs: set[Path]) -> InstalledMethod | None:
+def discover_method_at(method_dir: Path, *, seen_dirs: set[Path]) -> InstalledMethod | None:
"""Try to discover a single method at *method_dir*.
Returns an ``InstalledMethod`` if the directory contains a ``METHODS.toml``,
@@ -165,7 +166,7 @@ def discover_methods_from_library_dirs(
continue
# First, check if the directory itself is a method
- method = discover_method_at(lib_dir, seen_dirs)
+ method = discover_method_at(lib_dir, seen_dirs=seen_dirs)
if method is not None:
methods.append(method)
continue
@@ -173,7 +174,7 @@ def discover_methods_from_library_dirs(
# Otherwise, recursively find all METHODS.toml files below this directory
for manifest_path in sorted(lib_dir.rglob(MANIFEST_FILENAME)):
method_dir = manifest_path.parent
- sub_method = discover_method_at(method_dir, seen_dirs)
+ sub_method = discover_method_at(method_dir, seen_dirs=seen_dirs)
if sub_method is not None:
methods.append(sub_method)
@@ -182,6 +183,7 @@ def discover_methods_from_library_dirs(
def find_method_by_full_address(
full_address: str,
+ *,
methods: list[InstalledMethod] | None = None,
extra_search_dirs: list[Path] | None = None,
) -> InstalledMethod | None:
@@ -213,6 +215,7 @@ def find_method_by_full_address(
def find_method_by_name(
method_name: str,
+ *,
methods: list[InstalledMethod] | None = None,
library_dirs: list[str] | None = None,
) -> InstalledMethod:
diff --git a/pipelex/cli/method_resolver.py b/pipelex/cli/method_resolver.py
index c1be08374..850ad43ee 100644
--- a/pipelex/cli/method_resolver.py
+++ b/pipelex/cli/method_resolver.py
@@ -153,7 +153,7 @@ def resolve_method_from_path(method_path: str) -> InstalledMethod:
raise typer.Exit(1)
seen_dirs: set[Path] = set()
- method = discover_method_at(method_dir, seen_dirs)
+ method = discover_method_at(method_dir, seen_dirs=seen_dirs)
if method is None:
typer.secho(
f"No method package (METHODS.toml) found at '{method_path}'.",
@@ -212,7 +212,7 @@ def resolve_method_from_url(url: str) -> InstalledMethod:
# Discover the method package
seen_dirs: set[Path] = set()
- method = discover_method_at(method_dir, seen_dirs)
+ method = discover_method_at(method_dir, seen_dirs=seen_dirs)
if method is None:
typer.secho(
f"No method package (METHODS.toml) found at '{url}'.",
@@ -226,6 +226,7 @@ def resolve_method_from_url(url: str) -> InstalledMethod:
def resolve_method_target(
method_name: str,
+ *,
pipe_override: str | None = None,
library_dirs: list[str] | None = None,
) -> tuple[str, list[str], InstalledMethod]:
diff --git a/pipelex/cogt/config_cogt.py b/pipelex/cogt/config_cogt.py
index b0213211a..fca7b96f9 100644
--- a/pipelex/cogt/config_cogt.py
+++ b/pipelex/cogt/config_cogt.py
@@ -27,7 +27,7 @@ class ImgGenConfig(ConfigModel):
def make_default_img_gen_job_params(self) -> ImgGenJobParams:
return self.img_gen_param_defaults.make_img_gen_job_params()
- def get_num_inference_steps(self, model_name: str, quality: Quality) -> int:
+ def get_num_inference_steps(self, model_name: str, *, quality: Quality) -> int:
quality_to_steps_map = self.quality_to_steps_maps.get(model_name)
if not quality_to_steps_map:
msg = f"No quality-to-steps map found for model '{model_name}'"
@@ -93,7 +93,7 @@ class LLMConfig(ConfigModel):
raise LLMConfigError(msg)
return template
- def get_reasoning_budget(self, prompting_target: str, effort: ReasoningEffort) -> int:
+ def get_reasoning_budget(self, prompting_target: str, *, effort: ReasoningEffort) -> int:
effort_to_budget_map = self.effort_to_budget_maps.get(prompting_target)
if not effort_to_budget_map:
msg = f"No effort-to-budget map found for prompting target '{prompting_target}'"
diff --git a/pipelex/cogt/content_generation/assignment_models.py b/pipelex/cogt/content_generation/assignment_models.py
index 45100e33f..dc8c79ea6 100644
--- a/pipelex/cogt/content_generation/assignment_models.py
+++ b/pipelex/cogt/content_generation/assignment_models.py
@@ -26,6 +26,7 @@ class LLMAssignment(BaseModel):
@classmethod
def make_from_prompt(
cls,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
llm_setting: LLMSetting,
@@ -85,6 +86,7 @@ class ObjectAssignment(BaseModel):
@staticmethod
def make_for_class(
object_class: type[BaseModel],
+ *,
llm_assignment: LLMAssignment,
nb_items: int | None = None,
) -> "ObjectAssignment":
@@ -174,6 +176,7 @@ class SearchObjectAssignment(BaseModel):
@staticmethod
def make_for_class(
output_class: type[BaseModel],
+ *,
search_assignment: SearchAssignment,
) -> "SearchObjectAssignment":
return SearchObjectAssignment(
diff --git a/pipelex/cogt/content_generation/content_generator.py b/pipelex/cogt/content_generation/content_generator.py
index d08e8eeac..86f6817da 100644
--- a/pipelex/cogt/content_generation/content_generator.py
+++ b/pipelex/cogt/content_generation/content_generator.py
@@ -43,8 +43,8 @@ from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
def _revalidate_against_object_class(
raw_obj: BaseModel,
- object_class: type[BaseModelTypeVar],
*,
+ object_class: type[BaseModelTypeVar],
is_mock_built: bool,
) -> BaseModelTypeVar:
"""Re-validate a leaf-generated object's data against the original ``object_class``.
@@ -88,6 +88,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@update_job_metadata
async def make_llm_text(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
llm_setting_main: LLMSetting,
@@ -110,6 +111,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@update_job_metadata
async def make_object(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
object_class: type[BaseModelTypeVar],
@@ -129,12 +131,13 @@ class ContentGenerator(ContentGeneratorProtocol):
)
raw_obj = await llm_gen_object(object_assignment=object_assignment)
log.verbose(f"{self.__class__.__name__} generated object direct: {raw_obj}")
- return _revalidate_against_object_class(raw_obj, object_class, is_mock_built=cogt_run_params.run_mode.is_dry)
+ return _revalidate_against_object_class(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)
@override
@update_job_metadata
async def make_object_list(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
object_class: type[BaseModelTypeVar],
@@ -155,12 +158,16 @@ class ContentGenerator(ContentGeneratorProtocol):
)
raw_list = await llm_gen_object_list(object_assignment=object_assignment)
log.verbose(f"{self.__class__.__name__} generated object list direct: {raw_list}")
- return [_revalidate_against_object_class(raw_obj, object_class, is_mock_built=cogt_run_params.run_mode.is_dry) for raw_obj in raw_list]
+ return [
+ _revalidate_against_object_class(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)
+ for raw_obj in raw_list
+ ]
@override
@update_job_metadata
async def make_single_image(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
img_gen_handle: str,
@@ -189,6 +196,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@update_job_metadata
async def make_image_list(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
img_gen_handle: str,
@@ -217,6 +225,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@override
async def make_templated_text(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
context: dict[str, Any],
@@ -238,6 +247,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@update_job_metadata
async def make_render_page_views(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
extract_input: ExtractInput,
@@ -265,6 +275,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@update_job_metadata
async def make_extract_pages(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
extract_input: ExtractInput,
@@ -317,6 +328,7 @@ class ContentGenerator(ContentGeneratorProtocol):
@override
async def make_search_structured(
self,
+ *,
output_structure_class: type[BaseModelTypeVar],
search_assignment: SearchAssignment,
) -> BaseModelTypeVar:
diff --git a/pipelex/cogt/content_generation/content_generator_protocol.py b/pipelex/cogt/content_generation/content_generator_protocol.py
index e996acf86..15b6edc9a 100644
--- a/pipelex/cogt/content_generation/content_generator_protocol.py
+++ b/pipelex/cogt/content_generation/content_generator_protocol.py
@@ -55,6 +55,7 @@ class ContentGeneratorProtocol(Protocol):
def make_llm_text(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
llm_setting_main: LLMSetting,
@@ -63,6 +64,7 @@ class ContentGeneratorProtocol(Protocol):
def make_object(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
object_class: type[BaseModelTypeVar],
@@ -72,6 +74,7 @@ class ContentGeneratorProtocol(Protocol):
def make_object_list(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
object_class: type[BaseModelTypeVar],
@@ -82,6 +85,7 @@ class ContentGeneratorProtocol(Protocol):
def make_single_image(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
img_gen_handle: str,
@@ -92,6 +96,7 @@ class ContentGeneratorProtocol(Protocol):
def make_image_list(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
img_gen_handle: str,
@@ -103,6 +108,7 @@ class ContentGeneratorProtocol(Protocol):
def make_templated_text(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
context: dict[str, Any],
@@ -113,6 +119,7 @@ class ContentGeneratorProtocol(Protocol):
def make_render_page_views(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
extract_input: ExtractInput,
@@ -123,6 +130,7 @@ class ContentGeneratorProtocol(Protocol):
def make_extract_pages(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
extract_input: ExtractInput,
@@ -138,6 +146,7 @@ class ContentGeneratorProtocol(Protocol):
def make_search_structured(
self,
+ *,
output_structure_class: type[BaseModelTypeVar],
search_assignment: SearchAssignment,
) -> Coroutine[Any, Any, BaseModelTypeVar]: ...
diff --git a/pipelex/cogt/content_generation/dry_mock.py b/pipelex/cogt/content_generation/dry_mock.py
index e84423aa7..1c3834603 100644
--- a/pipelex/cogt/content_generation/dry_mock.py
+++ b/pipelex/cogt/content_generation/dry_mock.py
@@ -31,9 +31,9 @@ code path, identical mock everywhere); exotic format constraints must declare
``examples`` / ``mock_format`` — see ``DryRunObjectFidelityError``.
"""
-from collections.abc import Callable, Sequence
+from collections.abc import Sequence
from datetime import datetime
-from typing import Any
+from typing import Any, Protocol
from polyfactory.exceptions import FactoryException
from pydantic import BaseModel, ValidationError
@@ -140,7 +140,7 @@ def _report_synthetic_llm_job(
get_report_delegate().report_inference_job(inference_job=synthetic_job)
-def report_dry_llm_job(job_metadata: JobMetadata, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None:
+def report_dry_llm_job(job_metadata: JobMetadata, *, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None:
"""Report a zero-token synthetic LLM job for a ``--dry-run`` inference (cost report suppressed)."""
_report_synthetic_llm_job(
job_metadata=job_metadata,
@@ -152,7 +152,7 @@ def report_dry_llm_job(job_metadata: JobMetadata, llm_setting: LLMSetting, llm_p
)
-def report_mock_usage_llm_job(job_metadata: JobMetadata, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None:
+def report_mock_usage_llm_job(job_metadata: JobMetadata, *, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None:
"""Report a non-zero synthetic LLM job for a dry run with ``is_mock_usage=True`` (cost report renders)."""
_report_synthetic_llm_job(
job_metadata=job_metadata,
@@ -183,7 +183,7 @@ def build_mock_object(model_class: type[BaseModelTypeVar], **field_values: Any)
raise DryRunMockBuildError.for_object_class(model_class.__name__) from exc
-def build_mock_objects(model_class: type[BaseModelTypeVar], count: int) -> list[BaseModelTypeVar]:
+def build_mock_objects(model_class: type[BaseModelTypeVar], *, count: int) -> list[BaseModelTypeVar]:
"""Build ``count`` mock instances with a single factory construction.
``DryRunFactory.make_dry_run_factory`` recursively scans the model tree and mints dynamic
@@ -233,10 +233,11 @@ def _nb_list_items(object_assignment: ObjectAssignment) -> int:
return get_config().pipelex.dry_run_config.nb_list_items
-_ReportLLMJobFunc = Callable[[JobMetadata, LLMSetting, LLMPrompt], None]
+class _ReportLLMJobFunc(Protocol):
+ def __call__(self, job_metadata: JobMetadata, *, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None: ...
-def _leaf_gen_object(object_assignment: ObjectAssignment, report_func: _ReportLLMJobFunc) -> BaseModel:
+def _leaf_gen_object(object_assignment: ObjectAssignment, *, report_func: _ReportLLMJobFunc) -> BaseModel:
"""Shared object-mock pipeline: reconstruct the class from its schema, report once, build one mock.
Built from the schema-reconstructed class (the leaf carries only the JSON schema, not the original
@@ -254,17 +255,17 @@ def _leaf_gen_object(object_assignment: ObjectAssignment, report_func: _ReportLL
mock_object = build_mock_object(item_class)
# Report only after a successful build — a failed mock must not leave a usage event behind.
llm_assignment = object_assignment.llm_assignment_for_object
- report_func(llm_assignment.job_metadata, llm_assignment.llm_setting, llm_assignment.llm_prompt)
+ report_func(llm_assignment.job_metadata, llm_setting=llm_assignment.llm_setting, llm_prompt=llm_assignment.llm_prompt)
return mock_object
-def _leaf_gen_object_list(object_assignment: ObjectAssignment, report_func: _ReportLLMJobFunc) -> list[BaseModel]:
+def _leaf_gen_object_list(object_assignment: ObjectAssignment, *, report_func: _ReportLLMJobFunc) -> list[BaseModel]:
"""List counterpart of :func:`_leaf_gen_object`: one report, ``nb_items`` builds (D11)."""
item_class = _reconstruct_object_class(object_assignment)
- mock_objects = build_mock_objects(item_class, _nb_list_items(object_assignment))
+ mock_objects = build_mock_objects(item_class, count=_nb_list_items(object_assignment))
# Report only after a successful build — a failed mock must not leave a usage event behind.
llm_assignment = object_assignment.llm_assignment_for_object
- report_func(llm_assignment.job_metadata, llm_assignment.llm_setting, llm_assignment.llm_prompt)
+ report_func(llm_assignment.job_metadata, llm_setting=llm_assignment.llm_setting, llm_prompt=llm_assignment.llm_prompt)
return mock_objects
@@ -294,7 +295,7 @@ def dry_llm_gen_text(llm_assignment: LLMAssignment) -> str:
job_metadata = llm_assignment.job_metadata
log.verbose(f"🤡 DRY RUN: llm_gen_text for '{job_metadata.pipeline_run_id}'")
report_func = _dry_report_func(llm_assignment.cogt_run_params)
- report_func(job_metadata, llm_assignment.llm_setting, llm_assignment.llm_prompt)
+ report_func(job_metadata, llm_setting=llm_assignment.llm_setting, llm_prompt=llm_assignment.llm_prompt)
prompt_truncated = llm_assignment.llm_prompt.desc(truncate_text_length=_dry_text_gen_truncate_length())
return f"DRY RUN: llm_gen_text • llm_setting={llm_assignment.llm_setting.desc()} • prompt={prompt_truncated}"
@@ -339,7 +340,7 @@ def dry_templating_gen_text(templating_assignment: TemplatingAssignment) -> str:
)
-def _dry_image_content(image_url: str, img_gen_assignment: ImgGenAssignment | None = None) -> ImageContent:
+def _dry_image_content(image_url: str, *, img_gen_assignment: ImgGenAssignment | None = None) -> ImageContent:
image_content = ImageContent(
url=image_url,
public_url=image_url,
@@ -406,7 +407,7 @@ def dry_search_gen_sourced_answer(search_assignment: SearchAssignment) -> Search
"""Dry leaf for sourced-answer search: polyfactory-built result with mock sources, no provider."""
log.verbose(f"🤡 DRY RUN: search_gen_sourced_answer for '{search_assignment.search_handle}'")
nb_sources = get_config().pipelex.dry_run_config.nb_list_items
- mock_sources = build_mock_objects(DocumentContent, nb_sources)
+ mock_sources = build_mock_objects(DocumentContent, count=nb_sources)
return build_mock_object(SearchResultContent, sources=mock_sources)
diff --git a/pipelex/cogt/content_generation/dry_run_factory.py b/pipelex/cogt/content_generation/dry_run_factory.py
index d03340574..d689e6b34 100644
--- a/pipelex/cogt/content_generation/dry_run_factory.py
+++ b/pipelex/cogt/content_generation/dry_run_factory.py
@@ -71,7 +71,10 @@ class DryRunFactory:
return result
@staticmethod
- def _main_pipe_from_pipe_dict(_field_name: str, values: dict[str, Any]) -> str:
+ def _main_pipe_from_pipe_dict( # kw-only: ignore -- polyfactory PostGenerated invokes it positionally
+ _field_name: str,
+ values: dict[str, Any],
+ ) -> str:
"""PostGenerated callback that picks a key from the pipe dict for main_pipe."""
pipe_dict: dict[str, Any] | None = values.get("pipe")
if pipe_dict and len(pipe_dict) > 0:
@@ -194,6 +197,7 @@ class DryRunFactory:
def _find_nested_base_model_classes(
cls,
object_class: type[BaseModel],
+ *,
visited: set[type[BaseModel]] | None = None,
) -> set[type[BaseModel]]:
"""Recursively find all nested BaseModel classes in a model's field annotations.
@@ -226,7 +230,7 @@ class DryRunFactory:
if isinstance(type_to_check, type) and issubclass(type_to_check, BaseModel) and type_to_check not in visited:
nested_classes.add(type_to_check)
# Recursively find nested classes
- nested_classes.update(cls._find_nested_base_model_classes(type_to_check, visited))
+ nested_classes.update(cls._find_nested_base_model_classes(type_to_check, visited=visited))
return nested_classes
@@ -335,6 +339,7 @@ class DryRunFactory:
def make_dry_run_factory(
cls,
object_class: type[BaseModelTypeVar],
+ *,
snake_case_field_names: set[str] | None = None,
pascal_case_field_names: set[str] | None = None,
) -> type[ModelFactory[BaseModelTypeVar]]:
diff --git a/pipelex/cogt/content_generation/extract_generate.py b/pipelex/cogt/content_generation/extract_generate.py
index 1250940d9..f40f6b8aa 100644
--- a/pipelex/cogt/content_generation/extract_generate.py
+++ b/pipelex/cogt/content_generation/extract_generate.py
@@ -20,6 +20,7 @@ async def extract_gen_pages(extract_assignment: ExtractAssignment) -> ExtractOut
async def extract_gen_pages_and_store(
extract_assignment: ExtractAssignment,
+ *,
generated_content_factory: GeneratedContentFactory,
) -> list[PageContent]:
"""Extract pages and store extracted images, returning PageContent with URLs (no raw binary data).
diff --git a/pipelex/cogt/content_generation/generated_content_factory.py b/pipelex/cogt/content_generation/generated_content_factory.py
index 98353c9e0..cb28c8c83 100644
--- a/pipelex/cogt/content_generation/generated_content_factory.py
+++ b/pipelex/cogt/content_generation/generated_content_factory.py
@@ -25,6 +25,7 @@ class GeneratedContentFactory:
def _build_storage_key(
self,
primary_id: str,
+ *,
secondary_id: str,
data: bytes,
mime_type: str | None,
@@ -67,6 +68,7 @@ class GeneratedContentFactory:
async def make_image_content(
self,
primary_id: str,
+ *,
secondary_id: str,
raw_details: GeneratedImageRawDetails,
) -> ImageContent:
@@ -159,6 +161,7 @@ class GeneratedContentFactory:
async def make_page_contents(
self,
primary_id: str,
+ *,
secondary_id: str,
extract_output: ExtractOutput,
) -> list[PageContent]:
diff --git a/pipelex/cogt/content_generation/img_gen_generate.py b/pipelex/cogt/content_generation/img_gen_generate.py
index a92781884..0d817e7a8 100644
--- a/pipelex/cogt/content_generation/img_gen_generate.py
+++ b/pipelex/cogt/content_generation/img_gen_generate.py
@@ -39,6 +39,7 @@ async def img_gen_image_list(img_gen_assignment: ImgGenAssignment) -> list[Gener
async def img_gen_single_image_and_store(
img_gen_assignment: ImgGenAssignment,
+ *,
generated_content_factory: GeneratedContentFactory,
) -> ImageContent:
"""Generate a single image and store it, returning an ImageContent with URLs (no raw binary data).
@@ -64,6 +65,7 @@ async def img_gen_single_image_and_store(
async def img_gen_image_list_and_store(
img_gen_assignment: ImgGenAssignment,
+ *,
generated_content_factory: GeneratedContentFactory,
) -> list[ImageContent]:
"""Generate multiple images and store them, returning ImageContent list with URLs (no raw binary data).
diff --git a/pipelex/cogt/content_generation/render_generate.py b/pipelex/cogt/content_generation/render_generate.py
index 3b6b980cd..b041697d6 100644
--- a/pipelex/cogt/content_generation/render_generate.py
+++ b/pipelex/cogt/content_generation/render_generate.py
@@ -16,6 +16,7 @@ from pipelex.tools.misc.image_utils import ImageFormat
async def render_page_views_and_store(
render_assignment: RenderPageViewsAssignment,
+ *,
generated_content_factory: GeneratedContentFactory,
) -> list[ImageContent]:
"""Render PDF pages as images, store them, and return lightweight ImageContent references.
diff --git a/pipelex/cogt/content_generation/schema_to_model_factory.py b/pipelex/cogt/content_generation/schema_to_model_factory.py
index 5d9f221f9..9b920f849 100644
--- a/pipelex/cogt/content_generation/schema_to_model_factory.py
+++ b/pipelex/cogt/content_generation/schema_to_model_factory.py
@@ -79,7 +79,7 @@ class SchemaToModelFactory:
_source_cache_lock: ClassVar[threading.Lock] = threading.Lock()
@classmethod
- def make_from_json_schema(cls, schema: dict[str, Any], class_name: str) -> type[BaseModel]:
+ def make_from_json_schema(cls, schema: dict[str, Any], *, class_name: str) -> type[BaseModel]:
"""Reconstruct a BaseModel class from a JSON schema dict.
Args:
@@ -103,7 +103,7 @@ class SchemaToModelFactory:
return cls._schema_cache[cache_key]
source_code = cls._generate_source_from_schema(schema)
- reconstructed_class = cls._exec_and_extract_class(source_code, class_name)
+ reconstructed_class = cls._exec_and_extract_class(source_code, class_name=class_name)
reconstructed_class.__kajson_class_source__ = source_code # type: ignore[attr-defined]
if len(cls._schema_cache) >= cls._SCHEMA_CACHE_MAX_SIZE:
cls._schema_cache.popitem(last=False)
@@ -123,7 +123,7 @@ class SchemaToModelFactory:
return "".join(segment[0].upper() + segment[1:] if segment else "" for segment in segments)
@classmethod
- def _collect_unsafe_extension_paths(cls, node: Any, path: str, found: list[str]) -> None:
+ def _collect_unsafe_extension_paths(cls, node: Any, *, path: str, found: list[str]) -> None:
"""Walk a JSON-schema-shaped value, collecting dotted paths to any x-python-* key.
These extensions cause datamodel-code-generator to emit arbitrary `from X import Y`
@@ -136,11 +136,11 @@ class SchemaToModelFactory:
child_path = f"{path}.{key}" if path else key
if key.startswith(cls._UNSAFE_EXTENSION_PREFIX):
found.append(child_path)
- cls._collect_unsafe_extension_paths(value, child_path, found)
+ cls._collect_unsafe_extension_paths(value, path=child_path, found=found)
elif isinstance(node, list):
node_list = cast("list[Any]", node)
for index, item in enumerate(node_list):
- cls._collect_unsafe_extension_paths(item, f"{path}[{index}]", found)
+ cls._collect_unsafe_extension_paths(item, path=f"{path}[{index}]", found=found)
@classmethod
def _reject_unsafe_schema_extensions(cls, schema: dict[str, Any]) -> None:
@@ -152,7 +152,7 @@ class SchemaToModelFactory:
leaving no signal in logs for incident response.
"""
found: list[str] = []
- cls._collect_unsafe_extension_paths(schema, "", found)
+ cls._collect_unsafe_extension_paths(schema, path="", found=found)
if found:
msg = f"Unsafe codegen extensions found in schema: {found}"
raise UnsafeSchemaError(msg)
@@ -198,7 +198,7 @@ class SchemaToModelFactory:
output_path.unlink(missing_ok=True)
@classmethod
- def _restricted_import(
+ def _restricted_import( # kw-only: ignore -- registered as __import__; the interpreter calls it positionally
cls,
name: str,
import_globals: dict[str, Any] | None = None,
@@ -316,7 +316,7 @@ class SchemaToModelFactory:
return dict(types_dict)
@classmethod
- def _exec_and_extract_class(cls, source_code: str, class_name: str) -> type[BaseModel]:
+ def _exec_and_extract_class(cls, source_code: str, *, class_name: str) -> type[BaseModel]:
"""Execute source code and extract the named BaseModel class."""
all_user_types = cls.make_types_from_source(source_code)
model_classes: dict[str, type[BaseModel]] = {name: obj for name, obj in all_user_types.items() if issubclass(obj, BaseModel)}
diff --git a/pipelex/cogt/document/prompt_document_factory.py b/pipelex/cogt/document/prompt_document_factory.py
index 3980d70f6..eda37ad88 100644
--- a/pipelex/cogt/document/prompt_document_factory.py
+++ b/pipelex/cogt/document/prompt_document_factory.py
@@ -18,6 +18,7 @@ class PromptDocumentFactory:
def make_prompt_document(
cls,
uri: str | None = None,
+ *,
base64_data: str | None = None,
raw_bytes: bytes | None = None,
mime_type: str | None = None,
diff --git a/pipelex/cogt/document/prompt_document_utils.py b/pipelex/cogt/document/prompt_document_utils.py
index 4d3911e1c..0e06f0ed1 100644
--- a/pipelex/cogt/document/prompt_document_utils.py
+++ b/pipelex/cogt/document/prompt_document_utils.py
@@ -29,6 +29,7 @@ from pipelex.tools.uri.resolved_uri import (
async def prepare_prompt_document(
prompt_document: PromptDocument,
+ *,
is_http_url_enabled: bool,
) -> PreparedFile:
"""Prepare a single prompt document for LLM API consumption.
@@ -94,6 +95,7 @@ async def prepare_prompt_document(
async def prep_prompt_documents(
prompt_documents: list[PromptDocument],
+ *,
is_http_url_enabled: bool,
) -> list[PreparedFile]:
"""Prepare multiple prompt documents in parallel.
diff --git a/pipelex/cogt/exceptions.py b/pipelex/cogt/exceptions.py
index cb11e294a..643825da0 100644
--- a/pipelex/cogt/exceptions.py
+++ b/pipelex/cogt/exceptions.py
@@ -65,7 +65,7 @@ class CogtError(PipelexError):
if provider_metadata is not None:
self.provider_metadata = provider_metadata
- def fill_model_and_provider(self, model_handle: str | None, backend_name: str | None) -> None:
+ def fill_model_and_provider(self, model_handle: str | None, *, backend_name: str | None) -> None:
"""Fill ``model_handle`` / ``backend_name`` from the worker, only when still unset.
Inference-failure leaf errors raised deep inside a provider plugin
diff --git a/pipelex/cogt/extract/bounding_box.py b/pipelex/cogt/extract/bounding_box.py
index 2c2b70d20..544d69b87 100644
--- a/pipelex/cogt/extract/bounding_box.py
+++ b/pipelex/cogt/extract/bounding_box.py
@@ -16,7 +16,7 @@ class BoundingBox(BaseModel):
bottom_left_y: float = Field(description="Y coordinate of bottom-left corner")
@classmethod
- def make_from_two_corners(cls, top_left_x: float, top_left_y: float, bottom_right_x: float, bottom_right_y: float) -> BoundingBox:
+ def make_from_two_corners(cls, *, top_left_x: float, top_left_y: float, bottom_right_x: float, bottom_right_y: float) -> BoundingBox:
return BoundingBox(
top_left_x=top_left_x,
top_left_y=top_left_y,
diff --git a/pipelex/cogt/extract/extract_job_factory.py b/pipelex/cogt/extract/extract_job_factory.py
index 4919bd2f5..8f70b094a 100644
--- a/pipelex/cogt/extract/extract_job_factory.py
+++ b/pipelex/cogt/extract/extract_job_factory.py
@@ -9,6 +9,7 @@ class ExtractJobFactory:
def make_extract_job(
cls,
extract_input: ExtractInput,
+ *,
job_metadata: JobMetadata,
extract_job_params: ExtractJobParams | None = None,
extract_job_config: ExtractJobConfig | None = None,
diff --git a/pipelex/cogt/extract/extract_worker_factory.py b/pipelex/cogt/extract/extract_worker_factory.py
index c6b225d4f..1449ff80b 100644
--- a/pipelex/cogt/extract/extract_worker_factory.py
+++ b/pipelex/cogt/extract/extract_worker_factory.py
@@ -13,6 +13,7 @@ class ExtractWorkerFactory:
def make_extract_worker(
cls,
inference_model: InferenceModelSpec,
+ *,
reporting_delegate: ReportingProtocol | None = None,
) -> ExtractWorkerAbstract:
plugin = Plugin.make_for_inference_model(inference_model=inference_model)
diff --git a/pipelex/cogt/file/file_preparation_utils.py b/pipelex/cogt/file/file_preparation_utils.py
index fcc2f5345..2da6aa28b 100644
--- a/pipelex/cogt/file/file_preparation_utils.py
+++ b/pipelex/cogt/file/file_preparation_utils.py
@@ -23,6 +23,7 @@ from pipelex.tools.uri.uri_resolver import resolve_uri
async def prepare_file_from_uri(
uri: str,
+ *,
keep_http_url: bool,
keep_local_path: bool,
) -> PreparedFile:
diff --git a/pipelex/cogt/image/generated_image.py b/pipelex/cogt/image/generated_image.py
index b147d3b27..903b402a1 100644
--- a/pipelex/cogt/image/generated_image.py
+++ b/pipelex/cogt/image/generated_image.py
@@ -58,7 +58,7 @@ class GeneratedImageRawDetails(CustomBaseModel):
return self
@classmethod
- def make_from_pil_image(cls, pil_image: Image.Image, image_format: ImageFormat) -> GeneratedImageRawDetails:
+ def make_from_pil_image(cls, pil_image: Image.Image, *, image_format: ImageFormat) -> GeneratedImageRawDetails:
try:
width, height = pil_image.size
actual_bytes = pil_image_to_bytes(pil_image=pil_image, image_format=image_format)
diff --git a/pipelex/cogt/image/prompt_image_factory.py b/pipelex/cogt/image/prompt_image_factory.py
index 63b470727..41a38f8a0 100644
--- a/pipelex/cogt/image/prompt_image_factory.py
+++ b/pipelex/cogt/image/prompt_image_factory.py
@@ -18,6 +18,7 @@ class PromptImageFactory:
def make_prompt_image(
cls,
uri: str | None = None,
+ *,
base64_data: str | None = None,
raw_bytes: bytes | None = None,
) -> PromptImage:
diff --git a/pipelex/cogt/image/prompt_image_utils.py b/pipelex/cogt/image/prompt_image_utils.py
index 9f75304d4..253607297 100644
--- a/pipelex/cogt/image/prompt_image_utils.py
+++ b/pipelex/cogt/image/prompt_image_utils.py
@@ -29,6 +29,7 @@ from pipelex.tools.uri.resolved_uri import (
async def prepare_prompt_image(
prompt_image: PromptImage,
+ *,
is_http_url_enabled: bool,
) -> PreparedFile:
"""Prepare a single prompt image for LLM API consumption.
@@ -95,6 +96,7 @@ async def prepare_prompt_image(
async def prep_prompt_images(
prompt_images: list[PromptImage],
+ *,
is_http_url_enabled: bool,
) -> list[PreparedFile]:
"""Prepare multiple prompt images in parallel.
diff --git a/pipelex/cogt/img_gen/img_gen_args_factory.py b/pipelex/cogt/img_gen/img_gen_args_factory.py
index 99f513ffb..425fb1412 100644
--- a/pipelex/cogt/img_gen/img_gen_args_factory.py
+++ b/pipelex/cogt/img_gen/img_gen_args_factory.py
@@ -49,6 +49,7 @@ class ImgGenArgsFactory:
async def make_args_for_model(
cls,
model_rules: ImgGenModelRules,
+ *,
img_gen_job: ImgGenJob,
nb_images: int,
model_id: str,
@@ -195,7 +196,7 @@ class ImgGenArgsFactory:
return args_dict
@classmethod
- def make_args_from_num_images(cls, num_images_taxonomy: NumImagesTaxonomy, nb_images: int) -> dict[str, Any]:
+ def make_args_from_num_images(cls, num_images_taxonomy: NumImagesTaxonomy, *, nb_images: int) -> dict[str, Any]:
"""Map number of images to provider-specific parameter name."""
match num_images_taxonomy:
case NumImagesTaxonomy.FAL:
@@ -207,6 +208,7 @@ class ImgGenArgsFactory:
def make_args_from_prompt(
cls,
prompt_taxonomy: PromptTaxonomy,
+ *,
positive_text: str,
negative_text: str | None,
) -> dict[str, Any]:
@@ -236,6 +238,7 @@ class ImgGenArgsFactory:
def make_args_from_model_name(
cls,
model_name_taxonomy: ModelChoiceTaxonomy,
+ *,
model_id: str,
model_name: str,
) -> dict[str, Any]:
@@ -247,7 +250,7 @@ class ImgGenArgsFactory:
return {"model": model_name}
@classmethod
- def make_args_from_background(cls, background_taxonomy: BackgroundTaxonomy, background: Background, model_name: str) -> dict[str, Any]:
+ def make_args_from_background(cls, background_taxonomy: BackgroundTaxonomy, *, background: Background, model_name: str) -> dict[str, Any]:
"""Map background setting to provider-specific parameter.
Raises:
@@ -267,6 +270,7 @@ class ImgGenArgsFactory:
def make_args_from_aspect_ratio(
cls,
aspect_ratio_taxonomy: AspectRatioTaxonomy,
+ *,
aspect_ratio: AspectRatio,
size: ImageSize | None,
model_name: str,
@@ -369,6 +373,7 @@ class ImgGenArgsFactory:
def make_args_from_inference(
cls,
inference_taxonomy: InferenceTaxonomy,
+ *,
num_inference_steps: int | None,
quality: Quality | None,
guidance_scale: float | None,
@@ -420,6 +425,7 @@ class ImgGenArgsFactory:
def make_args_from_safety_checker(
cls,
safety_checker_taxonomy: SafetyCheckerTaxonomy,
+ *,
is_moderated: bool | None,
safety_tolerance: int | None,
) -> dict[str, Any]:
@@ -448,6 +454,7 @@ class ImgGenArgsFactory:
def make_args_from_output_format(
cls,
output_format_taxonomy: OutputFormatTaxonomy,
+ *,
output_format: ImageFormat | None,
) -> dict[str, Any]:
"""Map output format to provider-specific parameter name and validate support.
@@ -518,6 +525,7 @@ class ImgGenArgsFactory:
async def make_args_from_input_images(
cls,
input_images_taxonomy: InputImagesTaxonomy,
+ *,
input_images: list[PromptImage] | None,
) -> dict[str, Any]:
"""Map input images to provider-specific API parameters for image-to-image generation.
@@ -576,6 +584,7 @@ class ImgGenArgsFactory:
def make_args_from_input_fidelity(
cls,
input_fidelity_taxonomy: InputFidelityTaxonomy,
+ *,
input_fidelity: InputFidelity | None,
model_name: str,
) -> dict[str, Any]:
diff --git a/pipelex/cogt/img_gen/img_gen_job_factory.py b/pipelex/cogt/img_gen/img_gen_job_factory.py
index 3ac212896..e71671b40 100644
--- a/pipelex/cogt/img_gen/img_gen_job_factory.py
+++ b/pipelex/cogt/img_gen/img_gen_job_factory.py
@@ -10,6 +10,7 @@ class ImgGenJobFactory:
def make_img_gen_job_from_prompt(
cls,
img_gen_prompt: ImgGenPrompt,
+ *,
job_metadata: JobMetadata,
img_gen_job_params: ImgGenJobParams | None = None,
img_gen_job_config: ImgGenJobConfig | None = None,
@@ -31,6 +32,7 @@ class ImgGenJobFactory:
def make_img_gen_job_from_prompt_contents(
cls,
positive_text: str,
+ *,
negative_text: str | None,
job_metadata: JobMetadata,
img_gen_job_params: ImgGenJobParams | None = None,
diff --git a/pipelex/cogt/img_gen/img_gen_param_support.py b/pipelex/cogt/img_gen/img_gen_param_support.py
index 957ad025a..2d83f3d08 100644
--- a/pipelex/cogt/img_gen/img_gen_param_support.py
+++ b/pipelex/cogt/img_gen/img_gen_param_support.py
@@ -58,6 +58,7 @@ class ImgGenParamSupport:
@classmethod
def check_aspect_ratio(
cls,
+ *,
rules: ImgGenModelRules,
aspect_ratio: AspectRatio,
size: ImageSize | None,
@@ -85,6 +86,7 @@ class ImgGenParamSupport:
@classmethod
def check_background(
cls,
+ *,
rules: ImgGenModelRules,
background: Background,
model_name: str,
@@ -110,6 +112,7 @@ class ImgGenParamSupport:
@classmethod
def check_output_format(
cls,
+ *,
rules: ImgGenModelRules,
output_format: ImageFormat | None,
) -> SupportCheck:
@@ -133,6 +136,7 @@ class ImgGenParamSupport:
@classmethod
def check_input_fidelity(
cls,
+ *,
rules: ImgGenModelRules,
input_fidelity: InputFidelity | None,
model_name: str,
@@ -161,6 +165,7 @@ class ImgGenParamSupport:
@classmethod
def check_input_images_topic(
cls,
+ *,
rules: ImgGenModelRules,
has_input_images: bool,
) -> SupportCheck:
@@ -177,6 +182,7 @@ class ImgGenParamSupport:
@classmethod
def check_job_params(
cls,
+ *,
rules: ImgGenModelRules,
params: ImgGenJobParams,
model_name: str,
@@ -195,8 +201,8 @@ class ImgGenParamSupport:
@classmethod
def check_blueprint_params(
cls,
- rules: ImgGenModelRules,
*,
+ rules: ImgGenModelRules,
aspect_ratio: AspectRatio | None,
background: Background | None,
output_format: ImageFormat | None,
diff --git a/pipelex/cogt/img_gen/img_gen_worker_abstract.py b/pipelex/cogt/img_gen/img_gen_worker_abstract.py
index 3f384582a..6dc09b147 100644
--- a/pipelex/cogt/img_gen/img_gen_worker_abstract.py
+++ b/pipelex/cogt/img_gen/img_gen_worker_abstract.py
@@ -81,6 +81,7 @@ class ImgGenWorkerAbstract(InferenceWorkerAbstract):
async def gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
log.dev(f"✨ {self.desc} ✨")
@@ -115,6 +116,7 @@ class ImgGenWorkerAbstract(InferenceWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
pass
diff --git a/pipelex/cogt/img_gen/img_gen_worker_factory.py b/pipelex/cogt/img_gen/img_gen_worker_factory.py
index b83e1270b..e71eec0eb 100644
--- a/pipelex/cogt/img_gen/img_gen_worker_factory.py
+++ b/pipelex/cogt/img_gen/img_gen_worker_factory.py
@@ -14,6 +14,7 @@ class ImgGenWorkerFactory:
def make_img_gen_worker(
cls,
inference_model: InferenceModelSpec,
+ *,
reporting_delegate: ReportingProtocol | None = None,
) -> ImgGenWorkerAbstract:
plugin = Plugin.make_for_inference_model(inference_model=inference_model)
diff --git a/pipelex/cogt/inference/error_classification.py b/pipelex/cogt/inference/error_classification.py
index c63571661..b096e463b 100644
--- a/pipelex/cogt/inference/error_classification.py
+++ b/pipelex/cogt/inference/error_classification.py
@@ -44,7 +44,7 @@ _STATUSLESS_TRANSPORT_TYPE_NAMES: frozenset[str] = frozenset(
)
-def _resolve_sdk_exception_type(exc: BaseException, status_code: int | None) -> str:
+def _resolve_sdk_exception_type(exc: BaseException, *, status_code: int | None) -> str:
"""Return the ``sdk_exception_type`` name, normalizing status-less httpx transport errors.
Some ``httpx.TransportError`` subclasses (``ReadError``, ``WriteError``,
@@ -100,11 +100,11 @@ class ProviderErrorMetadata(BaseModel):
case ProviderName.GOOGLE:
return _is_quota_exhaustion_google(self.message)
case ProviderName.MISTRAL:
- return _is_quota_exhaustion_mistral(self.message, self.status_code or 0)
+ return _is_quota_exhaustion_mistral(self.message, status_code=self.status_code or 0)
case ProviderName.BEDROCK:
- return _is_quota_exhaustion_aws(self.message, self.provider_error_code)
+ return _is_quota_exhaustion_aws(self.message, provider_error_code=self.provider_error_code)
case ProviderName.GATEWAY:
- return _is_quota_exhaustion_gateway(self.message, self.status_code or 0)
+ return _is_quota_exhaustion_gateway(self.message, status_code=self.status_code or 0)
case (
ProviderName.AZURE | ProviderName.FAL | ProviderName.HUGGINGFACE | ProviderName.LINKUP | ProviderName.DOCLING | ProviderName.PYPDFIUM2
):
@@ -246,7 +246,7 @@ def _is_quota_exhaustion_google(error_message: str) -> bool:
return any(pattern in lower_message for pattern in _GOOGLE_QUOTA_PATTERNS)
-def _is_quota_exhaustion_mistral(error_message: str, status_code: int) -> bool:
+def _is_quota_exhaustion_mistral(error_message: str, *, status_code: int) -> bool:
"""Check if a Mistral error indicates quota/credits exhaustion.
HTTP 402 (Payment Required) is a definitive quota signal.
@@ -258,7 +258,7 @@ def _is_quota_exhaustion_mistral(error_message: str, status_code: int) -> bool:
return status_code == 429 and any(pattern in lower_message for pattern in _MISTRAL_QUOTA_PATTERNS)
-def _is_quota_exhaustion_aws(error_message: str, provider_error_code: str | None) -> bool:
+def _is_quota_exhaustion_aws(error_message: str, *, provider_error_code: str | None) -> bool:
"""Check if an AWS error indicates quota/credits exhaustion rather than rate limiting.
AWS botocore puts the canonical signal in the error ``Code`` (e.g.
@@ -273,7 +273,7 @@ def _is_quota_exhaustion_aws(error_message: str, provider_error_code: str | None
return any(pattern in lower_message for pattern in _AWS_QUOTA_PATTERNS)
-def _is_quota_exhaustion_gateway(error_message: str, status_code: int) -> bool:
+def _is_quota_exhaustion_gateway(error_message: str, *, status_code: int) -> bool:
"""Check if a Portkey/Gateway error indicates quota/credits exhaustion.
HTTP 402 (Payment Required) is a definitive quota signal.
@@ -557,7 +557,7 @@ def extract_google_metadata(exc: BaseException) -> ProviderErrorMetadata:
details = getattr(exc, "details", None)
return ProviderErrorMetadata(
provider=ProviderName.GOOGLE,
- sdk_exception_type=_resolve_sdk_exception_type(exc, status_code),
+ sdk_exception_type=_resolve_sdk_exception_type(exc, status_code=status_code),
message=str(exc),
status_code=status_code,
request_id=request_id,
@@ -583,7 +583,7 @@ def extract_azure_metadata(exc: BaseException) -> ProviderErrorMetadata:
)
-def extract_azure_metadata_from_response(response: Any, sdk_exception_type: str, message: str) -> ProviderErrorMetadata:
+def extract_azure_metadata_from_response(response: Any, *, sdk_exception_type: str, message: str) -> ProviderErrorMetadata:
"""Distill a *successful* Azure REST response into a ``ProviderErrorMetadata``.
Used when the HTTP status was fine but the body failed to parse (malformed
@@ -594,7 +594,7 @@ def extract_azure_metadata_from_response(response: Any, sdk_exception_type: str,
return _build_azure_metadata(response=response, sdk_exception_type=sdk_exception_type, message=message)
-def _build_azure_metadata(response: Any, sdk_exception_type: str, message: str) -> ProviderErrorMetadata:
+def _build_azure_metadata(response: Any, *, sdk_exception_type: str, message: str) -> ProviderErrorMetadata:
"""Read status code, headers, and body off an Azure ``httpx.Response`` on a best-effort basis."""
status_code = getattr(response, "status_code", None)
if not isinstance(status_code, int):
@@ -764,7 +764,7 @@ def extract_mistral_metadata(exc: BaseException) -> ProviderErrorMetadata:
provider_error_code = _provider_error_code_from_flat_body(parsed_dict) or _provider_error_code_from_body(parsed_dict)
return ProviderErrorMetadata(
provider=ProviderName.MISTRAL,
- sdk_exception_type=_resolve_sdk_exception_type(exc, status_code),
+ sdk_exception_type=_resolve_sdk_exception_type(exc, status_code=status_code),
message=str(exc),
status_code=status_code,
request_id=request_id,
@@ -875,7 +875,7 @@ _LOCAL_EXTRACT_TYPE_HIERARCHY: tuple[tuple[type[BaseException], str], ...] = (
)
-def extract_local_extract_metadata(exc: BaseException, provider: ProviderName) -> ProviderErrorMetadata:
+def extract_local_extract_metadata(exc: BaseException, *, provider: ProviderName) -> ProviderErrorMetadata:
"""Distill a local (non-HTTP) extraction exception into a ``ProviderErrorMetadata``.
Local extractors (``docling``, ``pypdfium2`` …) run in-process against the
diff --git a/pipelex/cogt/inference/error_render.py b/pipelex/cogt/inference/error_render.py
index 84fb3b81a..91fdebf51 100644
--- a/pipelex/cogt/inference/error_render.py
+++ b/pipelex/cogt/inference/error_render.py
@@ -50,13 +50,13 @@ _NOT_FOUND_CLASSES: dict[InferenceErrorFamily, type[ModelNotFoundError]] = {
}
-def _format_message(metadata: SDKErrorEnvelope, model_desc: str) -> str:
+def _format_message(metadata: SDKErrorEnvelope, *, model_desc: str) -> str:
"""Compose the human-readable error message from the provider, model, and SDK text."""
status_part = f" (HTTP {metadata.status_code})" if metadata.status_code is not None else ""
return f"{metadata.provider} inference failed for model '{model_desc}'{status_part}: {metadata.message}"
-def _render_detail(metadata: SDKErrorEnvelope, classification: ClassificationResult) -> str:
+def _render_detail(metadata: SDKErrorEnvelope, *, classification: ClassificationResult) -> str:
"""Produce the free-form user-facing advice text for the classified error."""
match classification.user_action_kind:
case UserActionKind.WAIT_AND_RETRY:
@@ -79,6 +79,7 @@ def _render_detail(metadata: SDKErrorEnvelope, classification: ClassificationRes
def render_inference_error(
metadata: SDKErrorEnvelope,
+ *,
classification: ClassificationResult,
family: InferenceErrorFamily,
model_desc: str,
@@ -97,10 +98,10 @@ def render_inference_error(
A ``CogtError`` subclass instance carrying the category, structured
``UserAction``, and ``provider_metadata``.
"""
- message = _format_message(metadata, model_desc)
+ message = _format_message(metadata, model_desc=model_desc)
user_action = UserAction(
kind=classification.user_action_kind,
- detail=_render_detail(metadata, classification),
+ detail=_render_detail(metadata, classification=classification),
)
if classification.is_model_not_found:
not_found_class = _NOT_FOUND_CLASSES[family]
diff --git a/pipelex/cogt/inference/inference_manager.py b/pipelex/cogt/inference/inference_manager.py
index a7725c09c..af9fada0d 100644
--- a/pipelex/cogt/inference/inference_manager.py
+++ b/pipelex/cogt/inference/inference_manager.py
@@ -73,6 +73,7 @@ class InferenceManager(InferenceManagerProtocol):
def set_llm_worker_from_external_plugin(
self,
llm_handle: str,
+ *,
llm_worker_class: type[LLMWorkerAbstract],
should_warn_if_already_registered: bool = True,
):
diff --git a/pipelex/cogt/inference/inference_manager_protocol.py b/pipelex/cogt/inference/inference_manager_protocol.py
index 0472d8278..d5c916072 100644
--- a/pipelex/cogt/inference/inference_manager_protocol.py
+++ b/pipelex/cogt/inference/inference_manager_protocol.py
@@ -21,6 +21,7 @@ class InferenceManagerProtocol(Protocol):
def set_llm_worker_from_external_plugin(
self,
llm_handle: str,
+ *,
llm_worker_class: type[LLMWorkerAbstract],
should_warn_if_already_registered: bool = True,
): ...
diff --git a/pipelex/cogt/inference/transport_retry.py b/pipelex/cogt/inference/transport_retry.py
index eed284f00..3e10edb97 100644
--- a/pipelex/cogt/inference/transport_retry.py
+++ b/pipelex/cogt/inference/transport_retry.py
@@ -109,6 +109,7 @@ def _make_retry_predicate(retry_on_ambiguous_failure: bool) -> Callable[[BaseExc
async def request_with_transport_retry(
send_request: Callable[[], Awaitable[httpx.Response]],
+ *,
max_retries: int,
retry_on_ambiguous_failure: bool = True,
) -> httpx.Response:
diff --git a/pipelex/cogt/llm/llm_job_factory.py b/pipelex/cogt/llm/llm_job_factory.py
index 792c427ed..bdb04cae9 100644
--- a/pipelex/cogt/llm/llm_job_factory.py
+++ b/pipelex/cogt/llm/llm_job_factory.py
@@ -10,6 +10,7 @@ class LLMJobFactory:
def make_llm_job(
cls,
llm_prompt: LLMPrompt,
+ *,
job_metadata: JobMetadata,
llm_job_params: LLMJobParams,
llm_job_config: LLMJobConfig | None = None,
diff --git a/pipelex/cogt/llm/llm_prompt_template.py b/pipelex/cogt/llm/llm_prompt_template.py
index f0c1c1631..74e41ab75 100644
--- a/pipelex/cogt/llm/llm_prompt_template.py
+++ b/pipelex/cogt/llm/llm_prompt_template.py
@@ -58,6 +58,7 @@ class LLMPromptTemplate(LLMPromptFactoryAbstract):
async def _make_llm_prompt(
self,
system_text: str | None = None,
+ *,
user_text: str | None = None,
user_images: list[PromptImage] | None = None,
is_user_images_append: bool | None = None,
diff --git a/pipelex/cogt/llm/llm_setting.py b/pipelex/cogt/llm/llm_setting.py
index 52ec3778c..ff9c4c468 100644
--- a/pipelex/cogt/llm/llm_setting.py
+++ b/pipelex/cogt/llm/llm_setting.py
@@ -95,6 +95,7 @@ class LLMSettingChoices(ConfigModel):
def make_completed_with_defaults(
cls,
for_text: LLMModelChoice | None = None,
+ *,
for_object: LLMModelChoice | None = None,
) -> Self:
return cls(
diff --git a/pipelex/cogt/llm/llm_worker_abstract.py b/pipelex/cogt/llm/llm_worker_abstract.py
index c81975d2a..a56fbcde3 100644
--- a/pipelex/cogt/llm/llm_worker_abstract.py
+++ b/pipelex/cogt/llm/llm_worker_abstract.py
@@ -83,7 +83,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
"""Get the response model name. Override in subclass."""
return "unknown"
- def _start_otel_span_llm(self, llm_job: LLMJob, output_type: InferenceOutputType, output_class_name: str | None = None) -> Span | None:
+ def _start_otel_span_llm(self, llm_job: LLMJob, *, output_type: InferenceOutputType, output_class_name: str | None = None) -> Span | None:
"""Start an OTel span for the LLM job and return it.
Always includes full (non-redacted) values in Pipelex attributes for PostHog exporters.
@@ -228,7 +228,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
return span
- def _end_otel_span_with_completion_text(self, span: Span | None, llm_job: LLMJob, completion_text: str) -> None:
+ def _end_otel_span_with_completion_text(self, span: Span | None, *, llm_job: LLMJob, completion_text: str) -> None:
"""End the OTel span, recording usage and status. Safe to call if span is None."""
if span is None:
return
@@ -259,7 +259,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
span.set_status(Status(StatusCode.OK))
span.end()
- def _end_otel_span_with_completion_object(self, span: Span | None, llm_job: LLMJob, completion_object: BaseModel) -> None:
+ def _end_otel_span_with_completion_object(self, span: Span | None, *, llm_job: LLMJob, completion_object: BaseModel) -> None:
"""End the OTel span, recording usage and status. Safe to call if span is None."""
if span is None:
return
@@ -291,7 +291,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
span.set_status(Status(StatusCode.OK))
span.end()
- def _end_otel_span_with_error(self, span: Span | None, llm_job: LLMJob, error: BaseException) -> None:
+ def _end_otel_span_with_error(self, span: Span | None, *, llm_job: LLMJob, error: BaseException) -> None:
"""End the OTel span, recording the error. Safe to call if span is None."""
if span is None:
return
@@ -326,6 +326,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
async def _after_text_job(
self,
+ *,
span: Span | None,
llm_job: LLMJob,
result_text: str,
@@ -340,6 +341,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
async def _after_object_job(
self,
+ *,
span: Span | None,
llm_job: LLMJob,
result_object: BaseModel,
@@ -396,6 +398,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
async def gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
log.verbose(f"LLM Worker gen_object using {self.desc}")
@@ -433,6 +436,7 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
pass
diff --git a/pipelex/cogt/llm/llm_worker_factory.py b/pipelex/cogt/llm/llm_worker_factory.py
index 224141a21..9bf2014b8 100644
--- a/pipelex/cogt/llm/llm_worker_factory.py
+++ b/pipelex/cogt/llm/llm_worker_factory.py
@@ -12,6 +12,7 @@ class LLMWorkerFactory:
@staticmethod
def make_llm_worker(
inference_model: InferenceModelSpec,
+ *,
reporting_delegate: ReportingProtocol | None = None,
) -> LLMWorkerInternalAbstract:
plugin = Plugin.make_for_inference_model(inference_model=inference_model)
diff --git a/pipelex/cogt/llm/llm_worker_internal_abstract.py b/pipelex/cogt/llm/llm_worker_internal_abstract.py
index 38c864495..34d2924a7 100644
--- a/pipelex/cogt/llm/llm_worker_internal_abstract.py
+++ b/pipelex/cogt/llm/llm_worker_internal_abstract.py
@@ -122,6 +122,7 @@ class LLMWorkerInternalAbstract(LLMWorkerAbstract):
@override
async def _after_text_job(
self,
+ *,
span: Span | None,
llm_job: LLMJob,
result_text: str,
@@ -133,6 +134,7 @@ class LLMWorkerInternalAbstract(LLMWorkerAbstract):
@override
async def _after_object_job(
self,
+ *,
span: Span | None,
llm_job: LLMJob,
result_object: BaseModel,
diff --git a/pipelex/cogt/llm/reasoning_config_base.py b/pipelex/cogt/llm/reasoning_config_base.py
index e95859d65..31d669a2a 100644
--- a/pipelex/cogt/llm/reasoning_config_base.py
+++ b/pipelex/cogt/llm/reasoning_config_base.py
@@ -8,6 +8,7 @@ DISABLED_LEVEL = "disabled"
def validate_effort_to_level_map(
effort_to_level_map: EffortToLevelMap,
+ *,
config_name: str,
level_type: type[StrEnum] | None = None,
) -> EffortToLevelMap:
@@ -36,7 +37,7 @@ def validate_effort_to_level_map(
return effort_to_level_map
-def get_reasoning_level_str(effort_to_level_map: EffortToLevelMap, effort: ReasoningEffort) -> str | None:
+def get_reasoning_level_str(*, effort_to_level_map: EffortToLevelMap, effort: ReasoningEffort) -> str | None:
"""Look up effort in the map, return None for 'disabled'."""
level = effort_to_level_map.get(effort)
if level is None:
diff --git a/pipelex/cogt/model_backends/backend_credentials.py b/pipelex/cogt/model_backends/backend_credentials.py
index b8e58b830..edd0aeb5f 100644
--- a/pipelex/cogt/model_backends/backend_credentials.py
+++ b/pipelex/cogt/model_backends/backend_credentials.py
@@ -25,6 +25,7 @@ class BackendCredentialsErrorMsgFactory:
@classmethod
def make_one_variable_missing_error_msg(
cls,
+ *,
secrets_provider: SecretsProviderAbstract,
backend_name: str | None,
var_name: str,
@@ -77,6 +78,7 @@ class BackendCredentialsErrorMsgFactory:
def make_comprehensive_error_msg(
cls,
backend_credential_reports: dict[str, BackendCredentialsReport],
+ *,
secrets_provider: SecretsProviderAbstract | None = None,
) -> str:
"""Build a comprehensive error message for missing backend credentials.
diff --git a/pipelex/cogt/model_backends/backend_factory.py b/pipelex/cogt/model_backends/backend_factory.py
index 4168a0958..129c2d297 100644
--- a/pipelex/cogt/model_backends/backend_factory.py
+++ b/pipelex/cogt/model_backends/backend_factory.py
@@ -39,6 +39,7 @@ class InferenceBackendFactory:
def make_inference_backend(
cls,
name: str,
+ *,
blueprint: InferenceBackendBlueprint,
extra_config: dict[str, Any],
model_specs: dict[str, InferenceModelSpec],
diff --git a/pipelex/cogt/model_backends/backend_library.py b/pipelex/cogt/model_backends/backend_library.py
index 628574a20..354e4246b 100644
--- a/pipelex/cogt/model_backends/backend_library.py
+++ b/pipelex/cogt/model_backends/backend_library.py
@@ -58,6 +58,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
def load(
self,
secrets_provider: SecretsProviderAbstract,
+ *,
backends_library_path: str,
backends_dir_path: str,
include_disabled: bool = False,
@@ -101,7 +102,9 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
if runtime_manager.is_ci_testing and backend_name == "vertexai":
continue
try:
- inference_backend_blueprint_dict = apply_to_strings_recursive(inference_backend_blueprint_dict_raw, substitute_vars_with_provider)
+ inference_backend_blueprint_dict = apply_to_strings_recursive(
+ inference_backend_blueprint_dict_raw, transform_func=substitute_vars_with_provider
+ )
except VarFallbackPatternError as var_fallback_pattern_exc:
if lenient:
log.verbose(f"Skipping backend '{backend_name}': variable fallback pattern error")
@@ -225,6 +228,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
def _load_gateway_model_specs(
self,
gateway_config: GatewayConfig,
+ *,
backends_dir_path: str,
substitute_vars_with_provider: Any,
) -> tuple[BackendModelSpecs, str]:
@@ -253,7 +257,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
# Apply variable substitution (in case remote config has any variables)
try:
- model_specs_dict = apply_to_strings_recursive(model_specs_dict, substitute_vars_with_provider)
+ model_specs_dict = apply_to_strings_recursive(model_specs_dict, transform_func=substitute_vars_with_provider)
except (VarNotFoundError, UnknownVarPrefixError) as exc:
msg = f"Variable substitution failed in remote gateway config: {exc}"
raise InferenceModelSpecError(msg) from exc
@@ -263,6 +267,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
def _load_local_model_specs(
self,
backend_name: str,
+ *,
backends_dir_path: str,
substitute_vars_with_provider: Any,
) -> tuple[BackendModelSpecs, str]:
@@ -283,7 +288,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
try:
model_specs_dict_raw = load_toml_from_path(path=path_to_model_specs_toml)
try:
- model_specs_dict = apply_to_strings_recursive(model_specs_dict_raw, substitute_vars_with_provider)
+ model_specs_dict = apply_to_strings_recursive(model_specs_dict_raw, transform_func=substitute_vars_with_provider)
except (VarNotFoundError, UnknownVarPrefixError) as exc:
msg = f"Variable substitution failed in file '{path_to_model_specs_toml}': {exc}"
raise InferenceModelSpecError(msg) from exc
@@ -292,7 +297,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):
raise InferenceBackendLibraryError(msg) from exc
return model_specs_dict, f"file '{path_to_model_specs_toml}'"
- def check_backend_credentials(self, path: str, include_disabled: bool = False) -> CredentialsValidationReport:
+ def check_backend_credentials(self, path: str, *, include_disabled: bool = False) -> CredentialsValidationReport:
"""Check if required environment variables are set for enabled backends.
This method loads backend configurations and extracts variable placeholders
diff --git a/pipelex/cogt/model_backends/model_lists.py b/pipelex/cogt/model_backends/model_lists.py
index 00e7b8d70..f3b659ebf 100644
--- a/pipelex/cogt/model_backends/model_lists.py
+++ b/pipelex/cogt/model_backends/model_lists.py
@@ -17,6 +17,7 @@ class ModelLister:
async def list_models(
cls,
backend_name: str,
+ *,
flat: bool = False,
) -> None:
"""List available models for a specific backend.
@@ -192,6 +193,7 @@ class ModelLister:
@staticmethod
def _display_unsupported_sdks_message(
any_listed: bool,
+ *,
unsupported_sdks: list[str],
backend_name: str,
models_by_sdk: dict[str, list[str]],
diff --git a/pipelex/cogt/model_backends/model_spec_factory.py b/pipelex/cogt/model_backends/model_spec_factory.py
index 0310c0fd4..b9298cc47 100644
--- a/pipelex/cogt/model_backends/model_spec_factory.py
+++ b/pipelex/cogt/model_backends/model_spec_factory.py
@@ -78,6 +78,7 @@ class InferenceModelSpecFactory(BaseModel):
def make_inference_model_spec(
cls,
backend_name: str,
+ *,
name: str,
blueprint: InferenceModelSpecBlueprint,
backend_listed_constraints: list[ListedConstraint],
diff --git a/pipelex/cogt/model_routing/routing_profile.py b/pipelex/cogt/model_routing/routing_profile.py
index e2e784dad..717a97480 100644
--- a/pipelex/cogt/model_routing/routing_profile.py
+++ b/pipelex/cogt/model_routing/routing_profile.py
@@ -22,7 +22,7 @@ class RoutingProfile(ConfigModel):
optional_routes: dict[str, str] = Field(default_factory=dict)
fallback_order: list[str] | None = None # Ordered list of backends for fallback
- def get_backend_match_for_model(self, enabled_backends: list[str], model_name: str) -> BackendMatchForModel | None:
+ def get_backend_match_for_model(self, enabled_backends: list[str], *, model_name: str) -> BackendMatchForModel | None:
"""Get the backend name for a given model name.
Args:
@@ -53,7 +53,7 @@ class RoutingProfile(ConfigModel):
for pattern, backend in possible_routes.items():
if backend not in enabled_backends:
continue
- if matches_wildcard_pattern(model_name, pattern):
+ if matches_wildcard_pattern(model_name, pattern=pattern):
return BackendMatchForModel(
model_name=model_name,
backend_name=backend,
diff --git a/pipelex/cogt/model_routing/routing_profile_factory.py b/pipelex/cogt/model_routing/routing_profile_factory.py
index e9e3816f6..4f5a9349a 100644
--- a/pipelex/cogt/model_routing/routing_profile_factory.py
+++ b/pipelex/cogt/model_routing/routing_profile_factory.py
@@ -38,6 +38,7 @@ class RoutingProfileFactory:
def make_routing_profile(
cls,
name: str,
+ *,
blueprint: RoutingProfileBlueprint,
) -> RoutingProfile:
"""Create a RoutingProfile from a blueprint.
diff --git a/pipelex/cogt/model_routing/routing_profile_loader.py b/pipelex/cogt/model_routing/routing_profile_loader.py
index 56d89d395..edb1c4a24 100644
--- a/pipelex/cogt/model_routing/routing_profile_loader.py
+++ b/pipelex/cogt/model_routing/routing_profile_loader.py
@@ -10,6 +10,7 @@ from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
def load_active_routing_profile(
routing_profile_library_path: str,
+ *,
enabled_backends: list[str],
lenient: bool = False,
) -> RoutingProfile:
diff --git a/pipelex/cogt/models/deck_manifest.py b/pipelex/cogt/models/deck_manifest.py
index 6c17aabd8..0df5bcc56 100644
--- a/pipelex/cogt/models/deck_manifest.py
+++ b/pipelex/cogt/models/deck_manifest.py
@@ -152,7 +152,7 @@ def read_manifest(deck_dir: Path) -> DeckManifest | None:
return None
-def write_manifest(deck_dir: Path, manifest: DeckManifest) -> None:
+def write_manifest(manifest: DeckManifest, *, deck_dir: Path) -> None:
"""Persist the manifest, creating the deck directory if needed."""
deck_dir.mkdir(parents=True, exist_ok=True)
payload = manifest.model_dump()
@@ -173,10 +173,10 @@ def is_deck_stale_fast(deck_dir: Path) -> bool:
manifest = read_manifest(deck_dir)
if manifest is None:
return True
- return _is_manifest_older(manifest.kit_version, get_package_version())
+ return _is_manifest_older(manifest.kit_version, current_version=get_package_version())
-def _is_manifest_older(manifest_version: str, current_version: str) -> bool:
+def _is_manifest_older(manifest_version: str, *, current_version: str) -> bool:
"""True iff the manifest's recorded core version is strictly older than the installed package.
Compares semver cores (``X.Y.Z``) ignoring pre-release/build metadata so that an editable build
diff --git a/pipelex/cogt/models/model_deck.py b/pipelex/cogt/models/model_deck.py
index b9c7b2ad7..e9bc7444d 100644
--- a/pipelex/cogt/models/model_deck.py
+++ b/pipelex/cogt/models/model_deck.py
@@ -132,7 +132,7 @@ class ModelDeck(ConfigModel):
case ModelType.SEARCH:
return self.search_aliases, self.search_waterfalls
- def is_model_handle_defined(self, model_handle: str, model_type: ModelType) -> bool:
+ def is_model_handle_defined(self, model_handle: str, *, model_type: ModelType) -> bool:
"""Check if a model handle is defined in the model deck.
Handles prefixed references (e.g., @alias_name, ~waterfall_name) by parsing
@@ -219,6 +219,7 @@ class ModelDeck(ConfigModel):
def _raise_handle_not_found_error(
self,
ref: ModelReference,
+ *,
model_type: ModelType,
presets: dict[str, LLMSetting] | dict[str, ExtractSetting] | dict[str, ImgGenSetting] | dict[str, SearchSetting],
) -> NoReturn:
@@ -249,6 +250,7 @@ class ModelDeck(ConfigModel):
def check_llm_choice(
self,
llm_choice: LLMModelChoice,
+ *,
is_disabled_allowed: bool = False,
):
if isinstance(llm_choice, LLMSetting):
@@ -519,7 +521,7 @@ class ModelDeck(ConfigModel):
############################################################
@classmethod
- def _validate_llm_setting(cls, llm_setting: LLMSetting, inference_model: InferenceModelSpec):
+ def _validate_llm_setting(cls, llm_setting: LLMSetting, *, inference_model: InferenceModelSpec):
if inference_model.max_tokens is not None and (llm_setting_max_tokens := llm_setting.max_tokens):
if llm_setting_max_tokens > inference_model.max_tokens:
msg = (
@@ -684,7 +686,7 @@ class ModelDeck(ConfigModel):
"""Return the set of backend names that have at least one model enabled."""
return {model.backend_name for model in self.inference_models.values()}
- def _is_model_available_in_backend(self, model_handle: str, backend_name: str) -> bool | None:
+ def _is_model_available_in_backend(self, model_handle: str, *, backend_name: str) -> bool | None:
"""Check if a model is available from a specific backend.
This is a low-level check that reads the backend TOML file directly,
@@ -713,6 +715,7 @@ class ModelDeck(ConfigModel):
def _resolve_waterfall(
self,
waterfall_name: str,
+ *,
fallback_list: list[str],
model_type: ModelType,
) -> InferenceModelSpec | None:
@@ -768,7 +771,7 @@ class ModelDeck(ConfigModel):
)
raise ModelWaterfallError(message=msg, model_handle=waterfall_name, fallback_list=fallback_list)
- def get_optional_inference_model(self, model_handle: str, model_type: ModelType) -> InferenceModelSpec | None:
+ def get_optional_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec | None:
"""Get an inference model spec, resolving aliases and waterfalls as needed.
Handles prefixed references (e.g., @alias_name, ~waterfall_name) by parsing
@@ -783,6 +786,7 @@ class ModelDeck(ConfigModel):
def _get_optional_inference_model(
self,
model_handle: str,
+ *,
model_type: ModelType,
_visited: frozenset[str],
) -> InferenceModelSpec | None:
@@ -855,11 +859,11 @@ class ModelDeck(ConfigModel):
log.verbose(f"Skipping model handle '{model_handle}' because it's was not found in the model deck, it could be an external plugin.")
return None
- def is_handle_defined(self, model_handle: str, model_type: ModelType) -> bool:
+ def is_handle_defined(self, model_handle: str, *, model_type: ModelType) -> bool:
aliases, waterfalls = self.get_aliases_and_waterfalls_for_type(model_type)
return model_handle in self.inference_models or model_handle in aliases or model_handle in waterfalls
- def get_required_inference_model(self, model_handle: str, model_type: ModelType) -> InferenceModelSpec:
+ def get_required_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec:
inference_model = self.get_optional_inference_model(model_handle=model_handle, model_type=model_type)
if inference_model is None:
msg = (
diff --git a/pipelex/cogt/models/model_deck_check.py b/pipelex/cogt/models/model_deck_check.py
index 05af028bc..6bde84c77 100644
--- a/pipelex/cogt/models/model_deck_check.py
+++ b/pipelex/cogt/models/model_deck_check.py
@@ -16,6 +16,7 @@ from pipelex.hub import get_model_deck
def _raise_model_choice_not_found(
msg: str,
+ *,
model_deck: ModelDeck,
model_type: ModelType,
raw_choice: str,
@@ -24,7 +25,7 @@ def _raise_model_choice_not_found(
available_options: list[str],
) -> NoReturn:
"""Compute fuzzy suggestions and raise ModelChoiceNotFoundError."""
- suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(model_deck, model_type, name, reference_kind)
+ suggestions, wrong_sigil_hints, cross_suggestions = suggest_model_alternatives(model_deck, model_type=model_type, name=name, kind=reference_kind)
raise ModelChoiceNotFoundError(
message=msg,
model_type=model_type,
@@ -50,14 +51,26 @@ def check_llm_choice_with_deck(llm_choice: LLMModelChoice) -> None:
return
msg = f"LLM preset '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
- msg, model_deck, ModelType.LLM, ref.raw, ref.name, ModelReferenceKind.PRESET, list(model_deck.llm_presets.keys())
+ msg,
+ model_deck=model_deck,
+ model_type=ModelType.LLM,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.PRESET,
+ available_options=list(model_deck.llm_presets.keys()),
)
case ModelReferenceKind.ALIAS:
if ref.name in model_deck.llm_aliases:
return
msg = f"Alias '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
- msg, model_deck, ModelType.LLM, ref.raw, ref.name, ModelReferenceKind.ALIAS, list(model_deck.llm_aliases.keys())
+ msg,
+ model_deck=model_deck,
+ model_type=ModelType.LLM,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.ALIAS,
+ available_options=list(model_deck.llm_aliases.keys()),
)
case ModelReferenceKind.WATERFALL:
if ref.name in model_deck.llm_waterfalls:
@@ -65,12 +78,12 @@ def check_llm_choice_with_deck(llm_choice: LLMModelChoice) -> None:
msg = f"Waterfall '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.LLM,
- ref.raw,
- ref.name,
- ModelReferenceKind.WATERFALL,
- list(model_deck.llm_waterfalls.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.LLM,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.WATERFALL,
+ available_options=list(model_deck.llm_waterfalls.keys()),
)
case ModelReferenceKind.HANDLE:
if model_deck.is_model_handle_defined(model_handle=ref.name, model_type=ModelType.LLM):
@@ -78,12 +91,12 @@ def check_llm_choice_with_deck(llm_choice: LLMModelChoice) -> None:
msg = f"Model handle '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.LLM,
- ref.raw,
- ref.name,
- ModelReferenceKind.HANDLE,
- list(model_deck.inference_models.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.LLM,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.HANDLE,
+ available_options=list(model_deck.inference_models.keys()),
)
@@ -101,12 +114,12 @@ def check_extract_choice_with_deck(extract_choice: ExtractModelChoice) -> None:
msg = f"Extract preset '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.TEXT_EXTRACTOR,
- ref.raw,
- ref.name,
- ModelReferenceKind.PRESET,
- list(model_deck.extract_presets.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.TEXT_EXTRACTOR,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.PRESET,
+ available_options=list(model_deck.extract_presets.keys()),
)
case ModelReferenceKind.ALIAS:
if ref.name in model_deck.extract_aliases:
@@ -114,12 +127,12 @@ def check_extract_choice_with_deck(extract_choice: ExtractModelChoice) -> None:
msg = f"Alias '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.TEXT_EXTRACTOR,
- ref.raw,
- ref.name,
- ModelReferenceKind.ALIAS,
- list(model_deck.extract_aliases.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.TEXT_EXTRACTOR,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.ALIAS,
+ available_options=list(model_deck.extract_aliases.keys()),
)
case ModelReferenceKind.WATERFALL:
if ref.name in model_deck.extract_waterfalls:
@@ -127,12 +140,12 @@ def check_extract_choice_with_deck(extract_choice: ExtractModelChoice) -> None:
msg = f"Waterfall '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.TEXT_EXTRACTOR,
- ref.raw,
- ref.name,
- ModelReferenceKind.WATERFALL,
- list(model_deck.extract_waterfalls.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.TEXT_EXTRACTOR,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.WATERFALL,
+ available_options=list(model_deck.extract_waterfalls.keys()),
)
case ModelReferenceKind.HANDLE:
if model_deck.is_model_handle_defined(model_handle=ref.name, model_type=ModelType.TEXT_EXTRACTOR):
@@ -140,12 +153,12 @@ def check_extract_choice_with_deck(extract_choice: ExtractModelChoice) -> None:
msg = f"Model handle '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.TEXT_EXTRACTOR,
- ref.raw,
- ref.name,
- ModelReferenceKind.HANDLE,
- list(model_deck.inference_models.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.TEXT_EXTRACTOR,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.HANDLE,
+ available_options=list(model_deck.inference_models.keys()),
)
@@ -163,12 +176,12 @@ def check_search_choice_with_deck(search_choice: SearchModelChoice) -> None:
msg = f"Search preset '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.SEARCH,
- ref.raw,
- ref.name,
- ModelReferenceKind.PRESET,
- list(model_deck.search_presets.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.SEARCH,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.PRESET,
+ available_options=list(model_deck.search_presets.keys()),
)
case ModelReferenceKind.ALIAS:
if ref.name in model_deck.search_aliases:
@@ -176,12 +189,12 @@ def check_search_choice_with_deck(search_choice: SearchModelChoice) -> None:
msg = f"Alias '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.SEARCH,
- ref.raw,
- ref.name,
- ModelReferenceKind.ALIAS,
- list(model_deck.search_aliases.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.SEARCH,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.ALIAS,
+ available_options=list(model_deck.search_aliases.keys()),
)
case ModelReferenceKind.WATERFALL:
if ref.name in model_deck.search_waterfalls:
@@ -189,12 +202,12 @@ def check_search_choice_with_deck(search_choice: SearchModelChoice) -> None:
msg = f"Waterfall '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.SEARCH,
- ref.raw,
- ref.name,
- ModelReferenceKind.WATERFALL,
- list(model_deck.search_waterfalls.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.SEARCH,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.WATERFALL,
+ available_options=list(model_deck.search_waterfalls.keys()),
)
case ModelReferenceKind.HANDLE:
if model_deck.is_model_handle_defined(model_handle=ref.name, model_type=ModelType.SEARCH):
@@ -202,12 +215,12 @@ def check_search_choice_with_deck(search_choice: SearchModelChoice) -> None:
msg = f"Model handle '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.SEARCH,
- ref.raw,
- ref.name,
- ModelReferenceKind.HANDLE,
- list(model_deck.inference_models.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.SEARCH,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.HANDLE,
+ available_options=list(model_deck.inference_models.keys()),
)
@@ -225,12 +238,12 @@ def check_img_gen_choice_with_deck(img_gen_choice: ImgGenModelChoice) -> None:
msg = f"Image generation preset '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.IMG_GEN,
- ref.raw,
- ref.name,
- ModelReferenceKind.PRESET,
- list(model_deck.img_gen_presets.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.IMG_GEN,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.PRESET,
+ available_options=list(model_deck.img_gen_presets.keys()),
)
case ModelReferenceKind.ALIAS:
if ref.name in model_deck.img_gen_aliases:
@@ -238,12 +251,12 @@ def check_img_gen_choice_with_deck(img_gen_choice: ImgGenModelChoice) -> None:
msg = f"Alias '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.IMG_GEN,
- ref.raw,
- ref.name,
- ModelReferenceKind.ALIAS,
- list(model_deck.img_gen_aliases.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.IMG_GEN,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.ALIAS,
+ available_options=list(model_deck.img_gen_aliases.keys()),
)
case ModelReferenceKind.WATERFALL:
if ref.name in model_deck.img_gen_waterfalls:
@@ -251,12 +264,12 @@ def check_img_gen_choice_with_deck(img_gen_choice: ImgGenModelChoice) -> None:
msg = f"Waterfall '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.IMG_GEN,
- ref.raw,
- ref.name,
- ModelReferenceKind.WATERFALL,
- list(model_deck.img_gen_waterfalls.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.IMG_GEN,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.WATERFALL,
+ available_options=list(model_deck.img_gen_waterfalls.keys()),
)
case ModelReferenceKind.HANDLE:
if model_deck.is_model_handle_defined(model_handle=ref.name, model_type=ModelType.IMG_GEN):
@@ -264,10 +277,10 @@ def check_img_gen_choice_with_deck(img_gen_choice: ImgGenModelChoice) -> None:
msg = f"Model handle '{ref.name}' was not found in the model deck"
_raise_model_choice_not_found(
msg,
- model_deck,
- ModelType.IMG_GEN,
- ref.raw,
- ref.name,
- ModelReferenceKind.HANDLE,
- list(model_deck.inference_models.keys()),
+ model_deck=model_deck,
+ model_type=ModelType.IMG_GEN,
+ raw_choice=ref.raw,
+ name=ref.name,
+ reference_kind=ModelReferenceKind.HANDLE,
+ available_options=list(model_deck.inference_models.keys()),
)
diff --git a/pipelex/cogt/models/model_deck_loader.py b/pipelex/cogt/models/model_deck_loader.py
index 908404e3f..1a406a86f 100644
--- a/pipelex/cogt/models/model_deck_loader.py
+++ b/pipelex/cogt/models/model_deck_loader.py
@@ -21,7 +21,7 @@ def load_model_deck_blueprint(model_deck_paths: list[str]) -> ModelDeckBlueprint
except FileNotFoundError as not_found_exc:
msg = f"Could not find Model Deck file at '{deck_path}': {not_found_exc}"
raise ModelDeckNotFoundError(msg) from not_found_exc
- deep_update(full_deck_dict, deck_dict)
+ deep_update(full_deck_dict, updates=deck_dict)
try:
return ModelDeckBlueprint.model_validate(full_deck_dict)
diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.py
index e6278c813..f76b780e5 100644
--- a/pipelex/cogt/models/model_manager.py
+++ b/pipelex/cogt/models/model_manager.py
@@ -64,6 +64,7 @@ class ModelManager(ModelManagerAbstract):
def setup(
self,
secrets_provider: SecretsProviderAbstract,
+ *,
gateway_config: GatewayConfig | None,
gateway_config_source: RemoteConfigSource | None,
needs_inference: bool = True,
@@ -99,6 +100,7 @@ class ModelManager(ModelManagerAbstract):
def _enforce_gateway_model_membership(
self,
gateway_config: GatewayConfig | None,
+ *,
gateway_config_source: RemoteConfigSource | None,
) -> None:
"""Fail loudly when the deck references a handle the gateway should provide but cannot.
@@ -191,6 +193,7 @@ class ModelManager(ModelManagerAbstract):
def _resolve_terminal_candidates(
cls,
deck: ModelDeck,
+ *,
ref: ModelReference,
model_type: ModelType,
) -> list[str]:
@@ -223,6 +226,7 @@ class ModelManager(ModelManagerAbstract):
def _collect_candidates(
cls,
ref: ModelReference,
+ *,
aliases: dict[str, str],
waterfalls: dict[str, list[str]],
is_fallback_enabled: bool,
@@ -295,7 +299,7 @@ class ModelManager(ModelManagerAbstract):
raise RuntimeError(msg)
return self._routing_profile
- def build_deck(self, enabled_backends: list[str], model_deck_blueprint: ModelDeckBlueprint) -> ModelDeck:
+ def build_deck(self, model_deck_blueprint: ModelDeckBlueprint, *, enabled_backends: list[str]) -> ModelDeck:
all_models_and_possible_backends = self.inference_backend_library.get_all_models_and_possible_backends()
inference_models: dict[str, InferenceModelSpec] = {}
@@ -385,7 +389,7 @@ class ModelManager(ModelManagerAbstract):
)
@override
- def get_inference_model(self, model_handle: str, model_type: ModelType) -> InferenceModelSpec:
+ def get_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec:
if self.model_deck is None:
msg = "Model deck is not initialized"
raise RuntimeError(msg)
diff --git a/pipelex/cogt/models/model_manager_abstract.py b/pipelex/cogt/models/model_manager_abstract.py
index 1fba6dcb8..4c97ff188 100644
--- a/pipelex/cogt/models/model_manager_abstract.py
+++ b/pipelex/cogt/models/model_manager_abstract.py
@@ -22,6 +22,7 @@ class ModelManagerAbstract(ABC):
def setup(
self,
secrets_provider: SecretsProviderAbstract,
+ *,
gateway_config: GatewayConfig | None,
gateway_config_source: RemoteConfigSource | None,
needs_inference: bool = True,
@@ -29,7 +30,7 @@ class ModelManagerAbstract(ABC):
pass
@abstractmethod
- def get_inference_model(self, model_handle: str, model_type: ModelType) -> InferenceModelSpec:
+ def get_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec:
pass
@abstractmethod
diff --git a/pipelex/cogt/models/model_suggestion.py b/pipelex/cogt/models/model_suggestion.py
index b37fa8247..8aad00dab 100644
--- a/pipelex/cogt/models/model_suggestion.py
+++ b/pipelex/cogt/models/model_suggestion.py
@@ -32,6 +32,7 @@ KIND_LABELS: dict[ModelReferenceKind, str] = {
def get_collection_keys(
model_deck: ModelDeck,
+ *,
model_type: ModelType,
kind: ModelReferenceKind,
) -> list[str]:
@@ -73,6 +74,7 @@ def get_collection_keys(
def suggest_model_alternatives(
model_deck: ModelDeck,
+ *,
model_type: ModelType,
name: str,
kind: ModelReferenceKind,
@@ -92,7 +94,7 @@ def suggest_model_alternatives(
- cross_collection_suggestions: fuzzy matches in other collections, with sigil and label
"""
sigil = KIND_SIGILS[kind]
- candidates = get_collection_keys(model_deck, model_type, kind)
+ candidates = get_collection_keys(model_deck, model_type=model_type, kind=kind)
fuzzy_matches = difflib.get_close_matches(name, candidates, n=5, cutoff=0.5)
suggestions = [f"{sigil}{match}" for match in fuzzy_matches]
@@ -100,7 +102,7 @@ def suggest_model_alternatives(
cross_suggestions: list[str] = []
other_kinds = [other_kind for other_kind in ModelReferenceKind if other_kind != kind]
for other_kind in other_kinds:
- other_candidates = get_collection_keys(model_deck, model_type, other_kind)
+ other_candidates = get_collection_keys(model_deck, model_type=model_type, kind=other_kind)
other_sigil = KIND_SIGILS[other_kind]
label = KIND_LABELS[other_kind]
if name in other_candidates:
diff --git a/pipelex/cogt/search/search_job_factory.py b/pipelex/cogt/search/search_job_factory.py
index d6899ade2..35290e97e 100644
--- a/pipelex/cogt/search/search_job_factory.py
+++ b/pipelex/cogt/search/search_job_factory.py
@@ -8,6 +8,7 @@ class SearchJobFactory:
def make_search_job(
cls,
query: str,
+ *,
search_setting: SearchSetting,
job_metadata: JobMetadata,
include_domains: list[str] | None = None,
diff --git a/pipelex/cogt/search/search_worker_abstract.py b/pipelex/cogt/search/search_worker_abstract.py
index 186c94b48..6928518aa 100644
--- a/pipelex/cogt/search/search_worker_abstract.py
+++ b/pipelex/cogt/search/search_worker_abstract.py
@@ -53,6 +53,7 @@ class SearchWorkerAbstract(InferenceWorkerAbstract):
async def search_structured(
self,
search_job: SearchJob,
+ *,
schema: type[BaseModelTypeVar],
) -> dict[str, Any]:
"""Execute a search query and return structured data matching the schema."""
@@ -84,6 +85,7 @@ class SearchWorkerAbstract(InferenceWorkerAbstract):
async def _search_structured(
self,
search_job: SearchJob,
+ *,
schema: type[BaseModelTypeVar],
) -> dict[str, Any]:
pass
diff --git a/pipelex/cogt/templating/template_preprocessor.py b/pipelex/cogt/templating/template_preprocessor.py
index 8ffa50326..90ce790a1 100644
--- a/pipelex/cogt/templating/template_preprocessor.py
+++ b/pipelex/cogt/templating/template_preprocessor.py
@@ -88,7 +88,7 @@ def _replace_dollar_sigil(match: Match[str]) -> str:
return f"{{{{ {variable}|format() }}}}"
-def _validate_at_sigil_alone_on_line(template: str, declared_inputs: set[str]) -> None:
+def _validate_at_sigil_alone_on_line(template: str, *, declared_inputs: set[str]) -> None:
r"""Scan for `@`/`@?` sigil candidates that are not alone on their own line and raise
when the candidate's root identifier is one of the surrounding pipe's declared inputs.
@@ -142,7 +142,7 @@ def _normalize_and_escape(template: str) -> str:
return normalized.replace("@@", _AT_ESCAPE_SENTINEL).replace("$$", _DOLLAR_ESCAPE_SENTINEL)
-def validate_template_sigils(template: str, declared_inputs: set[str]) -> None:
+def validate_template_sigils(template: str, *, declared_inputs: set[str]) -> None:
r"""Raise `TemplateSigilSyntaxError` when an inline `@`/`@?` candidate's root identifier
matches one of the pipe's declared inputs.
@@ -152,7 +152,7 @@ def validate_template_sigils(template: str, declared_inputs: set[str]) -> None:
the author actually plans to use — i.e. the "real typo" cases.
"""
prepared = _normalize_and_escape(template)
- _validate_at_sigil_alone_on_line(prepared, declared_inputs)
+ _validate_at_sigil_alone_on_line(prepared, declared_inputs=declared_inputs)
def rewrite_template_sigils(template: str) -> str:
@@ -197,5 +197,5 @@ def preprocess_template(template: str, *, declared_inputs: set[str] | None = Non
line-ending-insensitive.
"""
if declared_inputs is not None:
- validate_template_sigils(template, declared_inputs)
+ validate_template_sigils(template, declared_inputs=declared_inputs)
return rewrite_template_sigils(template)
diff --git a/pipelex/cogt/templating/template_rendering.py b/pipelex/cogt/templating/template_rendering.py
index 5ab99a81b..b8898960e 100644
--- a/pipelex/cogt/templating/template_rendering.py
+++ b/pipelex/cogt/templating/template_rendering.py
@@ -9,6 +9,7 @@ from pipelex.tools.jinja2.jinja2_rendering import render_jinja2_async
async def render_template(
template: str,
+ *,
category: TemplateCategory,
context: dict[str, Any],
templating_style: TemplatingStyle | None = None,
diff --git a/pipelex/cogt/usage/cost_registry.py b/pipelex/cogt/usage/cost_registry.py
index 972b7e52d..bfcb929ae 100644
--- a/pipelex/cogt/usage/cost_registry.py
+++ b/pipelex/cogt/usage/cost_registry.py
@@ -64,6 +64,7 @@ class CostRegistry(RootModel[CostRegistryRoot]):
def generate_report(
cls,
pipeline_run_id: str,
+ *,
tokens_usages: Sequence[TokensUsage],
unit_scale: float,
cost_report_file_path: Path | None = None,
@@ -188,10 +189,10 @@ class CostRegistry(RootModel[CostRegistryRoot]):
console.print(" [dim]Note: some costs might be missing or not up-to-date.[/dim]")
if cost_report_file_path:
- cls.save_to_csv(records, cost_report_file_path)
+ cls.save_to_csv(records, file_path=cost_report_file_path)
@staticmethod
- def save_to_csv(records: list[dict[str, Any]], file_path: Path) -> None:
+ def save_to_csv(records: list[dict[str, Any]], *, file_path: Path) -> None:
"""Save records to CSV file."""
if not records:
return
@@ -210,7 +211,7 @@ class CostRegistry(RootModel[CostRegistryRoot]):
writer.writerows(records)
@classmethod
- def compute_total_cost(cls, input_non_cached_cost: float, input_cached_cost: float, output_cost: float) -> float:
+ def compute_total_cost(cls, *, input_non_cached_cost: float, input_cached_cost: float, output_cost: float) -> float:
return input_non_cached_cost + input_cached_cost + output_cost
@classmethod
diff --git a/pipelex/cogt/usage/costs_per_token.py b/pipelex/cogt/usage/costs_per_token.py
index 05027958d..a073e56a8 100644
--- a/pipelex/cogt/usage/costs_per_token.py
+++ b/pipelex/cogt/usage/costs_per_token.py
@@ -1,7 +1,7 @@
from pipelex.cogt.usage.cost_category import CostCategory, CostsByCategoryDict
-def model_cost_per_token(costs: CostsByCategoryDict, cost_category: CostCategory) -> float:
+def model_cost_per_token(*, costs: CostsByCategoryDict, cost_category: CostCategory) -> float:
# cost_per_million_tokens_usd should be missing only for models that we run on our own GPUs
# all token types are not used for all models
match cost_category:
diff --git a/pipelex/core/bundles/pipelex_bundle_blueprint.py b/pipelex/core/bundles/pipelex_bundle_blueprint.py
index a7767c5f5..b6a425402 100644
--- a/pipelex/core/bundles/pipelex_bundle_blueprint.py
+++ b/pipelex/core/bundles/pipelex_bundle_blueprint.py
@@ -189,16 +189,16 @@ class PipelexBundleBlueprint(BaseModel):
# Collect from concepts
if self.concept:
for concept_code, concept_blueprint in self.concept.items():
- local_refs.extend(self._collect_local_refs_from_concept(concept_code, concept_blueprint))
+ local_refs.extend(self._collect_local_refs_from_concept(concept_code, concept_blueprint=concept_blueprint))
# Collect from pipes
if self.pipe:
for pipe_code, pipe_blueprint in self.pipe.items():
- local_refs.extend(self._collect_local_refs_from_pipe(pipe_code, pipe_blueprint))
+ local_refs.extend(self._collect_local_refs_from_pipe(pipe_code, pipe_blueprint=pipe_blueprint))
return local_refs
- def _collect_local_refs_from_concept(self, concept_code: str, concept_blueprint: ConceptBlueprint | str) -> list[tuple[str, str]]:
+ def _collect_local_refs_from_concept(self, concept_code: str, *, concept_blueprint: ConceptBlueprint | str) -> list[tuple[str, str]]:
local_refs: list[tuple[str, str]] = []
if isinstance(concept_blueprint, str):
@@ -221,7 +221,7 @@ class PipelexBundleBlueprint(BaseModel):
return local_refs
- def _collect_local_refs_from_pipe(self, pipe_code: str, pipe_blueprint: PipeBlueprintUnion) -> list[tuple[str, str]]:
+ def _collect_local_refs_from_pipe(self, pipe_code: str, *, pipe_blueprint: PipeBlueprintUnion) -> list[tuple[str, str]]:
local_refs: list[tuple[str, str]] = []
# Check inputs
diff --git a/pipelex/core/concepts/concept.py b/pipelex/core/concepts/concept.py
index c91b9f031..a8c3d0f69 100644
--- a/pipelex/core/concepts/concept.py
+++ b/pipelex/core/concepts/concept.py
@@ -93,6 +93,7 @@ class Concept(ConceptAbstract):
@classmethod
def are_concept_compatible(
cls,
+ *,
concept_1: "Concept",
concept_2: "Concept",
strict: bool = False,
@@ -144,7 +145,7 @@ class Concept(ConceptAbstract):
return False
# Check if classes are structurally equivalent (same fields, types)
- if are_classes_equivalent(concept_1_class, concept_2_class):
+ if are_classes_equivalent(concept_1_class, class_2=concept_2_class):
return True
if strict:
@@ -160,7 +161,7 @@ class Concept(ConceptAbstract):
pass
# Check if concept_1 has compatible fields with concept_2
- return has_compatible_field(concept_1_class, concept_2_class)
+ return has_compatible_field(concept_1_class, target_type=concept_2_class)
@classmethod
def is_valid_structure_class(cls, structure_class_name: str) -> bool:
@@ -192,6 +193,7 @@ class Concept(ConceptAbstract):
def render_concept_representation(
self,
+ *,
output_format: ConceptRepresentationFormat,
is_multiple: bool = False,
) -> tuple[dict[str, Any], set[str]]:
@@ -213,7 +215,7 @@ class Concept(ConceptAbstract):
case ConceptRepresentationFormat.JSON | ConceptRepresentationFormat.PYTHON:
generator = ConceptRepresentationGenerator(output_format)
# For inputs, we only want required fields (not optional ones)
- result = generator.generate_representation(self.concept_ref, self.get_structure_class(), include_optional=False)
+ result = generator.generate_representation(self.concept_ref, structure_class=self.get_structure_class(), include_optional=False)
# If multiple and JSON format, wrap content in a list
# For Python format, the caller handles wrapping since content is a string
diff --git a/pipelex/core/concepts/concept_factory.py b/pipelex/core/concepts/concept_factory.py
index c2eb9fb75..5b688822f 100644
--- a/pipelex/core/concepts/concept_factory.py
+++ b/pipelex/core/concepts/concept_factory.py
@@ -85,7 +85,7 @@ class DomainAndConceptCode(BaseModel):
class ConceptFactory:
@classmethod
- def make(cls, concept_code: str, domain_code: str, description: str, structure_class_name: str, refines: str | None = None) -> Concept:
+ def make(cls, concept_code: str, *, domain_code: str, description: str, structure_class_name: str, refines: str | None = None) -> Concept:
return Concept(
code=concept_code,
domain_code=domain_code,
@@ -187,6 +187,7 @@ class ConceptFactory:
def make_domain_and_concept_code_from_concept_ref_or_code(
cls,
concept_ref_or_code: str,
+ *,
domain_code: str | None = None,
) -> DomainAndConceptCode:
# Handle cross-package references (alias->domain.ConceptCode)
@@ -223,11 +224,11 @@ class ConceptFactory:
raise ConceptFactoryError(msg)
@classmethod
- def make_concept_ref_with_domain(cls, domain_code: str, concept_code: str) -> str:
+ def make_concept_ref_with_domain(cls, *, domain_code: str, concept_code: str) -> str:
return f"{domain_code}.{concept_code}"
@classmethod
- def make_concept_ref_with_domain_from_concept_ref_or_code(cls, domain_code: str, concept_ref_or_code: str) -> str:
+ def make_concept_ref_with_domain_from_concept_ref_or_code(cls, *, domain_code: str, concept_ref_or_code: str) -> str:
input_domain_and_code = cls.make_domain_and_concept_code_from_concept_ref_or_code(
concept_ref_or_code=concept_ref_or_code,
domain_code=domain_code,
@@ -239,7 +240,7 @@ class ConceptFactory:
)
@classmethod
- def make_refine(cls, refine: str, domain_code: str) -> str:
+ def make_refine(cls, refine: str, *, domain_code: str) -> str:
"""Validate and normalize a refine string.
If the refine is a native concept code without domain (e.g., 'Text'),
@@ -273,6 +274,7 @@ class ConceptFactory:
def _handle_structure_with_classname(
cls,
blueprint: ConceptBlueprint,
+ *,
concept_code: str,
domain_code: str,
) -> str:
@@ -299,6 +301,7 @@ class ConceptFactory:
def _handle_blueprint_with_structure(
cls,
blueprint: ConceptBlueprint,
+ *,
concept_code: str,
domain_code: str,
) -> str:
@@ -322,7 +325,7 @@ class ConceptFactory:
# Normalize the structure blueprint to ensure all values are ConceptStructureBlueprint objects
normalized_structure = normalize_structure_blueprint(blueprint.structure)
- qualified_class_name = make_qualified_structure_class_name(domain_code, concept_code)
+ qualified_class_name = make_qualified_structure_class_name(domain_code=domain_code, concept_code=concept_code)
try:
_, the_generated_class = StructureGenerator(local_domain=domain_code).generate_from_structure_blueprint(
class_name=qualified_class_name,
@@ -342,11 +345,12 @@ class ConceptFactory:
def _handle_basic_blueprint(
cls,
concept_code: str,
+ *,
domain_code: str,
description: str,
) -> StructureNameAndRefine:
"""Handle BASIC_BLUEPRINT declaration type."""
- qualified_class_name = make_qualified_structure_class_name(domain_code, concept_code)
+ qualified_class_name = make_qualified_structure_class_name(domain_code=domain_code, concept_code=concept_code)
# Check if a valid structure class already exists — first by bare concept_code
# (for pre-existing Python classes registered under their own name), then by
@@ -382,6 +386,7 @@ class ConceptFactory:
def _handle_refines(
cls,
blueprint: ConceptBlueprint,
+ *,
concept_code: str,
domain_code: str,
) -> StructureNameAndRefine:
@@ -400,7 +405,7 @@ class ConceptFactory:
msg = f"Could not validate refine '{blueprint.refines}' for concept '{concept_code}' in domain '{domain_code}': {exc}"
raise ConceptFactoryError(msg) from exc
- qualified_class_name = make_qualified_structure_class_name(domain_code, concept_code)
+ qualified_class_name = make_qualified_structure_class_name(domain_code=domain_code, concept_code=concept_code)
# Cross-package refines: base class isn't available locally, so generate
# a standalone TextContent subclass. The refinement relationship is tracked
@@ -431,7 +436,7 @@ class ConceptFactory:
refined_structure_class_name = refined_concept_code + "Content"
else:
refined_domain_code = refined_ref.domain_path or domain_code
- refined_structure_class_name = make_qualified_structure_class_name(refined_domain_code, refined_concept_code)
+ refined_structure_class_name = make_qualified_structure_class_name(domain_code=refined_domain_code, concept_code=refined_concept_code)
# Generate a new class that inherits from the refined structure class
# This creates an empty class that can be extended with additional fields in the future
@@ -457,6 +462,7 @@ class ConceptFactory:
@classmethod
def make_from_blueprint(
cls,
+ *,
domain_code: str,
concept_code: str,
blueprint_or_string_description: ConceptBlueprint | str,
diff --git a/pipelex/core/concepts/concept_representation_generator.py b/pipelex/core/concepts/concept_representation_generator.py
index 9e4daa5cd..f7de0763d 100644
--- a/pipelex/core/concepts/concept_representation_generator.py
+++ b/pipelex/core/concepts/concept_representation_generator.py
@@ -50,6 +50,7 @@ class ConceptRepresentationGenerator:
def generate_representation(
self,
concept_ref: str,
+ *,
structure_class: type[StuffContent],
include_optional: bool = True,
) -> dict[str, Any]:
@@ -74,6 +75,7 @@ class ConceptRepresentationGenerator:
def generate_class_representation(
self,
content_class: type[StuffContent],
+ *,
include_optional: bool = True,
) -> dict[str, Any] | str:
"""Generate representation for a StuffContent class (recursive).
@@ -97,7 +99,7 @@ class ConceptRepresentationGenerator:
case ConceptRepresentationFormat.JSON:
return fields_dict
case ConceptRepresentationFormat.PYTHON:
- return self._format_as_python(class_name, fields_dict)
+ return self._format_as_python(class_name, fields=fields_dict)
case ConceptRepresentationFormat.SCHEMA:
msg = "Schema format is not supported by ConceptRepresentationGenerator. Use render_concept_representation on Concept instead."
raise ValueError(msg)
@@ -105,6 +107,7 @@ class ConceptRepresentationGenerator:
def _generate_fields_dict(
self,
content_class: type[StuffContent],
+ *,
include_optional: bool = True,
) -> dict[str, Any]:
"""Generate a dict with field values for a class.
@@ -124,12 +127,12 @@ class ConceptRepresentationGenerator:
continue
field_type = field_info.annotation
- field_value = self.generate_field_value(field_type, field_name)
+ field_value = self.generate_field_value(field_type, field_name=field_name)
fields_dict[field_name] = field_value
return fields_dict
- def generate_field_value(self, field_type: Any, field_name: str) -> Any:
+ def generate_field_value(self, field_type: Any, *, field_name: str) -> Any:
"""Generate a representation value for a field based on its type (recursive).
Handles:
@@ -152,7 +155,7 @@ class ConceptRepresentationGenerator:
# Handle list types
if origin is list:
- return self._generate_list_value(args, field_name)
+ return self._generate_list_value(args, field_name=field_name)
# Handle dict types
if origin is dict:
@@ -160,11 +163,11 @@ class ConceptRepresentationGenerator:
# Handle Literal types (fields with choices)
if origin is typing.Literal:
- return self._generate_literal_value(args, field_name)
+ return self._generate_literal_value(args, field_name=field_name)
# Handle StrEnum types
if inspect.isclass(actual_type) and issubclass(actual_type, StrEnum):
- return self._generate_enum_value(actual_type, field_name)
+ return self._generate_enum_value(actual_type, field_name=field_name)
# Handle nested StuffContent (recursive)
if inspect.isclass(actual_type) and issubclass(actual_type, StuffContent):
@@ -175,7 +178,7 @@ class ConceptRepresentationGenerator:
return self._generate_basemodel_representation(actual_type)
# Handle basic types
- return self._generate_basic_value(actual_type, field_name)
+ return self._generate_basic_value(actual_type, field_name=field_name)
def _unwrap_optional(self, field_type: Any) -> Any:
"""Unwrap Optional[T] to get T.
@@ -193,7 +196,7 @@ class ConceptRepresentationGenerator:
return next((arg for arg in args if arg is not type(None)), field_type) if args else field_type
return field_type
- def _generate_list_value(self, args: tuple[Any, ...], field_name: str) -> list[Any]:
+ def _generate_list_value(self, args: tuple[Any, ...], *, field_name: str) -> list[Any]:
"""Generate a list value with one example item.
Args:
@@ -219,7 +222,7 @@ class ConceptRepresentationGenerator:
return [item_repr]
# Handle list of basic types
- return [self._generate_basic_value(item_type, f"{field_name}_item")]
+ return [self._generate_basic_value(item_type, field_name=f"{field_name}_item")]
def _generate_dict_value(self, field_name: str) -> dict[str, str]:
"""Generate a placeholder dict value.
@@ -232,7 +235,7 @@ class ConceptRepresentationGenerator:
"""
return {f"{field_name}_key": f"{field_name}_value"}
- def _generate_literal_value(self, literal_args: tuple[Any, ...], field_name: str) -> Any:
+ def _generate_literal_value(self, literal_args: tuple[Any, ...], *, field_name: str) -> Any:
"""Generate a value from a Literal type by randomly picking one of its choices.
Args:
@@ -247,7 +250,7 @@ class ConceptRepresentationGenerator:
return random.choice(literal_args)
return f"{field_name}_value"
- def _generate_enum_value(self, enum_type: type[StrEnum], field_name: str) -> str:
+ def _generate_enum_value(self, enum_type: type[StrEnum], *, field_name: str) -> str:
"""Generate a value from a StrEnum type.
Args:
@@ -275,19 +278,19 @@ class ConceptRepresentationGenerator:
fields_dict: dict[str, Any] = {}
for field_name, field_info in model_class.model_fields.items():
field_type = field_info.annotation
- field_value = self.generate_field_value(field_type, field_name)
+ field_value = self.generate_field_value(field_type, field_name=field_name)
fields_dict[field_name] = field_value
match self.output_format:
case ConceptRepresentationFormat.JSON:
return fields_dict
case ConceptRepresentationFormat.PYTHON:
- return self._format_as_python(class_name, fields_dict)
+ return self._format_as_python(class_name, fields=fields_dict)
case ConceptRepresentationFormat.SCHEMA:
msg = "Schema format is not supported by ConceptRepresentationGenerator. Use render_concept_representation on Concept instead."
raise ValueError(msg)
- def _generate_basic_value(self, actual_type: Any, field_name: str) -> Any:
+ def _generate_basic_value(self, actual_type: Any, *, field_name: str) -> Any:
"""Generate a value for basic Python types.
Args:
@@ -319,11 +322,11 @@ class ConceptRepresentationGenerator:
if set(non_none_args) == {int, float}:
return 1 # Return a sensible default for number types
# For other unions, try to generate a value for the first type
- return self._generate_basic_value(non_none_args[0], field_name)
+ return self._generate_basic_value(non_none_args[0], field_name=field_name)
type_name = getattr(actual_type, "__name__", str(actual_type))
return f"{field_name}_{type_name}"
- def _format_as_python(self, class_name: str, fields: dict[str, Any]) -> str:
+ def _format_as_python(self, class_name: str, *, fields: dict[str, Any]) -> str:
"""Format a class instantiation as Python code string.
Args:
@@ -390,6 +393,7 @@ class ConceptRepresentationGenerator:
def generate_json_representation(
concept_ref: str,
+ *,
structure_class: type[StuffContent],
) -> dict[str, Any]:
"""Convenience function to generate a JSON format representation.
@@ -402,11 +406,12 @@ def generate_json_representation(
Dict with concept and content
"""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- return generator.generate_representation(concept_ref, structure_class)
+ return generator.generate_representation(concept_ref, structure_class=structure_class)
def generate_python_representation(
concept_ref: str,
+ *,
structure_class: type[StuffContent],
) -> tuple[dict[str, Any], set[str]]:
"""Convenience function to generate a Python format representation.
@@ -419,5 +424,5 @@ def generate_python_representation(
Tuple of (representation dict, imports_needed set)
"""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- representation = generator.generate_representation(concept_ref, structure_class)
+ representation = generator.generate_representation(concept_ref, structure_class=structure_class)
return representation, generator.imports_needed
diff --git a/pipelex/core/concepts/concept_structure_blueprint.py b/pipelex/core/concepts/concept_structure_blueprint.py
index 17a66570f..8f2ba0038 100644
--- a/pipelex/core/concepts/concept_structure_blueprint.py
+++ b/pipelex/core/concepts/concept_structure_blueprint.py
@@ -161,30 +161,30 @@ class ConceptStructureBlueprint(BaseModel):
match self.type:
case ConceptStructureBlueprintFieldType.TEXT:
if not isinstance(self.default_value, str):
- self._raise_type_mismatch_error("str", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("str", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.INTEGER:
if not isinstance(self.default_value, int):
- self._raise_type_mismatch_error("int", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("int", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.BOOLEAN:
if not isinstance(self.default_value, bool):
- self._raise_type_mismatch_error("bool", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("bool", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.NUMBER:
if not isinstance(self.default_value, (int, float)):
- self._raise_type_mismatch_error("number (int or float)", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("number (int or float)", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.LIST:
if not isinstance(self.default_value, list):
- self._raise_type_mismatch_error("list", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("list", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.DICT:
if not isinstance(self.default_value, dict):
- self._raise_type_mismatch_error("dict", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("dict", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.DATE:
if not isinstance(self.default_value, datetime):
- self._raise_type_mismatch_error("date", type(self.default_value).__name__)
+ self._raise_type_mismatch_error("date", actual_type_name=type(self.default_value).__name__)
case ConceptStructureBlueprintFieldType.CONCEPT:
# CONCEPT type cannot have default values, this is already validated in validate_structure_blueprint
# This case is here for exhaustiveness
pass
- def _raise_type_mismatch_error(self, expected_type_name: str, actual_type_name: str) -> None:
+ def _raise_type_mismatch_error(self, expected_type_name: str, *, actual_type_name: str) -> None:
msg = f"default_value type mismatch: expected {expected_type_name} for type '{self.type}', but got {actual_type_name}"
raise ValueError(msg)
diff --git a/pipelex/core/concepts/helpers.py b/pipelex/core/concepts/helpers.py
index 001e192aa..b2c5ab6ca 100644
--- a/pipelex/core/concepts/helpers.py
+++ b/pipelex/core/concepts/helpers.py
@@ -12,6 +12,7 @@ if TYPE_CHECKING:
def get_structure_class_name_from_blueprint(
blueprint_or_string_description: ConceptBlueprint | str,
+ *,
concept_ref_or_code: str,
) -> str:
"""Get the structure class name from a blueprint.
@@ -87,7 +88,7 @@ def normalize_structure_blueprint(structure_dict: dict[str, str | ConceptStructu
return normalized
-def make_qualified_structure_class_name(domain_code: str, concept_code: str) -> str:
+def make_qualified_structure_class_name(*, domain_code: str, concept_code: str) -> str:
"""Build a domain-qualified class name for dynamically generated structure classes.
Uses double underscore as separator to produce a valid Python identifier
diff --git a/pipelex/core/concepts/structure_generation/generator.py b/pipelex/core/concepts/structure_generation/generator.py
index 268559081..3769be52a 100644
--- a/pipelex/core/concepts/structure_generation/generator.py
+++ b/pipelex/core/concepts/structure_generation/generator.py
@@ -77,6 +77,7 @@ class StructureGenerator:
def generate_from_structure_blueprint(
self,
+ *,
class_name: str,
structure_blueprint: dict[str, ConceptStructureBlueprint],
base_class_name: str | None = None,
@@ -98,7 +99,9 @@ class StructureGenerator:
"""
# Generate the class
- class_code = self._generate_class_source_code_from_blueprint(class_name, structure_blueprint, base_class_name, description)
+ class_code = self._generate_class_source_code_from_blueprint(
+ class_name, structure_blueprint=structure_blueprint, base_class_name=base_class_name, description=description
+ )
# Generate the complete module with a header comment
imports_section = "\n".join(sorted(self.imports))
@@ -141,6 +144,7 @@ class StructureGenerator:
def validate_generated_code(
self,
python_code: str,
+ *,
expected_class_name: str,
base_class_name: str | None = None,
) -> type:
@@ -204,7 +208,7 @@ class StructureGenerator:
return self._escape_string_for_python(value)
return repr(value)
- def _format_class_docstring(self, docstring: str, indent: str = " ") -> str:
+ def _format_class_docstring(self, docstring: str, *, indent: str = " ") -> str:
"""Render a class docstring, wrapping it across multiple lines when the single-line
form would exceed _MAX_LINE_LENGTH.
"""
@@ -245,6 +249,7 @@ class StructureGenerator:
def _generate_class_source_code_from_blueprint(
self,
class_name: str,
+ *,
structure_blueprint: dict[str, ConceptStructureBlueprint],
base_class_name: str | None = None,
description: str = "",
@@ -293,7 +298,7 @@ class StructureGenerator:
# Generate fields
field_definitions: list[str] = []
for field_name, field_blueprint in structure_blueprint.items():
- field_code = self._generate_field_from_blueprint(field_name, field_blueprint)
+ field_code = self._generate_field_from_blueprint(field_name, field_blueprint=field_blueprint)
field_definitions.append(field_code)
if not field_definitions:
@@ -303,7 +308,7 @@ class StructureGenerator:
fields_code = "\n".join(field_definitions)
return class_header + "\n" + fields_code
- def _generate_field_from_blueprint(self, field_name: str, field_blueprint: ConceptStructureBlueprint) -> str:
+ def _generate_field_from_blueprint(self, field_name: str, *, field_blueprint: ConceptStructureBlueprint) -> str:
"""Generate a field definition from ConceptStructureBlueprint.
Args:
@@ -468,11 +473,11 @@ class StructureGenerator:
# e.g., "myapp.Customer" -> '"myapp__Customer"'
concept_code = extract_concept_code_from_concept_ref_or_code(concept_ref)
if parsed_ref.domain_path and not NativeConceptCode.is_native_concept_ref_or_code(concept_ref):
- qualified_name = make_qualified_structure_class_name(parsed_ref.domain_path, concept_code)
+ qualified_name = make_qualified_structure_class_name(domain_code=parsed_ref.domain_path, concept_code=concept_code)
return f'"{qualified_name}"'
return f'"{concept_code}"'
- def _generate_field(self, field_name: str, field_def: dict[str, Any] | str) -> str:
+ def _generate_field(self, field_name: str, *, field_def: dict[str, Any] | str) -> str:
"""Generate a single field definition.
Args:
@@ -499,7 +504,7 @@ class StructureGenerator:
python_type = f"Literal[{', '.join(repr(c) for c in choices)}]"
else:
# Handle complex types or enum references
- python_type = self._get_python_type(field_type, field_def)
+ python_type = self._get_python_type(field_type, field_def=field_def)
# Make optional if not required
if not required:
@@ -522,7 +527,7 @@ class StructureGenerator:
return f" {field_name}: {python_type} = {field_call}"
- def _get_python_type(self, field_type: Any, field_def: dict[str, Any]) -> str:
+ def _get_python_type(self, field_type: Any, *, field_def: dict[str, Any]) -> str:
"""Convert high-level type to Python type annotation.
Args:
@@ -583,7 +588,7 @@ class StructureGenerator:
if isinstance(item_type, str):
try:
item_type_enum = ConceptStructureBlueprintFieldType(item_type)
- item_type = self._get_python_type(item_type_enum, {})
+ item_type = self._get_python_type(item_type_enum, field_def={})
except ValueError:
# Keep as string if not a known FieldType
pass
@@ -595,13 +600,13 @@ class StructureGenerator:
if isinstance(key_type, str):
try:
key_type_enum = ConceptStructureBlueprintFieldType(key_type)
- key_type = self._get_python_type(key_type_enum, {})
+ key_type = self._get_python_type(key_type_enum, field_def={})
except ValueError:
pass
if isinstance(value_type, str):
try:
value_type_enum = ConceptStructureBlueprintFieldType(value_type)
- value_type = self._get_python_type(value_type_enum, {})
+ value_type = self._get_python_type(value_type_enum, field_def={})
except ValueError:
pass
return f"Dict[{key_type}, {value_type}]"
@@ -609,6 +614,7 @@ class StructureGenerator:
def _validate_execution(
self,
python_code: str,
+ *,
expected_class_name: str,
base_class_name: str | None = None,
) -> type:
diff --git a/pipelex/core/interpreter/bundle_elaborator.py b/pipelex/core/interpreter/bundle_elaborator.py
index 090346b26..fcb5321c4 100644
--- a/pipelex/core/interpreter/bundle_elaborator.py
+++ b/pipelex/core/interpreter/bundle_elaborator.py
@@ -105,6 +105,7 @@ class BundleElaborator:
def _elaborate_preliminary_text(
cls,
pipe_code: str,
+ *,
pipe_blueprint: PipeLLMBlueprint,
new_pipe_dict: dict[str, PipeBlueprintUnion],
elaboration_metadata: dict[str, ElaborationMetadata],
diff --git a/pipelex/core/interpreter/interpreter.py b/pipelex/core/interpreter/interpreter.py
index 75171cebc..3ae86dc1e 100644
--- a/pipelex/core/interpreter/interpreter.py
+++ b/pipelex/core/interpreter/interpreter.py
@@ -19,7 +19,26 @@ class PipelexInterpreter(BaseModel):
"""MTHDS -> PipelexBundleBlueprint"""
@classmethod
- def make_pipelex_bundle_blueprint(cls, bundle_path: Path | None = None, mthds_content: str | None = None) -> PipelexBundleBlueprint:
+ def make_pipelex_bundle_blueprint(
+ cls,
+ bundle_path: Path | None = None,
+ *,
+ mthds_content: str | None = None,
+ mthds_source: str | None = None,
+ ) -> PipelexBundleBlueprint:
+ """Parse one MTHDS source into a ``PipelexBundleBlueprint``.
+
+ Exactly one of ``bundle_path`` (load from disk) or ``mthds_content``
+ (load from a string) must be provided. ``mthds_source`` is an optional
+ logical source for the *in-memory* path: the API submits sourceless bundle
+ text (``mthds_contents: list[str]``), so without it ``blueprint.source``
+ is ``None`` and cross-file diagnostics misfire. It is seeded into the
+ blueprint dict before validation (as the ``source`` field), so it lands
+ both on the validated blueprint AND on any blueprint-validation error the
+ categorizer reads off that dict — mirroring the real file path the disk
+ path already records, and overriding any ``source`` the bundle text
+ itself declared. Ignored when ``bundle_path`` is provided (the path wins).
+ """
blueprint_dict: dict[str, Any]
try:
if bundle_path is not None:
@@ -27,6 +46,11 @@ class PipelexInterpreter(BaseModel):
blueprint_dict[PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD] = str(bundle_path)
elif mthds_content is not None:
blueprint_dict = load_toml_from_content(content=mthds_content)
+ # Seed the logical source unconditionally (``None`` when unnamed): this
+ # overrides any ``source`` the bundle text declared and keeps the success
+ # path (``model_validate`` below) and the error path (the categorizer,
+ # which reads ``source`` off this dict) in agreement on one value.
+ blueprint_dict[PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD] = mthds_source
else:
msg = "Either 'bundle_path' or 'mthds_content' must be provided for the PipelexInterpreter to make a PipelexBundleBlueprint"
raise PipelexInterpreterError(msg)
@@ -39,8 +63,10 @@ class PipelexInterpreter(BaseModel):
raise PipelexInterpreterError(msg)
try:
+ # ``source`` is already populated from the seeded ``blueprint_dict`` above
+ # (disk path → real file path; in-memory path → ``mthds_source``), so no
+ # post-validate re-assignment is needed.
pipelex_bundle_blueprint = PipelexBundleBlueprint.model_validate(blueprint_dict)
- pipelex_bundle_blueprint.source = str(bundle_path) if bundle_path else None
except ValidationError as exc:
# TODO: Move this to the validate_bundle function
blueprint_validation_errors: list[PipelexBundleBlueprintValidationErrorData] = []
diff --git a/pipelex/core/interpreter/validation_error_categorizer.py b/pipelex/core/interpreter/validation_error_categorizer.py
index ffc1f996b..0802937a7 100644
--- a/pipelex/core/interpreter/validation_error_categorizer.py
+++ b/pipelex/core/interpreter/validation_error_categorizer.py
@@ -26,6 +26,7 @@ def _extract_variable_names_from_message(message: str) -> list[str] | None:
def _categorize_input_validation_error(
message: str,
+ *,
domain: str | None,
source: str | None,
pipe_code: str | None,
@@ -72,6 +73,7 @@ def _categorize_input_validation_error(
def _categorize_syntax_validation_error(
message: str,
+ *,
domain: str | None,
source: str | None,
) -> PipelexBundleBlueprintValidationErrorData | None:
@@ -124,6 +126,7 @@ def _is_pydantic_internal_loc_element(element: str) -> bool:
def _categorize_concept_validation_error(
loc: tuple[int | str, ...],
+ *,
message: str,
domain: str | None,
source: str | None,
@@ -167,14 +170,15 @@ def _categorize_concept_validation_error(
def categorize_blueprint_validation_error(
- blueprint_dict: dict[str, Any],
error: ErrorDetails,
+ *,
+ blueprint_dict: dict[str, Any],
) -> PipelexBundleBlueprintValidationErrorData | None:
"""Categorize a BLUEPRINT validation error and create structured error data or return None if the error cannot be categorized.
Args:
- blueprint_dict: The blueprint dict being validated (for context extraction)
error: Pydantic error from PipelexBundleBlueprint.model_validate()
+ blueprint_dict: The blueprint dict being validated (for context extraction)
Returns:
PipelexBundleBlueprintValidationErrorData with all relevant fields populated, or None if error cannot be categorized
diff --git a/pipelex/core/memory/working_memory.py b/pipelex/core/memory/working_memory.py
index 2a8fedb60..c6a10da02 100644
--- a/pipelex/core/memory/working_memory.py
+++ b/pipelex/core/memory/working_memory.py
@@ -116,13 +116,13 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
if MAIN_STUFF_NAME in self.root:
del self.root[MAIN_STUFF_NAME]
- def set_stuff(self, name: str, stuff: Stuff):
+ def set_stuff(self, *, name: str, stuff: Stuff):
self.root[name] = stuff
def is_stuff_exists(self, name: str) -> bool:
return name in self.root or name in self.aliases
- def add_new_stuff(self, name: str, stuff: Stuff, aliases: list[str] | None = None):
+ def add_new_stuff(self, *, name: str, stuff: Stuff, aliases: list[str] | None = None):
# TODO: Add unit tests for this method
if self.is_stuff_code_used(stuff_code=stuff.stuff_code):
msg = f"Stuff code '{stuff.stuff_code}' is already used by another stuff"
@@ -141,9 +141,9 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
self.set_stuff(name=name, stuff=stuff)
if aliases:
for alias in aliases:
- self.set_alias(alias, name)
+ self.set_alias(alias, target=name)
- def set_new_main_stuff(self, stuff: Stuff, name: str | None = None):
+ def set_new_main_stuff(self, stuff: Stuff, *, name: str | None = None):
# TODO: Add unit tests for this method
if name:
self.remove_main_stuff()
@@ -154,7 +154,7 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
self.set_stuff(name=MAIN_STUFF_NAME, stuff=stuff)
log.verbose(f"Setting new main stuff (unnamed): {stuff.concept.code} = '{stuff.short_desc}'")
- def set_alias(self, alias: str, target: str) -> None:
+ def set_alias(self, alias: str, *, target: str) -> None:
"""Add an alias pointing to a target name."""
if alias == target:
msg = f"Cannot create alias '{alias}' pointing to itself"
@@ -164,7 +164,7 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
raise WorkingMemoryConsistencyError(msg)
self.aliases[alias] = target
- def add_alias(self, alias: str, target: str) -> None:
+ def add_alias(self, alias: str, *, target: str) -> None:
"""Add an alias pointing to a target name."""
if alias in self.root:
msg = f"Cannot add alias '{alias}' as it already exists"
@@ -201,7 +201,7 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
return artefact_dict
@override
- def get_typed_object_or_attribute(self, name: str, wanted_type: type[Any] | None = None, accept_list: bool = False) -> Any:
+ def get_typed_object_or_attribute(self, name: str, *, wanted_type: type[Any] | None = None, accept_list: bool = False) -> Any:
"""Retrieve a typed object or nested attribute from working memory.
This method is primarily used to:
@@ -326,7 +326,7 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
return top_level_content
- def _get_typed_items_from_list_content(self, list_content: ListContent[Any], wanted_type: type[Any] | None) -> list[Any] | None:
+ def _get_typed_items_from_list_content(self, list_content: ListContent[Any], *, wanted_type: type[Any] | None) -> list[Any] | None:
"""Extract items from ListContent with optional type validation.
Used to collect specific content types (e.g., Images, Documents) from lists
@@ -367,17 +367,17 @@ class WorkingMemory(WorkingMemoryAbstract[Stuff], ContextProviderAbstract):
# Stuff accessors
################################################################################################
- def get_stuff_as(self, name: str, content_type: type[StuffContentType]) -> StuffContentType:
+ def get_stuff_as(self, name: str, *, content_type: type[StuffContentType]) -> StuffContentType:
"""Get stuff content as StuffContentType."""
return self.get_stuff(name=name).content_as(content_type=content_type)
- def get_stuff_as_list(self, name: str, item_type: type[StuffContentType]) -> ListContent[StuffContentType]:
+ def get_stuff_as_list(self, name: str, *, item_type: type[StuffContentType]) -> ListContent[StuffContentType]:
"""Get stuff content as ListContent with items of type StuffContentType.
If the items are of possibly various types, use item_type=StuffContent.
"""
return self.get_stuff(name=name).as_list_of_fixed_content_type(item_type=item_type)
- def get_list_stuff_first_item_as(self, name: str, item_type: type[StuffContentType]) -> StuffContentType:
+ def get_list_stuff_first_item_as(self, name: str, *, item_type: type[StuffContentType]) -> StuffContentType:
"""Get stuff content as ListContent with items of type StuffContentType then return the first item."""
return self.get_stuff_as_list(name=name, item_type=item_type).items[0]
diff --git a/pipelex/core/memory/working_memory_factory.py b/pipelex/core/memory/working_memory_factory.py
index 0df4978b6..b09395d07 100644
--- a/pipelex/core/memory/working_memory_factory.py
+++ b/pipelex/core/memory/working_memory_factory.py
@@ -39,6 +39,7 @@ class WorkingMemoryFactory(BaseModel):
def make_from_multiple_stuffs(
cls,
stuff_list: list[Stuff],
+ *,
main_name: str | None = None,
is_ignore_unnamed: bool = False,
) -> WorkingMemory:
@@ -67,6 +68,7 @@ class WorkingMemoryFactory(BaseModel):
def make_from_pipeline_inputs(
cls,
pipeline_inputs: PipelineInputs,
+ *,
search_domain_codes: list[str] | None = None,
) -> WorkingMemory:
"""Create a WorkingMemory from a pipeline inputs dictionary.
@@ -145,7 +147,7 @@ class WorkingMemoryFactory(BaseModel):
return needed_inputs_for_factory
@classmethod
- def convert_stuff_spec_to_typed_named(cls, stuff_spec: StuffSpec, name: str) -> TypedNamedStuffSpec:
+ def convert_stuff_spec_to_typed_named(cls, stuff_spec: StuffSpec, *, name: str) -> TypedNamedStuffSpec:
"""Resolve a single output `StuffSpec` to a `TypedNamedStuffSpec`.
Mirrors the class-registry lookup behavior of ``convert_to_working_memory_format``:
diff --git a/pipelex/core/pipes/handle_pipe_errors.py b/pipelex/core/pipes/handle_pipe_errors.py
index 6c67969f2..2e88935b8 100644
--- a/pipelex/core/pipes/handle_pipe_errors.py
+++ b/pipelex/core/pipes/handle_pipe_errors.py
@@ -118,6 +118,7 @@ def categorize_pipe_validation_error(
def _handle_pipe_errors(
error: ErrorDetails,
+ *,
pipe_code: str | None,
) -> PipesAndConceptValidationErrorData:
"""Handle all PIPE validation errors.
diff --git a/pipelex/core/pipes/inputs/input_renderer.py b/pipelex/core/pipes/inputs/input_renderer.py
index 56a3c3f44..82c73dcec 100644
--- a/pipelex/core/pipes/inputs/input_renderer.py
+++ b/pipelex/core/pipes/inputs/input_renderer.py
@@ -2,7 +2,7 @@ from pipelex.core.pipes.inputs.exceptions import NoInputsRequiredError
from pipelex.core.pipes.pipe_abstract import PipeAbstract
-def render_inputs(the_pipe: PipeAbstract, indent: int = 2) -> str:
+def render_inputs(the_pipe: PipeAbstract, *, indent: int = 2) -> str:
"""Render a JSON representation of the pipe's inputs.
Args:
diff --git a/pipelex/core/pipes/inputs/input_stuff_specs.py b/pipelex/core/pipes/inputs/input_stuff_specs.py
index ee8d95257..cf01b8bbf 100644
--- a/pipelex/core/pipes/inputs/input_stuff_specs.py
+++ b/pipelex/core/pipes/inputs/input_stuff_specs.py
@@ -26,6 +26,7 @@ class TypedNamedStuffSpec(NamedStuffSpec):
def make_from_named(
cls,
named: NamedStuffSpec,
+ *,
structure_class: type[StuffContent],
) -> "TypedNamedStuffSpec":
return cls(**named.model_dump(), structure_class=structure_class)
@@ -80,7 +81,7 @@ class InputStuffSpecs(RootModel[PipeInputsRoot]):
def is_variable_existing(self, variable_name: str) -> bool:
return variable_name in self.root
- def add_stuff_spec(self, variable_name: str, concept: Concept, multiplicity: VariableMultiplicity | None = None):
+ def add_stuff_spec(self, variable_name: str, *, concept: Concept, multiplicity: VariableMultiplicity | None = None):
self.root[variable_name] = StuffSpec(concept=concept, multiplicity=multiplicity)
@property
diff --git a/pipelex/core/pipes/inputs/input_stuff_specs_factory.py b/pipelex/core/pipes/inputs/input_stuff_specs_factory.py
index a31b40f10..614f5ecd3 100644
--- a/pipelex/core/pipes/inputs/input_stuff_specs_factory.py
+++ b/pipelex/core/pipes/inputs/input_stuff_specs_factory.py
@@ -24,6 +24,7 @@ class InputStuffSpecsFactory:
@classmethod
def make_from_blueprint(
cls,
+ *,
domain_code: str,
blueprint: dict[str, str],
) -> InputStuffSpecs:
@@ -39,6 +40,7 @@ class InputStuffSpecsFactory:
@classmethod
def make_from_string(
cls,
+ *,
domain_code: str,
stuff_spec_str: str,
) -> StuffSpec:
diff --git a/pipelex/core/pipes/output/output_renderer.py b/pipelex/core/pipes/output/output_renderer.py
index 582a7c4fe..c02e20ca0 100644
--- a/pipelex/core/pipes/output/output_renderer.py
+++ b/pipelex/core/pipes/output/output_renderer.py
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
def _collect_possible_outputs(
the_pipe: PipeAbstract,
+ *,
output_format: ConceptRepresentationFormat = ConceptRepresentationFormat.JSON,
) -> list[dict[str, Any]]:
"""Collect all possible outputs for a pipe with native.Anything output.
@@ -84,7 +85,7 @@ def _collect_possible_outputs(
# If last pipe also has Anything output, recurse
if last_pipe.output.concept.code == NativeConceptCode.ANYTHING:
- return _collect_possible_outputs(last_pipe, output_format)
+ return _collect_possible_outputs(last_pipe, output_format=output_format)
# Otherwise render the last pipe's output
try:
@@ -117,6 +118,7 @@ def _collect_possible_outputs(
def render_output(
the_pipe: PipeAbstract,
+ *,
indent: int = 2,
output_format: ConceptRepresentationFormat = ConceptRepresentationFormat.JSON,
) -> str:
@@ -142,14 +144,14 @@ def render_output(
# Handle each format type
match output_format:
case ConceptRepresentationFormat.SCHEMA:
- return _render_schema_output(the_pipe, indent)
+ return _render_schema_output(the_pipe, indent=indent)
case ConceptRepresentationFormat.PYTHON:
return _render_python_output(the_pipe)
case ConceptRepresentationFormat.JSON:
- return _render_json_output(the_pipe, indent)
+ return _render_json_output(the_pipe, indent=indent)
-def _render_json_output(the_pipe: PipeAbstract, indent: int = 2) -> str:
+def _render_json_output(the_pipe: PipeAbstract, *, indent: int = 2) -> str:
"""Render JSON representation of the pipe's output.
Args:
@@ -164,7 +166,7 @@ def _render_json_output(the_pipe: PipeAbstract, indent: int = 2) -> str:
"""
# Check if output is native.Anything (has no specific shape)
if the_pipe.output.concept.code == NativeConceptCode.ANYTHING:
- possible_outputs = _collect_possible_outputs(the_pipe, ConceptRepresentationFormat.JSON)
+ possible_outputs = _collect_possible_outputs(the_pipe, output_format=ConceptRepresentationFormat.JSON)
if not possible_outputs:
msg = f"Output is '{NativeConceptCode.ANYTHING.concept_ref}' which has no specific shape and no possible outputs could be determined."
@@ -200,7 +202,7 @@ def _render_python_output(the_pipe: PipeAbstract) -> str:
"""
# Check if output is native.Anything (has no specific shape)
if the_pipe.output.concept.code == NativeConceptCode.ANYTHING:
- possible_outputs = _collect_possible_outputs(the_pipe, ConceptRepresentationFormat.PYTHON)
+ possible_outputs = _collect_possible_outputs(the_pipe, output_format=ConceptRepresentationFormat.PYTHON)
if not possible_outputs:
msg = f"Output is '{NativeConceptCode.ANYTHING.concept_ref}' which has no specific shape and no possible outputs could be determined."
@@ -235,7 +237,7 @@ def _render_python_output(the_pipe: PipeAbstract) -> str:
return "\n".join(lines)
-def _render_schema_output(the_pipe: PipeAbstract, indent: int = 2) -> str:
+def _render_schema_output(the_pipe: PipeAbstract, *, indent: int = 2) -> str:
"""Render JSON Schema for the pipe's output.
Args:
@@ -250,7 +252,7 @@ def _render_schema_output(the_pipe: PipeAbstract, indent: int = 2) -> str:
"""
# Check if output is native.Anything (has no specific shape)
if the_pipe.output.concept.code == NativeConceptCode.ANYTHING:
- possible_outputs = _collect_possible_outputs(the_pipe, ConceptRepresentationFormat.SCHEMA)
+ possible_outputs = _collect_possible_outputs(the_pipe, output_format=ConceptRepresentationFormat.SCHEMA)
if not possible_outputs:
msg = f"Output is '{NativeConceptCode.ANYTHING.concept_ref}' which has no specific shape and no possible outputs could be determined."
diff --git a/pipelex/core/pipes/pipe_abstract.py b/pipelex/core/pipes/pipe_abstract.py
index 359ecc4cc..d36d4e687 100644
--- a/pipelex/core/pipes/pipe_abstract.py
+++ b/pipelex/core/pipes/pipe_abstract.py
@@ -100,7 +100,7 @@ class PipeAbstract(ABC, BaseModel):
return unique_concepts
- def _register_execution_data(self, job_metadata: JobMetadata, execution_data: dict[str, Any]) -> None:
+ def _register_execution_data(self, job_metadata: JobMetadata, *, execution_data: dict[str, Any]) -> None:
"""Register execution metadata with the graph tracer.
Called by pipe subclasses during execution to capture runtime-resolved data
@@ -212,7 +212,7 @@ class PipeAbstract(ABC, BaseModel):
# First validate required variables are in the inputs (using prefix-based matching)
input_names = set(self.inputs.variables)
for required_variable_path in self.required_variables():
- if not is_variable_satisfied_by_inputs(required_variable_path, input_names):
+ if not is_variable_satisfied_by_inputs(required_variable_path, input_names=input_names):
msg = (
f"Required variable '{required_variable_path}' is not in the inputs of pipe '{self.code}'. "
f"Current inputs: {self.inputs.format_for_display()}"
@@ -316,6 +316,7 @@ class PipeAbstract(ABC, BaseModel):
async def validate_before_run(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -368,6 +369,7 @@ class PipeAbstract(ABC, BaseModel):
async def _validate_before_run(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -378,6 +380,7 @@ class PipeAbstract(ABC, BaseModel):
async def validate_after_run(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -390,6 +393,7 @@ class PipeAbstract(ABC, BaseModel):
async def _validate_after_run(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -437,6 +441,7 @@ class PipeAbstract(ABC, BaseModel):
async def run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -462,6 +467,7 @@ class PipeAbstract(ABC, BaseModel):
async def _run_pipe_traced(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -624,6 +630,7 @@ class PipeAbstract(ABC, BaseModel):
async def live_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -696,6 +703,7 @@ class PipeAbstract(ABC, BaseModel):
async def dry_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -715,6 +723,7 @@ class PipeAbstract(ABC, BaseModel):
async def _live_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -726,6 +735,7 @@ class PipeAbstract(ABC, BaseModel):
async def _dry_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -736,6 +746,7 @@ class PipeAbstract(ABC, BaseModel):
def _start_pipe_span(
self,
parent_otel_context: OtelContext,
+ *,
pipeline_run_id: str,
working_memory: WorkingMemory,
) -> tuple[Span | None, bool]:
@@ -848,7 +859,7 @@ class PipeAbstract(ABC, BaseModel):
return span, is_root_span
- def _end_pipe_span_success(self, span: Span | None, pipe_output: PipeOutput, is_root_span: bool) -> None:
+ def _end_pipe_span_success(self, span: Span | None, *, pipe_output: PipeOutput, is_root_span: bool) -> None:
"""End the pipe's OTel span with success status. Safe to call if span is None.
Args:
@@ -882,7 +893,7 @@ class PipeAbstract(ABC, BaseModel):
span.set_attribute(LangfuseSpanAttr.TRACE_OUTCOME, SpanOutcome.SUCCESS)
span.end()
- def _end_pipe_span_error(self, span: Span | None, error: Exception, is_root_span: bool = False) -> None:
+ def _end_pipe_span_error(self, span: Span | None, *, error: Exception, is_root_span: bool = False) -> None:
"""End the pipe's OTel span with error status. Safe to call if span is None.
Args:
diff --git a/pipelex/core/pipes/pipe_factory.py b/pipelex/core/pipes/pipe_factory.py
index 4e0a5c86f..28e9083dc 100644
--- a/pipelex/core/pipes/pipe_factory.py
+++ b/pipelex/core/pipes/pipe_factory.py
@@ -27,6 +27,7 @@ class PipeFactoryProtocol(Protocol[PipeBlueprintType, PipeAbstractType]):
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
@@ -39,12 +40,13 @@ class PipeFactoryProtocol(Protocol[PipeBlueprintType, PipeAbstractType]):
class PipeFactory(Generic[PipeAbstractType]):
@classmethod
- def make_pipe_ref_with_domain(cls, domain_code: str, pipe_code: str) -> str:
+ def make_pipe_ref_with_domain(cls, *, domain_code: str, pipe_code: str) -> str:
return f"{domain_code}.{pipe_code}"
@classmethod
def make_from_blueprint(
cls,
+ *,
domain_code: str,
pipe_code: str,
blueprint: PipeBlueprint,
diff --git a/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py b/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py
index 9cffae7f7..0e5f48a47 100644
--- a/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py
+++ b/pipelex/core/pipes/stuff_spec/stuff_spec_factory.py
@@ -11,6 +11,7 @@ class StuffSpecFactory:
@classmethod
def make_from_blueprint(
cls,
+ *,
domain_code: str,
output_string: str,
) -> StuffSpec:
diff --git a/pipelex/core/pipes/validation.py b/pipelex/core/pipes/validation.py
index 5790e2bf8..033fdc75d 100644
--- a/pipelex/core/pipes/validation.py
+++ b/pipelex/core/pipes/validation.py
@@ -1,7 +1,7 @@
from pipelex.tools.misc.string_utils import is_snake_case
-def is_variable_satisfied_by_inputs(variable_path: str, input_names: set[str]) -> bool:
+def is_variable_satisfied_by_inputs(variable_path: str, *, input_names: set[str]) -> bool:
"""Check if a variable path is satisfied by the declared inputs.
A variable path is satisfied if:
@@ -29,7 +29,7 @@ def is_variable_satisfied_by_inputs(variable_path: str, input_names: set[str]) -
return False
-def is_input_used_by_variables(input_name: str, variable_paths: set[str]) -> bool:
+def is_input_used_by_variables(input_name: str, *, variable_paths: set[str]) -> bool:
"""Check if an input is used by any of the variable paths.
An input is considered used if:
diff --git a/pipelex/core/pipes/variable_multiplicity.py b/pipelex/core/pipes/variable_multiplicity.py
index 3652fc889..7cf16d3e0 100644
--- a/pipelex/core/pipes/variable_multiplicity.py
+++ b/pipelex/core/pipes/variable_multiplicity.py
@@ -19,7 +19,7 @@ class VariableMultiplicityResolution(BaseModel):
specific_output_count: int | None = Field(default=None, description="Exact number of items to expect/generate, if specified")
-def make_variable_multiplicity(nb_items: int | None, multiple_items: bool | None) -> VariableMultiplicity | None:
+def make_variable_multiplicity(*, nb_items: int | None, multiple_items: bool | None) -> VariableMultiplicity | None:
"""This function takes two mutually exclusive parameters that control how many items a variable can have
and converts them into a single VariableMultiplicity type.
@@ -110,7 +110,7 @@ def parse_concept_with_multiplicity(concept_ref_or_code: str) -> MultiplicityPar
return MultiplicityParseResult(concept_ref_or_code=extracted_concept, multiplicity=multiplicity)
-def is_multiplicity_compatible(source_multiplicity: VariableMultiplicity | None, target_multiplicity: VariableMultiplicity | None) -> bool:
+def is_multiplicity_compatible(*, source_multiplicity: VariableMultiplicity | None, target_multiplicity: VariableMultiplicity | None) -> bool:
"""Check if a source multiplicity is compatible with a target multiplicity.
This is used to validate that a pipe's output multiplicity can fulfill a required output multiplicity.
@@ -131,19 +131,19 @@ def is_multiplicity_compatible(source_multiplicity: VariableMultiplicity | None,
True if source_multiplicity can fulfill target_multiplicity, False otherwise
Examples:
- >>> is_multiplicity_compatible(None, None)
+ >>> is_multiplicity_compatible(source_multiplicity=None, target_multiplicity=None)
True
- >>> is_multiplicity_compatible(True, True)
+ >>> is_multiplicity_compatible(source_multiplicity=True, target_multiplicity=True)
True
- >>> is_multiplicity_compatible(3, True) # Fixed count fulfills variable expectation
+ >>> is_multiplicity_compatible(source_multiplicity=3, target_multiplicity=True) # Fixed count fulfills variable expectation
True
- >>> is_multiplicity_compatible(True, 3) # Variable cannot fulfill fixed expectation
+ >>> is_multiplicity_compatible(source_multiplicity=True, target_multiplicity=3) # Variable cannot fulfill fixed expectation
False
- >>> is_multiplicity_compatible(3, 3)
+ >>> is_multiplicity_compatible(source_multiplicity=3, target_multiplicity=3)
True
- >>> is_multiplicity_compatible(3, 5) # Different fixed counts are incompatible
+ >>> is_multiplicity_compatible(source_multiplicity=3, target_multiplicity=5) # Different fixed counts are incompatible
False
- >>> is_multiplicity_compatible(None, True) # Single cannot fulfill list expectation
+ >>> is_multiplicity_compatible(source_multiplicity=None, target_multiplicity=True) # Single cannot fulfill list expectation
False
"""
# Case 1: Target expects single item (None)
@@ -167,7 +167,7 @@ def is_multiplicity_compatible(source_multiplicity: VariableMultiplicity | None,
return source_multiplicity == target_multiplicity
-def format_concept_with_multiplicity(concept_code_or_string: str, multiplicity: VariableMultiplicity | None) -> str:
+def format_concept_with_multiplicity(concept_code_or_string: str, *, multiplicity: VariableMultiplicity | None) -> str:
"""Format a concept code or string with multiplicity notation.
This is the reverse operation of parse_concept_with_multiplicity.
diff --git a/pipelex/core/qualified_ref.py b/pipelex/core/qualified_ref.py
index c219c9f88..bc0aaa469 100644
--- a/pipelex/core/qualified_ref.py
+++ b/pipelex/core/qualified_ref.py
@@ -133,7 +133,7 @@ class QualifiedRef(BaseModel):
return ref
@classmethod
- def from_domain_and_code(cls, domain_path: str, local_code: str) -> "QualifiedRef":
+ def from_domain_and_code(cls, domain_path: str, *, local_code: str) -> "QualifiedRef":
"""Build from already-known parts.
Args:
diff --git a/pipelex/core/stuffs/document_content.py b/pipelex/core/stuffs/document_content.py
index 0c786a861..90bd5ddd7 100644
--- a/pipelex/core/stuffs/document_content.py
+++ b/pipelex/core/stuffs/document_content.py
@@ -75,7 +75,7 @@ class DocumentContent(StuffContent):
)
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
display_text = self.title or self.public_url or self.url
result = f"[{display_text}]({self.public_url or self.url})"
if self.snippet:
@@ -83,7 +83,7 @@ class DocumentContent(StuffContent):
return result
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
source_text = Text()
if self.title:
source_text.append(self.title, style="bold")
diff --git a/pipelex/core/stuffs/dynamic_content.py b/pipelex/core/stuffs/dynamic_content.py
index b138398be..a72efcacd 100644
--- a/pipelex/core/stuffs/dynamic_content.py
+++ b/pipelex/core/stuffs/dynamic_content.py
@@ -14,5 +14,5 @@ class DynamicContent(StuffContent):
return str(self.smart_dump())
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return str(self.smart_dump())
diff --git a/pipelex/core/stuffs/html_content.py b/pipelex/core/stuffs/html_content.py
index fa968c5df..650d42cf0 100644
--- a/pipelex/core/stuffs/html_content.py
+++ b/pipelex/core/stuffs/html_content.py
@@ -37,7 +37,7 @@ class HtmlContent(StuffContent):
)
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return self.inner_html
@override
diff --git a/pipelex/core/stuffs/image_content.py b/pipelex/core/stuffs/image_content.py
index 87718863e..68e9c7c90 100644
--- a/pipelex/core/stuffs/image_content.py
+++ b/pipelex/core/stuffs/image_content.py
@@ -65,12 +65,13 @@ class ImageContent(StuffContent):
)
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return f"![{self.url[:100]}]({self.url})"
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat, # noqa: ARG002
) -> str:
"""Register this image and return a token."""
@@ -78,7 +79,7 @@ class ImageContent(StuffContent):
return f"[Image {image_index + 1}]"
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
group = Group()
# title indicating it's an image:
diff --git a/pipelex/core/stuffs/image_field_search.py b/pipelex/core/stuffs/image_field_search.py
index 1b93c914e..42c8d5a46 100644
--- a/pipelex/core/stuffs/image_field_search.py
+++ b/pipelex/core/stuffs/image_field_search.py
@@ -9,6 +9,7 @@ from pipelex.core.stuffs.stuff_content import StuffContent
def search_for_nested_image_fields(
content_class: type[StuffContent],
+ *,
current_path: str = "",
) -> list[str]:
"""Recursively search for image fields in a structure class.
diff --git a/pipelex/core/stuffs/json_content.py b/pipelex/core/stuffs/json_content.py
index 116931804..4829e88c3 100644
--- a/pipelex/core/stuffs/json_content.py
+++ b/pipelex/core/stuffs/json_content.py
@@ -38,7 +38,7 @@ class JSONContent(StuffContent):
return html
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return convert_to_markdown(data=self.json_obj, level=level, is_pretty=is_pretty)
@override
@@ -50,5 +50,5 @@ class JSONContent(StuffContent):
return json.dumps(self.json_obj, indent=4)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
return JSON.from_data(self.json_obj, indent=4)
diff --git a/pipelex/core/stuffs/list_content.py b/pipelex/core/stuffs/list_content.py
index 92aa414c9..159a1f1ff 100644
--- a/pipelex/core/stuffs/list_content.py
+++ b/pipelex/core/stuffs/list_content.py
@@ -105,7 +105,7 @@ class ListContent(StuffContent, Generic[StuffContentType]):
return self.rendered_markdown()
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
rendered = ""
if self._single_class_name == "TextContent":
for item in self.items:
@@ -126,7 +126,7 @@ class ListContent(StuffContent, Generic[StuffContentType]):
return await self.rendered_markdown_async()
@override
- async def rendered_markdown_async(self, level: int = 1, is_pretty: bool = False) -> str:
+ async def rendered_markdown_async(self, *, level: int = 1, is_pretty: bool = False) -> str:
rendered = ""
if self._single_class_name == "TextContent":
for item in self.items:
@@ -141,13 +141,14 @@ class ListContent(StuffContent, Generic[StuffContentType]):
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat,
) -> str:
"""Render each item with images."""
parts: list[str] = []
for item in self.items:
if isinstance(item, ImageRenderable): # pyright: ignore[reportUnnecessaryIsInstance]
- rendered = item.render_with_images(registry, text_format)
+ rendered = item.render_with_images(registry, text_format=text_format)
else:
rendered = item.rendered_markdown()
if rendered:
@@ -155,7 +156,7 @@ class ListContent(StuffContent, Generic[StuffContentType]):
return "\n".join(parts)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Check if we've exceeded maximum depth - fall back to Pretty rendering
# Pretty shows the Python object structure beautifully, just like when calling pretty_print(stuff)
if depth >= MAX_RENDER_DEPTH:
diff --git a/pipelex/core/stuffs/mermaid_content.py b/pipelex/core/stuffs/mermaid_content.py
index b2c888428..480b2db5d 100644
--- a/pipelex/core/stuffs/mermaid_content.py
+++ b/pipelex/core/stuffs/mermaid_content.py
@@ -32,7 +32,7 @@ class MermaidContent(StuffContent):
)
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return self.mermaid_code
@override
diff --git a/pipelex/core/stuffs/number_content.py b/pipelex/core/stuffs/number_content.py
index be9a13982..a9ed6f1e5 100644
--- a/pipelex/core/stuffs/number_content.py
+++ b/pipelex/core/stuffs/number_content.py
@@ -22,7 +22,7 @@ class NumberContent(StuffContent):
return str(self.number)
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return str(self.number)
@override
diff --git a/pipelex/core/stuffs/page_content.py b/pipelex/core/stuffs/page_content.py
index 3f3e41bf0..daa30e877 100644
--- a/pipelex/core/stuffs/page_content.py
+++ b/pipelex/core/stuffs/page_content.py
@@ -15,7 +15,7 @@ class PageContent(StructuredContent):
page_view: ImageContent | None = Field(default=None, description="The screenshot of the page")
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# If there's no page_view, just return the text_and_images rendering
if self.page_view is None:
return self.text_and_images.rendered_pretty(depth=depth)
diff --git a/pipelex/core/stuffs/search_result_content.py b/pipelex/core/stuffs/search_result_content.py
index 52d28e2ec..c304535e3 100644
--- a/pipelex/core/stuffs/search_result_content.py
+++ b/pipelex/core/stuffs/search_result_content.py
@@ -43,7 +43,7 @@ class SearchResultContent(StuffContent):
return result
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
result = self.answer
if self.sources:
result += "\n\n**Sources:**\n\n"
@@ -51,7 +51,7 @@ class SearchResultContent(StuffContent):
return result
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
group = Group()
# Title
diff --git a/pipelex/core/stuffs/structured_content.py b/pipelex/core/stuffs/structured_content.py
index 0e9b40d44..2087f867c 100644
--- a/pipelex/core/stuffs/structured_content.py
+++ b/pipelex/core/stuffs/structured_content.py
@@ -110,7 +110,7 @@ class StructuredContent(StuffContent):
return html_module.escape(str(value))
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
dict_dump = clean_model_to_dict(obj=self)
return convert_to_markdown(data=dict_dump, level=level, is_pretty=is_pretty)
@@ -121,6 +121,7 @@ class StructuredContent(StuffContent):
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat,
) -> str:
"""Render with image extraction - recursively handles nested structures.
@@ -141,7 +142,7 @@ class StructuredContent(StuffContent):
field_value = getattr(self, field_name)
if field_value is None:
continue
- rendered = self._render_value_with_images(field_value, registry, text_format)
+ rendered = self._render_value_with_images(field_value, registry=registry, text_format=text_format)
if rendered:
parts.append(f"{field_name}: {rendered}")
return "\n".join(parts)
@@ -149,6 +150,7 @@ class StructuredContent(StuffContent):
def _render_value_with_images(
self,
value: Any,
+ *,
registry: ImageRegistry,
text_format: TextFormat,
) -> str:
@@ -165,12 +167,12 @@ class StructuredContent(StuffContent):
if value is None:
return ""
if isinstance(value, ImageRenderable):
- return value.render_with_images(registry, text_format)
+ return value.render_with_images(registry, text_format=text_format)
if isinstance(value, (list, tuple)):
parts: list[str] = []
list_value = cast("list[Any]", value)
for item in list_value:
- rendered = self._render_value_with_images(item, registry, text_format)
+ rendered = self._render_value_with_images(item, registry=registry, text_format=text_format)
if rendered:
parts.append(rendered)
return "\n".join(parts)
@@ -178,7 +180,7 @@ class StructuredContent(StuffContent):
dict_parts: list[str] = []
dict_value = cast("dict[str, Any]", value)
for key, val in dict_value.items():
- rendered = self._render_value_with_images(val, registry, text_format)
+ rendered = self._render_value_with_images(val, registry=registry, text_format=text_format)
if rendered:
dict_parts.append(f"{key}: {rendered}")
return "\n".join(dict_parts)
@@ -191,7 +193,7 @@ class StructuredContent(StuffContent):
# -------------------------------------------------------------------------
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# Check if we've exceeded maximum depth - fall back to Pretty rendering
# Pretty shows the Python object structure beautifully, just like when calling pretty_print(stuff)
if depth >= MAX_RENDER_DEPTH:
diff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.py
index 7691c17ae..769a5e4e7 100644
--- a/pipelex/core/stuffs/stuff.py
+++ b/pipelex/core/stuffs/stuff.py
@@ -94,10 +94,10 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffConte
def content_as(self, content_type: type[StuffContentType]) -> StuffContentType:
"""Get content with proper typing if it's of the expected type."""
- return self.verify_content_type(self.content, content_type)
+ return self.verify_content_type(self.content, content_type=content_type)
@classmethod
- def verify_content_type(cls, content: StuffContent, content_type: type[StuffContentType]) -> StuffContentType:
+ def verify_content_type(cls, content: StuffContent, *, content_type: type[StuffContentType]) -> StuffContentType:
"""Verify and convert content to the expected type."""
# First try the direct isinstance check for performance
if isinstance(content, content_type):
@@ -184,7 +184,7 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffConte
converted_items: list[StuffContentType] = []
for item in list_content.items:
- converted_item = self.verify_content_type(item, item_type)
+ converted_item = self.verify_content_type(item, content_type=item_type)
converted_items.append(converted_item)
return ListContent[StuffContentType](items=converted_items)
@@ -230,7 +230,7 @@ class Stuff(PrettyRenderable, CustomBaseModel, StuffAbstract[Concept, StuffConte
return self.content_as(MermaidContent)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
"""Render stuff for pretty printing.
Args:
diff --git a/pipelex/core/stuffs/stuff_artefact.py b/pipelex/core/stuffs/stuff_artefact.py
index 853cfb544..405636bee 100644
--- a/pipelex/core/stuffs/stuff_artefact.py
+++ b/pipelex/core/stuffs/stuff_artefact.py
@@ -192,7 +192,7 @@ class StuffArtefact:
msg = f"'{content_type}' content does not support indexing."
raise TypeError(msg)
- def get(self, key: str, default: Any = None) -> Any:
+ def get(self, key: str, *, default: Any = None) -> Any:
"""Dict-like get method.
Args:
@@ -350,6 +350,7 @@ class StuffArtefact:
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat,
) -> str:
"""Delegate to content's render_with_images.
@@ -372,7 +373,7 @@ class StuffArtefact:
f"ImageContent, TextAndImagesContent, ListContent, StructuredContent (and subclasses like PageContent)."
)
raise TypeError(msg)
- return content.render_with_images(registry, text_format)
+ return content.render_with_images(registry, text_format=text_format)
# -------------------------------------------------------------------------
# Access to underlying Stuff
diff --git a/pipelex/core/stuffs/stuff_content.py b/pipelex/core/stuffs/stuff_content.py
index 7640fe0dd..228a799a6 100644
--- a/pipelex/core/stuffs/stuff_content.py
+++ b/pipelex/core/stuffs/stuff_content.py
@@ -61,7 +61,7 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
"""
return f"<pre>{self.rendered_json()}</pre>"
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str: # noqa: ARG002
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str: # noqa: ARG002
"""Render content as Markdown for documentation or LLM prompts.
Defaults to JSON in a code block. Override in subclasses for custom Markdown output.
@@ -110,7 +110,7 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
"""Default HTML rendering - subclasses can override for custom rendering."""
return self.rendered_html()
- async def rendered_markdown_async(self, level: int = 1, is_pretty: bool = False) -> str:
+ async def rendered_markdown_async(self, *, level: int = 1, is_pretty: bool = False) -> str:
"""Default Markdown rendering - subclasses can override for custom rendering."""
return self.rendered_markdown(level=level, is_pretty=is_pretty)
@@ -122,7 +122,7 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
# -------------------------------------------------------------------------
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
"""Render content for pretty printing.
Args:
@@ -138,5 +138,5 @@ class StuffContent(PrettyRenderable, CustomBaseModel, StuffContentAbstract):
pretty_print(pretty, title=title, width=width)
@override
- def rendered_pretty_html(self, title: str | None = None, width: int | None = None) -> str:
+ def rendered_pretty_html(self, *, title: str | None = None, width: int | None = None) -> str:
return self.rendered_html()
diff --git a/pipelex/core/stuffs/stuff_content_factory.py b/pipelex/core/stuffs/stuff_content_factory.py
index 979bc9240..c7514976d 100644
--- a/pipelex/core/stuffs/stuff_content_factory.py
+++ b/pipelex/core/stuffs/stuff_content_factory.py
@@ -9,13 +9,13 @@ from pipelex.hub import get_class_registry
class StuffContentFactory:
@classmethod
- def make_content_from_value(cls, stuff_content_subclass: type[StuffContent], value: dict[str, Any] | str) -> StuffContent:
+ def make_content_from_value(cls, stuff_content_subclass: type[StuffContent], *, value: dict[str, Any] | str) -> StuffContent:
if isinstance(value, str) and stuff_content_subclass == TextContent:
return TextContent(text=value)
return stuff_content_subclass.model_validate(obj=value)
@classmethod
- def make_stuff_content_from_concept_required(cls, concept: Concept, value: dict[str, Any] | str) -> StuffContent:
+ def make_stuff_content_from_concept_required(cls, concept: Concept, *, value: dict[str, Any] | str) -> StuffContent:
"""Create StuffContent from concept code, requiring the concept to be linked to a class in the registry.
Raises StuffContentFactoryError if no registry class is found.
"""
@@ -24,7 +24,7 @@ class StuffContentFactory:
return cls.make_content_from_value(stuff_content_subclass=the_subclass, value=value)
@classmethod
- def make_stuff_content_from_concept_with_fallback(cls, concept: Concept, value: dict[str, Any] | str) -> StuffContent:
+ def make_stuff_content_from_concept_with_fallback(cls, concept: Concept, *, value: dict[str, Any] | str) -> StuffContent:
"""Create StuffContent from concept code, falling back to TextContent if no registry class is found."""
the_structure_class = get_class_registry().get_class(name=concept.structure_class_name)
diff --git a/pipelex/core/stuffs/stuff_factory.py b/pipelex/core/stuffs/stuff_factory.py
index bd5b19fdf..923dbc7ba 100644
--- a/pipelex/core/stuffs/stuff_factory.py
+++ b/pipelex/core/stuffs/stuff_factory.py
@@ -48,7 +48,7 @@ class StuffFactory:
return Stuff.make_stuff_name(concept=concept)
@classmethod
- def make_from_str(cls, str_value: str, name: str) -> Stuff:
+ def make_from_str(cls, str_value: str, *, name: str) -> Stuff:
return cls.make_stuff(
concept=ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT),
content=TextContent(text=str_value),
@@ -56,7 +56,7 @@ class StuffFactory:
)
@classmethod
- def make_from_concept_ref(cls, concept_ref: str, name: str, content: StuffContent) -> Stuff:
+ def make_from_concept_ref(cls, concept_ref: str, *, name: str, content: StuffContent) -> Stuff:
validate_concept_ref(concept_ref)
concept = get_required_concept(concept_ref=concept_ref)
return cls.make_stuff(
@@ -69,6 +69,7 @@ class StuffFactory:
def make_stuff(
cls,
concept: Concept,
+ *,
content: StuffContent,
name: str | None = None,
code: str | None = None,
@@ -113,8 +114,9 @@ class StuffFactory:
@classmethod
def combine_stuffs(
cls,
- concept: Concept,
stuff_contents: dict[str, StuffContent],
+ *,
+ concept: Concept,
name: str | None = None,
) -> Stuff:
"""Combine a dictionary of stuffs into a single stuff."""
@@ -134,6 +136,7 @@ class StuffFactory:
def _try_make_csv_list_stuff(
cls,
concept: Concept,
+ *,
content: dict[str, Any],
name: str | None,
code: str | None,
@@ -217,13 +220,14 @@ class StuffFactory:
# caller-fixable input problem, not a raw ValueError that escapes into core/runner.
msg = f"CSV input for stuff '{name}': concept '{concept.concept_ref}' has no registered structure class to read CSV rows into."
raise CsvError(msg) from exc
- list_content = list_content_from_csv(Path(resolved.path), row_model)
+ list_content = list_content_from_csv(Path(resolved.path), row_model=row_model)
return cls.make_stuff(concept=concept, content=list_content, name=name, code=code)
@classmethod
def make_stuff_from_stuff_content_or_data(
cls,
stuff_content_or_data: StuffContentOrData,
+ *,
name: str | None = None,
code: str | None = None,
search_domain_codes: list[str] | None = None,
diff --git a/pipelex/core/stuffs/stuff_viewer.py b/pipelex/core/stuffs/stuff_viewer.py
index 59a33ad38..d8898365c 100644
--- a/pipelex/core/stuffs/stuff_viewer.py
+++ b/pipelex/core/stuffs/stuff_viewer.py
@@ -71,10 +71,10 @@ async def render_stuff_viewer(
async def render_stuff_content_viewer(
stuff_data: str | dict[str, Any] | list[str] | list[dict[str, Any]],
+ *,
stuff_data_text: str,
stuff_data_html: str,
content_type: str | None = None,
- *,
title: str = "Stuff Content",
subtitle: str | None = None,
) -> str:
diff --git a/pipelex/core/stuffs/text_and_images_content.py b/pipelex/core/stuffs/text_and_images_content.py
index 83fecdeff..959e57e57 100644
--- a/pipelex/core/stuffs/text_and_images_content.py
+++ b/pipelex/core/stuffs/text_and_images_content.py
@@ -36,7 +36,7 @@ class TextAndImagesContent(StuffContent):
return ""
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
if self.text:
return self.text.rendered_markdown(level=level, is_pretty=is_pretty)
return ""
@@ -55,7 +55,7 @@ class TextAndImagesContent(StuffContent):
# -------------------------------------------------------------------------------------
@override
- async def rendered_markdown_async(self, level: int = 1, is_pretty: bool = False) -> str:
+ async def rendered_markdown_async(self, *, level: int = 1, is_pretty: bool = False) -> str:
if self.text:
rendered = await self.text.rendered_markdown_async(level=level, is_pretty=is_pretty)
else:
@@ -76,6 +76,7 @@ class TextAndImagesContent(StuffContent):
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat,
) -> str:
"""Render text, then register images."""
@@ -89,7 +90,7 @@ class TextAndImagesContent(StuffContent):
return "\n".join(parts)
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
# If neither text nor images are present
if not self.text and not self.images:
return Text("(empty)", style="dim italic")
diff --git a/pipelex/core/stuffs/text_content.py b/pipelex/core/stuffs/text_content.py
index 4412636c4..014771cd4 100644
--- a/pipelex/core/stuffs/text_content.py
+++ b/pipelex/core/stuffs/text_content.py
@@ -31,7 +31,7 @@ class TextContent(StuffContent):
return html.escape(self.text)
@override
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:
return self.text
@override
@@ -43,7 +43,7 @@ class TextContent(StuffContent):
return bool(HTML_PATTERN.match(self.text))
@override
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
if self._looks_like_html():
return Syntax(self.text, "html", word_wrap=True)
return Markdown(self.text)
diff --git a/pipelex/core/validation.py b/pipelex/core/validation.py
index ead9fe43b..6da2690e3 100644
--- a/pipelex/core/validation.py
+++ b/pipelex/core/validation.py
@@ -5,7 +5,7 @@ from pipelex.system.configuration.configs import MigrationConfig, PipelexConfig
from pipelex.tools.typing.pydantic_utils import analyze_pydantic_validation_error
-def report_validation_error(category: str, validation_error: ValidationError) -> str:
+def report_validation_error(*, category: str, validation_error: ValidationError) -> str:
validation_error_analysis = analyze_pydantic_validation_error(validation_error)
# Doctor calls this from inside its bootstrap, where setup_config may have raised
diff --git a/pipelex/errors/error_pages_generator.py b/pipelex/errors/error_pages_generator.py
index 6393fd687..db4a2b232 100644
--- a/pipelex/errors/error_pages_generator.py
+++ b/pipelex/errors/error_pages_generator.py
@@ -252,6 +252,7 @@ def render_error_page(cls: type[PipelexError]) -> str:
def generate_error_pages(
output_dir: Path,
+ *,
classes: Iterable[type[PipelexError]] | None = None,
) -> ErrorPagesReport:
"""Write one markdown page per :class:`PipelexError` subclass into ``output_dir``.
@@ -307,7 +308,7 @@ def generate_error_pages(
expected_stems: set[str] = {page_slug(cls) for cls in target_classes} | {INDEX_STEM}
for cls in target_classes:
target = output_dir / f"{page_slug(cls)}.md"
- _commit_page(target, render_error_page(cls), report)
+ _commit_page(target, new_content=render_error_page(cls), report=report)
# Macro listing pages — one per non-empty macro area. Their stems join
# ``expected_stems`` so a macro that still has classes is never treated as an
@@ -315,21 +316,21 @@ def generate_error_pages(
# falls through to ``_remove_orphans`` and is deleted like any stale page.
by_subsystem = _group_by_subsystem(target_classes)
for macro_slug, macro_heading in _MACRO_SECTIONS:
- sections = _subsystems_for_macro(macro_slug, by_subsystem)
+ sections = _subsystems_for_macro(macro_slug, by_subsystem=by_subsystem)
if not sections:
continue
- _commit_page(output_dir / f"{macro_slug}.md", render_macro_page(macro_heading, sections), report)
+ _commit_page(output_dir / f"{macro_slug}.md", new_content=render_macro_page(macro_heading, sections=sections), report=report)
expected_stems.add(macro_slug)
index_target = output_dir / f"{INDEX_STEM}.md"
- _commit_page(index_target, render_index_page(by_subsystem), report)
+ _commit_page(index_target, new_content=render_index_page(by_subsystem), report=report)
_remove_orphans(output_dir=output_dir, expected_stems=expected_stems, report=report)
return report
-def _remove_orphans(output_dir: Path, expected_stems: set[str], report: ErrorPagesReport) -> None:
+def _remove_orphans(output_dir: Path, *, expected_stems: set[str], report: ErrorPagesReport) -> None:
"""Delete generated ``.md`` files whose stem is not in ``expected_stems``.
Files carrying :data:`AUTHORED_MARKER` are preserved verbatim — those
@@ -351,7 +352,7 @@ def _remove_orphans(output_dir: Path, expected_stems: set[str], report: ErrorPag
report.removed.append(path)
-def _commit_page(target: Path, new_content: str, report: ErrorPagesReport) -> None:
+def _commit_page(target: Path, *, new_content: str, report: ErrorPagesReport) -> None:
"""Apply the write / unchanged / preserved classification to one target path."""
if target.exists():
existing = target.read_text(encoding="utf-8")
@@ -446,6 +447,7 @@ def _group_by_subsystem(classes: Iterable[type[PipelexError]]) -> dict[str, list
def _subsystems_for_macro(
macro_slug: str,
+ *,
by_subsystem: dict[str, list[type[PipelexError]]],
) -> list[tuple[str, list[type[PipelexError]]]]:
"""Return the ``(heading, classes)`` subsystem sections that belong on a macro page.
@@ -468,7 +470,7 @@ def _subsystems_for_macro(
return sections
-def render_macro_page(macro_heading: str, sections: list[tuple[str, list[type[PipelexError]]]]) -> str:
+def render_macro_page(macro_heading: str, *, sections: list[tuple[str, list[type[PipelexError]]]]) -> str:
"""Render one macro listing page: a ``## subsystem`` block per section, class links beneath.
``sections`` is the output of :func:`_subsystems_for_macro` — already ordered
@@ -529,7 +531,7 @@ def render_index_page(by_subsystem: dict[str, list[type[PipelexError]]]) -> str:
"",
]
for macro_slug, macro_heading in _MACRO_SECTIONS:
- sections = _subsystems_for_macro(macro_slug, by_subsystem)
+ sections = _subsystems_for_macro(macro_slug, by_subsystem=by_subsystem)
if not sections:
continue
covered = ", ".join(heading for heading, _ in sections)
diff --git a/pipelex/graph/graph_factory.py b/pipelex/graph/graph_factory.py
index 9fd8228d9..06e74d4c4 100644
--- a/pipelex/graph/graph_factory.py
+++ b/pipelex/graph/graph_factory.py
@@ -44,8 +44,8 @@ class GraphOutputs(BaseModel):
async def generate_graph_outputs(
graph_spec: GraphSpec,
- graph_config: GraphConfig,
*,
+ graph_config: GraphConfig,
pipe_code: str = "",
title: str | None = None,
direction: FlowchartDirection | None = None,
@@ -93,7 +93,7 @@ async def generate_graph_outputs(
# Generate mermaidflow view
if inclusion.mermaidflow_mmd or inclusion.mermaidflow_html:
mermaidflow = MermaidflowFactory.make_from_graphspec(
- graph_spec, graph_config, direction=effective_direction, include_subgraphs=include_subgraphs
+ graph_spec, graph_config=graph_config, direction=effective_direction, include_subgraphs=include_subgraphs
)
if inclusion.mermaidflow_mmd:
mermaidflow_mmd = mermaidflow.mermaid_code
@@ -120,7 +120,7 @@ async def generate_graph_outputs(
effective_rf_config = effective_rf_config.model_copy(update={"layout_direction": direction})
reactflow_html = await generate_reactflow_html_async(
graph_spec,
- effective_rf_config,
+ config=effective_rf_config,
title=page_title,
)
@@ -134,6 +134,7 @@ async def generate_graph_outputs(
def save_graph_outputs_to_dir(
graph_outputs: GraphOutputs,
+ *,
output_dir: Path,
) -> dict[str, Path]:
"""Save graph outputs to a directory.
diff --git a/pipelex/graph/graph_rendering.py b/pipelex/graph/graph_rendering.py
index 80e25f047..adb4dfb6c 100644
--- a/pipelex/graph/graph_rendering.py
+++ b/pipelex/graph/graph_rendering.py
@@ -39,11 +39,11 @@ class GraphFormat(StrEnum):
async def render_graph_from_spec(
graph_spec: GraphSpec,
+ *,
graph_config: GraphConfig,
include_mermaidflow: bool,
include_reactflow: bool,
output_dir: Path,
- *,
pipe_code: str = "",
title: str | None = None,
direction: FlowchartDirection | None = None,
@@ -102,6 +102,7 @@ async def render_graph_from_spec(
async def _dry_run_bundle(
bundle_path: Path,
+ *,
library_dirs: list[str] | None = None,
) -> tuple[GraphSpec, str]:
"""Dry-run a bundle file to produce a GraphSpec.
@@ -138,6 +139,7 @@ async def _dry_run_bundle(
async def generate_graph_for_bundle(
bundle_path: Path,
+ *,
graph_format: GraphFormat,
library_dirs: list[str] | None = None,
direction: FlowchartDirection | None = None,
@@ -163,7 +165,7 @@ async def generate_graph_for_bundle(
PipelexError: If pipeline execution does not produce a graph spec.
PipelineExecutionError: If dry-run execution fails.
"""
- graph_spec, pipe_code = await _dry_run_bundle(bundle_path, library_dirs)
+ graph_spec, pipe_code = await _dry_run_bundle(bundle_path, library_dirs=library_dirs)
execution_config = get_config().pipelex.pipeline_execution_config.with_execution_overrides(
generate_graph=True,
@@ -212,6 +214,7 @@ async def generate_graph_for_bundle(
async def generate_view_for_bundle(
bundle_path: Path,
+ *,
library_dirs: list[str] | None = None,
direction: FlowchartDirection | None = None,
) -> dict[str, Any]:
@@ -233,7 +236,7 @@ async def generate_view_for_bundle(
PipelexError: If pipeline execution does not produce a graph spec.
PipelineExecutionError: If dry-run execution fails.
"""
- graph_spec, pipe_code = await _dry_run_bundle(bundle_path, library_dirs)
+ graph_spec, pipe_code = await _dry_run_bundle(bundle_path, library_dirs=library_dirs)
execution_config = get_config().pipelex.pipeline_execution_config.with_execution_overrides(
generate_graph=True,
diff --git a/pipelex/graph/graph_tracer.py b/pipelex/graph/graph_tracer.py
index 8602770a0..c9eaee1d1 100644
--- a/pipelex/graph/graph_tracer.py
+++ b/pipelex/graph/graph_tracer.py
@@ -214,6 +214,7 @@ class GraphTracer(GraphTracerProtocol):
def setup(
self,
graph_id: str,
+ *,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -464,6 +465,7 @@ class GraphTracer(GraphTracerProtocol):
def register_batch_item_extraction(
self,
list_stuff_code: str,
+ *,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -507,6 +509,7 @@ class GraphTracer(GraphTracerProtocol):
def register_batch_aggregation(
self,
output_list_stuff_code: str,
+ *,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -550,6 +553,7 @@ class GraphTracer(GraphTracerProtocol):
def register_parallel_combine(
self,
combined_stuff_code: str,
+ *,
branch_stuff_codes: list[str],
parallel_controller_node_id: str,
) -> None:
@@ -592,6 +596,7 @@ class GraphTracer(GraphTracerProtocol):
def on_pipe_start(
self,
trace_context: TraceContext,
+ *,
pipe_code: str,
pipe_type: str,
node_kind: NodeKind,
@@ -606,7 +611,7 @@ class GraphTracer(GraphTracerProtocol):
if not self._is_active:
# Return dummy values when not active
node_id = trace_context.make_node_id()
- child_context = trace_context.copy_for_child(node_id, trace_context.node_sequence + 1)
+ child_context = trace_context.copy_for_child(node_id, next_sequence=trace_context.node_sequence + 1)
return node_id, child_context
# Generate node ID (includes workflow_id in Temporal mode)
@@ -680,6 +685,7 @@ class GraphTracer(GraphTracerProtocol):
def register_execution_data(
self,
node_id: str,
+ *,
execution_data: dict[str, Any],
) -> None:
"""Register execution metadata for a node."""
@@ -708,6 +714,7 @@ class GraphTracer(GraphTracerProtocol):
def on_pipe_end_success(
self,
node_id: str,
+ *,
ended_at: datetime,
output_preview: str | None = None,
metrics: dict[str, float] | None = None,
@@ -770,6 +777,7 @@ class GraphTracer(GraphTracerProtocol):
def register_controller_output(
self,
node_id: str,
+ *,
output_spec: IOSpec,
) -> None:
"""Register an additional output for a controller node.
@@ -811,6 +819,7 @@ class GraphTracer(GraphTracerProtocol):
def on_pipe_end_error(
self,
node_id: str,
+ *,
ended_at: datetime,
error_type: str,
error_message: str,
@@ -851,6 +860,7 @@ class GraphTracer(GraphTracerProtocol):
@override
def add_edge(
self,
+ *,
source_node_id: str,
target_node_id: str,
edge_kind: EdgeKind,
@@ -897,6 +907,7 @@ class GraphTracer(GraphTracerProtocol):
def add_selected_outcome_edge(
self,
condition_node_id: str,
+ *,
outcome_node_id: str,
outcome_value: str,
) -> None:
diff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.py
index df25ae27f..1b45d88ce 100644
--- a/pipelex/graph/graph_tracer_manager.py
+++ b/pipelex/graph/graph_tracer_manager.py
@@ -94,6 +94,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def open_tracer(
self,
graph_id: str,
+ *,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -217,6 +218,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def on_pipe_start(
self,
trace_context: TraceContext,
+ *,
pipe_code: str,
pipe_type: str,
node_kind: NodeKind,
@@ -263,6 +265,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def on_pipe_end_success(
self,
+ *,
lookup_key: str,
node_id: str | None,
ended_at: datetime,
@@ -300,6 +303,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def register_execution_data(
self,
+ *,
lookup_key: str,
node_id: str | None,
execution_data: dict[str, Any],
@@ -320,6 +324,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def on_pipe_end_error(
self,
+ *,
lookup_key: str,
node_id: str | None,
ended_at: datetime,
@@ -354,6 +359,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def add_edge(
self,
+ *,
lookup_key: str,
source_node_id: str,
target_node_id: str,
@@ -382,6 +388,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def register_controller_output(
self,
+ *,
lookup_key: str,
node_id: str,
output_spec: IOSpec,
@@ -403,6 +410,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def register_batch_item_extraction(
self,
+ *,
lookup_key: str,
list_stuff_code: str,
item_stuff_code: str,
@@ -431,6 +439,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def register_batch_aggregation(
self,
+ *,
lookup_key: str,
output_list_stuff_code: str,
item_stuff_code: str,
@@ -459,6 +468,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
def register_parallel_combine(
self,
+ *,
lookup_key: str,
combined_stuff_code: str,
branch_stuff_codes: list[str],
diff --git a/pipelex/graph/graph_tracer_protocol.py b/pipelex/graph/graph_tracer_protocol.py
index ebdbf80e2..0b754bd1c 100644
--- a/pipelex/graph/graph_tracer_protocol.py
+++ b/pipelex/graph/graph_tracer_protocol.py
@@ -19,6 +19,7 @@ class GraphTracerProtocol(Protocol):
def setup(
self,
graph_id: str,
+ *,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -59,6 +60,7 @@ class GraphTracerProtocol(Protocol):
def on_pipe_start(
self,
trace_context: TraceContext,
+ *,
pipe_code: str,
pipe_type: str,
node_kind: NodeKind,
@@ -91,6 +93,7 @@ class GraphTracerProtocol(Protocol):
def on_pipe_end_success(
self,
node_id: str,
+ *,
ended_at: datetime,
output_preview: str | None = None,
metrics: dict[str, float] | None = None,
@@ -112,6 +115,7 @@ class GraphTracerProtocol(Protocol):
def on_pipe_end_error(
self,
node_id: str,
+ *,
ended_at: datetime,
error_type: str,
error_message: str,
@@ -130,6 +134,7 @@ class GraphTracerProtocol(Protocol):
def add_edge(
self,
+ *,
source_node_id: str,
target_node_id: str,
edge_kind: EdgeKind,
@@ -152,6 +157,7 @@ class GraphTracerProtocol(Protocol):
def register_controller_output(
self,
node_id: str,
+ *,
output_spec: IOSpec,
) -> None:
"""Register an additional output for a controller node.
@@ -168,6 +174,7 @@ class GraphTracerProtocol(Protocol):
def register_batch_item_extraction(
self,
list_stuff_code: str,
+ *,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -186,6 +193,7 @@ class GraphTracerProtocol(Protocol):
def register_batch_aggregation(
self,
output_list_stuff_code: str,
+ *,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -205,6 +213,7 @@ class GraphTracerProtocol(Protocol):
def register_parallel_combine(
self,
combined_stuff_code: str,
+ *,
branch_stuff_codes: list[str],
parallel_controller_node_id: str,
) -> None:
@@ -223,6 +232,7 @@ class GraphTracerProtocol(Protocol):
def register_execution_data(
self,
node_id: str,
+ *,
execution_data: dict[str, Any],
) -> None:
"""Register execution metadata for a node.
@@ -244,6 +254,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def setup(
self,
graph_id: str,
+ *,
data_inclusion: DataInclusionConfig,
pipeline_ref_domain: str | None = None,
pipeline_ref_main_pipe: str | None = None,
@@ -268,6 +279,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def on_pipe_start(
self,
trace_context: TraceContext,
+ *,
pipe_code: str,
pipe_type: str,
node_kind: NodeKind,
@@ -279,13 +291,14 @@ class GraphTracerNoOp(GraphTracerProtocol):
domain_code: str | None = None,
) -> tuple[str, TraceContext]:
node_id = trace_context.make_node_id()
- child_context = trace_context.copy_for_child(node_id, trace_context.node_sequence + 1)
+ child_context = trace_context.copy_for_child(node_id, next_sequence=trace_context.node_sequence + 1)
return node_id, child_context
@override
def on_pipe_end_success(
self,
node_id: str,
+ *,
ended_at: datetime,
output_preview: str | None = None,
metrics: dict[str, float] | None = None,
@@ -298,6 +311,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def register_execution_data(
self,
node_id: str,
+ *,
execution_data: dict[str, Any],
) -> None:
pass
@@ -306,6 +320,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def on_pipe_end_error(
self,
node_id: str,
+ *,
ended_at: datetime,
error_type: str,
error_message: str,
@@ -316,6 +331,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
@override
def add_edge(
self,
+ *,
source_node_id: str,
target_node_id: str,
edge_kind: EdgeKind,
@@ -329,6 +345,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def register_controller_output(
self,
node_id: str,
+ *,
output_spec: IOSpec,
) -> None:
pass
@@ -337,6 +354,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def register_batch_item_extraction(
self,
list_stuff_code: str,
+ *,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -347,6 +365,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def register_batch_aggregation(
self,
output_list_stuff_code: str,
+ *,
item_stuff_code: str,
item_index: int,
batch_controller_node_id: str | None = None,
@@ -357,6 +376,7 @@ class GraphTracerNoOp(GraphTracerProtocol):
def register_parallel_combine(
self,
combined_stuff_code: str,
+ *,
branch_stuff_codes: list[str],
parallel_controller_node_id: str,
) -> None:
diff --git a/pipelex/graph/graphspec.py b/pipelex/graph/graphspec.py
index 1980fc06c..971e9a759 100644
--- a/pipelex/graph/graphspec.py
+++ b/pipelex/graph/graphspec.py
@@ -125,7 +125,7 @@ class EdgeKind(StrEnum):
return False
-def _truncate_string(value: str | None, max_length: int) -> str | None:
+def _truncate_string(value: str | None, *, max_length: int) -> str | None:
"""Truncate a string to max_length with ellipsis if needed."""
if value is None:
return None
@@ -195,7 +195,7 @@ class IOSpec(BaseModel):
@classmethod
def truncate_preview(cls, value: str | None) -> str | None:
"""Truncate preview to MAX_PREVIEW_LENGTH."""
- return _truncate_string(value, MAX_PREVIEW_LENGTH)
+ return _truncate_string(value, max_length=MAX_PREVIEW_LENGTH)
class NodeIOSpec(BaseModel):
@@ -223,7 +223,7 @@ class ErrorSpec(BaseModel):
@classmethod
def truncate_stack(cls, value: str | None) -> str | None:
"""Truncate stack trace to MAX_STACK_LENGTH."""
- return _truncate_string(value, MAX_STACK_LENGTH)
+ return _truncate_string(value, max_length=MAX_STACK_LENGTH)
class NodeSpec(BaseModel):
diff --git a/pipelex/graph/mermaidflow/mermaid_html.py b/pipelex/graph/mermaidflow/mermaid_html.py
index dc30953e3..dd5fb7fc0 100644
--- a/pipelex/graph/mermaidflow/mermaid_html.py
+++ b/pipelex/graph/mermaidflow/mermaid_html.py
@@ -85,12 +85,12 @@ async def render_mermaid_html_async(
async def render_mermaid_html_with_data_async(
mermaid_code: str,
+ *,
stuff_data: dict[str, str | dict[str, object] | list[str] | list[dict[str, object]] | None] | None = None,
stuff_data_text: dict[str, str] | None = None,
stuff_data_html: dict[str, str] | None = None,
stuff_metadata: dict[str, dict[str, str]] | None = None,
stuff_content_type: dict[str, str] | None = None,
- *,
title: str = "Pipelex Graph",
theme: str = "dark",
) -> str:
diff --git a/pipelex/graph/mermaidflow/mermaidflow_factory.py b/pipelex/graph/mermaidflow/mermaidflow_factory.py
index 7a3159c05..314efcb3f 100644
--- a/pipelex/graph/mermaidflow/mermaidflow_factory.py
+++ b/pipelex/graph/mermaidflow/mermaidflow_factory.py
@@ -53,8 +53,8 @@ class MermaidflowFactory:
def make_from_graphspec(
cls,
graph: GraphSpec,
- graph_config: GraphConfig,
*,
+ graph_config: GraphConfig,
direction: FlowchartDirection | None = None,
show_stuff_codes: bool = False,
include_subgraphs: bool = True,
@@ -256,8 +256,16 @@ class MermaidflowFactory:
if batch_item_edges or batch_aggregate_edges:
lines.append("")
lines.append(" %% Batch edges: list-item relationships")
- cls._render_dashed_edges(batch_item_edges, lines, stuff_id_mapping, all_stuff_info, show_stuff_codes)
- cls._render_dashed_edges(batch_aggregate_edges, lines, stuff_id_mapping, all_stuff_info, show_stuff_codes)
+ cls._render_dashed_edges(
+ batch_item_edges, lines=lines, stuff_id_mapping=stuff_id_mapping, all_stuff_info=all_stuff_info, show_stuff_codes=show_stuff_codes
+ )
+ cls._render_dashed_edges(
+ batch_aggregate_edges,
+ lines=lines,
+ stuff_id_mapping=stuff_id_mapping,
+ all_stuff_info=all_stuff_info,
+ show_stuff_codes=show_stuff_codes,
+ )
# Render parallel combine edges (branch outputs → combined output) with dashed styling
# Same approach: use stuff digests to connect stuff-to-stuff.
@@ -265,7 +273,13 @@ class MermaidflowFactory:
if parallel_combine_edges:
lines.append("")
lines.append(" %% Parallel combine edges: branch outputs → combined output")
- cls._render_dashed_edges(parallel_combine_edges, lines, stuff_id_mapping, all_stuff_info, show_stuff_codes)
+ cls._render_dashed_edges(
+ parallel_combine_edges,
+ lines=lines,
+ stuff_id_mapping=stuff_id_mapping,
+ all_stuff_info=all_stuff_info,
+ show_stuff_codes=show_stuff_codes,
+ )
# Style definitions
lines.append("")
@@ -335,6 +349,7 @@ class MermaidflowFactory:
def _render_node(
cls,
node: NodeSpec,
+ *,
mermaid_id: str,
indent: str = " ",
) -> str:
@@ -374,6 +389,7 @@ class MermaidflowFactory:
def _render_stuff_node(
cls,
digest: str,
+ *,
name: str,
concept: str | None,
stuff_id_mapping: dict[str, str],
@@ -411,6 +427,7 @@ class MermaidflowFactory:
def _render_dashed_edges(
cls,
edges: list[EdgeSpec],
+ *,
lines: list[str],
stuff_id_mapping: dict[str, str],
all_stuff_info: dict[str, tuple[str, str | None]],
@@ -470,6 +487,7 @@ class MermaidflowFactory:
def _render_subgraph_recursive(
cls,
node_id: str,
+ *,
nodes_by_id: dict[str, NodeSpec],
id_mapping: dict[str, str],
children_map: dict[str, list[str]],
@@ -576,7 +594,7 @@ class MermaidflowFactory:
lines.append(f"{indent}end")
else:
# Leaf node - render as simple node
- lines.append(cls._render_node(node, mermaid_id, indent))
+ lines.append(cls._render_node(node, mermaid_id=mermaid_id, indent=indent))
# Render batch item stuffs (no producer, with -branch-N suffix) consumed by this node
# This ensures batch item stuffs are placed inside the batch controller's subgraph
diff --git a/pipelex/graph/mermaidflow/stuff_collector.py b/pipelex/graph/mermaidflow/stuff_collector.py
index ff949e12e..23f55e9ed 100644
--- a/pipelex/graph/mermaidflow/stuff_collector.py
+++ b/pipelex/graph/mermaidflow/stuff_collector.py
@@ -17,6 +17,7 @@ T = TypeVar("T")
def _collect_stuff_field(
graph: GraphSpec,
+ *,
extractor: Callable[[IOSpec], T | None],
) -> dict[str, T]:
"""Generic collector that iterates all IOSpecs and extracts values.
@@ -69,7 +70,7 @@ def collect_stuff_data(graph: GraphSpec) -> dict[str, Any]:
Dict mapping stuff IDs (s_xxx format) to their IOSpec.data content.
Only includes entries where data is not None.
"""
- return _collect_stuff_field(graph, lambda io_spec: io_spec.data)
+ return _collect_stuff_field(graph, extractor=lambda io_spec: io_spec.data)
def collect_stuff_data_text(graph: GraphSpec) -> dict[str, str]:
@@ -82,7 +83,7 @@ def collect_stuff_data_text(graph: GraphSpec) -> dict[str, str]:
Dict mapping stuff IDs (s_xxx format) to their text representation.
Only includes entries where data_text is not None.
"""
- return _collect_stuff_field(graph, lambda io_spec: io_spec.data_text)
+ return _collect_stuff_field(graph, extractor=lambda io_spec: io_spec.data_text)
def collect_stuff_data_html(graph: GraphSpec) -> dict[str, str]:
@@ -95,7 +96,7 @@ def collect_stuff_data_html(graph: GraphSpec) -> dict[str, str]:
Dict mapping stuff IDs (s_xxx format) to their HTML representation.
Only includes entries where data_html is not None.
"""
- return _collect_stuff_field(graph, lambda io_spec: io_spec.data_html)
+ return _collect_stuff_field(graph, extractor=lambda io_spec: io_spec.data_html)
def collect_stuff_content_type(graph: GraphSpec) -> dict[str, str]:
@@ -110,7 +111,7 @@ def collect_stuff_content_type(graph: GraphSpec) -> dict[str, str]:
Dict mapping stuff IDs (s_xxx format) to their content_type.
Only includes entries where content_type is not None.
"""
- return _collect_stuff_field(graph, lambda io_spec: io_spec.content_type)
+ return _collect_stuff_field(graph, extractor=lambda io_spec: io_spec.content_type)
def collect_stuff_metadata(graph: GraphSpec) -> dict[str, dict[str, str]]:
@@ -129,4 +130,4 @@ def collect_stuff_metadata(graph: GraphSpec) -> dict[str, dict[str, str]]:
meta["concept"] = io_spec.concept
return meta
- return _collect_stuff_field(graph, extract_metadata)
+ return _collect_stuff_field(graph, extractor=extract_metadata)
diff --git a/pipelex/graph/reactflow/reactflow_html.py b/pipelex/graph/reactflow/reactflow_html.py
index f30853716..8682b4c4a 100644
--- a/pipelex/graph/reactflow/reactflow_html.py
+++ b/pipelex/graph/reactflow/reactflow_html.py
@@ -33,6 +33,7 @@ def _build_viewer_config(config: ReactFlowRenderingConfig) -> dict[str, object]:
def _build_templating_context(
graphspec: GraphSpec,
+ *,
config: ReactFlowRenderingConfig,
title: str | None,
) -> dict[str, object]:
@@ -49,8 +50,8 @@ def _build_templating_context(
def generate_reactflow_html(
graphspec: GraphSpec,
- config: ReactFlowRenderingConfig,
*,
+ config: ReactFlowRenderingConfig,
title: str | None = None,
) -> str:
"""Generate HTML with embedded GraphSpec; viewer assets load from jsDelivr (SRI-pinned).
@@ -67,14 +68,14 @@ def generate_reactflow_html(
return render_jinja2_sync(
template_source=template_source,
template_category=TemplateCategory.HTML,
- templating_context=_build_templating_context(graphspec, config, title),
+ templating_context=_build_templating_context(graphspec, config=config, title=title),
)
async def generate_reactflow_html_async(
graphspec: GraphSpec,
- config: ReactFlowRenderingConfig,
*,
+ config: ReactFlowRenderingConfig,
title: str | None = None,
) -> str:
"""Async variant of `generate_reactflow_html`."""
@@ -82,5 +83,5 @@ async def generate_reactflow_html_async(
return await render_jinja2_async(
template_source=template_source,
template_category=TemplateCategory.HTML,
- templating_context=_build_templating_context(graphspec, config, title),
+ templating_context=_build_templating_context(graphspec, config=config, title=title),
)
diff --git a/pipelex/graph/trace_context.py b/pipelex/graph/trace_context.py
index cb6b4312b..7988c2144 100644
--- a/pipelex/graph/trace_context.py
+++ b/pipelex/graph/trace_context.py
@@ -63,7 +63,7 @@ class TraceContext(BaseModel):
"""
return f"{self.graph_id}:node_{self.node_sequence}"
- def copy_for_child(self, child_node_id: str, next_sequence: int) -> "TraceContext":
+ def copy_for_child(self, child_node_id: str, *, next_sequence: int) -> "TraceContext":
"""Create a child context for a nested pipe execution.
Args:
diff --git a/pipelex/hub.py b/pipelex/hub.py
index ca4cbda0e..5c0be9b91 100644
--- a/pipelex/hub.py
+++ b/pipelex/hub.py
@@ -118,7 +118,7 @@ class PipelexHub:
# tools
- def setup_config(self, config_cls: type[ConfigRoot], config_overrides: dict[str, Any] | None = None, config_dir: Path | None = None):
+ def setup_config(self, config_cls: type[ConfigRoot], *, config_overrides: dict[str, Any] | None = None, config_dir: Path | None = None):
"""Set the global configuration instance.
Args:
diff --git a/pipelex/kit/agent_rules/pipelex_standards.md b/pipelex/kit/agent_rules/pipelex_standards.md
index 5d4c5037b..777cfaa50 100644
--- a/pipelex/kit/agent_rules/pipelex_standards.md
+++ b/pipelex/kit/agent_rules/pipelex_standards.md
@@ -16,3 +16,14 @@ When adding validation or fields, decide which layer they belong to. Language ru
- **Important**: NEVER EVER set default values for config attributes in the class definition. All the default values are defined in the main config file `pipelex/pipelex.toml`. The only exception si for Optional values which must be set to `None` in the class definition.
- If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file `.pipelex/pipelex.toml`. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matching `pipelex/pipelex.toml`, even empty ones like `activity_queues = {}`) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden.
- The different `pipelex.toml` files and the python model `configs.py` must be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just run `make tb` which tests the boot sequence, which includes the config loading.
+
+## Keyword-only arguments
+
+Non-subject function parameters across `pipelex/` source must be **keyword-only**, so call sites are self-documenting: `do_thing(retries=3, timeout=30)` over the opaque `do_thing(3, 30)`. The compliant shape places a bare `*` after the subject:
+
+- `def f(subject, *, opt1, opt2): ...` — the first non-`self`/`cls` parameter (the subject) may stay positional; everything after it must be keyword-only. Making the subject keyword-only too (`def f(*, a, b)`) is always allowed and often preferable.
+- A lone subject (`def render(node)`) is compliant; a second bare positional (`def f(a, b)`, `def truncate(text, max_length=80)`) is a violation.
+
+The rule is mechanically enforced by the `check-keyword-only` AST guard, which runs in `make agent-check`, in the `make check` aggregate, and in CI; the tree is fully compliant, so it hard-blocks on **any** violation. Carve-outs (dunders, pydantic validators/serializers, Typer/Temporal/pytest/Jinja2 framework entrypoints, `@override` impls) are skipped automatically. A genuinely justified one-off uses an inline `# kw-only: ignore` comment on the `def` line (place it right after the open paren so `ruff format` keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, `__import__` hooks, route handlers): the type checker is blind to those, so `make agent-test` is the safety net.
+
+The full specification — the two exceptions, the carve-out list, the symmetric-tuple allowlist, the escape hatch, and worked examples — is in [`docs/contribute/keyword-only-arguments.md`](docs/contribute/keyword-only-arguments.md).
diff --git a/pipelex/kit/cursor_rules.py b/pipelex/kit/cursor_rules.py
index da0ecfaa2..3c59d366c 100644
--- a/pipelex/kit/cursor_rules.py
+++ b/pipelex/kit/cursor_rules.py
@@ -31,7 +31,7 @@ def _iter_agent_files(agents_dir: Traversable) -> Iterable[tuple[str, str]]:
yield child.name, child.read_text(encoding="utf-8")
-def _front_matter_for(name: str, kit_index: KitIndex) -> dict[str, Any]:
+def _front_matter_for(name: str, *, kit_index: KitIndex) -> dict[str, Any]:
"""Build front-matter for a specific file.
Args:
@@ -74,7 +74,7 @@ def _is_pipelex_managed(mdc_path: Path) -> bool:
return parsed_dict.get(_PIPELEX_MARKER_KEY) is True
-def update_cursor_rules(repo_root: Path, kit_index: KitIndex, agent_set: str) -> None:
+def update_cursor_rules(repo_root: Path, *, kit_index: KitIndex, agent_set: str) -> None:
"""Update Cursor .mdc rule files from agent markdown with YAML front-matter.
Args:
@@ -96,7 +96,7 @@ def update_cursor_rules(repo_root: Path, kit_index: KitIndex, agent_set: str) ->
for fname, body in _iter_agent_files(agents_dir):
if fname not in allowed_files:
continue
- fm = _front_matter_for(fname, kit_index)
+ fm = _front_matter_for(fname, kit_index=kit_index)
yaml_block = "---\n" + yaml.safe_dump(fm, sort_keys=False).rstrip() + "\n---\n"
mdc = yaml_block + body
out_path = out_dir / (fname.removesuffix(".md") + ".mdc")
@@ -110,7 +110,7 @@ def update_cursor_rules(repo_root: Path, kit_index: KitIndex, agent_set: str) ->
typer.echo(f"⚪ Unchanged {out_path}")
-def remove_cursor_rules(repo_root: Path, kit_index: KitIndex | None = None) -> None:
+def remove_cursor_rules(repo_root: Path, *, kit_index: KitIndex | None = None) -> None:
"""Remove Pipelex-generated Cursor .mdc files.
Scans every .mdc file in `.cursor/rules/` and deletes the file when any of:
diff --git a/pipelex/kit/single_file_agent_rules.py b/pipelex/kit/single_file_agent_rules.py
index 0ce1d872e..b507280c9 100644
--- a/pipelex/kit/single_file_agent_rules.py
+++ b/pipelex/kit/single_file_agent_rules.py
@@ -9,7 +9,7 @@ from pipelex.kit.paths import get_kit_agents_dir
from pipelex.types import Traversable
-def _read_agent_file(agents_dir: Traversable, name: str) -> str:
+def _read_agent_file(*, agents_dir: Traversable, name: str) -> str:
"""Read an agent markdown file.
Args:
@@ -22,7 +22,7 @@ def _read_agent_file(agents_dir: Traversable, name: str) -> str:
return (agents_dir / name).read_text(encoding="utf-8")
-def _demote_headings(md_content: str, levels: int) -> str:
+def _demote_headings(md_content: str, *, levels: int) -> str:
"""Demote all headings in markdown content by specified levels.
Args:
@@ -46,7 +46,7 @@ def _demote_headings(md_content: str, levels: int) -> str:
return re.sub(pattern, demote_match, md_content, flags=re.MULTILINE)
-def build_merged_rules(kit_index: KitIndex, agent_set: str | None = None, file_list: list[str] | None = None) -> str:
+def build_merged_rules(*, kit_index: KitIndex, agent_set: str | None = None, file_list: list[str] | None = None) -> str:
"""Build merged agent documentation from ordered files.
Args:
@@ -76,8 +76,8 @@ def build_merged_rules(kit_index: KitIndex, agent_set: str | None = None, file_l
parts: list[str] = []
for name in files_to_merge:
- md_content = _read_agent_file(agents_dir, name)
- demoted = _demote_headings(md_content, kit_index.agent_rules.demote)
+ md_content = _read_agent_file(agents_dir=agents_dir, name=name)
+ demoted = _demote_headings(md_content, levels=kit_index.agent_rules.demote)
parts.append(demoted.rstrip())
return ("\n\n".join(parts)).strip() + "\n"
@@ -106,6 +106,7 @@ def unified_diff(before: str, after: str, path: str) -> str:
def update_single_file_agent_rules(
repo_root: Path,
+ *,
kit_index: KitIndex,
agent_set: str,
targets: dict[str, Target],
@@ -125,7 +126,7 @@ def update_single_file_agent_rules(
target_file_list = target.sets[agent_set]
# Build merged rules for this specific target (with override if applicable)
- merged_rules = build_merged_rules(kit_index, agent_set=agent_set, file_list=target_file_list)
+ merged_rules = build_merged_rules(kit_index=kit_index, agent_set=agent_set, file_list=target_file_list)
# Add heading
after = f"# Pipelex Coding Rules\n\n{merged_rules}"
@@ -143,6 +144,7 @@ def update_single_file_agent_rules(
def remove_from_targets(
repo_root: Path,
+ *,
targets: dict[str, Target],
) -> None:
"""Remove agent rule files.
diff --git a/pipelex/language/mthds_factory.py b/pipelex/language/mthds_factory.py
index 4501276b4..ece125628 100644
--- a/pipelex/language/mthds_factory.py
+++ b/pipelex/language/mthds_factory.py
@@ -49,7 +49,7 @@ class MthdsFactory:
)
@classmethod
- def convert_dicts_to_inline_tables(cls, value: Any, field_ordering: list[str] | None = None) -> Any: # Can't type this because of tomlkit
+ def convert_dicts_to_inline_tables(cls, value: Any, *, field_ordering: list[str] | None = None) -> Any: # Can't type this because of tomlkit
"""Recursively convert Python values; dicts -> inline tables; lists kept as arrays."""
if isinstance(value, Mapping):
value = cast("Mapping[str, Any]", value)
@@ -89,7 +89,7 @@ class MthdsFactory:
@classmethod
def convert_mapping_to_table(
- cls, mapping: Mapping[str, Any], field_ordering: list[str] | None = None
+ cls, mapping: Mapping[str, Any], *, field_ordering: list[str] | None = None
) -> Any: # Can't type this because of tomlkit
"""Convert a mapping into a TOML Table where any nested mappings (third level+)
are converted to inline tables.
diff --git a/pipelex/language/mthds_schema_generator.py b/pipelex/language/mthds_schema_generator.py
index bac888e3c..8aa19cea1 100644
--- a/pipelex/language/mthds_schema_generator.py
+++ b/pipelex/language/mthds_schema_generator.py
@@ -68,25 +68,25 @@ def _remove_internal_fields(schema: dict[str, Any]) -> dict[str, Any]:
root_props = schema.get("properties", {})
for field_name in _INTERNAL_FIELDS:
root_props.pop(field_name, None)
- _remove_from_required(schema, _INTERNAL_FIELDS)
+ _remove_from_required(schema, field_names=_INTERNAL_FIELDS)
# Remove internal fields from all definitions
for def_name, def_schema in definitions.items():
props = def_schema.get("properties", {})
for field_name in _INTERNAL_FIELDS:
props.pop(field_name, None)
- _remove_from_required(def_schema, _INTERNAL_FIELDS)
+ _remove_from_required(def_schema, field_names=_INTERNAL_FIELDS)
# Remove pipe_category only from pipe blueprint definitions
if def_name in _PIPE_DEFINITION_NAMES:
for field_name in _PIPE_INTERNAL_FIELDS:
props.pop(field_name, None)
- _remove_from_required(def_schema, _PIPE_INTERNAL_FIELDS)
+ _remove_from_required(def_schema, field_names=_PIPE_INTERNAL_FIELDS)
return schema
-def _remove_from_required(schema_obj: dict[str, Any], field_names: set[str]) -> None:
+def _remove_from_required(schema_obj: dict[str, Any], *, field_names: set[str]) -> None:
"""Remove field names from a schema object's 'required' list."""
required = schema_obj.get("required")
if required is not None:
@@ -165,7 +165,7 @@ def _convert_to_draft4(schema: dict[str, Any]) -> dict[str, Any]:
schema["definitions"] = schema.pop("$defs")
# Walk the schema tree to apply conversions
- _walk_schema(schema, _draft4_visitor)
+ _walk_schema(schema, visitor=_draft4_visitor)
return schema
@@ -307,7 +307,7 @@ def _add_taplo_metadata(schema: dict[str, Any]) -> dict[str, Any]:
return schema
-def _walk_schema(node: dict[str, Any] | list[Any] | Any, visitor: Callable[[dict[str, Any]], None]) -> None:
+def _walk_schema(node: dict[str, Any] | list[Any] | Any, *, visitor: Callable[[dict[str, Any]], None]) -> None:
"""Recursively walk a JSON Schema tree, calling visitor on each dict node.
Args:
@@ -318,8 +318,8 @@ def _walk_schema(node: dict[str, Any] | list[Any] | Any, visitor: Callable[[dict
typed_node = cast("dict[str, Any]", node)
visitor(typed_node)
for child_value in typed_node.values():
- _walk_schema(child_value, visitor)
+ _walk_schema(child_value, visitor=visitor)
elif isinstance(node, list):
typed_list = cast("list[Any]", node)
for child_item in typed_list:
- _walk_schema(child_item, visitor)
+ _walk_schema(child_item, visitor=visitor)
diff --git a/pipelex/libraries/concept/concept_library.py b/pipelex/libraries/concept/concept_library.py
index 32a452bfa..ad822e2e5 100644
--- a/pipelex/libraries/concept/concept_library.py
+++ b/pipelex/libraries/concept/concept_library.py
@@ -96,7 +96,7 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):
del self.root[concept_ref]
@override
- def is_compatible(self, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:
+ def is_compatible(self, tested_concept: Concept, *, wanted_concept: Concept, strict: bool = False) -> bool:
return Concept.are_concept_compatible(
concept_1=tested_concept,
concept_2=wanted_concept,
@@ -145,7 +145,7 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):
return [self.get_native_concept(native_concept=native_concept) for native_concept in NativeConceptCode.values_list()]
@override
- def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, search_domain_codes: list[str] | None = None) -> Concept:
+ def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, *, search_domain_codes: list[str] | None = None) -> Concept:
try:
validate_concept_ref_or_code(concept_ref_or_code=concept_ref_or_code)
except ConceptStringError as exc:
@@ -188,7 +188,7 @@ class ConceptLibrary(RootModel[ConceptLibraryRoot], ConceptLibraryAbstract):
raise ConceptLibraryConceptNotFoundError(msg)
return found_concepts[0]
- def add_dependency_concept(self, alias: str, concept: Concept) -> None:
+ def add_dependency_concept(self, *, alias: str, concept: Concept) -> None:
"""Add a concept from a dependency package with an aliased key.
Args:
diff --git a/pipelex/libraries/concept/concept_library_abstract.py b/pipelex/libraries/concept/concept_library_abstract.py
index 0f1d2f942..afb192f40 100644
--- a/pipelex/libraries/concept/concept_library_abstract.py
+++ b/pipelex/libraries/concept/concept_library_abstract.py
@@ -30,7 +30,7 @@ class ConceptLibraryAbstract(ABC):
pass
@abstractmethod
- def is_compatible(self, tested_concept: Concept, wanted_concept: Concept, strict: bool = False) -> bool:
+ def is_compatible(self, tested_concept: Concept, *, wanted_concept: Concept, strict: bool = False) -> bool:
pass
@abstractmethod
@@ -50,5 +50,5 @@ class ConceptLibraryAbstract(ABC):
pass
@abstractmethod
- def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, search_domain_codes: list[str] | None = None) -> Concept:
+ def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, *, search_domain_codes: list[str] | None = None) -> Concept:
pass
diff --git a/pipelex/libraries/concept_reference_validation.py b/pipelex/libraries/concept_reference_validation.py
index 4d76f16c6..85ed93513 100644
--- a/pipelex/libraries/concept_reference_validation.py
+++ b/pipelex/libraries/concept_reference_validation.py
@@ -7,6 +7,7 @@ from pipelex.libraries.concept.exceptions import ConceptLibraryError
def validate_concept_references_in_blueprints(
blueprints: list[PipelexBundleBlueprint],
+ *,
already_loaded_concept_refs: set[str] | None = None,
) -> None:
"""Validate that every same-domain concept reference resolves against the merged library.
diff --git a/pipelex/libraries/contract_match.py b/pipelex/libraries/contract_match.py
index 5cc29c87c..6ae491302 100644
--- a/pipelex/libraries/contract_match.py
+++ b/pipelex/libraries/contract_match.py
@@ -56,7 +56,7 @@ def _canonical_concept_spec(spec: str, *, domain_code: str) -> str:
return f"{ConceptFactory.make_concept_ref_with_domain(domain_code=domain_code, concept_code=ref.local_code)}{suffix}"
-def contracts_match(existing: PipeBlueprint, incoming: PipeBlueprint, *, domain_code: str) -> bool:
+def contracts_match(*, existing: PipeBlueprint, incoming: PipeBlueprint, domain_code: str) -> bool:
"""True if two declarations of the same pipe denote the same contract after normalization.
Both declarations share ``domain_code`` (they collided on the same qualified ``pipe_ref``), so
diff --git a/pipelex/libraries/library_crate.py b/pipelex/libraries/library_crate.py
index 622a5db85..19c6fa152 100644
--- a/pipelex/libraries/library_crate.py
+++ b/pipelex/libraries/library_crate.py
@@ -37,6 +37,7 @@ class LibraryCrate(BaseModel):
@staticmethod
def compute_fingerprint_from_content(
+ *,
concepts: dict[str, "ConceptBlueprint | str"],
pipes: dict[str, PipeBlueprintUnion],
) -> str:
diff --git a/pipelex/libraries/library_crate_factory.py b/pipelex/libraries/library_crate_factory.py
index f4bb65583..6cf8d16aa 100644
--- a/pipelex/libraries/library_crate_factory.py
+++ b/pipelex/libraries/library_crate_factory.py
@@ -150,6 +150,7 @@ class LibraryCrateFactory:
def _reconcile_pipe_collision(
cls,
pipe_ref: str,
+ *,
existing: PipeDeclaration,
incoming: PipeDeclaration,
domain_code: str,
@@ -181,7 +182,7 @@ class LibraryCrateFactory:
)
# At least one is a signature: the declarations' contracts must match (normalized identity).
- if not contracts_match(existing.blueprint, incoming.blueprint, domain_code=domain_code):
+ if not contracts_match(existing=existing.blueprint, incoming=incoming.blueprint, domain_code=domain_code):
raise PipeLibraryError(cls._contract_mismatch_msg(pipe_ref=pipe_ref, existing=existing, incoming=incoming))
# A concrete definition beats a forward declaration.
@@ -200,7 +201,7 @@ class LibraryCrateFactory:
return (declaration.blueprint.model_dump_json(), declaration.source or "")
@staticmethod
- def _contract_mismatch_msg(pipe_ref: str, existing: PipeDeclaration, incoming: PipeDeclaration) -> str:
+ def _contract_mismatch_msg(pipe_ref: str, *, existing: PipeDeclaration, incoming: PipeDeclaration) -> str:
return (
f"Pipe '{pipe_ref}' is declared with mismatched contracts: "
f"'{existing.source or 'unknown'}' has inputs={existing.blueprint.inputs or {}}, output='{existing.blueprint.output}' "
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index abedeb300..1201650eb 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -273,6 +273,7 @@ class LibraryManager(LibraryManagerAbstract):
def load_libraries(
self,
library_id: str,
+ *,
library_dirs: list[Path] | None = None,
library_file_paths: list[Path] | None = None,
) -> list[PipeAbstract]:
@@ -335,6 +336,7 @@ class LibraryManager(LibraryManagerAbstract):
def load_libraries_concepts_only(
self,
library_id: str,
+ *,
library_dirs: list[Path] | None = None,
library_file_paths: list[Path] | None = None,
) -> list["Concept"]:
@@ -420,7 +422,7 @@ class LibraryManager(LibraryManagerAbstract):
return self.load_concepts_only_from_blueprints(library_id=library_id, blueprints=all_blueprints)
@override
- def load_from_crate(self, library_id: str, crate: LibraryCrate) -> list[PipeAbstract]:
+ def load_from_crate(self, library_id: str, *, crate: LibraryCrate) -> list[PipeAbstract]:
"""Load a LibraryCrate into a live Library.
Fingerprint idempotency: if a crate with the same fingerprint was already loaded
@@ -514,7 +516,7 @@ class LibraryManager(LibraryManagerAbstract):
return all_pipes
@override
- def load_from_blueprints(self, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
+ def load_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
"""Load domains, concepts, and pipes from a list of blueprints.
Delegates through LibraryCrate: builds a crate from blueprints, then loads from the crate.
@@ -558,6 +560,7 @@ class LibraryManager(LibraryManagerAbstract):
def load_concepts_only_from_blueprints(
self,
library_id: str,
+ *,
blueprints: list[PipelexBundleBlueprint],
) -> list["Concept"]:
"""Load only domains and concepts from blueprints, skipping pipes.
@@ -758,7 +761,7 @@ class LibraryManager(LibraryManagerAbstract):
# Private helper methods
############################################################
- def _load_mthds_files_into_library(self, library_id: str, valid_mthds_paths: list[Path]) -> list[PipeAbstract]:
+ def _load_mthds_files_into_library(self, library_id: str, *, valid_mthds_paths: list[Path]) -> list[PipeAbstract]:
"""Load MTHDS files into a specific library.
This method:
@@ -836,6 +839,7 @@ class LibraryManager(LibraryManagerAbstract):
def _warn_if_mthds_version_unsatisfied(
self,
mthds_version_constraint: str,
+ *,
package_address: str,
) -> None:
"""Emit a warning if the current MTHDS standard version does not satisfy the package's constraint."""
@@ -846,7 +850,7 @@ class LibraryManager(LibraryManagerAbstract):
log.warning(f"Could not parse mthds_version constraint '{mthds_version_constraint}' for package '{package_address}': {exc}")
return
- if not version_satisfies(current_version, constraint):
+ if not version_satisfies(current_version, constraint=constraint):
log.warning(
f"Package '{package_address}' requires MTHDS standard version "
f"'{mthds_version_constraint}', but the current version is "
@@ -856,6 +860,7 @@ class LibraryManager(LibraryManagerAbstract):
def _check_package_visibility(
self,
blueprints: list[PipelexBundleBlueprint],
+ *,
mthds_paths: list[Path],
) -> MethodsManifest | None:
"""Check package visibility if a METHODS.toml manifest exists.
@@ -940,6 +945,7 @@ class LibraryManager(LibraryManagerAbstract):
def _load_dependency_packages(
self,
library_id: str,
+ *,
manifest: MethodsManifest,
package_root: Path,
) -> None:
@@ -975,6 +981,7 @@ class LibraryManager(LibraryManagerAbstract):
def _load_single_dependency(
self,
library: Library,
+ *,
resolved_dep: ResolvedDependency,
) -> None:
"""Load a single resolved dependency into an isolated child library.
@@ -1135,6 +1142,7 @@ class LibraryManager(LibraryManagerAbstract):
def _load_address_based_dependencies(
self,
library_id: str,
+ *,
blueprints: list[PipelexBundleBlueprint],
) -> None:
"""Scan blueprints for cross-package pipe refs with address-based aliases and load them.
@@ -1185,6 +1193,7 @@ class LibraryManager(LibraryManagerAbstract):
def _load_address_based_dependency(
self,
library: "Library",
+ *,
full_address: str,
extra_search_dirs: list[Path] | None = None,
) -> bool:
@@ -1243,12 +1252,12 @@ class LibraryManager(LibraryManagerAbstract):
library.concept_library.remove_concepts_by_concept_refs(concept_refs=concept_codes_to_remove)
@override
- def _remove_from_blueprint(self, library_id: str, blueprint: PipelexBundleBlueprint) -> None:
+ def _remove_from_blueprint(self, library_id: str, *, blueprint: PipelexBundleBlueprint) -> None:
self._remove_pipes_from_blueprint(blueprint=blueprint)
self._remove_concepts_from_blueprint(blueprint=blueprint)
@override
- def _remove_from_blueprints(self, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> None:
+ def _remove_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> None:
for blueprint in blueprints:
self._remove_from_blueprint(library_id=library_id, blueprint=blueprint)
@@ -1345,7 +1354,7 @@ class LibraryManager(LibraryManagerAbstract):
return refs
- def check_for_cycle(concept_ref: str, visiting: set[str], path: list[str]) -> None:
+ def check_for_cycle(concept_ref: str, *, visiting: set[str], path: list[str]) -> None:
"""Recursively check for cycles starting from concept_ref."""
if concept_ref in visiting:
# Found a cycle - build error message
@@ -1364,11 +1373,11 @@ class LibraryManager(LibraryManagerAbstract):
path.append(concept_ref)
for ref in get_referenced_concepts(concept):
- check_for_cycle(ref, visiting, path)
+ check_for_cycle(ref, visiting=visiting, path=path)
path.pop()
visiting.remove(concept_ref)
# Check each concept as a starting point
for concept in concepts:
- check_for_cycle(concept.concept_ref, set(), [])
+ check_for_cycle(concept.concept_ref, visiting=set(), path=[])
diff --git a/pipelex/libraries/library_manager_abstract.py b/pipelex/libraries/library_manager_abstract.py
index 1e587b445..eea984bdc 100644
--- a/pipelex/libraries/library_manager_abstract.py
+++ b/pipelex/libraries/library_manager_abstract.py
@@ -81,7 +81,7 @@ class LibraryManagerAbstract(ABC):
"""
@abstractmethod
- def load_from_crate(self, library_id: str, crate: LibraryCrate) -> list[PipeAbstract]:
+ def load_from_crate(self, library_id: str, *, crate: LibraryCrate) -> list[PipeAbstract]:
"""Load a LibraryCrate into a live Library.
Note: This method does NOT resolve cross-package address-based dependencies.
@@ -93,11 +93,11 @@ class LibraryManagerAbstract(ABC):
"""
@abstractmethod
- def load_from_blueprints(self, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
+ def load_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]:
pass
@abstractmethod
- def load_concepts_only_from_blueprints(self, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> list["Concept"]:
+ def load_concepts_only_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list["Concept"]:
"""Load only domains and concepts from blueprints, skipping pipes.
This is a lightweight alternative to load_from_blueprints() that only processes
@@ -113,17 +113,18 @@ class LibraryManagerAbstract(ABC):
"""
@abstractmethod
- def _remove_from_blueprint(self, library_id: str, blueprint: PipelexBundleBlueprint) -> None:
+ def _remove_from_blueprint(self, library_id: str, *, blueprint: PipelexBundleBlueprint) -> None:
pass
@abstractmethod
- def _remove_from_blueprints(self, library_id: str, blueprints: list[PipelexBundleBlueprint]) -> None:
+ def _remove_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> None:
pass
@abstractmethod
def load_libraries(
self,
library_id: str,
+ *,
library_dirs: list[Path] | None = None,
library_file_paths: list[Path] | None = None,
) -> list[PipeAbstract]:
@@ -133,6 +134,7 @@ class LibraryManagerAbstract(ABC):
def load_libraries_concepts_only(
self,
library_id: str,
+ *,
library_dirs: list[Path] | None = None,
library_file_paths: list[Path] | None = None,
) -> list["Concept"]:
diff --git a/pipelex/libraries/library_utils.py b/pipelex/libraries/library_utils.py
index 14a4fe27b..756b2d11a 100644
--- a/pipelex/libraries/library_utils.py
+++ b/pipelex/libraries/library_utils.py
@@ -21,7 +21,7 @@ def get_pipelex_mthds_files_from_package() -> list[Path]:
mthds_files: list[Path] = []
pipelex_package = files("pipelex")
- def _find_mthds_in_traversable(traversable: Traversable, collected: list[Path]) -> None:
+ def _find_mthds_in_traversable(traversable: Traversable, *, collected: list[Path]) -> None:
"""Recursively find .mthds files in a Traversable."""
excluded_dirs = get_config().pipelex.scan_config.excluded_dirs
try:
@@ -36,11 +36,11 @@ def get_pipelex_mthds_files_from_package() -> list[Path]:
elif child.is_dir():
# Skip excluded directories
if child.name not in excluded_dirs:
- _find_mthds_in_traversable(child, collected)
+ _find_mthds_in_traversable(child, collected=collected)
except (PermissionError, OSError) as exc:
log.warning(f"Could not access {traversable}: {exc}")
- _find_mthds_in_traversable(pipelex_package, mthds_files)
+ _find_mthds_in_traversable(pipelex_package, collected=mthds_files)
log.verbose(f"Found {len(mthds_files)} MTHDS files in pipelex package")
return mthds_files
diff --git a/pipelex/libraries/pipe/pipe_library.py b/pipelex/libraries/pipe/pipe_library.py
index db2e7e307..1c44d68e4 100644
--- a/pipelex/libraries/pipe/pipe_library.py
+++ b/pipelex/libraries/pipe/pipe_library.py
@@ -94,7 +94,7 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
return None
- def add_dependency_pipe(self, alias: str, pipe: PipeAbstract) -> None:
+ def add_dependency_pipe(self, *, alias: str, pipe: PipeAbstract) -> None:
"""Add a pipe from a dependency package with an aliased key.
Args:
@@ -134,7 +134,7 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
@override
def pretty_list_pipes(self) -> None:
- def _format_concept_code(concept_code: str | None, current_domain: str) -> str:
+ def _format_concept_code(concept_code: str | None, *, current_domain: str) -> str:
"""Format concept code by removing domain prefix if it matches current domain."""
if not concept_code:
return ""
@@ -172,9 +172,11 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
for pipe in domain_pipes:
inputs = pipe.inputs
- formatted_inputs = [f"{name}: {_format_concept_code(stuff_spec.concept.code, domain_code)}" for name, stuff_spec in inputs.items]
+ formatted_inputs = [
+ f"{name}: {_format_concept_code(stuff_spec.concept.code, current_domain=domain_code)}" for name, stuff_spec in inputs.items
+ ]
formatted_inputs_str = ", ".join(formatted_inputs)
- output_code = _format_concept_code(pipe.output.concept.code, domain_code)
+ output_code = _format_concept_code(pipe.output.concept.code, current_domain=domain_code)
table.add_row(
pipe.code,
diff --git a/pipelex/libraries/visibility_utils.py b/pipelex/libraries/visibility_utils.py
index 910690277..261ae526e 100644
--- a/pipelex/libraries/visibility_utils.py
+++ b/pipelex/libraries/visibility_utils.py
@@ -33,6 +33,7 @@ def _blueprint_to_metadata(blueprint: PipelexBundleBlueprint) -> BundleMetadata:
def make_visibility_checker(
+ *,
manifest: MethodsManifest | None,
blueprints: list[PipelexBundleBlueprint],
) -> PackageVisibilityChecker:
@@ -50,6 +51,7 @@ def make_visibility_checker(
def check_visibility_for_blueprints(
+ *,
manifest: MethodsManifest | None,
blueprints: list[PipelexBundleBlueprint],
) -> list[VisibilityError]:
diff --git a/pipelex/observer/local_observer.py b/pipelex/observer/local_observer.py
index 69cac749c..b20ba57e1 100644
--- a/pipelex/observer/local_observer.py
+++ b/pipelex/observer/local_observer.py
@@ -19,7 +19,7 @@ class LocalObserver(ObserverProtocol):
self.storage_dir = Path(storage_dir or get_config().pipelex.observer_config.observer_dir)
self.storage_dir.mkdir(parents=True, exist_ok=True)
- def _write_to_jsonl(self, event_type: str, payload: PayloadType) -> None:
+ def _write_to_jsonl(self, *, event_type: str, payload: PayloadType) -> None:
# event_type goes last so a payload key cannot overwrite the lifecycle event name
payload = {
**payload,
@@ -32,12 +32,12 @@ class LocalObserver(ObserverProtocol):
@override
async def observe_before_run(self, payload: PayloadType) -> None:
- self._write_to_jsonl(LocalObserverEventType.BEFORE_RUN, payload)
+ self._write_to_jsonl(event_type=LocalObserverEventType.BEFORE_RUN, payload=payload)
@override
async def observe_after_successful_run(self, payload: PayloadType) -> None:
- self._write_to_jsonl(LocalObserverEventType.AFTER_SUCCESSFUL_RUN, payload)
+ self._write_to_jsonl(event_type=LocalObserverEventType.AFTER_SUCCESSFUL_RUN, payload=payload)
@override
async def observe_after_failing_run(self, payload: PayloadType) -> None:
- self._write_to_jsonl(LocalObserverEventType.AFTER_FAILING_RUN, payload)
+ self._write_to_jsonl(event_type=LocalObserverEventType.AFTER_FAILING_RUN, payload=payload)
diff --git a/pipelex/observer/multi_observer.py b/pipelex/observer/multi_observer.py
index 206bb1958..c8875e1d1 100644
--- a/pipelex/observer/multi_observer.py
+++ b/pipelex/observer/multi_observer.py
@@ -7,11 +7,11 @@ class MultiObserver(ObserverProtocol):
def __init__(self, observers: dict[str, ObserverProtocol] | None = None) -> None:
self.observers: dict[str, ObserverProtocol] = observers or {}
- def add_observer(self, name: str, observer: ObserverProtocol) -> None:
+ def add_observer(self, *, name: str, observer: ObserverProtocol) -> None:
"""Add an observer with a given name."""
self.observers[name] = observer
- def remove_observer(self, name: str) -> None:
+ def remove_observer(self, *, name: str) -> None:
"""Remove an observer by name."""
self.observers.pop(name, None)
diff --git a/pipelex/pipe_controllers/batch/pipe_batch.py b/pipelex/pipe_controllers/batch/pipe_batch.py
index 77f1f8841..8d34cc226 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch.py
@@ -93,7 +93,7 @@ class PipeBatch(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
) -> None:
batch_params = pipe_run_params.batch_params or self.batch_params or BatchParams.make_default()
input_list_stuff_name = batch_params.input_list_stuff_name
@@ -116,6 +116,7 @@ class PipeBatch(PipeController):
@override
async def _live_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -148,7 +149,7 @@ class PipeBatch(PipeController):
f"for a workload this size, consider running on Temporal for durable, rate-limited execution."
)
- async def _run_branch(item_input_stuff: "Stuff", branch_output_item_code: str) -> PipeOutput:
+ async def _run_branch(item_input_stuff: "Stuff", *, branch_output_item_code: str) -> PipeOutput:
branch_memory = working_memory.make_deep_copy()
branch_memory.set_new_main_stuff(stuff=item_input_stuff, name=input_item_stuff_name)
@@ -202,7 +203,7 @@ class PipeBatch(PipeController):
batch_controller_node_id=batch_controller_node_id,
)
- branch_factories.append(functools.partial(_run_branch, item_input_stuff, branch_output_item_code))
+ branch_factories.append(functools.partial(_run_branch, item_input_stuff, branch_output_item_code=branch_output_item_code))
pipe_outputs = await gather_bounded(branch_factories, max_concurrency=max_concurrency)
@@ -248,7 +249,7 @@ class PipeBatch(PipeController):
"item_count": len(input_content.items),
"branch_pipe_code": self.branch_pipe_code,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=working_memory,
@@ -258,6 +259,7 @@ class PipeBatch(PipeController):
@override
async def _dry_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -281,6 +283,6 @@ class PipeBatch(PipeController):
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_controllers/batch/pipe_batch_factory.py b/pipelex/pipe_controllers/batch/pipe_batch_factory.py
index ac53ab161..5c3ae1ed6 100644
--- a/pipelex/pipe_controllers/batch/pipe_batch_factory.py
+++ b/pipelex/pipe_controllers/batch/pipe_batch_factory.py
@@ -16,6 +16,7 @@ class PipeBatchFactory(PipeFactoryProtocol[PipeBatchBlueprint, PipeBatch]):
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/condition/pipe_condition.py b/pipelex/pipe_controllers/condition/pipe_condition.py
index de20c1056..465078579 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition.py
@@ -173,7 +173,7 @@ class PipeCondition(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
evaluated_expression = await render_template(
template=self.expression,
@@ -190,7 +190,7 @@ class PipeCondition(PipeController):
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@@ -224,6 +224,7 @@ class PipeCondition(PipeController):
@override
async def _live_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -243,11 +244,11 @@ class PipeCondition(PipeController):
# Handle continue case
if SpecialOutcome.is_continue(outcome):
log.dev(f"PipeCondition '{self.code}' continued with outcome: {outcome}. Evaluated expression: {evaluated_expression}")
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeOutput(working_memory=working_memory)
if SpecialOutcome.is_fail(outcome):
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
msg = f"PipeCondition '{self.code}' failed with outcome: {outcome}. Evaluated expression: {evaluated_expression}"
raise PipeRunError(message=msg, run_mode=pipe_run_params.run_mode, pipe_code=self.code)
@@ -277,12 +278,13 @@ class PipeCondition(PipeController):
library_crate=library_crate,
),
)
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return pipe_output
@override
async def _dry_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -334,5 +336,5 @@ class PipeCondition(PipeController):
"evaluated_expression": "dry_run",
"selected_outcome": "all_outcomes",
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeOutput(working_memory=working_memory)
diff --git a/pipelex/pipe_controllers/condition/pipe_condition_factory.py b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
index 4a0b2408c..5f20693e6 100644
--- a/pipelex/pipe_controllers/condition/pipe_condition_factory.py
+++ b/pipelex/pipe_controllers/condition/pipe_condition_factory.py
@@ -16,6 +16,7 @@ class PipeConditionFactory(PipeFactoryProtocol[PipeConditionBlueprint, PipeCondi
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel.py b/pipelex/pipe_controllers/parallel/pipe_parallel.py
index a821c0c78..e91f58a8c 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel.py
@@ -96,10 +96,10 @@ class PipeParallel(PipeController):
)
for input_name, stuff_spec in pipe_needed_inputs.items:
if input_name != sub_pipe.batch_params.input_item_stuff_name:
- needed_inputs.add_stuff_spec(input_name, stuff_spec.concept, stuff_spec.multiplicity)
+ needed_inputs.add_stuff_spec(input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity)
else:
for input_name, stuff_spec in pipe_needed_inputs.items:
- needed_inputs.add_stuff_spec(input_name, stuff_spec.concept, stuff_spec.multiplicity)
+ needed_inputs.add_stuff_spec(input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity)
return needed_inputs
@model_validator(mode="after")
@@ -134,6 +134,7 @@ class PipeParallel(PipeController):
@override
async def _live_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -217,7 +218,7 @@ class PipeParallel(PipeController):
"add_each_output": self.add_each_output,
"combined_output_concept": self.combined_output.concept_ref if self.combined_output else None,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=working_memory,
@@ -227,6 +228,7 @@ class PipeParallel(PipeController):
@override
async def _dry_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -314,7 +316,7 @@ class PipeParallel(PipeController):
"add_each_output": self.add_each_output,
"combined_output_concept": self.combined_output.concept_ref if self.combined_output else None,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=working_memory,
@@ -323,6 +325,7 @@ class PipeParallel(PipeController):
def _register_branch_outputs_with_graph_tracer(
self,
+ *,
job_metadata: JobMetadata,
output_stuffs: dict[str, "Stuff"],
) -> None:
@@ -365,6 +368,7 @@ class PipeParallel(PipeController):
def _register_parallel_combine_with_graph_tracer(
self,
+ *,
job_metadata: JobMetadata,
combined_stuff: "Stuff",
branch_stuffs: dict[str, "Stuff"],
@@ -395,12 +399,12 @@ class PipeParallel(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py b/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
index 4e421c5b0..cbc5e00e9 100644
--- a/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
+++ b/pipelex/pipe_controllers/parallel/pipe_parallel_factory.py
@@ -22,6 +22,7 @@ class PipeParallelFactory(PipeFactoryProtocol[PipeParallelBlueprint, PipeParalle
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/pipe_controller.py b/pipelex/pipe_controllers/pipe_controller.py
index 615c36930..04f4a6606 100644
--- a/pipelex/pipe_controllers/pipe_controller.py
+++ b/pipelex/pipe_controllers/pipe_controller.py
@@ -34,6 +34,7 @@ class PipeController(PipeAbstract):
async def _live_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -52,6 +53,7 @@ class PipeController(PipeAbstract):
async def _dry_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -68,6 +70,7 @@ class PipeController(PipeAbstract):
@abstractmethod
async def _live_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -79,6 +82,7 @@ class PipeController(PipeAbstract):
@abstractmethod
async def _dry_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence.py b/pipelex/pipe_controllers/sequence/pipe_sequence.py
index b92f6f8a2..7a859aa4b 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence.py
@@ -158,11 +158,11 @@ class PipeSequence(PipeController):
)
for input_name, stuff_spec in sub_pipe_needed_inputs.items:
if input_name != sequential_sub_pipe.batch_params.input_item_stuff_name and input_name not in generated_outputs:
- needed_inputs.add_stuff_spec(input_name, stuff_spec.concept, stuff_spec.multiplicity)
+ needed_inputs.add_stuff_spec(input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity)
else:
for input_name, stuff_spec in sub_pipe_needed_inputs.items:
if input_name not in generated_outputs:
- needed_inputs.add_stuff_spec(input_name, stuff_spec.concept, stuff_spec.multiplicity)
+ needed_inputs.add_stuff_spec(input_name, concept=stuff_spec.concept, multiplicity=stuff_spec.multiplicity)
# Add this step's output to generated outputs
if sequential_sub_pipe.output_name:
@@ -177,6 +177,7 @@ class PipeSequence(PipeController):
@override
async def _live_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -203,7 +204,7 @@ class PipeSequence(PipeController):
execution_data_dict: dict[str, Any] = {
"step_count": len(self.sequential_sub_pipes),
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeOutput(
working_memory=evolving_memory,
@@ -213,6 +214,7 @@ class PipeSequence(PipeController):
@override
async def _dry_run_controller_pipe(
self,
+ *,
job_metadata: JobMetadata,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
@@ -229,12 +231,12 @@ class PipeSequence(PipeController):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
index fb12c5d32..d9f8601f5 100644
--- a/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
+++ b/pipelex/pipe_controllers/sequence/pipe_sequence_factory.py
@@ -19,6 +19,7 @@ class PipeSequenceFactory(PipeFactoryProtocol[PipeSequenceBlueprint, PipeSequenc
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_controllers/sub_pipe.py b/pipelex/pipe_controllers/sub_pipe.py
index 6c2a4b7d4..108323e2f 100644
--- a/pipelex/pipe_controllers/sub_pipe.py
+++ b/pipelex/pipe_controllers/sub_pipe.py
@@ -33,6 +33,7 @@ class SubPipe(BaseModel):
async def run_pipe(
self,
+ *,
calling_pipe_code: str,
working_memory: WorkingMemory,
job_metadata: JobMetadata,
diff --git a/pipelex/pipe_operators/compose/pipe_compose.py b/pipelex/pipe_operators/compose/pipe_compose.py
index e9089a9cf..cdb8c33e8 100644
--- a/pipelex/pipe_operators/compose/pipe_compose.py
+++ b/pipelex/pipe_operators/compose/pipe_compose.py
@@ -142,6 +142,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -164,6 +165,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
async def _run_template_mode(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None,
@@ -212,7 +214,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
"compose_mode": "template",
"rendered_text": rendered_template_text,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeComposeOutput(
working_memory=working_memory,
@@ -222,6 +224,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
async def _run_construct_mode(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None,
@@ -264,7 +267,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
"compose_mode": "construct",
"fields": composer.field_resolutions,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeComposeOutput(
working_memory=working_memory,
@@ -275,6 +278,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
async def _dry_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -314,6 +318,7 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
def _make_mock_construct_output(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
output_name: str | None,
) -> PipeComposeOutput:
@@ -333,12 +338,12 @@ class PipeCompose(PipeOperator[PipeComposeOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/compose/pipe_compose_factory.py b/pipelex/pipe_operators/compose/pipe_compose_factory.py
index ec0b32d6e..1c5735bdd 100644
--- a/pipelex/pipe_operators/compose/pipe_compose_factory.py
+++ b/pipelex/pipe_operators/compose/pipe_compose_factory.py
@@ -20,6 +20,7 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
@@ -51,6 +52,7 @@ class PipeComposeFactory(PipeFactoryProtocol[PipeComposeBlueprint, PipeCompose])
def _make_template_mode(
cls,
pipe_code: str,
+ *,
domain_code: str,
description: str,
inputs: InputStuffSpecs,
diff --git a/pipelex/pipe_operators/compose/structured_content_composer.py b/pipelex/pipe_operators/compose/structured_content_composer.py
index 07be8c06d..1908aebec 100644
--- a/pipelex/pipe_operators/compose/structured_content_composer.py
+++ b/pipelex/pipe_operators/compose/structured_content_composer.py
@@ -116,7 +116,7 @@ class StructuredContentComposer:
return field_values
- async def _resolve_field(self, field_blueprint: ConstructFieldBlueprint, field_name: str) -> Any:
+ async def _resolve_field(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> Any:
"""Resolve a single field according to its composition method.
Args:
@@ -142,7 +142,7 @@ class StructuredContentComposer:
case ConstructFieldMethod.NESTED:
return await self._resolve_nested(field_blueprint=field_blueprint, field_name=field_name)
- def _resolve_from_var(self, field_blueprint: ConstructFieldBlueprint, field_name: str) -> Any:
+ def _resolve_from_var(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> Any:
"""Resolve a FROM_VAR field by getting value from working memory.
The resolution is type-aware: it checks what the target field expects
@@ -184,7 +184,7 @@ class StructuredContentComposer:
return resolved_value
- def _convert_list_to_dict_keyed_by(self, value: Any, key_attr: str) -> dict[str, Any]:
+ def _convert_list_to_dict_keyed_by(self, value: Any, *, key_attr: str) -> dict[str, Any]:
"""Convert a ListContent or list to a dict keyed by a specified attribute.
Items are converted to dicts to allow Pydantic's discriminated union validation
@@ -240,7 +240,7 @@ class StructuredContentComposer:
log.verbose(f" Converted to dict with keys: {list(result.keys())}")
return result
- def _resolve_dotted_path(self, path: str, expected_type: type[Any] | None) -> Any:
+ def _resolve_dotted_path(self, path: str, *, expected_type: type[Any] | None) -> Any:
"""Resolve a dotted path by navigating through object attributes.
Handles paths like "deal.customer_name" by getting the base object
@@ -280,7 +280,7 @@ class StructuredContentComposer:
else:
return current_value # pyright: ignore[reportUnknownVariableType]
- def _resolve_from_stuff_name(self, name: str, expected_type: type[Any] | None) -> StuffContent | list[dict[str, Any]] | str:
+ def _resolve_from_stuff_name(self, name: str, *, expected_type: type[Any] | None) -> StuffContent | list[dict[str, Any]] | str:
"""Resolve a simple (non-dotted) path and convert content based on expected type.
Args:
@@ -295,7 +295,7 @@ class StructuredContentComposer:
log.verbose(f" Stuff '{name}' content type: {type(stuff_content).__name__}")
return self._convert_for_target_type(stuff_content=stuff_content, expected_type=expected_type)
- def _convert_for_target_type(self, stuff_content: StuffContent, expected_type: type[Any] | None) -> StuffContent | list[dict[str, Any]] | str:
+ def _convert_for_target_type(self, stuff_content: StuffContent, *, expected_type: type[Any] | None) -> StuffContent | list[dict[str, Any]] | str:
"""Convert content based on the expected target field type.
Central dispatcher for type-aware conversion. Routes to specific
@@ -321,7 +321,7 @@ class StructuredContentComposer:
log.verbose(f" -> Unknown target type, returning {type(stuff_content).__name__} object")
return stuff_content
- def _convert_text_content(self, text_content: TextContent, expected_type: Any) -> TextContent | str:
+ def _convert_text_content(self, text_content: TextContent, *, expected_type: Any) -> TextContent | str:
"""Convert TextContent based on expected type (str, TextContent, or subclass).
Args:
@@ -346,7 +346,7 @@ class StructuredContentComposer:
return text_content
def _convert_list_content(
- self, list_content: ListContent[StuffContent], expected_type: type[Any] | None
+ self, list_content: ListContent[StuffContent], *, expected_type: type[Any] | None
) -> ListContent[StuffContent] | list[dict[str, Any]]:
"""Convert ListContent based on expected type (list[X] or ListContent[X]).
@@ -389,7 +389,7 @@ class StructuredContentComposer:
else:
return None
- def _expects_type(self, expected_type: type[Any], target_type: type) -> bool:
+ def _expects_type(self, *, expected_type: type[Any], target_type: type) -> bool:
"""Check if the expected type matches or is a subclass of target_type.
Args:
@@ -407,7 +407,7 @@ class StructuredContentComposer:
# expected_type is not a class (e.g., it's a generic like list[X])
return False
- def _convert_content_for_field(self, stuff_content: StuffContent, expected_type: type[StuffContent]) -> StuffContent:
+ def _convert_content_for_field(self, stuff_content: StuffContent, *, expected_type: type[StuffContent]) -> StuffContent:
"""Convert any StuffContent to the expected type if needed.
This is a generic conversion method that handles class compatibility for
@@ -498,7 +498,7 @@ class StructuredContentComposer:
else:
return None
- def _convert_list_items_as_dicts(self, items: list[StuffContent], expected_item_type: type[Any] | None) -> list[dict[str, Any]]:
+ def _convert_list_items_as_dicts(self, items: list[StuffContent], *, expected_item_type: type[Any] | None) -> list[dict[str, Any]]:
"""Convert list items to dicts for Pydantic model_validate reconstruction.
Used when target is list[X] - items are returned as dicts so Pydantic
@@ -525,7 +525,7 @@ class StructuredContentComposer:
log.verbose(f" Returning {len(converted_items)} items as dicts")
return converted_items
- def _convert_list_items_as_objects(self, items: list[StuffContent], expected_item_type: type[Any] | None) -> list[StuffContent]:
+ def _convert_list_items_as_objects(self, items: list[StuffContent], *, expected_item_type: type[Any] | None) -> list[StuffContent]:
"""Convert list items while keeping them as objects (for ListContent target).
Used when target is ListContent[X] - items are validated and potentially
@@ -546,13 +546,13 @@ class StructuredContentComposer:
converted_items: list[StuffContent] = []
for idx, item in enumerate(items):
- converted_item = self._convert_single_item_as_object(item, expected_item_type, idx)
+ converted_item = self._convert_single_item_as_object(item, expected_type=expected_item_type, idx=idx)
converted_items.append(converted_item)
log.verbose(f" Returning {len(converted_items)} items as objects")
return converted_items
- def _validate_item_compatibility(self, item: StuffContent, expected_type: type[Any], idx: int) -> None:
+ def _validate_item_compatibility(self, item: StuffContent, *, expected_type: type[Any], idx: int) -> None:
"""Validate that an item can be converted to the expected type.
Args:
@@ -596,7 +596,7 @@ class StructuredContentComposer:
msg = f"Cannot convert item[{idx}] from {actual_type.__name__} to {expected_type_name}: {formatted_error}"
raise StructuredContentComposerTypeError(msg) from exc
- def _convert_single_item_as_object(self, item: StuffContent, expected_type: type[Any], idx: int) -> StuffContent:
+ def _convert_single_item_as_object(self, item: StuffContent, *, expected_type: type[Any], idx: int) -> StuffContent:
"""Convert a single list item while keeping it as an object.
Delegates to the generic _convert_content_for_field method,
@@ -615,7 +615,7 @@ class StructuredContentComposer:
"""
try:
log.verbose(f" Item[{idx}]: Converting {type(item).__name__} to {expected_type.__name__}")
- return self._convert_content_for_field(item, expected_type)
+ return self._convert_content_for_field(item, expected_type=expected_type)
except StructuredContentComposerTypeError as exc:
# Re-raise with item index in message
msg = f"Item[{idx}]: {exc}"
@@ -659,7 +659,7 @@ class StructuredContentComposer:
context=context,
)
- async def _resolve_nested(self, field_blueprint: ConstructFieldBlueprint, field_name: str) -> StuffContent:
+ async def _resolve_nested(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> StuffContent:
"""Resolve a NESTED field by recursively composing a nested StructuredContent.
Args:
diff --git a/pipelex/pipe_operators/extract/pipe_extract.py b/pipelex/pipe_operators/extract/pipe_extract.py
index d64a376f3..f60cc0566 100644
--- a/pipelex/pipe_operators/extract/pipe_extract.py
+++ b/pipelex/pipe_operators/extract/pipe_extract.py
@@ -118,6 +118,7 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -182,7 +183,7 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
"should_include_page_views": self.should_include_page_views,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeExtractOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -190,12 +191,12 @@ class PipeExtract(PipeOperator[PipeExtractOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/extract/pipe_extract_factory.py b/pipelex/pipe_operators/extract/pipe_extract_factory.py
index ba88e77ae..937008250 100644
--- a/pipelex/pipe_operators/extract/pipe_extract_factory.py
+++ b/pipelex/pipe_operators/extract/pipe_extract_factory.py
@@ -18,6 +18,7 @@ class PipeExtractFactory(PipeFactoryProtocol[PipeExtractBlueprint, PipeExtract])
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/func/pipe_func.py b/pipelex/pipe_operators/func/pipe_func.py
index 45f693515..e8c3144dc 100644
--- a/pipelex/pipe_operators/func/pipe_func.py
+++ b/pipelex/pipe_operators/func/pipe_func.py
@@ -175,6 +175,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -242,7 +243,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
"function_qualname": getattr(function, "__qualname__", self.function_name),
"output_content_type": type(the_content).__name__,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeFuncOutput(
working_memory=working_memory,
@@ -253,6 +254,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
async def _dry_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -302,7 +304,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
"output_content_type": type(mock_content).__name__,
"is_mock_output": True,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeFuncOutput(
working_memory=working_memory,
@@ -311,7 +313,7 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
function = func_registry.get_required_function(self.function_name)
return_type = get_type_hints(function).get("return")
@@ -329,6 +331,6 @@ class PipeFunc(PipeOperator[PipeFuncOutput]):
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/func/pipe_func_factory.py b/pipelex/pipe_operators/func/pipe_func_factory.py
index 6b024db43..1ad0a5b37 100644
--- a/pipelex/pipe_operators/func/pipe_func_factory.py
+++ b/pipelex/pipe_operators/func/pipe_func_factory.py
@@ -15,6 +15,7 @@ class PipeFuncFactory(PipeFactoryProtocol[PipeFuncBlueprint, PipeFunc]):
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py b/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py
index a417913cc..00f7f19d8 100644
--- a/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py
+++ b/pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py
@@ -64,6 +64,7 @@ class ImgGenPromptBlueprint(BaseModel):
async def make_img_gen_prompt(
self,
+ *,
context_provider: ContextProviderAbstract,
extra_params: dict[str, Any] | None = None,
max_prompt_images: int | None = None,
@@ -197,6 +198,7 @@ class ImgGenPromptBlueprint(BaseModel):
def _extract_direct_image(
self,
image_ref: ImageReference,
+ *,
context_provider: ContextProviderAbstract,
image_registry: ImageRegistry,
image_registry_indices: dict[str, int],
@@ -222,6 +224,7 @@ class ImgGenPromptBlueprint(BaseModel):
def _extract_direct_list_images(
self,
image_ref: ImageReference,
+ *,
context_provider: ContextProviderAbstract,
image_registry: ImageRegistry,
image_registry_indices: dict[str, int],
@@ -265,6 +268,7 @@ class ImgGenPromptBlueprint(BaseModel):
async def _render_text(
self,
+ *,
context_provider: ContextProviderAbstract,
template_blueprint: TemplateBlueprint,
extra_params: dict[str, Any] | None = None,
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen.py b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
index 269f6453c..343902559 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen.py
@@ -137,6 +137,7 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -281,7 +282,7 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
"nb_images": nb_images,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeImgGenOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -289,12 +290,12 @@ class PipeImgGen(PipeOperator[PipeImgGenOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
index 5a791549e..9ea28ce3b 100644
--- a/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
+++ b/pipelex/pipe_operators/img_gen/pipe_img_gen_factory.py
@@ -23,6 +23,7 @@ class PipeImgGenFactory(PipeFactoryProtocol[PipeImgGenBlueprint, PipeImgGen]):
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
index a2a2eb3d4..483265f46 100644
--- a/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
+++ b/pipelex/pipe_operators/llm/llm_prompt_blueprint.py
@@ -61,6 +61,7 @@ class LLMPromptBlueprint(BaseModel):
async def make_llm_prompt(
self,
output_concept_ref: str,
+ *,
context_provider: ContextProviderAbstract,
output_structure_prompt: str | None = None,
extra_params: dict[str, Any] | None = None,
@@ -278,6 +279,7 @@ class LLMPromptBlueprint(BaseModel):
def _extract_direct_image(
self,
image_ref: ImageReference,
+ *,
context_provider: ContextProviderAbstract,
image_registry: ImageRegistry,
image_registry_indices: dict[str, int],
@@ -303,6 +305,7 @@ class LLMPromptBlueprint(BaseModel):
def _extract_direct_list_images(
self,
image_ref: ImageReference,
+ *,
context_provider: ContextProviderAbstract,
image_registry: ImageRegistry,
image_registry_indices: dict[str, int],
@@ -346,6 +349,7 @@ class LLMPromptBlueprint(BaseModel):
async def _unravel_text(
self,
+ *,
context_provider: ContextProviderAbstract,
jinja2_blueprint: TemplateBlueprint,
extra_params: dict[str, Any] | None = None,
@@ -378,6 +382,7 @@ class LLMPromptBlueprint(BaseModel):
def _extract_direct_document(
self,
doc_ref: DocumentReference,
+ *,
context_provider: ContextProviderAbstract,
prompt_user_documents: dict[str, PromptDocument],
) -> None:
@@ -405,6 +410,7 @@ class LLMPromptBlueprint(BaseModel):
def _extract_direct_list_documents(
self,
doc_ref: DocumentReference,
+ *,
context_provider: ContextProviderAbstract,
prompt_user_documents: dict[str, PromptDocument],
) -> None:
diff --git a/pipelex/pipe_operators/llm/pipe_llm.py b/pipelex/pipe_operators/llm/pipe_llm.py
index ddcc35dd6..726497fa0 100644
--- a/pipelex/pipe_operators/llm/pipe_llm.py
+++ b/pipelex/pipe_operators/llm/pipe_llm.py
@@ -70,7 +70,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
# Check for unused inputs: declared in inputs but not used by any variable path
for input_name in input_names:
- if not is_input_used_by_variables(input_name, required_variable_paths):
+ if not is_input_used_by_variables(input_name, variable_paths=required_variable_paths):
msg = f"PipeLLM '{self.code}' has input '{input_name}' declared but it is not used in the prompt or system_prompt."
raise PipeValidationError(
message=msg,
@@ -82,7 +82,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
# Check for missing inputs: variable paths in prompt/system_prompt not satisfied by any input
for variable_path in required_variable_paths:
- if not is_variable_satisfied_by_inputs(variable_path, input_names):
+ if not is_variable_satisfied_by_inputs(variable_path, input_names=input_names):
msg = f"PipeLLM '{self.code}' uses variable '{variable_path}' in prompt/system_prompt but it is not declared in inputs."
raise PipeValidationError(
message=msg,
@@ -168,6 +168,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -320,7 +321,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
)
execution_data_dict["structuring_path"] = "text" if output_is_text else "object_direct"
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeLLMOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -329,6 +330,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
async def _llm_gen_object_stuff_content(
self,
job_metadata: JobMetadata,
+ *,
pipe_run_params: PipeRunParams,
is_multiple_output: bool,
fixed_nb_output: int | None,
@@ -381,7 +383,7 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
def _format_error_location(self, pipe_run_params: PipeRunParams) -> str:
return f"in pipe '{pipe_run_params.pipe_stack_str}'"
- def _format_llm_error(self, exc: LLMCompletionError, settings: list[LLMSetting]) -> str:
+ def _format_llm_error(self, exc: LLMCompletionError, *, settings: list[LLMSetting]) -> str:
"""Format an LLMCompletionError, extracting and formatting any ValidationError in the chain."""
error_details = str(exc)
for current_exc in iter_cause_chain(exc):
@@ -392,12 +394,12 @@ class PipeLLM(PipeOperator[PipeLLMOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
index 166975adf..47a145fa9 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_blueprint.py
@@ -106,10 +106,14 @@ class PipeLLMBlueprint(PipeBlueprint):
}
# Find variables used in prompts but not satisfied by any input
- missing_inputs = {var_path for var_path in filtered_variable_paths if not is_variable_satisfied_by_inputs(var_path, declared_inputs)}
+ missing_inputs = {
+ var_path for var_path in filtered_variable_paths if not is_variable_satisfied_by_inputs(var_path, input_names=declared_inputs)
+ }
# Find inputs declared but not used by any variable path
- unused_inputs = {input_name for input_name in declared_inputs if not is_input_used_by_variables(input_name, filtered_variable_paths)}
+ unused_inputs = {
+ input_name for input_name in declared_inputs if not is_input_used_by_variables(input_name, variable_paths=filtered_variable_paths)
+ }
if missing_inputs:
missing_vars_str = ", ".join(sorted(missing_inputs))
diff --git a/pipelex/pipe_operators/llm/pipe_llm_factory.py b/pipelex/pipe_operators/llm/pipe_llm_factory.py
index df026211a..6863e2006 100644
--- a/pipelex/pipe_operators/llm/pipe_llm_factory.py
+++ b/pipelex/pipe_operators/llm/pipe_llm_factory.py
@@ -26,6 +26,7 @@ class PipeLLMFactory(PipeFactoryProtocol[PipeLLMBlueprint, PipeLLM]):
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/llm/template_document_analyzer.py b/pipelex/pipe_operators/llm/template_document_analyzer.py
index 49359e686..8fa8aa32f 100644
--- a/pipelex/pipe_operators/llm/template_document_analyzer.py
+++ b/pipelex/pipe_operators/llm/template_document_analyzer.py
@@ -31,6 +31,7 @@ class TemplateDocumentAnalyzer:
def analyze_template_for_documents(
cls,
template_source: str,
+ *,
input_specs: dict[str, str],
domain_code: str,
) -> list[DocumentReference]:
@@ -69,10 +70,10 @@ class TemplateDocumentAnalyzer:
has_multiplicity = parsed_input.multiplicity is not None and parsed_input.multiplicity is not False
# Resolve the concept for this variable
- concept = cls._resolve_concept(input_spec, domain_code)
+ concept = cls._resolve_concept(input_spec, domain_code=domain_code)
# Determine what type the variable path resolves to
- resolved_type_info = cls._resolve_variable_type(var_ref.path, root_var, concept)
+ resolved_type_info = cls._resolve_variable_type(var_ref.path, root_var=root_var, root_concept=concept)
if resolved_type_info is None:
continue
@@ -103,7 +104,7 @@ class TemplateDocumentAnalyzer:
return document_references
@classmethod
- def _resolve_concept(cls, concept_ref_or_code: str, domain_code: str) -> Concept:
+ def _resolve_concept(cls, concept_ref_or_code: str, *, domain_code: str) -> Concept:
"""Resolve a concept reference to a Concept object.
Handles multiplicity brackets like Document[] or Document[3] by stripping them.
@@ -127,6 +128,7 @@ class TemplateDocumentAnalyzer:
def _resolve_variable_type(
cls,
var_path: str,
+ *,
root_var: str,
root_concept: Concept,
) -> tuple[bool, bool] | None:
diff --git a/pipelex/pipe_operators/pipe_operator.py b/pipelex/pipe_operators/pipe_operator.py
index 9b7a4ee1c..aa6b14b2a 100644
--- a/pipelex/pipe_operators/pipe_operator.py
+++ b/pipelex/pipe_operators/pipe_operator.py
@@ -31,6 +31,7 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
async def _live_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -86,6 +87,7 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
async def _dry_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -99,6 +101,7 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -108,6 +111,7 @@ class PipeOperator(PipeAbstract, Generic[PipeOperatorOutputType]):
async def _dry_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
diff --git a/pipelex/pipe_operators/search/pipe_search.py b/pipelex/pipe_operators/search/pipe_search.py
index abcb8d813..2a55aa4c7 100644
--- a/pipelex/pipe_operators/search/pipe_search.py
+++ b/pipelex/pipe_operators/search/pipe_search.py
@@ -74,6 +74,7 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -151,7 +152,7 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
"is_structured_output": self.is_structured_output,
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeSearchOutput(
working_memory=working_memory,
pipeline_run_id=job_metadata.pipeline_run_id,
@@ -159,12 +160,12 @@ class PipeSearch(PipeOperator[PipeSearchOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/search/pipe_search_factory.py b/pipelex/pipe_operators/search/pipe_search_factory.py
index 18f262ff4..dcca1141e 100644
--- a/pipelex/pipe_operators/search/pipe_search_factory.py
+++ b/pipelex/pipe_operators/search/pipe_search_factory.py
@@ -19,6 +19,7 @@ class PipeSearchFactory(PipeFactoryProtocol[PipeSearchBlueprint, PipeSearch]):
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_operators/shared/template_image_analyzer.py b/pipelex/pipe_operators/shared/template_image_analyzer.py
index 831a4c30e..88007718d 100644
--- a/pipelex/pipe_operators/shared/template_image_analyzer.py
+++ b/pipelex/pipe_operators/shared/template_image_analyzer.py
@@ -34,6 +34,7 @@ class TemplateImageAnalyzer:
def analyze_template_for_images(
cls,
template_source: str,
+ *,
input_specs: dict[str, str],
domain_code: str,
template_category: TemplateCategory = TemplateCategory.LLM_PROMPT,
@@ -77,11 +78,11 @@ class TemplateImageAnalyzer:
has_multiplicity = parsed_input.multiplicity is not None and parsed_input.multiplicity is not False
# Resolve the concept for this variable
- concept = cls._resolve_concept(input_spec, domain_code)
+ concept = cls._resolve_concept(input_spec, domain_code=domain_code)
# Determine what type the variable path resolves to
# For nested paths like "doc.cover", we need to traverse the structure
- resolved_type_info = cls._resolve_variable_type(var_ref.path, root_var, concept)
+ resolved_type_info = cls._resolve_variable_type(var_ref.path, root_var=root_var, root_concept=concept)
if resolved_type_info is None:
continue
@@ -136,6 +137,7 @@ class TemplateImageAnalyzer:
def validate_unused_inputs(
cls,
template_sources: list[str],
+ *,
input_specs: dict[str, str],
template_category: TemplateCategory = TemplateCategory.LLM_PROMPT,
) -> None:
@@ -169,7 +171,7 @@ class TemplateImageAnalyzer:
raise UnusedInputError(msg)
@classmethod
- def _resolve_concept(cls, concept_ref_or_code: str, domain_code: str) -> Concept:
+ def _resolve_concept(cls, concept_ref_or_code: str, *, domain_code: str) -> Concept:
"""Resolve a concept reference to a Concept object.
Handles multiplicity brackets like Image[] or Text[3] by stripping them.
@@ -193,6 +195,7 @@ class TemplateImageAnalyzer:
def _resolve_variable_type(
cls,
var_path: str,
+ *,
root_var: str,
root_concept: Concept,
) -> tuple[bool, bool, bool, list[str] | None] | None:
diff --git a/pipelex/pipe_operators/structure/pipe_structure.py b/pipelex/pipe_operators/structure/pipe_structure.py
index 9db4cdfbe..7122e1d46 100644
--- a/pipelex/pipe_operators/structure/pipe_structure.py
+++ b/pipelex/pipe_operators/structure/pipe_structure.py
@@ -102,6 +102,7 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
async def _live_run_operator_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -193,7 +194,7 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
"rendered_user_prompt": rendered_user_prompt,
"structuring_path": "structure",
}
- self._register_execution_data(job_metadata, execution_data_dict)
+ self._register_execution_data(job_metadata, execution_data=execution_data_dict)
return PipeStructureOutput(
working_memory=working_memory,
@@ -205,12 +206,12 @@ class PipeStructure(PipeOperator[PipeStructureOutput]):
@override
async def _validate_before_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
@override
async def _validate_after_run(
- self, job_metadata: JobMetadata, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
+ self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None = None
):
pass
diff --git a/pipelex/pipe_operators/structure/pipe_structure_factory.py b/pipelex/pipe_operators/structure/pipe_structure_factory.py
index 4add78266..2d74fb6a9 100644
--- a/pipelex/pipe_operators/structure/pipe_structure_factory.py
+++ b/pipelex/pipe_operators/structure/pipe_structure_factory.py
@@ -16,6 +16,7 @@ class PipeStructureFactory(PipeFactoryProtocol[PipeStructureBlueprint, PipeStruc
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.py
index f5e6f3112..2bac41f34 100644
--- a/pipelex/pipe_run/delivery_executor.py
+++ b/pipelex/pipe_run/delivery_executor.py
@@ -40,6 +40,7 @@ class DeliveryExecutor:
async def execute(
self,
pipe_output: PipeOutput | None,
+ *,
user_id: str,
pipeline_run_id: str,
delivery_assignment: DeliveryAssignment,
@@ -56,11 +57,20 @@ class DeliveryExecutor:
# Step 1: Persist the result files to storage (only on success with output)
result_url: str | None = None
if delivery_assignment.storage is not None and pipe_output is not None:
- result_url = await self._store_results(pipe_output, user_id, pipeline_run_id, delivery_assignment.storage, request_id=request_id)
+ result_url = await self._store_results(
+ pipe_output, user_id=user_id, pipeline_run_id=pipeline_run_id, storage=delivery_assignment.storage, request_id=request_id
+ )
# Step 2: Notify webhooks with status + result_url (always, even on failure)
for webhook in delivery_assignment.webhooks:
- await self._notify_webhook(pipeline_run_id, status, result_url, webhook, error_report, request_id=request_id)
+ await self._notify_webhook(
+ pipeline_run_id=pipeline_run_id,
+ status=status,
+ result_url=result_url,
+ webhook=webhook,
+ error_report=error_report,
+ request_id=request_id,
+ )
# ---- Result file generation ----
@@ -89,9 +99,9 @@ class DeliveryExecutor:
raw_main_stuff = self._get_raw_main_stuff_dict(pipe_output.working_memory_raw)
main_stuff = self.try_local_hydrate_stuff(raw_main_stuff) if raw_main_stuff is not None else None
if main_stuff is not None:
- await self._generate_main_stuff_files(main_stuff, files)
+ await self._generate_main_stuff_files(main_stuff, files=files)
elif raw_main_stuff is not None:
- self._generate_main_stuff_files_from_raw(raw_main_stuff, files)
+ self._generate_main_stuff_files_from_raw(raw_main_stuff, files=files)
else:
files["working_memory.json"] = ResultFile(
data=clean_json_dumps(pipe_output.working_memory.smart_dump(), indent=2).encode("utf-8"),
@@ -99,11 +109,11 @@ class DeliveryExecutor:
)
main_stuff = pipe_output.working_memory.get_optional_main_stuff()
if main_stuff is not None:
- await self._generate_main_stuff_files(main_stuff, files)
+ await self._generate_main_stuff_files(main_stuff, files=files)
graph_spec = pipe_output.graph_spec
if graph_spec:
- await self._generate_graph_files(graph_spec, files)
+ await self._generate_graph_files(graph_spec, files=files)
return files
@@ -150,7 +160,7 @@ class DeliveryExecutor:
return None
@classmethod
- def _generate_main_stuff_files_from_raw(cls, raw_main_stuff: dict[str, Any], files: dict[str, ResultFile]) -> None:
+ def _generate_main_stuff_files_from_raw(cls, raw_main_stuff: dict[str, Any], *, files: dict[str, ResultFile]) -> None:
"""Generic fallback rendering of a main stuff that we couldn't locally hydrate.
Produces JSON-in-markdown and `<pre>`-in-HTML so the user still gets
@@ -165,24 +175,30 @@ class DeliveryExecutor:
# like "</pre><script>...</script>" in pipeline outputs.
files["main_stuff.html"] = ResultFile(data=f"<pre>{html.escape(json_text)}</pre>".encode(), content_type="text/html")
- async def _generate_main_stuff_files(self, main_stuff: Stuff, files: dict[str, ResultFile]) -> None:
+ async def _generate_main_stuff_files(self, main_stuff: Stuff, *, files: dict[str, ResultFile]) -> None:
content = main_stuff.content
- await self._try_add_rendered_file(files, "main_stuff.json", content.rendered_json_async(), "application/json")
- await self._try_add_rendered_file(files, "main_stuff.md", content.rendered_markdown_async(), "text/markdown")
- await self._try_add_rendered_file(files, "main_stuff.html", content.rendered_html_async(), "text/html")
- await self._try_add_rendered_file(files, "main_stuff_viewer.html", render_stuff_viewer(main_stuff), "text/html")
-
- async def _generate_graph_files(self, graph_spec: Any, files: dict[str, ResultFile]) -> None:
+ await self._try_add_rendered_file(
+ files=files, filename="main_stuff.json", render=content.rendered_json_async(), content_type="application/json"
+ )
+ await self._try_add_rendered_file(
+ files=files, filename="main_stuff.md", render=content.rendered_markdown_async(), content_type="text/markdown"
+ )
+ await self._try_add_rendered_file(files=files, filename="main_stuff.html", render=content.rendered_html_async(), content_type="text/html")
+ await self._try_add_rendered_file(
+ files=files, filename="main_stuff_viewer.html", render=render_stuff_viewer(main_stuff), content_type="text/html"
+ )
+
+ async def _generate_graph_files(self, graph_spec: Any, *, files: dict[str, ResultFile]) -> None:
try:
graph_config = get_config().pipelex.pipeline_execution_config.graph_config
graph_outputs = await generate_graph_outputs(
graph_spec=graph_spec,
graph_config=graph_config,
)
- self._add_optional_text_file(files, "graphspec.json", graph_outputs.graphspec_json, "application/json")
- self._add_optional_text_file(files, "mermaidflow.mmd", graph_outputs.mermaidflow_mmd, "text/plain")
- self._add_optional_text_file(files, "mermaidflow.html", graph_outputs.mermaidflow_html, "text/html")
- self._add_optional_text_file(files, "reactflow.html", graph_outputs.reactflow_html, "text/html")
+ self._add_optional_text_file(files=files, filename="graphspec.json", text=graph_outputs.graphspec_json, content_type="application/json")
+ self._add_optional_text_file(files=files, filename="mermaidflow.mmd", text=graph_outputs.mermaidflow_mmd, content_type="text/plain")
+ self._add_optional_text_file(files=files, filename="mermaidflow.html", text=graph_outputs.mermaidflow_html, content_type="text/html")
+ self._add_optional_text_file(files=files, filename="reactflow.html", text=graph_outputs.reactflow_html, content_type="text/html")
except Exception: # noqa: BLE001
# 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")
@@ -190,6 +206,7 @@ class DeliveryExecutor:
@classmethod
async def _try_add_rendered_file(
cls,
+ *,
files: dict[str, ResultFile],
filename: str,
render: Awaitable[str],
@@ -205,7 +222,7 @@ class DeliveryExecutor:
files[filename] = ResultFile(data=text.encode("utf-8"), content_type=content_type)
@classmethod
- def _add_optional_text_file(cls, files: dict[str, ResultFile], filename: str, text: str | None, content_type: str) -> None:
+ def _add_optional_text_file(cls, *, files: dict[str, ResultFile], filename: str, text: str | None, content_type: str) -> None:
"""Encode `text` and store it under `filename`. No-op when `text` is None."""
if text is not None:
files[filename] = ResultFile(data=text.encode("utf-8"), content_type=content_type)
@@ -215,6 +232,7 @@ class DeliveryExecutor:
async def _store_results(
self,
pipe_output: PipeOutput,
+ *,
user_id: str,
pipeline_run_id: str,
storage: StorageTarget,
@@ -248,6 +266,7 @@ class DeliveryExecutor:
async def _notify_webhook(
self,
+ *,
pipeline_run_id: str,
status: DeliveryStatus,
result_url: str | None,
diff --git a/pipelex/pipe_run/pipe_job_factory.py b/pipelex/pipe_run/pipe_job_factory.py
index 22bba9751..3c7638773 100644
--- a/pipelex/pipe_run/pipe_job_factory.py
+++ b/pipelex/pipe_run/pipe_job_factory.py
@@ -13,6 +13,7 @@ class PipeJobFactory:
def make_pipe_job(
cls,
pipe: PipeAbstract,
+ *,
job_metadata: JobMetadata,
pipe_run_params: PipeRunParams | None = None,
working_memory: WorkingMemory | None = None,
diff --git a/pipelex/pipe_run/pipe_router_protocol.py b/pipelex/pipe_run/pipe_router_protocol.py
index f7ca5f54d..7e2793eb6 100644
--- a/pipelex/pipe_run/pipe_router_protocol.py
+++ b/pipelex/pipe_run/pipe_router_protocol.py
@@ -24,6 +24,7 @@ class PipeRouterProtocol(Protocol):
async def _after_successful_run(
self,
pipe_job: PipeJob,
+ *,
pipe_output: PipeOutput,
) -> None:
payload: PayloadType = {
@@ -36,6 +37,7 @@ class PipeRouterProtocol(Protocol):
async def _after_failing_run(
self,
pipe_job: PipeJob,
+ *,
error: Exception,
) -> None:
payload: PayloadType = {
@@ -58,7 +60,7 @@ class PipeRouterProtocol(Protocol):
# retry here. This handler is error propagation, not retry: a PipeRunError wraps into
# PipeRouterError (preserving the pipe location context); a raw CogtError is re-raised
# as-is so its cause chain is preserved. Resilience is the Temporal track's job.
- await self._after_failing_run(pipe_job, exc)
+ await self._after_failing_run(pipe_job, error=exc)
if isinstance(exc, PipeRunError):
raise PipeRouterError(
message=exc.message,
@@ -71,7 +73,7 @@ class PipeRouterProtocol(Protocol):
) from exc
raise
- await self._after_successful_run(pipe_job, pipe_output)
+ await self._after_successful_run(pipe_job, pipe_output=pipe_output)
return pipe_output
diff --git a/pipelex/pipe_run/pipe_run.py b/pipelex/pipe_run/pipe_run.py
index 906888a70..3119fdca4 100644
--- a/pipelex/pipe_run/pipe_run.py
+++ b/pipelex/pipe_run/pipe_run.py
@@ -30,6 +30,7 @@ class PipeRun(PipeRunProtocol):
async def run(
self,
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None = None,
) -> PipeOutput:
pipeline_run_id: str = pipe_job.job_metadata.pipeline_run_id
diff --git a/pipelex/pipe_run/pipe_run_params.py b/pipelex/pipe_run/pipe_run_params.py
index 2bf209b88..69a7546e5 100644
--- a/pipelex/pipe_run/pipe_run_params.py
+++ b/pipelex/pipe_run/pipe_run_params.py
@@ -26,6 +26,7 @@ FORCE_DRY_RUN_MODE_ENV_KEY = "PIPELEX_FORCE_DRY_RUN_MODE"
def output_multiplicity_to_apply(
+ *,
base_multiplicity: VariableMultiplicity | None,
override_multiplicity: VariableMultiplicity | None,
) -> VariableMultiplicityResolution:
@@ -59,13 +60,13 @@ def output_multiplicity_to_apply(
- If override is int: Use override count, enable multiple outputs
Examples:
- >>> result = output_multiplicity_to_apply(None, None)
+ >>> result = output_multiplicity_to_apply(base_multiplicity=None, override_multiplicity=None)
>>> (result.resolved_multiplicity, result.enable_multiple_outputs, result.specific_output_count)
(None, False, None)
- >>> result = output_multiplicity_to_apply(True, None)
+ >>> result = output_multiplicity_to_apply(base_multiplicity=True, override_multiplicity=None)
>>> (result.resolved_multiplicity, result.enable_multiple_outputs, result.specific_output_count)
(True, True, None)
- >>> result = output_multiplicity_to_apply(3, None)
+ >>> result = output_multiplicity_to_apply(base_multiplicity=3, override_multiplicity=None)
>>> (result.resolved_multiplicity, result.enable_multiple_outputs, result.specific_output_count)
(3, True, 3)
@@ -120,6 +121,7 @@ class BatchParams(BaseModel):
def make_batch_params(
cls,
input_list_name: str,
+ *,
input_item_name: str,
) -> BatchParams:
return BatchParams(
@@ -204,6 +206,7 @@ class PipeRunParams(BaseModel):
def copy_by_injecting_multiplicity(
cls,
pipe_run_params: Self,
+ *,
applied_output_multiplicity: VariableMultiplicity | None,
) -> Self:
"""Copy the run params the nb_output into the params, and remove the attribute.
diff --git a/pipelex/pipe_run/pipe_run_protocol.py b/pipelex/pipe_run/pipe_run_protocol.py
index a52392b3c..dc8c3f7f5 100644
--- a/pipelex/pipe_run/pipe_run_protocol.py
+++ b/pipelex/pipe_run/pipe_run_protocol.py
@@ -20,6 +20,7 @@ class PipeRunProtocol(Protocol):
async def run(
self,
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None = None,
) -> PipeOutput:
"""Execute a pipe job and, if `delivery_assignment` is provided, deliver the output.
diff --git a/pipelex/pipe_run/tracing_assembly.py b/pipelex/pipe_run/tracing_assembly.py
index b71f5521a..544406bdb 100644
--- a/pipelex/pipe_run/tracing_assembly.py
+++ b/pipelex/pipe_run/tracing_assembly.py
@@ -141,8 +141,8 @@ def assemble_tracing(
def assemble_tracing_on_output(
pipe_output: PipeOutput,
- pipeline_run_id: str,
*,
+ pipeline_run_id: str,
assemble_graph: bool,
assemble_usage: bool,
domain_code: str | None = None,
diff --git a/pipelex/pipe_signature/exceptions.py b/pipelex/pipe_signature/exceptions.py
index 1f3289194..2edf7a90e 100644
--- a/pipelex/pipe_signature/exceptions.py
+++ b/pipelex/pipe_signature/exceptions.py
@@ -1,4 +1,4 @@
-from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.base_exceptions import PipelexError
class PipeSignatureNotExecutableError(PipelexError):
@@ -7,6 +7,10 @@ class PipeSignatureNotExecutableError(PipelexError):
Signatures are contract-only placeholders: they declare inputs and outputs but have
no implementation. Encountering one at live-run time means the pipeline was not
fully implemented before being launched.
+
+ This is the **execute/run**-path guard. Validation no longer rejects signatures: a
+ `PipeSignature` reached during a dry-run sweep is a runnability fact (`pending_signatures`
+ + `is_runnable`), not a validation error (D-B). Running a stub, by contrast, must fail.
"""
def __init__(self, pipe_ref: str) -> None:
@@ -16,52 +20,3 @@ class PipeSignatureNotExecutableError(PipelexError):
f"Replace it with a real pipe before running, or validate with --allow-signatures."
)
super().__init__(message)
-
-
-class SignaturesNotAllowedError(PipelexError):
- """Raised in strict validation when one or more `PipeSignature` placeholders are reachable.
-
- Strict mode (the default) refuses to dry-run any pipe whose dependency graph contains a
- `PipeSignature` — they are contract-only stubs and a strict caller is asking for a
- fully-implemented pipeline. Lenient mode (`allow_signatures=True`) bypasses this check.
-
- Classified ``INPUT``: the bundle the caller submitted carries unimplemented placeholders —
- the caller fixes it by implementing the pipes or opting in via ``allow_signatures``. This makes
- the API render it as a 422 (not a 500 server fault) and the CLI log it as a caller mistake,
- matching the agent-CLI's existing ``AGENT_ERROR_DOMAINS`` classification of this error.
- """
-
- error_domain = ErrorDomain.INPUT
- _authors_caller_facing_message = True
-
- def __init__(
- self,
- offending_pipe_refs: set[str],
- signature_refs: set[str],
- dep_paths: dict[str, list[str]],
- ) -> None:
- self.offending_pipe_refs = offending_pipe_refs
- self.signature_refs = signature_refs
- self.dep_paths = dep_paths
- message = self._format_message()
- super().__init__(message)
-
- def _format_message(self) -> str:
- sorted_offenders = sorted(self.offending_pipe_refs)
- if len(sorted_offenders) == 1:
- header = f"Pipe '{sorted_offenders[0]}' depends on PipeSignature placeholders that have no implementation:"
- elif len(sorted_offenders) > 1:
- offender_list = ", ".join(f"'{ref}'" for ref in sorted_offenders)
- header = f"The following pipes depend on PipeSignature placeholders that have no implementation: {offender_list}"
- else:
- header = "Validation found PipeSignature placeholders that have no implementation:"
- lines: list[str] = [header]
- for sig_ref in sorted(self.signature_refs):
- dep_chain = self.dep_paths.get(sig_ref, [])
- if dep_chain:
- chain_str = " → ".join([*dep_chain, sig_ref])
- lines.append(f" - {sig_ref} (via {chain_str})")
- else:
- lines.append(f" - {sig_ref}")
- lines.append("Replace each signature with a real implementation, or re-run with `--allow-signatures` to accept placeholders.")
- return "\n".join(lines)
diff --git a/pipelex/pipe_signature/pipe_signature.py b/pipelex/pipe_signature/pipe_signature.py
index c67df2a6f..ad84cc1ba 100644
--- a/pipelex/pipe_signature/pipe_signature.py
+++ b/pipelex/pipe_signature/pipe_signature.py
@@ -63,6 +63,7 @@ class PipeSignature(PipeAbstract):
async def _validate_before_run(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -73,6 +74,7 @@ class PipeSignature(PipeAbstract):
async def _validate_after_run(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -83,6 +85,7 @@ class PipeSignature(PipeAbstract):
async def _live_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
@@ -94,6 +97,7 @@ class PipeSignature(PipeAbstract):
async def _dry_run_pipe(
self,
job_metadata: JobMetadata,
+ *,
working_memory: WorkingMemory,
pipe_run_params: PipeRunParams,
output_name: str | None = None,
diff --git a/pipelex/pipe_signature/pipe_signature_factory.py b/pipelex/pipe_signature/pipe_signature_factory.py
index 9e5bf5a3f..9a1b8f5ad 100644
--- a/pipelex/pipe_signature/pipe_signature_factory.py
+++ b/pipelex/pipe_signature/pipe_signature_factory.py
@@ -15,6 +15,7 @@ class PipeSignatureFactory(PipeFactoryProtocol[PipeSignatureBlueprint, PipeSigna
def make(
cls,
pipe_category: Any,
+ *,
pipe_type: str,
pipe_code: str,
domain_code: str,
diff --git a/pipelex/pipe_signature/signature_walk.py b/pipelex/pipe_signature/signature_walk.py
index 19136a27c..bacb3a874 100644
--- a/pipelex/pipe_signature/signature_walk.py
+++ b/pipelex/pipe_signature/signature_walk.py
@@ -11,7 +11,7 @@ from pipelex.core.pipes.pipe_abstract import PipeAbstract
from pipelex.hub import get_optional_pipe
-def collect_signature_refs(pipe: PipeAbstract, visited: set[str] | None = None) -> set[str]:
+def collect_signature_refs(pipe: PipeAbstract, *, visited: set[str] | None = None) -> set[str]:
"""Return the qualified pipe_refs of every signature reachable from `pipe`.
Walks `pipe.pipe_dependencies()`, resolving each dependency via `get_optional_pipe`.
@@ -39,6 +39,7 @@ def collect_signature_refs(pipe: PipeAbstract, visited: set[str] | None = None)
def collect_signature_paths(
pipe: PipeAbstract,
+ *,
current_path: list[str] | None = None,
paths: dict[str, list[str]] | None = None,
) -> dict[str, list[str]]:
@@ -46,8 +47,8 @@ def collect_signature_paths(
Each value is the ordered list of controller pipe_refs traversed (entry-point first).
Keys and path entries are qualified pipe_refs. Companion of `collect_signature_refs`
- used to render the dep chain in `SignaturesNotAllowedError`. When a signature is reachable
- by several paths (a diamond), the longest — most informative — chain is kept.
+ used to render the dep chain that reaches each unimplemented signature. When a signature
+ is reachable by several paths (a diamond), the longest — most informative — chain is kept.
"""
if current_path is None:
current_path = []
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index d5fe41f6b..521bb19b7 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -142,7 +142,7 @@ class Pipelex(metaclass=MetaSingleton):
return f"Config files are missing for the {component_name}. Run `pipelex init config` to generate the missing files."
@staticmethod
- def _get_validation_error_msg(component_name: str, validation_exc: Exception) -> str:
+ def _get_validation_error_msg(*, component_name: str, validation_exc: Exception) -> str:
"""Generate error message for invalid config files."""
msg = ""
cause_exc = validation_exc.__cause__
@@ -164,6 +164,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
def setup(
self,
+ *,
integration_mode: IntegrationMode,
needs_inference: bool = True,
temporal_enabled: bool | None = None,
@@ -349,10 +350,10 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
raise PipelexSetupError(msg) from routing_profile_exc
except InferenceBackendLibraryValidationError as backend_validation_exc:
- msg = self._get_validation_error_msg("inference backend library", backend_validation_exc)
+ msg = self._get_validation_error_msg(component_name="inference backend library", validation_exc=backend_validation_exc)
raise PipelexSetupError(msg) from backend_validation_exc
except ModelDeckValidationError as deck_validation_exc:
- msg = self._get_validation_error_msg("model deck", deck_validation_exc)
+ msg = self._get_validation_error_msg(component_name="model deck", validation_exc=deck_validation_exc)
msg += "\n\nIf you added your own config files to the model deck then you'll have to change them manually."
raise PipelexSetupError(msg) from deck_validation_exc
@@ -510,6 +511,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
@classmethod
def make(
cls,
+ *,
integration_mode: IntegrationMode = IntegrationMode.PYTHON,
needs_inference: bool = True,
temporal_enabled: bool | None = None,
diff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.py
index 137dc10d6..512b2612a 100644
--- a/pipelex/pipeline/bundle_validator.py
+++ b/pipelex/pipeline/bundle_validator.py
@@ -1,7 +1,7 @@
"""The batch validation service (D1) — the explicit home for the validation sweep.
A validation sweep is **not** a run: it is a batch *policy* that *uses* runs. So
-``BundleValidator`` owns the sweep semantics (signature pre-pass, the
+``BundleValidator`` owns the sweep semantics (strict-mode signature exclusion, the
``validate_with_libraries`` wiring check, the per-pipe tolerant
``SUCCESS / FAILURE / SKIPPED`` aggregation, ``allowed_to_fail`` policy) and
**composes** the shared execution seams (``acquire_library`` /
@@ -54,8 +54,6 @@ from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipe_run.pipe_router import PipeRouter
from pipelex.pipe_run.pipe_run import PipeRun
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
-from pipelex.pipe_signature.signature_walk import collect_signature_paths, collect_signature_refs
from pipelex.pipeline.execution_seams import acquire_library, prepare_pipe_job
from pipelex.pipeline.pipeline_factory import PipelineFactory
from pipelex.system.configuration.configs import PipelineExecutionConfig
@@ -157,16 +155,14 @@ class BundleValidator:
"""Sweep every pipe in the already-open **current** library, **without** tearing it down.
The public inner sweep over the active library (D6): the caller owns the library lifecycle —
- this borrows the current library, classifies its pipes, and leaves it loaded. In strict mode
- signatures are excluded (validating one directly would always trip the pre-check); in lenient
- mode they stay (they dry-run trivially by minting a mock). This is the loaded-library twin of
- :meth:`acquire_and_validate` (which acquires + tears down) and the shared core both the
- ``validate --all`` CLI and downstream consumers (e.g. cocode) build on instead of re-deriving
- ``get_pipes`` + signature filtering + ``validate_pipes`` by hand.
+ this borrows the current library, classifies its pipes, and leaves it loaded. Signature
+ filtering is delegated to :meth:`validate_pipes` (the single sweep entry): in strict mode
+ signature pipes are excluded from the sweep; in lenient mode they stay (they dry-run trivially
+ by minting a mock). This is the loaded-library twin of :meth:`acquire_and_validate` (which
+ acquires + tears down) and the shared core both the ``validate --all`` CLI and downstream
+ consumers (e.g. cocode) build on instead of re-deriving ``get_pipes`` + ``validate_pipes`` by hand.
"""
- all_pipes = get_pipe_library().get_pipes()
- pipes = all_pipes if allow_signatures else [pipe for pipe in all_pipes if not pipe.is_signature]
- return await self.validate_pipes(pipes, library_id=get_current_library(), allow_signatures=allow_signatures)
+ return await self.validate_pipes(get_pipe_library().get_pipes(), library_id=get_current_library(), allow_signatures=allow_signatures)
async def validate_pipes(
self,
@@ -177,36 +173,47 @@ class BundleValidator:
) -> dict[str, DryRunOutput]:
"""Classify each pipe ``SUCCESS / FAILURE / SKIPPED`` against an already-open library.
- Borrows the caller's open library and **never tears it down** (D6). Order (D7):
-
- 1. ``validate_with_libraries`` wiring pass (before the signature pre-pass, preserving
- today's error precedence — a wiring error surfaces ahead of a signature error). A
- controller referencing an unloaded cross-package sub-pipe is recorded SKIPPED and dropped
- from the remaining steps rather than aborting the sweep.
- 2. Aggregated signature pre-pass (strict mode): one ``SignaturesNotAllowedError`` listing
- every reached signature, never short-circuiting on the first.
- 3. One ``PIPE_DRY_RUN`` telemetry event for the whole sweep.
- 4. The per-pipe dry-run sweep, classifying each outcome.
- 5. Aggregation: a single ``allowed_to_fail`` match on the namespaced ``pipe_ref`` collecting
+ Borrows the caller's open library and **never tears it down** (D6). Order:
+
+ 1. ``validate_with_libraries`` wiring pass. A controller referencing an unloaded
+ cross-package sub-pipe is recorded SKIPPED and dropped from the remaining steps rather
+ than aborting the sweep.
+ 2. One ``PIPE_DRY_RUN`` telemetry event for the whole sweep.
+ 3. The per-pipe dry-run sweep, classifying each outcome.
+ 4. Aggregation: a single ``allowed_to_fail`` match on the namespaced ``pipe_ref`` collecting
**all** unexpected failures into one ``DryRunError`` (never a per-pipe early abort).
- Returns the per-pipe status map (carrying allowed failures + skips). Raises
- ``SignaturesNotAllowedError`` (strict mode) or ``DryRunError`` (≥1 unexpected failure).
+ Signatures are **never an error** (D-B): ``allow_signatures`` is a sweep-mechanics flag, not a
+ verdict. In strict mode (``allow_signatures=False``) signature pipes are excluded from the
+ sweep up front — not mock-run, absent from the returned status map (and so from
+ ``validated_pipes``). In lenient mode they stay and dry-run trivially by minting a mock. Either
+ way the unsatisfied set is reported library-wide via ``pending_signatures`` + ``is_runnable``
+ by the caller, and the "is this a failure?" decision is the consumer's (the CLI exit-code gate;
+ the HTTP caller reading ``is_runnable``). A non-signature pipe that *reaches* a signature
+ dry-runs trivially in both modes (the signature mints a mock), so it is never a failure here.
+
+ Returns the per-pipe status map (carrying allowed failures + skips). Raises ``DryRunError``
+ on ≥1 unexpected failure.
"""
start_time = time.time()
+ # allow_signatures is the sweep-mechanics flag (D-B): in strict mode signature pipes are
+ # excluded from the sweep entirely (not mock-run, absent from validated_pipes); in lenient
+ # mode they stay and dry-run trivially. Filter up front so a signature pipe is dropped from
+ # BOTH the wiring check and the dry-run sweep — never raised on, never an error.
+ sweep_candidates = pipes if allow_signatures else [pipe for pipe in pipes if not pipe.is_signature]
+
# 1. Static library-wiring check. This is *more* than a dry run (the runner's DRY path does
# not perform it) — keeping it here preserves coverage and removes the old redundancy where
# both `validate --all` and the per-pipe dry run called it. A controller whose branch
# references an UNLOADED cross-package sub-pipe (PipeParallel / PipeBatch / PipeCondition
# resolve their sub-pipes with an unguarded get_required_pipe) raises PipeNotFoundError here.
# Same-package gaps already hard-fail earlier at library load, so the only case reaching this
- # catch is the intended cross-package one — record it SKIPPED and drop it from BOTH the
- # signature pre-pass and the sweep, matching the old per-pipe dry-run's PipeNotFoundError
- # tolerance instead of aborting the whole sweep (preserves the D7 wiring-before-signature order).
+ # catch is the intended cross-package one — record it SKIPPED and drop it from the sweep,
+ # matching the old per-pipe dry-run's PipeNotFoundError tolerance instead of aborting the sweep.
sweepable_pipes: list[PipeAbstract] = []
results: dict[str, DryRunOutput] = {}
- for pipe in pipes:
+ for pipe in sweep_candidates:
try:
pipe.validate_with_libraries()
except PipeNotFoundError as not_found_error:
@@ -218,21 +225,10 @@ class BundleValidator:
continue
sweepable_pipes.append(pipe)
- # 2. Aggregated signature pre-pass (strict mode only). Run over the FULL `pipes` list — NOT just
- # the wiring survivors — so a pipe dropped to SKIPPED in step 1 for an unresolved cross-package
- # dependency still gets its signatures checked. Otherwise an unimplemented PipeSignature reached
- # through a resolved branch of a pipe whose OTHER branch has a wiring gap would silently pass
- # strict validation (collect_signature_refs tolerates the unresolved branch via get_optional_pipe,
- # so it still finds the signature). This restores the old dry_run_pipes precedence: the signature
- # pre-pass ran over all pipes, before the per-pipe SKIPPED tolerance. A wiring-SKIPPED pipe with no
- # signature is unaffected (the pre-pass finds nothing for it and it stays SKIPPED).
- if not allow_signatures:
- self._signature_pre_pass(pipes=pipes)
-
- # 3. One validation telemetry event per sweep (relocated from the CLI's _validate_core).
+ # 2. One validation telemetry event per sweep (relocated from the CLI's _validate_core).
get_telemetry_manager().track_event(event_name=EventName.PIPE_DRY_RUN, properties={EventProperty.NB_PIPES: len(sweepable_pipes)})
- # 4. The dry-run sweep. Each pipe is dry-run under a UNIQUE per-sweep pipeline run id (a
+ # 3. The dry-run sweep. Each pipe is dry-run under a UNIQUE per-sweep pipeline run id (a
# `dry_run_`-prefixed uuid, not a constant — self-describing if it ever surfaces in a log).
# The DRY leaf emits a synthetic zero-token LLM report; with the live registry gone (usage now
# rides on PipeOutput) the sweep accumulates no per-run state on the process-global reporting
@@ -263,40 +259,9 @@ class BundleValidator:
pipe=pipe, library_id=library_id, execution_config=execution_config, dry_run_pipeline_id=dry_run_pipeline_id
)
- # 5. Aggregate + report.
+ # 4. Aggregate + report.
return self._aggregate(results=results, start_time=start_time)
- @classmethod
- def _signature_pre_pass(cls, pipes: list[PipeAbstract]) -> None:
- """Walk the selected pipes; raise one aggregated ``SignaturesNotAllowedError`` if any reached.
-
- Aggregates across all pipes so the user sees every offender (and the longest, most informative
- dep chain per signature) in a single error, rather than only the first one to fail.
- """
- all_signature_refs: set[str] = set()
- all_dep_paths: dict[str, list[str]] = {}
- offending_pipe_refs: set[str] = set()
- for pipe in pipes:
- sig_refs = collect_signature_refs(pipe=pipe)
- if not sig_refs:
- continue
- # A signature is the placeholder itself, not an offender that "depends on" one.
- if not pipe.is_signature:
- offending_pipe_refs.add(pipe.pipe_ref)
- all_signature_refs.update(sig_refs)
- for sig_ref, path in collect_signature_paths(pipe=pipe).items():
- # Prefer the longest known dep chain so the error shows the most informative path
- # (a chain rooted at a controller beats an empty chain rooted at the signature itself).
- existing = all_dep_paths.get(sig_ref)
- if existing is None or len(path) > len(existing):
- all_dep_paths[sig_ref] = path
- if all_signature_refs:
- raise SignaturesNotAllowedError(
- offending_pipe_refs=offending_pipe_refs,
- signature_refs=all_signature_refs,
- dep_paths=all_dep_paths,
- )
-
async def _classify_pipe(
self, *, pipe: PipeAbstract, library_id: str, execution_config: PipelineExecutionConfig, dry_run_pipeline_id: str
) -> DryRunOutput:
diff --git a/pipelex/pipeline/dry_run_pipeline.py b/pipelex/pipeline/dry_run_pipeline.py
index 6d13989d0..655a03711 100644
--- a/pipelex/pipeline/dry_run_pipeline.py
+++ b/pipelex/pipeline/dry_run_pipeline.py
@@ -25,6 +25,7 @@ from pipelex.tracing.in_memory_event_log import InMemoryEventLog
async def dry_run_pipeline(
mthds_contents: list[str] | None = None,
+ *,
bundle_uris: list[str] | None = None,
library_dirs: list[str] | None = None,
) -> tuple[GraphSpec, str]:
diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.py
index b15a1976c..567c46d6a 100644
--- a/pipelex/pipeline/exceptions.py
+++ b/pipelex/pipeline/exceptions.py
@@ -5,7 +5,7 @@ from pipelex.cogt.inference.error_classification import UserAction, UserActionKi
from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData
from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
+from pipelex.pipeline.validation_errors import build_validation_error_items
class PipeExecutionError(PipelexError):
@@ -77,8 +77,11 @@ class ValidateBundleError(PipelexError):
- Pipe factory errors (from PipeFactoryError exceptions, e.g., missing concepts)
- Pipe validation errors (from PipeValidationError exceptions)
- Pipe/Concept instantiation errors (from Pydantic ValidationError during factory instantiation)
- - Dry run errors
- - Signature pre-check errors (strict-mode validation refused due to PipeSignature placeholders)
+ - Dry run errors (the residual message, projected as one ``dry_run`` item by the shared builder)
+
+ Signatures are **never** an error (D-B): an unimplemented ``PipeSignature`` reached during
+ validation is a runnability fact (reported library-wide via the report's ``pending_signatures``
+ + ``is_runnable``), not a validation failure — so this error no longer carries a signature channel.
All errors are categorized and stored in their respective lists.
"""
@@ -100,7 +103,6 @@ class ValidateBundleError(PipelexError):
pipe_validation_errors: list[PipesAndConceptValidationErrorData] | None = None,
pipe_concept_instantiation_errors: list[PipesAndConceptValidationErrorData] | None = None,
dry_run_error_message: str | None = None,
- signature_check_error: SignaturesNotAllowedError | None = None,
):
self.pipelex_bundle_blueprint_validation_errors = pipelex_bundle_blueprint_validation_errors or []
self.pipe_factory_errors = pipe_factory_errors or []
@@ -112,9 +114,6 @@ class ValidateBundleError(PipelexError):
self.dry_run_error_message = dry_run_error_message
- # Signature pre-check error (strict-mode validation refused due to PipeSignature placeholders)
- self.signature_check_error = signature_check_error
-
super().__init__(message)
@property
@@ -126,6 +125,41 @@ class ValidateBundleError(PipelexError):
# TODO: refactor so we don't need this anymore?
return self.pipe_validation_errors + self.pipe_concept_instantiation_errors
+ @override
+ def to_error_report(self) -> ErrorReport:
+ """Attach the structured ``validation_errors`` list onto the base report.
+
+ ``super().to_error_report()`` builds the report and enriches it from the
+ ``__cause__`` chain; this override then attaches the per-error structured
+ list — the same items the agent CLI emits, via the shared
+ ``build_validation_error_items`` builder — so the API 422 problem
+ document carries machine-mappable diagnostics. The list is set to
+ ``None`` when empty so it drops out of the ``exclude_none`` wire
+ projection (and the round-trip stays identical to a plain report).
+
+ The pipe-validation arm uses :attr:`pipe_validation_error_data` (pipe
+ validation **plus** pipe/concept instantiation errors) so the
+ instantiation category is not silently dropped from the wire. The
+ ``dry_run_error_message`` channel is a single message, not per-error data
+ with identity fields, so the shared builder projects it as one
+ ``dry_run``-category item **only** when no categorized error has data.
+ Finally ``fallback_message=self.message`` is passed so a parse-level
+ failure (TOML syntax, an empty blueprint, a bundle elaborator) — which
+ carries only a message — still surfaces one ``blueprint_validation``
+ residual item. Together these make the structured-info invariant
+ **total**: an invalid verdict never rides a bare ``detail`` with an empty
+ ``validation_errors[]``.
+ """
+ report = super().to_error_report()
+ validation_error_items = build_validation_error_items(
+ blueprint_errors=self.pipelex_bundle_blueprint_validation_errors,
+ factory_errors=self.pipe_factory_errors,
+ pipe_validation_errors=self.pipe_validation_error_data,
+ dry_run_error_message=self.dry_run_error_message,
+ fallback_message=self.message,
+ )
+ return report.model_copy(update={"validation_errors": validation_error_items or None})
+
class PipeIOContractError(PipelexError):
"""Raised when projecting a validated pipe into its `pipe_io_contracts` IO contract fails.
diff --git a/pipelex/pipeline/input_normalizer.py b/pipelex/pipeline/input_normalizer.py
index 48ef3fa68..c0423bdcd 100644
--- a/pipelex/pipeline/input_normalizer.py
+++ b/pipelex/pipeline/input_normalizer.py
@@ -60,6 +60,7 @@ async def normalize_data_urls_to_storage(working_memory: WorkingMemory) -> Worki
async def _normalize_value(
value: Any,
+ *,
storage: StorageProviderAbstract,
) -> tuple[Any, bool]:
"""Recursively normalize a value, converting data URLs in ImageContent/DocumentContent to storage URIs.
@@ -94,6 +95,7 @@ async def _normalize_value(
async def _normalize_structured_content(
structured_content: StructuredContent,
+ *,
storage: StorageProviderAbstract,
) -> tuple[StructuredContent, bool]:
"""Normalize a StructuredContent by recursively processing all its fields.
@@ -124,6 +126,7 @@ async def _normalize_structured_content(
async def _normalize_list_content(
list_content: ListContent[Any],
+ *,
storage: StorageProviderAbstract,
) -> tuple[ListContent[Any], bool]:
"""Normalize a ListContent by processing all its items.
@@ -157,6 +160,7 @@ async def _normalize_list_content(
async def _normalize_list(
items: list[Any],
+ *,
storage: StorageProviderAbstract,
) -> tuple[list[Any], bool]:
"""Normalize a list by processing all its items.
@@ -182,6 +186,7 @@ async def _normalize_list(
async def _normalize_url_content(
content: NormalizableContent,
+ *,
storage: StorageProviderAbstract,
) -> NormalizableContent:
"""Normalize ImageContent or DocumentContent by converting data URLs to storage URIs.
diff --git a/pipelex/pipeline/job_metadata.py b/pipelex/pipeline/job_metadata.py
index 3107490f3..914c21711 100644
--- a/pipelex/pipeline/job_metadata.py
+++ b/pipelex/pipeline/job_metadata.py
@@ -88,6 +88,7 @@ class JobMetadata(BaseModel):
def copy_with_update(
self,
+ *,
otel_context: OtelContext | None,
trace_context: TraceContext | None = None,
**updates: Any,
diff --git a/pipelex/pipeline/pipeline_manager.py b/pipelex/pipeline/pipeline_manager.py
index 47faa7a9d..f772b62a9 100644
--- a/pipelex/pipeline/pipeline_manager.py
+++ b/pipelex/pipeline/pipeline_manager.py
@@ -32,12 +32,12 @@ class PipelineManager(PipelineManagerAbstract, RootModel[PipelineManagerRoot]):
raise PipelineManagerNotFoundError(msg)
return pipeline
- def _set_pipeline(self, pipeline_run_id: str, pipeline: Pipeline) -> Pipeline:
+ def _set_pipeline(self, pipeline_run_id: str, *, pipeline: Pipeline) -> Pipeline:
self.root[pipeline_run_id] = pipeline
return pipeline
@override
- def add_new_pipeline(self, pipe_code: str | None, pipeline_run_id: str | None = None) -> Pipeline:
+ def add_new_pipeline(self, pipe_code: str | None, *, pipeline_run_id: str | None = None) -> Pipeline:
if pipeline_run_id is not None and pipeline_run_id in self.root:
msg = f"Pipeline {pipeline_run_id} already exists"
raise PipelineManagerAlreadyExistsError(msg)
diff --git a/pipelex/pipeline/pipeline_manager_abstract.py b/pipelex/pipeline/pipeline_manager_abstract.py
index 3e756cefe..16605f841 100644
--- a/pipelex/pipeline/pipeline_manager_abstract.py
+++ b/pipelex/pipeline/pipeline_manager_abstract.py
@@ -21,7 +21,7 @@ class PipelineManagerAbstract(ABC):
pass
@abstractmethod
- def add_new_pipeline(self, pipe_code: str | None, pipeline_run_id: str | None = None) -> Pipeline:
+ def add_new_pipeline(self, pipe_code: str | None, *, pipeline_run_id: str | None = None) -> Pipeline:
pass
@abstractmethod
diff --git a/pipelex/pipeline/pipeline_response.py b/pipelex/pipeline/pipeline_response.py
index e6bb3d2b3..43b9f492c 100644
--- a/pipelex/pipeline/pipeline_response.py
+++ b/pipelex/pipeline/pipeline_response.py
@@ -36,6 +36,7 @@ class PipelexRunResultExecute(RunResultExecute[PipeOutput]):
def from_pipe_output(
cls,
pipe_output: PipeOutput,
+ *,
pipeline_run_id: str = "",
created_at: str = "",
state: RunState = RunState.COMPLETED,
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index 4942d408c..f2b75fa6d 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -42,6 +42,7 @@ if TYPE_CHECKING:
async def pipeline_run_setup(
execution_config: PipelineExecutionConfig,
+ *,
library_id: str | None = None,
library_dirs: list[str] | None = None,
pipe_code: str | None = None,
diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.py
index faa4d48cb..a2f7ba6aa 100644
--- a/pipelex/pipeline/runner.py
+++ b/pipelex/pipeline/runner.py
@@ -14,7 +14,6 @@ from mthds.protocol.protocol import PROTOCOL_VERSION, MTHDSProtocol
from pydantic import Field, ValidationError
from typing_extensions import override
-from pipelex import log
from pipelex.base_exceptions import PipelexError
from pipelex.builder.operations.models_ops import ModelCategory, list_models
from pipelex.config import get_config
@@ -29,15 +28,11 @@ from pipelex.hub import (
get_telemetry_manager,
set_current_library,
)
-from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec
from pipelex.pipe_run.exceptions import PipeRouterError
-from pipelex.pipeline.blueprint_selection import select_primary_blueprint
from pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionError
-from pipelex.pipeline.pipe_io_contracts import PipeIOContract, build_pipe_io_contracts
from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRunResultStart, RunState
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
-from pipelex.pipeline.validate_bundle import validate_bundle
-from pipelex.pipeline.validation_report import PipelexValidationReport, build_validation_report
+from pipelex.pipeline.validate_in_process import validate_bundles_in_process
from pipelex.system.telemetry.events import EventName, EventProperty, Outcome
from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error
@@ -50,11 +45,11 @@ if TYPE_CHECKING:
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.pipe_output import PipeOutput
- from pipelex.graph.graphspec import GraphSpec
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
+ from pipelex.pipeline.validation_report import PipelexValidationReport
from pipelex.system.configuration.configs import PipelineExecutionConfig
@@ -350,9 +345,12 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
verdict — `pending_signatures` (qualified refs of pipes still declared
as `PipeSignature` in the assembled library) plus
`is_runnable = not pending_signatures`, the same convention as the
- agent-CLI / builder validate envelopes. The verdict only matters on the
- lenient `allow_signatures=True` path: in strict mode an unsatisfied
- signature makes `validate_bundle` raise instead.
+ agent-CLI / builder validate envelopes. Signatures are never a validation
+ error (D-B): strict and lenient return the same report body — `allow_signatures`
+ only controls whether signature pipes are mock-run and listed in
+ `validated_pipes`, not the verdict. The "is an unsatisfied signature a
+ failure?" decision is the consumer's (the CLI gates its exit code on
+ `is_runnable`; this protocol method just reports it).
`graph_spec` is best-effort: when the batch declares a `main_pipe`
(primary-selection rule: first blueprint declaring one), it is dry-run
@@ -376,67 +374,17 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
PipelexError: When the bundle is invalid (parse, static validation, or dry-run failure).
"""
library_dirs = [Path(library_dir) for library_dir in self.library_dirs] if self.library_dirs else None
- # `validate_bundle` deliberately leaves its validation library OPEN and
- # current on success (the CLI surfaces consume it before process exit).
- # This protocol wrapper is a long-lived entry point, so restore the
- # caller's current-library and tear the validation library down on the
- # way out — on failure `validate_bundle` already did both, so
- # `validation_library_id` stays None and the cleanup below is a no-op.
- # Artifacts that need the open validation library are built INSIDE the
- # window, before the `finally` tears the library down:
- # `pipe_io_contracts`'s JSON-Schema rendering resolves bundle-defined
- # structure classes through the class registry, and the graph arm
- # dry-runs the main pipe against the loaded library.
- prev_library_id = get_current_library_id_or_none()
- validation_library_id: str | None = None
- # Explicit body-success flag — NOT sys.exc_info() in the finally, which also sees an
- # exception the CALLER is currently handling (validate awaited inside an except block)
- # and would wrongly suppress a genuine teardown failure after a successful body.
- body_succeeded = False
- try:
- result = await validate_bundle(
- mthds_contents=mthds_contents,
- library_dirs=library_dirs,
- allow_signatures=allow_signatures,
- )
- # Capture the validation library id ONCE, right after validate_bundle leaves
- # it current — the graph arm and the finally must target the SAME library
- # even if something inside the window later moves the contextvar.
- validation_library_id = get_current_library_id_or_none()
- pipe_io_contracts: dict[str, PipeIOContract] = build_pipe_io_contracts(result.pipes)
- graph_spec: GraphSpec | None = await best_effort_graph_spec(
- pipe_ref=select_primary_blueprint(result.blueprints).main_pipe_ref,
- library_id=validation_library_id,
- log_context="Protocol validate",
- )
- body_succeeded = True
- finally:
- if validation_library_id is not None and validation_library_id != prev_library_id:
- # Restore the caller's outer current-library FIRST so the guarantee
- # survives a teardown raise — mirrors act_dry_validate.
- if prev_library_id is not None:
- set_current_library(library_id=prev_library_id)
- else:
- clear_current_library()
- try:
- get_library_manager().teardown(library_id=validation_library_id)
- except PipelexError as teardown_error:
- # A teardown failure must not REPLACE the body's in-flight error (the
- # caller's error would name the teardown instead of the actual problem) —
- # suppress it and let the primary propagate; raise it only when the body
- # succeeded. Mirrors act_dry_validate's finally.
- if body_succeeded:
- raise
- log.error(
- f"Protocol validate: library teardown also failed after a body error; "
- f"raising the original error. Suppressed teardown error: {teardown_error}"
- )
- return build_validation_report(
- blueprints=result.blueprints,
- pipe_io_contracts=pipe_io_contracts,
- dry_run_result=result.dry_run_result,
- pending_signatures=result.pending_signatures,
- graph_spec=graph_spec,
+ # Delegate to the shared in-process orchestrator (library-window management,
+ # graph arm, report assembly). The protocol `validate` interface carries only
+ # sourceless content strings, so `mthds_sources` stays `None` and `blueprint.source`
+ # is `None` on this path. (The CLI's disk path populates `source` from the real
+ # file path via a separate `validate_bundle(mthds_file_path=…)` entry point that
+ # does not route through this orchestrator.)
+ return await validate_bundles_in_process(
+ mthds_contents=mthds_contents,
+ library_dirs=library_dirs,
+ allow_signatures=allow_signatures,
+ log_context="Protocol validate",
)
@override
diff --git a/pipelex/pipeline/validate_bundle.py b/pipelex/pipeline/validate_bundle.py
index c1340d71f..b7184bd4a 100644
--- a/pipelex/pipeline/validate_bundle.py
+++ b/pipelex/pipeline/validate_bundle.py
@@ -11,6 +11,7 @@ from pydantic import BaseModel, ValidationError
from typing_extensions import TypedDict, assert_never
from pipelex import log
+from pipelex.base_exceptions import PipelexUnexpectedError
from pipelex.core.bundles.pipelex_bundle_blueprint import PipelexBundleBlueprint
from pipelex.core.concepts.concept import Concept
from pipelex.core.interpreter.exceptions import PipelexInterpreterError
@@ -35,7 +36,6 @@ from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError
from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_run.exceptions import DryRunError, PipeRunError
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunOutput, DryRunStatus
from pipelex.pipeline.exceptions import ValidateBundleError
@@ -104,9 +104,9 @@ def _translate_to_validate_bundle_error(category: Literal["pipe", "concept"]) ->
``PipeFactoryError`` carries the categorized factory error, etc. Sharing one
source of truth means a new handler only needs to be added once. The
pipe-loading / dry-run handlers (``PipeFactoryError``, ``PipeValidationError``,
- ``PipeRunError``, ``DryRunError``, ``SignaturesNotAllowedError``) are dead code
- in the concepts-only paths (those functions never instantiate pipes or run dry
- runs), but they are harmless there — they simply never fire.
+ ``PipeRunError``, ``DryRunError``) are dead code in the concepts-only paths
+ (those functions never instantiate pipes or run dry runs), but they are
+ harmless there — they simply never fire.
``category`` controls the user-facing framing for the one branch that fires
from both paths: the ``except ValidationError`` arm catches pydantic
@@ -191,24 +191,16 @@ def _translate_to_validate_bundle_error(category: Literal["pipe", "concept"]) ->
message=dry_run_error.message,
dry_run_error_message=dry_run_error.message,
) from dry_run_error
- except SignaturesNotAllowedError as sig_error:
- # Strict-mode dry-run refused because the dependency graph reaches a
- # ``PipeSignature`` placeholder. Carry the error so the CLI can render the
- # offending signatures and the dependency chains that reach them.
- raise ValidateBundleError(
- message=str(sig_error),
- signature_check_error=sig_error,
- ) from sig_error
-def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], dry_run_pipe_codes: list[str] | None) -> list[PipeAbstract]:
+def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], *, dry_run_pipe_codes: list[str] | None) -> list[PipeAbstract]:
"""Select which loaded pipes to dry-run.
Returns every loaded pipe when ``dry_run_pipe_codes`` is ``None`` (whole-bundle validation).
Otherwise returns only the pipes whose bare ``code`` or qualified ``pipe_ref`` is requested —
used by the ``--pipe`` path to validate a single implemented slice of a partially stubbed
- bundle without dry-running (and thus rejecting) unrelated pipes or signatures. Filtering here,
- before ``BundleValidator.validate_pipes``, also narrows its strict signature pre-check to just the selected pipe.
+ bundle without dry-running unrelated pipes. Filtering here, before ``BundleValidator.validate_pipes``,
+ narrows the dry-run sweep to just the selected pipe (signatures are never an error either way — D-B).
Raises:
PipeNotFoundError: when ``dry_run_pipe_codes`` names a pipe absent from the loaded bundle —
@@ -229,7 +221,9 @@ def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], dry_run_pipe_codes: list
async def validate_bundle(
mthds_file_path: Path | None = None,
+ *,
mthds_contents: list[str] | None = None,
+ mthds_sources: list[str] | None = None,
library_dirs: Sequence[Path] | None = None,
allow_signatures: bool = False,
dry_run_pipe_codes: list[str] | None = None,
@@ -241,17 +235,31 @@ async def validate_bundle(
]
)
if provided_params == 0:
+ # Programmer error: a caller (the HTTP request layer, a builder op) must wire exactly one
+ # input. It is not a content verdict the end user can fix → PipelexUnexpectedError (→ 500,
+ # redacted under STRICT), matching the mthds_sources-mismatch guard below — never a
+ # ValidateBundleError, which would 200/422 a host-wiring bug as if the bundle were invalid.
msg = "At least one of mthds_contents or mthds_file_path must be provided to validate_bundle"
- raise ValidateBundleError(message=msg)
+ raise PipelexUnexpectedError(msg)
if provided_params > 1:
msg = "Only one of mthds_contents or mthds_file_path can be provided to validate_bundle, not both"
- raise ValidateBundleError(message=msg)
+ raise PipelexUnexpectedError(msg)
if mthds_contents is not None and not mthds_contents:
# An EMPTY list is not None, so it passes the provided-params check above — without this
# guard it would yield a blueprint-less result that downstream consumers (the canonical
# report's primary-blueprint selection) cannot represent.
msg = "mthds_contents must not be empty: provide at least one MTHDS content to validate"
raise ValidateBundleError(message=msg)
+ if mthds_sources is not None and (mthds_contents is None or len(mthds_sources) != len(mthds_contents)):
+ # ``mthds_sources`` is a per-content source list (the host — e.g. an HTTP API —
+ # threads each bundle's source onto the in-memory load path so its diagnostics carry a
+ # real ``source``). It is never supplied by the end caller, so a missing-alongside /
+ # length-mismatch is a host wiring bug, not bad user input: raise an internal error
+ # (→ 500, redacted under STRICT) rather than ``ValidateBundleError`` (→ caller-facing
+ # 422). Contrast the empty-``mthds_contents`` guard above, which can legitimately
+ # reflect an end user submitting no bundles and so stays a caller-facing input error.
+ msg = "mthds_sources, when provided, must be a per-item source list matching mthds_contents in length"
+ raise PipelexUnexpectedError(msg)
library_manager = get_library_manager()
library_id, library = library_manager.open_library()
@@ -276,10 +284,16 @@ async def validate_bundle(
else:
log.verbose(f"No library directories to load ({source_label})")
if mthds_contents is not None:
- loaded_blueprints = [PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=content) for content in mthds_contents]
+ content_sources: list[str | None] = list(mthds_sources) if mthds_sources is not None else [None] * len(mthds_contents)
+ loaded_blueprints = [
+ PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=content, mthds_source=source)
+ for content, source in zip(mthds_contents, content_sources, strict=True)
+ ]
loaded_pipes = library_manager.load_from_blueprints(library_id=library_id, blueprints=loaded_blueprints)
dry_run_results = await BundleValidator().validate_pipes(
- pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes), library_id=library_id, allow_signatures=allow_signatures
+ pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes=dry_run_pipe_codes),
+ library_id=library_id,
+ allow_signatures=allow_signatures,
)
result = ValidateBundleResult(
blueprints=loaded_blueprints,
@@ -302,7 +316,9 @@ async def validate_bundle(
loaded_pipes = [library.pipe_library.get_required_pipe(pipe_code=code) for code in pipe_codes]
dry_run_results = await BundleValidator().validate_pipes(
- pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes), library_id=library_id, allow_signatures=allow_signatures
+ pipes=_pipes_to_dry_run(loaded_pipes, dry_run_pipe_codes=dry_run_pipe_codes),
+ library_id=library_id,
+ allow_signatures=allow_signatures,
)
result = ValidateBundleResult(
blueprints=loaded_blueprints,
@@ -327,7 +343,7 @@ async def validate_bundle(
library_manager.teardown(library_id=library_id)
-async def validate_bundles_from_directory(directory: Path, allow_signatures: bool = False) -> ValidateBundleResult:
+async def validate_bundles_from_directory(directory: Path, *, allow_signatures: bool = False) -> ValidateBundleResult:
mthds_files = get_pipelex_mthds_files_from_dirs(dirs={directory})
all_blueprints: list[PipelexBundleBlueprint] = []
@@ -372,6 +388,7 @@ class LoadConceptsOnlyResult(BaseModel):
def load_concepts_only(
mthds_file_path: Path | None = None,
+ *,
mthds_contents: list[str] | None = None,
library_dirs: Sequence[Path] | None = None,
) -> LoadConceptsOnlyResult:
@@ -394,11 +411,13 @@ def load_concepts_only(
"""
provided_params = sum([mthds_contents is not None, mthds_file_path is not None])
if provided_params == 0:
+ # Programmer error (see validate_bundle's twin guard): the caller must wire exactly one
+ # input. Not a content verdict → PipelexUnexpectedError (→ 500), never ValidateBundleError.
msg = "At least one of mthds_contents or mthds_file_path must be provided to load_concepts_only"
- raise ValidateBundleError(message=msg)
+ raise PipelexUnexpectedError(msg)
if provided_params > 1:
msg = "Only one of mthds_contents or mthds_file_path can be provided to load_concepts_only, not both"
- raise ValidateBundleError(message=msg)
+ raise PipelexUnexpectedError(msg)
library_manager = get_library_manager()
library_id, library = library_manager.open_library()
diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.py
new file mode 100644
index 000000000..d6c9a9657
--- /dev/null
+++ b/pipelex/pipeline/validate_in_process.py
@@ -0,0 +1,138 @@
+"""In-process orchestration for the protocol `validate` operation.
+
+`validate_bundles_in_process` is the single in-process implementation of `validate`,
+shared by every Pipelex backend that runs the sweep locally: the local runtime
+(`PipelexMTHDSProtocol.validate`) and the hosted API's direct (non-Temporal) path
+(`ApiRunner.validate`). Keeping it in one place means the load-bearing library-window
+management — `validate_bundle` leaves its validation library OPEN on success, and this
+long-lived entry point must restore the caller's current-library and tear the validation
+library down — lives once, so the two backends cannot drift on teardown semantics.
+
+The `mthds_sources` parameter is the in-memory source-threading hook: the API submits
+sourceless bundle text (`mthds_contents: list[str]`), so without per-content sources
+`blueprint.source` is `None` and cross-file diagnostics misfire. Threading sources here lands
+them on `blueprint.source` for both the success path and the categorized
+`ValidateBundleError` (whose per-error `source` the extension maps to the owning file). The
+local protocol runtime passes `None` — its `validate` interface carries only sourceless
+content strings, so `blueprint.source` stays `None` on that path too. (The CLI populates
+`source` from the real file path via a separate `validate_bundle(mthds_file_path=…)` entry
+point that bypasses this orchestrator.)
+"""
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pipelex import log
+from pipelex.base_exceptions import PipelexError
+from pipelex.hub import (
+ clear_current_library,
+ get_current_library_id_or_none,
+ get_library_manager,
+ set_current_library,
+)
+from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec
+from pipelex.pipeline.blueprint_selection import select_primary_blueprint
+from pipelex.pipeline.pipe_io_contracts import PipeIOContract, build_pipe_io_contracts
+from pipelex.pipeline.validate_bundle import validate_bundle
+from pipelex.pipeline.validation_report import PipelexValidationReport, build_validation_report
+
+if TYPE_CHECKING:
+ from pipelex.graph.graphspec import GraphSpec
+
+
+async def validate_bundles_in_process(
+ *,
+ mthds_contents: list[str],
+ mthds_sources: list[str] | None = None,
+ library_dirs: Sequence[Path] | None = None,
+ allow_signatures: bool = False,
+ log_context: str = "validate",
+) -> PipelexValidationReport:
+ """Parse, validate, and dry-run MTHDS bundles in-process; assemble the canonical report.
+
+ Wraps `validate_bundle` and assembles its result into the canonical
+ `PipelexValidationReport` via `build_validation_report`: the primary
+ `bundle_blueprint`, `pipe_io_contracts` keyed by namespaced `pipe_ref`, the per-pipe
+ `validated_pipes` sweep outcomes, and the runnability verdict — `pending_signatures`
+ plus `is_runnable = not pending_signatures`. `graph_spec` is best-effort: when the batch
+ declares a `main_pipe` it is dry-run in-process against the validation library; a
+ graph-arm domain failure degrades to `graph_spec=None` with validation still successful.
+
+ Args:
+ mthds_contents: MTHDS contents to load (always a list, even for one file).
+ mthds_sources: Optional per-content sources threaded onto `blueprint.source`
+ (length must match `mthds_contents` — `validate_bundle` enforces it). `None`
+ for the local protocol runtime, which receives only sourceless content strings
+ (so `source` stays `None` on that path).
+ library_dirs: Resolved library directories to load before the bundle.
+ allow_signatures: Tolerate unimplemented pipe signatures (strict by default).
+ log_context: Label used in graph-arm degradation and teardown-failure logs.
+
+ Returns:
+ PipelexValidationReport with the structural artifacts of a valid bundle.
+
+ Raises:
+ PipelexError: When the bundle is invalid (parse, static validation, or dry-run failure).
+ """
+ # `validate_bundle` deliberately leaves its validation library OPEN and current on
+ # success (the CLI surfaces consume it before process exit). This entry point is
+ # long-lived, so restore the caller's current-library and tear the validation library
+ # down on the way out — on failure `validate_bundle` already did both, so
+ # `validation_library_id` stays None and the cleanup below is a no-op. Artifacts that
+ # need the open validation library are built INSIDE the window, before the `finally`
+ # tears it down: `pipe_io_contracts`'s JSON-Schema rendering resolves bundle-defined
+ # structure classes through the class registry, and the graph arm dry-runs the main
+ # pipe against the loaded library.
+ prev_library_id = get_current_library_id_or_none()
+ validation_library_id: str | None = None
+ # Explicit body-success flag — NOT sys.exc_info() in the finally, which also sees an
+ # exception the CALLER is currently handling (validate awaited inside an except block)
+ # and would wrongly suppress a genuine teardown failure after a successful body.
+ body_succeeded = False
+ try:
+ result = await validate_bundle(
+ mthds_contents=mthds_contents,
+ mthds_sources=mthds_sources,
+ library_dirs=library_dirs,
+ allow_signatures=allow_signatures,
+ )
+ # Capture the validation library id ONCE, right after validate_bundle leaves it
+ # current — the graph arm and the finally must target the SAME library even if
+ # something inside the window later moves the contextvar.
+ validation_library_id = get_current_library_id_or_none()
+ pipe_io_contracts: dict[str, PipeIOContract] = build_pipe_io_contracts(result.pipes)
+ graph_spec: GraphSpec | None = await best_effort_graph_spec(
+ pipe_ref=select_primary_blueprint(result.blueprints).main_pipe_ref,
+ library_id=validation_library_id,
+ log_context=log_context,
+ )
+ body_succeeded = True
+ finally:
+ if validation_library_id is not None and validation_library_id != prev_library_id:
+ # Restore the caller's outer current-library FIRST so the guarantee survives a
+ # teardown raise — mirrors act_dry_validate.
+ if prev_library_id is not None:
+ set_current_library(library_id=prev_library_id)
+ else:
+ clear_current_library()
+ try:
+ get_library_manager().teardown(library_id=validation_library_id)
+ except PipelexError as teardown_error:
+ # A teardown failure must not REPLACE the body's in-flight error (the
+ # caller's error would name the teardown instead of the actual problem) —
+ # suppress it and let the primary propagate; raise it only when the body
+ # succeeded. Mirrors act_dry_validate's finally.
+ if body_succeeded:
+ raise
+ log.error(
+ f"{log_context}: library teardown also failed after a body error; "
+ f"raising the original error. Suppressed teardown error: {teardown_error}"
+ )
+ return build_validation_report(
+ blueprints=result.blueprints,
+ pipe_io_contracts=pipe_io_contracts,
+ dry_run_result=result.dry_run_result,
+ pending_signatures=result.pending_signatures,
+ graph_spec=graph_spec,
+ )
diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.py
new file mode 100644
index 000000000..b5d950b5b
--- /dev/null
+++ b/pipelex/pipeline/validation_errors.py
@@ -0,0 +1,152 @@
+"""Shared builder that flattens bundle-validation error data into typed wire items.
+
+``build_validation_error_items`` is the single source of truth behind both
+structured-error surfaces:
+
+- the agent CLI's ``validation_errors`` JSON array (via
+ ``pipelex.cli.agent_cli.commands.agent_output.extract_validation_errors``), and
+- the API 422's ``ErrorReport.validation_errors`` (via
+ ``ValidateBundleError.to_error_report``).
+
+Both call this one builder, so the CLI and API structured shapes cannot drift.
+It takes the three categorized error-data lists directly rather than a
+``ValidateBundleError`` instance — that keeps the dependency one-directional
+(``pipelex.pipeline.exceptions`` imports this module, never the reverse) so there
+is no import cycle.
+"""
+
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData
+from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
+
+
+def build_validation_error_items(
+ *,
+ blueprint_errors: list[PipelexBundleBlueprintValidationErrorData],
+ factory_errors: list[PipeFactoryErrorData],
+ pipe_validation_errors: list[PipesAndConceptValidationErrorData],
+ dry_run_error_message: str | None = None,
+ fallback_message: str | None = None,
+) -> list[ValidationErrorItem]:
+ """Flatten a bundle-validation error's categorized lists into typed items.
+
+ Covers the three populated error-data sources a ``ValidateBundleError``
+ aggregates — blueprint validation, pipe-factory, and pipe/concept validation
+ — tagging each item with its :class:`ValidationErrorCategory`. Empty
+ collections collapse to ``None`` so they drop out of the ``exclude_none``
+ wire projection. The ``source`` (declaring file path) rides whenever the
+ underlying error-data model carries it, so a consumer can map each error to
+ its owning file.
+
+ Two residual safety nets make the structured-info invariant **total** — an
+ invalid verdict never rides a bare ``detail`` with an empty
+ ``validation_errors[]``:
+
+ - The ``dry_run`` residual: a dry-run failure (``DryRunError`` /
+ ``PipeRunError``) surfaces only a single message, not per-error data with
+ identity fields. When it is the *only* failure channel (no categorized
+ error has data), it becomes one :class:`ValidationErrorCategory.DRY_RUN`
+ item carrying that message.
+ - The ``fallback_message`` residual: a parse-level failure (a TOML-syntax
+ error, an empty blueprint, a bundle-elaborator failure) surfaces only the
+ error's top-level message, with no categorized data and no dry-run channel.
+ When *nothing else* produced an item, it becomes one
+ :class:`ValidationErrorCategory.BLUEPRINT_VALIDATION` item carrying that
+ message — the bundle could not be turned into a blueprint at all.
+
+ Both residuals are graph/parse-level (the builder has no file context), so
+ they carry no ``source``. They are ordered ``dry_run`` then
+ ``fallback_message`` (most-specific channel first): a dry-run failure that
+ also passes a fallback message must still surface its ``dry_run`` item, and
+ the ``not items`` guard on each block guarantees only one residual fires.
+
+ Args:
+ blueprint_errors: Interpreter / blueprint-validation error data.
+ factory_errors: Pipe-factory error data (e.g. a missing concept).
+ pipe_validation_errors: Pipe/concept validation error data.
+ dry_run_error_message: The residual dry-run failure message, if any. Only
+ projected as a ``dry_run`` item when no categorized error has data.
+ fallback_message: The error's caller-facing message, used as the
+ last-resort residual. Only projected as a ``blueprint_validation``
+ item when no categorized error and no dry-run residual produced one.
+
+ Returns:
+ One :class:`ValidationErrorItem` per underlying error, in the order
+ blueprint → factory → pipe/concept validation, then the ``dry_run`` or
+ (last-resort) ``fallback_message`` residual when it is the sole failure
+ channel.
+ """
+ items: list[ValidationErrorItem] = []
+
+ for blueprint_error in blueprint_errors:
+ items.append(
+ ValidationErrorItem(
+ category=ValidationErrorCategory.BLUEPRINT_VALIDATION,
+ error_type=blueprint_error.error_type,
+ pipe_code=blueprint_error.pipe_code,
+ concept_code=blueprint_error.concept_code,
+ domain_code=blueprint_error.domain_code,
+ source=blueprint_error.source,
+ variable_names=blueprint_error.variable_names or None,
+ message=blueprint_error.message,
+ )
+ )
+
+ for factory_error in factory_errors:
+ items.append(
+ ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_FACTORY,
+ error_type=factory_error.error_type,
+ pipe_code=factory_error.pipe_code,
+ domain_code=factory_error.domain_code,
+ missing_concept_code=factory_error.missing_concept_code,
+ declared_concepts=factory_error.declared_concepts or None,
+ message=factory_error.message,
+ )
+ )
+
+ for pipe_error in pipe_validation_errors:
+ items.append(
+ ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ error_type=pipe_error.error_type,
+ pipe_code=pipe_error.pipe_code,
+ concept_code=pipe_error.concept_code,
+ domain_code=pipe_error.domain_code,
+ source=pipe_error.source,
+ field_path=pipe_error.field_path or None,
+ field_name=pipe_error.field_name,
+ variable_names=pipe_error.variable_names or None,
+ message=pipe_error.message,
+ )
+ )
+
+ # The dry-run residual is the structured-info safety net: emit it only when no categorized
+ # error carries data, so an invalid verdict driven solely by a dry-run failure still surfaces
+ # a non-empty validation_errors[] instead of a bare detail. Graph-level → no source.
+ if not items and dry_run_error_message:
+ items.append(
+ ValidationErrorItem(
+ category=ValidationErrorCategory.DRY_RUN,
+ error_type="DryRunError",
+ message=dry_run_error_message,
+ )
+ )
+
+ # Last-resort residual: a parse-level failure (TOML syntax, an empty blueprint, a bundle
+ # elaborator failure) surfaces only a top-level message — no categorized data and no dry-run
+ # channel. Emit one BLUEPRINT_VALIDATION item carrying that message so an invalid verdict is
+ # NEVER a bare detail with an empty validation_errors[] — the structured-info invariant, now
+ # total. The bundle could not be turned into a blueprint at all, so blueprint_validation is the
+ # right bucket; parse-level → no source, and error_type stays None (the message is
+ # authoritative and the residual fires for several distinct underlying errors). Ordered after
+ # the dry_run residual (the more specific channel); the `not items` guard fires only one.
+ if not items and fallback_message:
+ items.append(
+ ValidationErrorItem(
+ category=ValidationErrorCategory.BLUEPRINT_VALIDATION,
+ message=fallback_message,
+ )
+ )
+
+ return items
diff --git a/pipelex/pipeline/validation_report.py b/pipelex/pipeline/validation_report.py
index a79f69207..ebab5a9ea 100644
--- a/pipelex/pipeline/validation_report.py
+++ b/pipelex/pipeline/validation_report.py
@@ -12,6 +12,7 @@ nowhere. Primary-blueprint selection (`bundle_blueprint`) goes through
"""
from collections.abc import Sequence
+from typing import Literal
from mthds.protocol.models import ValidationReport
from pydantic import Field
@@ -34,6 +35,11 @@ class PipelexValidationReport(ValidationReport):
`pipelex_` prefix inside this already-Pipelex-branded envelope.
"""
+ is_valid: Literal[True] = True
+ """Always `True` on this report — the discriminant of the valid arm of the HTTP response
+ union (mirrored by pipelex-api's `InvalidReport` `Literal[False]`). Self-describing, sits
+ beside `is_runnable`: a sound bundle may still be not-yet-runnable (pending signatures)."""
+
bundle_blueprint: PipelexBundleBlueprint
"""The batch's primary blueprint: first declaring `main_pipe`, else first."""
diff --git a/pipelex/plugins/anthropic/anthropic_config.py b/pipelex/plugins/anthropic/anthropic_config.py
index 1e7a4ab97..20e05d144 100644
--- a/pipelex/plugins/anthropic/anthropic_config.py
+++ b/pipelex/plugins/anthropic/anthropic_config.py
@@ -21,7 +21,7 @@ class AnthropicConfig(ConfigModel):
@field_validator("effort_to_level_map")
@classmethod
def validate_effort_map(cls, value: EffortToLevelMap) -> EffortToLevelMap:
- return validate_effort_to_level_map(value, "anthropic_config", level_type=AnthropicEffortLevel)
+ return validate_effort_to_level_map(value, config_name="anthropic_config", level_type=AnthropicEffortLevel)
def get_reasoning_level(self, effort: ReasoningEffort) -> AnthropicEffortLevel | None:
"""Resolve a ReasoningEffort to an Anthropic effort level.
@@ -30,7 +30,7 @@ class AnthropicConfig(ConfigModel):
The Anthropic effort level string, or None if reasoning is disabled.
"""
- level_str = get_reasoning_level_str(self.effort_to_level_map, effort)
+ level_str = get_reasoning_level_str(effort_to_level_map=self.effort_to_level_map, effort=effort)
if level_str is None:
return None
return AnthropicEffortLevel(level_str)
diff --git a/pipelex/plugins/anthropic/anthropic_factory.py b/pipelex/plugins/anthropic/anthropic_factory.py
index 2b862714b..c2950fa70 100644
--- a/pipelex/plugins/anthropic/anthropic_factory.py
+++ b/pipelex/plugins/anthropic/anthropic_factory.py
@@ -37,6 +37,7 @@ class AnthropicFactory:
@staticmethod
def make_anthropic_client(
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> AsyncAnthropic | AsyncAnthropicBedrock:
try:
@@ -101,7 +102,7 @@ class AnthropicFactory:
return image_block_param
@staticmethod
- def _make_document_block_param(prepped_document: PreparedFile, title: str | None = None) -> DocumentBlockParam:
+ def _make_document_block_param(prepped_document: PreparedFile, *, title: str | None = None) -> DocumentBlockParam:
"""Convert a PreparedFile to an Anthropic DocumentBlockParam."""
document_block_param: DocumentBlockParam
match prepped_document:
@@ -168,6 +169,7 @@ class AnthropicFactory:
def openai_typed_user_message(
cls,
user_content_txt: str,
+ *,
prepped_user_images: list[PreparedFile] | None = None,
prepped_user_documents: list[tuple[PreparedFile, str | None]] | None = None,
) -> "ChatCompletionMessageParam":
@@ -239,7 +241,7 @@ class AnthropicFactory:
return nb_tokens_by_category
@staticmethod
- def make_nb_tokens_by_category_from_nb(nb_input: int, nb_output: int) -> NbTokensByCategoryDict:
+ def make_nb_tokens_by_category_from_nb(*, nb_input: int, nb_output: int) -> NbTokensByCategoryDict:
nb_tokens_by_category: NbTokensByCategoryDict = {
TokenCategory.INPUT: nb_input,
TokenCategory.OUTPUT: nb_output,
diff --git a/pipelex/plugins/anthropic/anthropic_list.py b/pipelex/plugins/anthropic/anthropic_list.py
index b81a35e3c..5d07d1426 100644
--- a/pipelex/plugins/anthropic/anthropic_list.py
+++ b/pipelex/plugins/anthropic/anthropic_list.py
@@ -19,6 +19,7 @@ if TYPE_CHECKING:
async def list_anthropic_models(
sdk: str,
+ *,
backend_name: str,
backend: InferenceBackend,
flat: bool,
@@ -70,6 +71,7 @@ async def list_anthropic_models(
def _display_anthropic_models_flat(
models: list[ModelInfo],
+ *,
sdk: str,
backend_name: str,
any_listed: bool,
@@ -86,6 +88,7 @@ def _display_anthropic_models_flat(
def _display_anthropic_models_table(
models: list[ModelInfo],
+ *,
sdk: str,
backend_name: str,
) -> None:
diff --git a/pipelex/plugins/anthropic/anthropic_llm_worker.py b/pipelex/plugins/anthropic/anthropic_llm_worker.py
index 5d5a8501f..ee533c732 100644
--- a/pipelex/plugins/anthropic/anthropic_llm_worker.py
+++ b/pipelex/plugins/anthropic/anthropic_llm_worker.py
@@ -112,7 +112,7 @@ class AnthropicLLMWorker(LLMWorkerInternalAbstract):
# Instance methods
#########################################################
- def _build_thinking_params(self, job_params: LLMJobParams, max_tokens: int) -> _ThinkingParams:
+ def _build_thinking_params(self, job_params: LLMJobParams, *, max_tokens: int) -> _ThinkingParams:
"""Build thinking-related SDK parameters from job params and model spec.
Args:
@@ -145,6 +145,7 @@ class AnthropicLLMWorker(LLMWorkerInternalAbstract):
def _build_thinking_params_for_effort(
self,
thinking_mode: ThinkingMode,
+ *,
effort: ReasoningEffort,
max_tokens: int,
) -> _ThinkingParams:
@@ -199,6 +200,7 @@ class AnthropicLLMWorker(LLMWorkerInternalAbstract):
def _build_thinking_params_for_budget(
self,
thinking_mode: ThinkingMode,
+ *,
budget: int,
max_tokens: int,
) -> _ThinkingParams:
@@ -307,6 +309,7 @@ class AnthropicLLMWorker(LLMWorkerInternalAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
diff --git a/pipelex/plugins/anthropic/anthropic_llms.py b/pipelex/plugins/anthropic/anthropic_llms.py
index b1f340ccd..621b027e7 100644
--- a/pipelex/plugins/anthropic/anthropic_llms.py
+++ b/pipelex/plugins/anthropic/anthropic_llms.py
@@ -7,7 +7,7 @@ from pipelex.plugins.anthropic.anthropic_factory import AnthropicFactory
from pipelex.plugins.plugin import Plugin
-async def anthropic_list_available_models(plugin: Plugin, backend: InferenceBackend) -> list[ModelInfo]:
+async def anthropic_list_available_models(plugin: Plugin, *, backend: InferenceBackend) -> list[ModelInfo]:
"""List available Anthropic models.
Returns:
diff --git a/pipelex/plugins/azure_rest/azure_img_gen_worker.py b/pipelex/plugins/azure_rest/azure_img_gen_worker.py
index 6160aeb65..5a23f2a7a 100644
--- a/pipelex/plugins/azure_rest/azure_img_gen_worker.py
+++ b/pipelex/plugins/azure_rest/azure_img_gen_worker.py
@@ -104,6 +104,7 @@ class AzureImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
if self.inference_model.rules is None:
@@ -216,7 +217,7 @@ class AzureImgGenWorker(ImgGenWorkerAbstract):
try:
response_dict = response.json()
except json.JSONDecodeError as exc:
- metadata = extract_azure_metadata_from_response(response, type(exc).__name__, message=str(exc))
+ metadata = extract_azure_metadata_from_response(response, sdk_exception_type=type(exc).__name__, message=str(exc))
classification = classify_inference_error(metadata)
raise render_inference_error(
metadata=metadata,
diff --git a/pipelex/plugins/bedrock/bedrock_client_aioboto3.py b/pipelex/plugins/bedrock/bedrock_client_aioboto3.py
index 435d20882..e5b906ac3 100644
--- a/pipelex/plugins/bedrock/bedrock_client_aioboto3.py
+++ b/pipelex/plugins/bedrock/bedrock_client_aioboto3.py
@@ -23,6 +23,7 @@ class BedrockClientAioboto3(BedrockClientProtocol):
async def chat(
self,
messages: BedrockMessageDictList,
+ *,
system_text: str | None,
model: str,
temperature: float,
diff --git a/pipelex/plugins/bedrock/bedrock_client_boto3.py b/pipelex/plugins/bedrock/bedrock_client_boto3.py
index a97cd892f..6b7458457 100644
--- a/pipelex/plugins/bedrock/bedrock_client_boto3.py
+++ b/pipelex/plugins/bedrock/bedrock_client_boto3.py
@@ -19,6 +19,7 @@ class BedrockClientBoto3(BedrockClientProtocol):
async def chat(
self,
messages: BedrockMessageDictList,
+ *,
system_text: str | None,
model: str,
temperature: float,
diff --git a/pipelex/plugins/bedrock/bedrock_client_protocol.py b/pipelex/plugins/bedrock/bedrock_client_protocol.py
index 6ce5290b3..64f90656f 100644
--- a/pipelex/plugins/bedrock/bedrock_client_protocol.py
+++ b/pipelex/plugins/bedrock/bedrock_client_protocol.py
@@ -9,6 +9,7 @@ class BedrockClientProtocol(Protocol):
async def chat(
self,
messages: BedrockMessageDictList,
+ *,
system_text: str | None,
model: str,
temperature: float,
diff --git a/pipelex/plugins/bedrock/bedrock_factory.py b/pipelex/plugins/bedrock/bedrock_factory.py
index ea64d6dca..da869b226 100644
--- a/pipelex/plugins/bedrock/bedrock_factory.py
+++ b/pipelex/plugins/bedrock/bedrock_factory.py
@@ -27,6 +27,7 @@ class BedrockFactory:
def make_bedrock_client(
cls,
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> BedrockClientProtocol:
try:
diff --git a/pipelex/plugins/bedrock/bedrock_list.py b/pipelex/plugins/bedrock/bedrock_list.py
index 8d0ceae98..8e1edc7d6 100644
--- a/pipelex/plugins/bedrock/bedrock_list.py
+++ b/pipelex/plugins/bedrock/bedrock_list.py
@@ -19,6 +19,7 @@ if TYPE_CHECKING:
def list_bedrock_models(
sdk: str,
+ *,
backend_name: str,
backend: InferenceBackend,
flat: bool,
@@ -78,6 +79,7 @@ def list_bedrock_models(
def _display_bedrock_models_flat(
models: list[dict[str, Any]],
+ *,
sdk: str,
backend_name: str,
aws_region: str,
@@ -96,6 +98,7 @@ def _display_bedrock_models_flat(
def _display_bedrock_models_table(
models: list[dict[str, Any]],
+ *,
sdk: str,
aws_region: str,
) -> None:
diff --git a/pipelex/plugins/bedrock/bedrock_llm_worker.py b/pipelex/plugins/bedrock/bedrock_llm_worker.py
index a58ce2dc6..0d83cbbd9 100644
--- a/pipelex/plugins/bedrock/bedrock_llm_worker.py
+++ b/pipelex/plugins/bedrock/bedrock_llm_worker.py
@@ -90,6 +90,7 @@ class BedrockLLMWorker(LLMWorkerInternalAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
# TODO: try with the newest instructor release
diff --git a/pipelex/plugins/bedrock/bedrock_llms.py b/pipelex/plugins/bedrock/bedrock_llms.py
index 52f798c77..35c8beb17 100644
--- a/pipelex/plugins/bedrock/bedrock_llms.py
+++ b/pipelex/plugins/bedrock/bedrock_llms.py
@@ -9,6 +9,7 @@ from pipelex.tools.aws.exceptions import AwsCredentialsError
def bedrock_list_available_models(
plugin: Plugin, # noqa: ARG001
+ *,
backend: InferenceBackend, # noqa: ARG001
) -> list[dict[str, Any]]:
"""List available Bedrock foundation models.
diff --git a/pipelex/plugins/blackboxai/blackboxai_completions_factory.py b/pipelex/plugins/blackboxai/blackboxai_completions_factory.py
index 6153e4e06..8373f8622 100644
--- a/pipelex/plugins/blackboxai/blackboxai_completions_factory.py
+++ b/pipelex/plugins/blackboxai/blackboxai_completions_factory.py
@@ -16,7 +16,7 @@ if TYPE_CHECKING:
class BlackboxaiCompletionsFactory(OpenAICompletionsFactory):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
if isinstance(inference_job, ImgGenJob):
if isinstance(inference_job.job_params.seed, int):
diff --git a/pipelex/plugins/fal/fal_img_gen_worker.py b/pipelex/plugins/fal/fal_img_gen_worker.py
index 4bd8f9f16..9f0e687c8 100644
--- a/pipelex/plugins/fal/fal_img_gen_worker.py
+++ b/pipelex/plugins/fal/fal_img_gen_worker.py
@@ -37,6 +37,7 @@ class FalImgGenWorker(ImgGenWorkerAbstract):
async def _submit_and_get_result(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> Any:
if self.inference_model.rules is None:
@@ -96,6 +97,7 @@ class FalImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
fal_result = await self._submit_and_get_result(img_gen_job=img_gen_job, nb_images=nb_images)
diff --git a/pipelex/plugins/gateway/gateway_completions_factory.py b/pipelex/plugins/gateway/gateway_completions_factory.py
index 7733178a3..c24c2bc35 100644
--- a/pipelex/plugins/gateway/gateway_completions_factory.py
+++ b/pipelex/plugins/gateway/gateway_completions_factory.py
@@ -104,6 +104,7 @@ class GatewayCompletionsFactory(OpenAICompletionsFactory):
def make_portkey_openai_client_for_completions(
cls,
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> openai.AsyncOpenAI:
# Deferred import: avoid pulling heavy SDK at module-load time
@@ -136,6 +137,7 @@ class GatewayCompletionsFactory(OpenAICompletionsFactory):
@classmethod
def make_extract_output_from_response(
cls,
+ *,
inference_model: InferenceModelSpec,
response: GenericResponse,
) -> ExtractOutput:
@@ -365,6 +367,6 @@ class GatewayCompletionsFactory(OpenAICompletionsFactory):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
return GatewayFactory.make_extras(inference_model=inference_model, inference_job=inference_job, output_desc=output_desc)
diff --git a/pipelex/plugins/gateway/gateway_extract_worker.py b/pipelex/plugins/gateway/gateway_extract_worker.py
index 4da6c9dd0..7ff76ed9e 100644
--- a/pipelex/plugins/gateway/gateway_extract_worker.py
+++ b/pipelex/plugins/gateway/gateway_extract_worker.py
@@ -191,6 +191,7 @@ class GatewayExtractWorker(ExtractWorkerAbstract):
async def _extract_base64_url(
self,
extract_job: ExtractJob,
+ *,
base64_url: str,
should_include_images: bool = False,
) -> ExtractOutput:
diff --git a/pipelex/plugins/gateway/gateway_factory.py b/pipelex/plugins/gateway/gateway_factory.py
index 64df6e3da..710205e86 100644
--- a/pipelex/plugins/gateway/gateway_factory.py
+++ b/pipelex/plugins/gateway/gateway_factory.py
@@ -62,7 +62,7 @@ class GatewayFactory:
@classmethod
def make_extras(
- cls, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ cls, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
extra_headers: dict[str, str] = {}
extra_body: dict[str, Any] = {}
diff --git a/pipelex/plugins/gateway/gateway_img_gen_worker.py b/pipelex/plugins/gateway/gateway_img_gen_worker.py
index a0626a018..9e66b4af6 100644
--- a/pipelex/plugins/gateway/gateway_img_gen_worker.py
+++ b/pipelex/plugins/gateway/gateway_img_gen_worker.py
@@ -61,6 +61,7 @@ class GatewayImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
if self.inference_model.rules is None:
diff --git a/pipelex/plugins/gateway/gateway_responses_factory.py b/pipelex/plugins/gateway/gateway_responses_factory.py
index 790074606..a5d18963a 100644
--- a/pipelex/plugins/gateway/gateway_responses_factory.py
+++ b/pipelex/plugins/gateway/gateway_responses_factory.py
@@ -26,6 +26,7 @@ class GatewayResponsesFactory(OpenAIResponsesFactory):
def make_portkey_openai_client_for_responses(
cls,
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> openai.AsyncOpenAI:
is_debug_enabled = GatewayFactory.is_debug_enabled(backend=backend)
@@ -52,6 +53,6 @@ class GatewayResponsesFactory(OpenAIResponsesFactory):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
return GatewayFactory.make_extras(inference_model=inference_model, inference_job=inference_job, output_desc=output_desc)
diff --git a/pipelex/plugins/gateway/gateway_search_worker.py b/pipelex/plugins/gateway/gateway_search_worker.py
index d33eb213b..e19326dc0 100644
--- a/pipelex/plugins/gateway/gateway_search_worker.py
+++ b/pipelex/plugins/gateway/gateway_search_worker.py
@@ -92,6 +92,7 @@ class GatewaySearchWorker(SearchWorkerAbstract):
async def _search_structured(
self,
search_job: SearchJob,
+ *,
schema: type[BaseModelTypeVar],
) -> dict[str, Any]:
job_params = search_job.job_params
@@ -124,7 +125,7 @@ class GatewaySearchWorker(SearchWorkerAbstract):
result: dict[str, Any] = json.loads(content_str)
return result
- def _extract_usage(self, response: GenericResponse, search_job: SearchJob) -> None:
+ def _extract_usage(self, response: GenericResponse, *, search_job: SearchJob) -> None:
"""Extract token usage from the GenericResponse and populate the search job report."""
response_dict: dict[str, Any] = response.model_dump(serialize_as_any=True)
search_tokens_usage = search_job.job_report.search_tokens_usage
@@ -136,7 +137,7 @@ class GatewaySearchWorker(SearchWorkerAbstract):
nb_tokens[TokenCategory.OUTPUT] = output_tokens
search_tokens_usage.nb_tokens_by_category = nb_tokens
- async def _call_relay(self, model: str, content: str) -> GenericResponse:
+ async def _call_relay(self, model: str, *, content: str) -> GenericResponse:
"""Send a request through Portkey to the relay.
Args:
diff --git a/pipelex/plugins/google/google_config.py b/pipelex/plugins/google/google_config.py
index 77457aa8c..a931d0334 100644
--- a/pipelex/plugins/google/google_config.py
+++ b/pipelex/plugins/google/google_config.py
@@ -27,7 +27,7 @@ class GoogleConfig(ConfigModel):
@field_validator("effort_to_level_map")
@classmethod
def validate_effort_map(cls, value: EffortToLevelMap) -> EffortToLevelMap:
- return validate_effort_to_level_map(value, "google_config", level_type=GoogleThinkingLevel)
+ return validate_effort_to_level_map(value, config_name="google_config", level_type=GoogleThinkingLevel)
def get_reasoning_level(self, effort: ReasoningEffort) -> genai_types.ThinkingLevel | None:
"""Resolve a ReasoningEffort to a Google ThinkingLevel enum value.
@@ -38,7 +38,7 @@ class GoogleConfig(ConfigModel):
"""
from google.genai import types as genai_types # noqa: PLC0415
- level_str = get_reasoning_level_str(self.effort_to_level_map, effort)
+ level_str = get_reasoning_level_str(effort_to_level_map=self.effort_to_level_map, effort=effort)
if level_str is None:
return None
google_level = GoogleThinkingLevel(level_str)
diff --git a/pipelex/plugins/google/google_factory.py b/pipelex/plugins/google/google_factory.py
index afe7bad79..04627d3f0 100644
--- a/pipelex/plugins/google/google_factory.py
+++ b/pipelex/plugins/google/google_factory.py
@@ -76,7 +76,7 @@ class GoogleFactory:
return genai_types.Content(parts=parts, role="user")
@classmethod
- def extract_text_from_response(cls, response: genai_types.GenerateContentResponse, model_desc: str) -> str:
+ def extract_text_from_response(cls, response: genai_types.GenerateContentResponse, *, model_desc: str) -> str:
"""Extract text from a Google Gemini response, skipping thinking parts.
Args:
diff --git a/pipelex/plugins/google/google_img_gen_factory.py b/pipelex/plugins/google/google_img_gen_factory.py
index 38c162e53..0c040bc13 100644
--- a/pipelex/plugins/google/google_img_gen_factory.py
+++ b/pipelex/plugins/google/google_img_gen_factory.py
@@ -103,7 +103,7 @@ class GoogleImgGenFactory:
raise ImgGenParameterError(msg)
@classmethod
- def dimensions_for_aspect_ratio_and_size(cls, model: str, aspect_ratio: AspectRatio, size: GoogleImageSize) -> tuple[int, int]:
+ def dimensions_for_aspect_ratio_and_size(cls, model: str, *, aspect_ratio: AspectRatio, size: GoogleImageSize) -> tuple[int, int]:
"""Get pixel dimensions (width, height) for the given aspect ratio."""
aspect_ratio_str = cls.aspect_ratio_literal(aspect_ratio)
match model:
diff --git a/pipelex/plugins/google/google_img_gen_worker.py b/pipelex/plugins/google/google_img_gen_worker.py
index 2948a166d..e606887cd 100644
--- a/pipelex/plugins/google/google_img_gen_worker.py
+++ b/pipelex/plugins/google/google_img_gen_worker.py
@@ -201,6 +201,7 @@ class GoogleImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
"""Generate multiple images by calling _gen_image multiple times.
diff --git a/pipelex/plugins/google/google_list.py b/pipelex/plugins/google/google_list.py
index 409e1efb7..69b76f73b 100644
--- a/pipelex/plugins/google/google_list.py
+++ b/pipelex/plugins/google/google_list.py
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
async def list_google_models(
sdk: str,
+ *,
backend_name: str,
backend: InferenceBackend,
flat: bool,
@@ -55,6 +56,7 @@ async def list_google_models(
def _display_google_models_flat(
models: list[Any],
+ *,
sdk: str,
backend_name: str,
any_listed: bool,
@@ -72,6 +74,7 @@ def _display_google_models_flat(
def _display_google_models_table(
models: list[Any],
+ *,
sdk: str,
backend_name: str,
) -> None:
diff --git a/pipelex/plugins/google/google_llm_worker.py b/pipelex/plugins/google/google_llm_worker.py
index e57424391..d408e9ac8 100644
--- a/pipelex/plugins/google/google_llm_worker.py
+++ b/pipelex/plugins/google/google_llm_worker.py
@@ -108,7 +108,7 @@ class GoogleLLMWorker(LLMWorkerInternalAbstract):
# Reasoning helpers
#########################################################
- def _build_thinking_config(self, job_params: LLMJobParams, max_tokens: int | None) -> genai_types.ThinkingConfig | None:
+ def _build_thinking_config(self, job_params: LLMJobParams, *, max_tokens: int | None) -> genai_types.ThinkingConfig | None:
"""Build thinking config from job params and model spec.
Args:
@@ -135,6 +135,7 @@ class GoogleLLMWorker(LLMWorkerInternalAbstract):
def _build_thinking_config_for_effort(
self,
thinking_mode: ThinkingMode,
+ *,
effort: ReasoningEffort,
max_tokens: int | None,
) -> genai_types.ThinkingConfig:
@@ -171,6 +172,7 @@ class GoogleLLMWorker(LLMWorkerInternalAbstract):
def _build_thinking_config_for_budget(
self,
thinking_mode: ThinkingMode,
+ *,
budget: int,
max_tokens: int | None,
) -> genai_types.ThinkingConfig:
@@ -242,6 +244,7 @@ class GoogleLLMWorker(LLMWorkerInternalAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
"""Generate structured output using Google Gemini API with instructor."""
diff --git a/pipelex/plugins/huggingface/huggingface_img_gen_worker.py b/pipelex/plugins/huggingface/huggingface_img_gen_worker.py
index 4cba5cd72..9fb7c1bfc 100644
--- a/pipelex/plugins/huggingface/huggingface_img_gen_worker.py
+++ b/pipelex/plugins/huggingface/huggingface_img_gen_worker.py
@@ -85,6 +85,7 @@ class HuggingFaceImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
# HuggingFace's text_to_image doesn't support batch generation directly,
diff --git a/pipelex/plugins/linkup/linkup_search_worker.py b/pipelex/plugins/linkup/linkup_search_worker.py
index b8a54dc42..56f5daa05 100644
--- a/pipelex/plugins/linkup/linkup_search_worker.py
+++ b/pipelex/plugins/linkup/linkup_search_worker.py
@@ -110,6 +110,7 @@ class LinkupSearchWorker(SearchWorkerAbstract):
async def _search_structured(
self,
search_job: SearchJob,
+ *,
schema: type[BaseModelTypeVar],
) -> dict[str, Any]:
job_params = search_job.job_params
diff --git a/pipelex/plugins/mistral/mistral_config.py b/pipelex/plugins/mistral/mistral_config.py
index 1c257cb77..6fbd9c552 100644
--- a/pipelex/plugins/mistral/mistral_config.py
+++ b/pipelex/plugins/mistral/mistral_config.py
@@ -24,7 +24,7 @@ class MistralConfig(ConfigModel):
@field_validator("effort_to_level_map")
@classmethod
def validate_effort_map(cls, value: EffortToLevelMap) -> EffortToLevelMap:
- return validate_effort_to_level_map(value, "mistral_config", level_type=MistralReasoningLevel)
+ return validate_effort_to_level_map(value, config_name="mistral_config", level_type=MistralReasoningLevel)
def get_reasoning_level(self, effort: ReasoningEffort) -> MistralPromptMode | None:
"""Resolve a ReasoningEffort to a Mistral MistralPromptMode value.
@@ -33,7 +33,7 @@ class MistralConfig(ConfigModel):
The Mistral prompt mode, or None if reasoning is disabled.
"""
- level_str = get_reasoning_level_str(self.effort_to_level_map, effort)
+ level_str = get_reasoning_level_str(effort_to_level_map=self.effort_to_level_map, effort=effort)
if level_str is None:
return None
mistral_level = MistralReasoningLevel(level_str)
diff --git a/pipelex/plugins/mistral/mistral_extract_worker.py b/pipelex/plugins/mistral/mistral_extract_worker.py
index 16524b011..6effa0e14 100644
--- a/pipelex/plugins/mistral/mistral_extract_worker.py
+++ b/pipelex/plugins/mistral/mistral_extract_worker.py
@@ -86,6 +86,7 @@ class MistralExtractWorker(ExtractWorkerAbstract):
async def _extract_pages_from_document(
self,
document_uri: str,
+ *,
extract_job_params: ExtractJobParams,
) -> ExtractOutput:
if extract_job_params.should_caption_images:
diff --git a/pipelex/plugins/mistral/mistral_factory.py b/pipelex/plugins/mistral/mistral_factory.py
index dc2c10e25..0d40b7e24 100644
--- a/pipelex/plugins/mistral/mistral_factory.py
+++ b/pipelex/plugins/mistral/mistral_factory.py
@@ -364,6 +364,7 @@ class MistralFactory:
@classmethod
async def make_mistral_document_url_chunk_from_uri(
cls,
+ *,
mistral_client: Mistral,
uri: str,
) -> DocumentURLChunkTypedDict:
@@ -384,7 +385,7 @@ class MistralFactory:
ValueError: If mistral_client is None and a local file needs to be uploaded
Example:
- >>> doc = await make_mistral_document_url_chunk_from_uri("https://pipelex-pytest-assets.s3.eu-west-3.amazonaws.com/Job-Offer-Scan.pdf")
+ >>> doc = await make_mistral_document_url_chunk_from_uri(uri="https://pipelex-pytest-assets.s3.eu-west-3.amazonaws.com/Job-Offer-Scan.pdf")
>>> doc
{"type": "document_url", "document_url": "https://pipelex-pytest-assets.s3.eu-west-3.amazonaws.com/Job-Offer-Scan.pdf"}
"""
@@ -421,6 +422,7 @@ class MistralFactory:
@classmethod
async def upload_file_to_mistral_for_ocr(
cls,
+ *,
mistral_client: Mistral,
file_path: Path,
) -> str:
diff --git a/pipelex/plugins/mistral/mistral_list.py b/pipelex/plugins/mistral/mistral_list.py
index 8afbd0ef6..81fc11e81 100644
--- a/pipelex/plugins/mistral/mistral_list.py
+++ b/pipelex/plugins/mistral/mistral_list.py
@@ -12,6 +12,7 @@ from pipelex.hub import get_console
def list_mistral_models(
sdk: str,
+ *,
backend_name: str,
flat: bool,
any_listed: bool,
@@ -52,6 +53,7 @@ def list_mistral_models(
def _display_mistral_models_flat(
models: list[Any],
+ *,
sdk: str,
backend_name: str,
any_listed: bool,
@@ -67,6 +69,7 @@ def _display_mistral_models_flat(
def _display_mistral_models_table(
models: list[Any],
+ *,
sdk: str,
backend_name: str,
) -> None:
diff --git a/pipelex/plugins/mistral/mistral_llm_worker.py b/pipelex/plugins/mistral/mistral_llm_worker.py
index 964511bef..b1c6ab892 100644
--- a/pipelex/plugins/mistral/mistral_llm_worker.py
+++ b/pipelex/plugins/mistral/mistral_llm_worker.py
@@ -206,6 +206,7 @@ class MistralLLMWorker(LLMWorkerInternalAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
diff --git a/pipelex/plugins/openai/openai_client_factory.py b/pipelex/plugins/openai/openai_client_factory.py
index 8d43d1956..c100cf42a 100644
--- a/pipelex/plugins/openai/openai_client_factory.py
+++ b/pipelex/plugins/openai/openai_client_factory.py
@@ -27,6 +27,7 @@ class OpenAIClientFactory:
def make_openai_client(
cls,
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> openai.AsyncClient:
try:
diff --git a/pipelex/plugins/openai/openai_completions_factory.py b/pipelex/plugins/openai/openai_completions_factory.py
index d3a290222..0e11dd2a5 100644
--- a/pipelex/plugins/openai/openai_completions_factory.py
+++ b/pipelex/plugins/openai/openai_completions_factory.py
@@ -113,6 +113,6 @@ class OpenAICompletionsFactory(PluginFactoryAbstract):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
return inference_model.extra_headers or {}, {}
diff --git a/pipelex/plugins/openai/openai_completions_img_gen_worker.py b/pipelex/plugins/openai/openai_completions_img_gen_worker.py
index f46815e0c..3b9f0e819 100644
--- a/pipelex/plugins/openai/openai_completions_img_gen_worker.py
+++ b/pipelex/plugins/openai/openai_completions_img_gen_worker.py
@@ -226,6 +226,7 @@ class OpenAICompletionsImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
if nb_images > 1:
diff --git a/pipelex/plugins/openai/openai_completions_llm_worker.py b/pipelex/plugins/openai/openai_completions_llm_worker.py
index 0103e70ff..f8b2b83dc 100644
--- a/pipelex/plugins/openai/openai_completions_llm_worker.py
+++ b/pipelex/plugins/openai/openai_completions_llm_worker.py
@@ -206,6 +206,7 @@ class OpenAICompletionsLLMWorker(LLMWorkerInternalAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
diff --git a/pipelex/plugins/openai/openai_config.py b/pipelex/plugins/openai/openai_config.py
index 7653f0dd4..177a2949f 100644
--- a/pipelex/plugins/openai/openai_config.py
+++ b/pipelex/plugins/openai/openai_config.py
@@ -27,7 +27,7 @@ class OpenAIConfig(ConfigModel):
@field_validator("effort_to_level_map")
@classmethod
def validate_effort_map(cls, value: EffortToLevelMap) -> EffortToLevelMap:
- return validate_effort_to_level_map(value, "openai_config", level_type=OpenAIReasoningLevel)
+ return validate_effort_to_level_map(value, config_name="openai_config", level_type=OpenAIReasoningLevel)
def get_reasoning_level(self, effort: ReasoningEffort) -> "ChatCompletionReasoningEffort | None":
"""Resolve a ReasoningEffort to an OpenAI ChatCompletionReasoningEffort value.
@@ -36,7 +36,7 @@ class OpenAIConfig(ConfigModel):
The OpenAI effort value, or None if reasoning is disabled.
"""
- level_str = get_reasoning_level_str(self.effort_to_level_map, effort)
+ level_str = get_reasoning_level_str(effort_to_level_map=self.effort_to_level_map, effort=effort)
if level_str is None:
return None
openai_level = OpenAIReasoningLevel(level_str)
diff --git a/pipelex/plugins/openai/openai_img_gen_worker.py b/pipelex/plugins/openai/openai_img_gen_worker.py
index a2a79ca6e..93426df20 100644
--- a/pipelex/plugins/openai/openai_img_gen_worker.py
+++ b/pipelex/plugins/openai/openai_img_gen_worker.py
@@ -56,6 +56,7 @@ class OpenAIImgGenWorker(ImgGenWorkerAbstract):
async def _gen_image_list(
self,
img_gen_job: ImgGenJob,
+ *,
nb_images: int,
) -> list[GeneratedImageRawDetails]:
if self.inference_model.rules is None:
diff --git a/pipelex/plugins/openai/openai_list.py b/pipelex/plugins/openai/openai_list.py
index 2ee470d03..b651c682a 100644
--- a/pipelex/plugins/openai/openai_list.py
+++ b/pipelex/plugins/openai/openai_list.py
@@ -18,6 +18,7 @@ if TYPE_CHECKING:
async def list_openai_models(
sdk: str,
+ *,
backend_name: str,
backend: InferenceBackend,
flat: bool,
@@ -47,6 +48,7 @@ async def list_openai_models(
def _display_openai_models_flat(
models: list[Model],
+ *,
sdk: str,
backend_name: str,
any_listed: bool,
@@ -67,6 +69,7 @@ def _display_openai_models_flat(
def _display_openai_models_table(
models: list[Model],
+ *,
sdk: str,
backend_name: str,
) -> None:
diff --git a/pipelex/plugins/openai/openai_llms.py b/pipelex/plugins/openai/openai_llms.py
index e7974d6bf..299812b0f 100644
--- a/pipelex/plugins/openai/openai_llms.py
+++ b/pipelex/plugins/openai/openai_llms.py
@@ -7,6 +7,7 @@ from pipelex.plugins.plugin_sdk_registry import Plugin
async def openai_list_available_models(
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> list[Model]:
openai_client_async = OpenAIClientFactory.make_openai_client(
diff --git a/pipelex/plugins/openai/openai_responses_factory.py b/pipelex/plugins/openai/openai_responses_factory.py
index 038bf7c7c..680408272 100644
--- a/pipelex/plugins/openai/openai_responses_factory.py
+++ b/pipelex/plugins/openai/openai_responses_factory.py
@@ -108,6 +108,6 @@ class OpenAIResponsesFactory(PluginFactoryAbstract):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
return inference_model.extra_headers or {}, {}
diff --git a/pipelex/plugins/openai/openai_responses_llm_worker.py b/pipelex/plugins/openai/openai_responses_llm_worker.py
index 728a3ee4e..9410896a9 100644
--- a/pipelex/plugins/openai/openai_responses_llm_worker.py
+++ b/pipelex/plugins/openai/openai_responses_llm_worker.py
@@ -184,6 +184,7 @@ class OpenAIResponsesLLMWorker(LLMWorkerInternalAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
diff --git a/pipelex/plugins/openai/vertexai_factory.py b/pipelex/plugins/openai/vertexai_factory.py
index 6debe79a6..0b5e5544c 100644
--- a/pipelex/plugins/openai/vertexai_factory.py
+++ b/pipelex/plugins/openai/vertexai_factory.py
@@ -44,7 +44,7 @@ class VertexAIFactory(ConfigModel):
return endpoint, api_key
@classmethod
- def _make_endpoint(cls, gcp_project_id: str, gcp_location: str) -> str:
+ def _make_endpoint(cls, gcp_project_id: str, *, gcp_location: str) -> str:
return f"https://{gcp_location}-aiplatform.googleapis.com/v1beta1/projects/{gcp_project_id}/locations/{gcp_location}/endpoints/openapi"
@classmethod
diff --git a/pipelex/plugins/openrouter/openrouter_completions_factory.py b/pipelex/plugins/openrouter/openrouter_completions_factory.py
index 2e9770505..41db063a4 100644
--- a/pipelex/plugins/openrouter/openrouter_completions_factory.py
+++ b/pipelex/plugins/openrouter/openrouter_completions_factory.py
@@ -15,7 +15,7 @@ if TYPE_CHECKING:
class OpenRouterCompletionsFactory(OpenAICompletionsFactory):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
if isinstance(inference_job, ImgGenJob):
extra_body = {"modalities": ["image"]}
diff --git a/pipelex/plugins/plugin_factory_abstract.py b/pipelex/plugins/plugin_factory_abstract.py
index c59529dba..f122409c1 100644
--- a/pipelex/plugins/plugin_factory_abstract.py
+++ b/pipelex/plugins/plugin_factory_abstract.py
@@ -8,6 +8,6 @@ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
class PluginFactoryAbstract(ABC):
@abstractmethod
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
pass
diff --git a/pipelex/plugins/plugin_sdk_registry.py b/pipelex/plugins/plugin_sdk_registry.py
index 228f9a376..d316560ad 100644
--- a/pipelex/plugins/plugin_sdk_registry.py
+++ b/pipelex/plugins/plugin_sdk_registry.py
@@ -19,6 +19,6 @@ class PluginSdkRegistry(RootModel[PluginSdkRegistryRoot]):
def get_sdk_instance(self, plugin: Plugin) -> Any | None:
return self.root.get(plugin.sdk_handle)
- def set_sdk_instance(self, plugin: Plugin, sdk_instance: Any) -> Any:
+ def set_sdk_instance(self, *, plugin: Plugin, sdk_instance: Any) -> Any:
self.root[plugin.sdk_handle] = sdk_instance
return sdk_instance
diff --git a/pipelex/plugins/portkey/portkey_completions_factory.py b/pipelex/plugins/portkey/portkey_completions_factory.py
index a5913fbf7..4e82073b5 100644
--- a/pipelex/plugins/portkey/portkey_completions_factory.py
+++ b/pipelex/plugins/portkey/portkey_completions_factory.py
@@ -95,6 +95,7 @@ class PortkeyCompletionsFactory(OpenAICompletionsFactory):
def make_portkey_openai_client_for_completions(
cls,
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> openai.AsyncOpenAI:
# Deferred import: avoid pulling heavy SDK at module-load time
@@ -125,6 +126,6 @@ class PortkeyCompletionsFactory(OpenAICompletionsFactory):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
return PortkeyFactory.make_extras(inference_model=inference_model, inference_job=inference_job, output_desc=output_desc)
diff --git a/pipelex/plugins/portkey/portkey_factory.py b/pipelex/plugins/portkey/portkey_factory.py
index c7c556205..f30af3987 100644
--- a/pipelex/plugins/portkey/portkey_factory.py
+++ b/pipelex/plugins/portkey/portkey_factory.py
@@ -38,7 +38,7 @@ class PortkeyFactory:
@classmethod
def make_extras(
- cls, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ cls, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
extra_headers: dict[str, str] = {}
extra_body: dict[str, Any] = {}
diff --git a/pipelex/plugins/portkey/portkey_responses_factory.py b/pipelex/plugins/portkey/portkey_responses_factory.py
index cb5b1230b..ead67cd51 100644
--- a/pipelex/plugins/portkey/portkey_responses_factory.py
+++ b/pipelex/plugins/portkey/portkey_responses_factory.py
@@ -26,6 +26,7 @@ class PortkeyResponsesFactory(OpenAIResponsesFactory):
def make_portkey_openai_client_for_responses(
cls,
plugin: Plugin,
+ *,
backend: InferenceBackend,
) -> openai.AsyncOpenAI:
is_debug_enabled = PortkeyFactory.is_debug_enabled(backend=backend)
@@ -51,6 +52,6 @@ class PortkeyResponsesFactory(OpenAIResponsesFactory):
@override
def make_extras(
- self, inference_model: InferenceModelSpec, inference_job: InferenceJobAbstract, output_desc: str
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
) -> tuple[dict[str, str], dict[str, Any]]:
return PortkeyFactory.make_extras(inference_model=inference_model, inference_job=inference_job, output_desc=output_desc)
diff --git a/pipelex/reporting/reporting_manager.py b/pipelex/reporting/reporting_manager.py
index 5c2b067c6..1928ef1d2 100644
--- a/pipelex/reporting/reporting_manager.py
+++ b/pipelex/reporting/reporting_manager.py
@@ -90,6 +90,7 @@ class ReportingManager(ReportingProtocol):
def set_event_log(
self,
context_key: str,
+ *,
event_log: EventLogProtocol,
workflow_id: str,
pipeline_run_id: str,
@@ -146,7 +147,7 @@ class ReportingManager(ReportingProtocol):
log.warning("LLM job has no llm_tokens_usage")
return
- self._emit_usage_event(llm_job, llm_tokens_usage)
+ self._emit_usage_event(llm_job, tokens_usage=llm_tokens_usage)
def _report_img_gen_job(self, img_gen_job: ImgGenJob):
img_gen_tokens_usage = img_gen_job.job_report.img_gen_tokens_usage
@@ -155,7 +156,7 @@ class ReportingManager(ReportingProtocol):
log.warning("ImgGen job has no img_gen_tokens_usage")
return
- self._emit_usage_event(img_gen_job, img_gen_tokens_usage)
+ self._emit_usage_event(img_gen_job, tokens_usage=img_gen_tokens_usage)
def _report_extract_job(self, extract_job: ExtractJob):
extract_tokens_usage = extract_job.job_report.extract_tokens_usage
@@ -164,7 +165,7 @@ class ReportingManager(ReportingProtocol):
log.warning("Extract job has no extract_tokens_usage")
return
- self._emit_usage_event(extract_job, extract_tokens_usage)
+ self._emit_usage_event(extract_job, tokens_usage=extract_tokens_usage)
def _report_search_job(self, search_job: SearchJob):
search_tokens_usage = search_job.job_report.search_tokens_usage
@@ -173,9 +174,9 @@ class ReportingManager(ReportingProtocol):
log.warning("Search job has no search_tokens_usage")
return
- self._emit_usage_event(search_job, search_tokens_usage)
+ self._emit_usage_event(search_job, tokens_usage=search_tokens_usage)
- def _emit_usage_event(self, inference_job: InferenceJobAbstract, tokens_usage: AnyTokensUsage) -> None:
+ def _emit_usage_event(self, inference_job: InferenceJobAbstract, *, tokens_usage: AnyTokensUsage) -> None:
"""Emit a UsageReportEvent for this job.
Fast path: when set_event_log was registered for this trace context's
@@ -215,7 +216,7 @@ class ReportingManager(ReportingProtocol):
if not _is_in_temporal_activity():
context = self._event_log_contexts.get(trace_context.lookup_key)
if context is not None:
- self._emit_via_registered_context(context, trace_context, tokens_usage)
+ self._emit_via_registered_context(context, trace_context=trace_context, tokens_usage=tokens_usage)
return
self._emit_usage_event_runner_fallback(
@@ -227,6 +228,7 @@ class ReportingManager(ReportingProtocol):
@staticmethod
def _emit_via_registered_context(
context: _EventLogContext,
+ *,
trace_context: TraceContext,
tokens_usage: AnyTokensUsage,
) -> None:
@@ -246,7 +248,7 @@ class ReportingManager(ReportingProtocol):
ReportingManager._emit_best_effort(event_log=context.event_log, event=event)
@staticmethod
- def _emit_best_effort(event_log: EventLogProtocol, event: UsageReportEvent) -> None:
+ def _emit_best_effort(*, event_log: EventLogProtocol, event: UsageReportEvent) -> None:
"""Emit a usage event, dropping infra-level backend failures with a WARNING.
Shared by both emit paths (the registered-context fast path and the runner fallback).
@@ -263,6 +265,7 @@ class ReportingManager(ReportingProtocol):
def _emit_usage_event_runner_fallback(
self,
inference_job: InferenceJobAbstract,
+ *,
tokens_usage: AnyTokensUsage,
trace_context: TraceContext,
) -> None:
diff --git a/pipelex/reporting/reporting_protocol.py b/pipelex/reporting/reporting_protocol.py
index 72995df8a..3718caa34 100644
--- a/pipelex/reporting/reporting_protocol.py
+++ b/pipelex/reporting/reporting_protocol.py
@@ -16,6 +16,7 @@ class ReportingProtocol(Protocol):
def set_event_log(
self,
context_key: str,
+ *,
event_log: EventLogProtocol,
workflow_id: str,
pipeline_run_id: str,
@@ -41,6 +42,7 @@ class ReportingNoOp(ReportingProtocol):
def set_event_log(
self,
context_key: str,
+ *,
event_log: EventLogProtocol,
workflow_id: str,
pipeline_run_id: str,
diff --git a/pipelex/runtime_bridge/bridge.py b/pipelex/runtime_bridge/bridge.py
index 7ffbfbb6c..f1a932abf 100644
--- a/pipelex/runtime_bridge/bridge.py
+++ b/pipelex/runtime_bridge/bridge.py
@@ -105,6 +105,7 @@ class PipelexPipeRunOutput(BaseModel):
async def run_pipe_via_bridge(
input_payload: PipelexPipeRunInput,
+ *,
trace_context: TraceContext | None = None,
) -> PipelexPipeRunOutput:
"""Run a Pipelex pipe from inside a host-runtime activity.
@@ -158,6 +159,7 @@ async def run_pipe_via_bridge(
def build_pipe_job_from_input(
input_payload: PipelexPipeRunInput,
+ *,
library_crate: LibraryCrate | None,
trace_context: TraceContext | None = None,
) -> PipeJob:
@@ -235,7 +237,7 @@ def serialize_pipe_output(pipe_output: PipeOutput) -> dict[str, Any]:
return pipe_output.working_memory.dump_for_temporal()
-def _validate_input(input_payload: PipelexPipeRunInput, delivery_assignment: DeliveryAssignment | None) -> None:
+def _validate_input(input_payload: PipelexPipeRunInput, *, delivery_assignment: DeliveryAssignment | None) -> None:
if input_payload.execution_mode is PipelexExecutionMode.TEMPORAL_FIRE_AND_FORGET:
if delivery_assignment is None or not delivery_assignment.has_delivery_target:
msg = (
@@ -267,6 +269,7 @@ def _decode_delivery_assignment(delivery_assignment_dump: dict[str, Any] | None)
async def _run_direct(
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None,
) -> PipelexPipeRunOutput:
# DIRECT mode forces in-process execution even inside a Temporal-enabled
@@ -293,6 +296,7 @@ async def _run_direct(
async def _run_temporal_blocking(
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None,
) -> PipelexPipeRunOutput:
from pipelex.temporal.exceptions import WorkflowExecutionError # noqa: PLC0415
@@ -325,6 +329,7 @@ async def _run_temporal_blocking(
async def _run_temporal_fire_and_forget(
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None,
) -> PipelexPipeRunOutput:
from pipelex.temporal.exceptions import WorkflowExecutionError # noqa: PLC0415
@@ -352,6 +357,7 @@ async def _run_temporal_fire_and_forget(
def _serialize_completed_output(
pipe_output: PipeOutput,
+ *,
workflow_id: str | None,
) -> PipelexPipeRunOutput:
output_dict = serialize_pipe_output(pipe_output=pipe_output)
@@ -401,6 +407,7 @@ def _require_pipelex_temporal_extra() -> None:
async def _run_mistral_native(
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None,
) -> PipelexPipeRunOutput:
try:
diff --git a/pipelex/runtime_bridge/primitives/delivery.py b/pipelex/runtime_bridge/primitives/delivery.py
index 2d207254d..46a834e30 100644
--- a/pipelex/runtime_bridge/primitives/delivery.py
+++ b/pipelex/runtime_bridge/primitives/delivery.py
@@ -11,6 +11,7 @@ from pipelex.pipe_run.delivery_executor import DeliveryExecutor
async def execute_delivery(
+ *,
pipe_output: PipeOutput | None,
user_id: str,
pipeline_run_id: str,
diff --git a/pipelex/runtime_bridge/primitives/hydration.py b/pipelex/runtime_bridge/primitives/hydration.py
index 6e07f3f20..7b94ff2fe 100644
--- a/pipelex/runtime_bridge/primitives/hydration.py
+++ b/pipelex/runtime_bridge/primitives/hydration.py
@@ -14,7 +14,7 @@ from pipelex.hub import get_class_registry
from pipelex.pipe_run.exceptions import PipeJobError
-def _validate_as_known_class(item_class: type[StuffContent], raw_item: StuffContent | dict[str, Any]) -> StuffContent:
+def _validate_as_known_class(*, item_class: type[StuffContent], raw_item: StuffContent | dict[str, Any]) -> StuffContent:
"""Validate raw_item into item_class, tolerating cross-exec instances.
The Temporal hot path now ships ListContent items as plain dicts with
@@ -54,7 +54,7 @@ def _hydrate_list_item(raw_item: dict[str, Any] | str | StuffContent) -> StuffCo
class_name_from_instance = type(raw_item).__name__
item_class_or_none = get_class_registry().get_class(name=class_name_from_instance)
if item_class_or_none is not None and issubclass(item_class_or_none, StuffContent):
- return _validate_as_known_class(item_class_or_none, raw_item)
+ return _validate_as_known_class(item_class=item_class_or_none, raw_item=raw_item)
return raw_item
class_name = raw_item.get("__pipelex_class__")
@@ -72,7 +72,7 @@ def _hydrate_list_item(raw_item: dict[str, Any] | str | StuffContent) -> StuffCo
raise PipeJobError(msg)
-def hydrate_content(concept: Concept, raw_content: list[Any] | dict[str, Any] | str) -> StuffContent:
+def hydrate_content(raw_content: list[Any] | dict[str, Any] | str, *, concept: Concept) -> StuffContent:
"""Hydrate a single StuffContent from a raw value.
Handles both plain content and ListContent. The Temporal serialization
@@ -93,7 +93,7 @@ def hydrate_content(concept: Concept, raw_content: list[Any] | dict[str, Any] |
# structured concept class). Use _validate_as_known_class so that
# cross-exec instances rebuilt by kajson during Temporal transit
# get normalized through a dict round-trip.
- items = [_validate_as_known_class(item_class_or_none, raw_item) for raw_item in raw_content]
+ items = [_validate_as_known_class(item_class=item_class_or_none, raw_item=raw_item) for raw_item in raw_content]
else:
# Anything or unknown concept — resolve each item by its embedded type metadata
raw_items = cast("list[dict[str, Any]]", raw_content)
diff --git a/pipelex/runtime_bridge/primitives/scoped_library.py b/pipelex/runtime_bridge/primitives/scoped_library.py
index 11365ad64..b63578efe 100644
--- a/pipelex/runtime_bridge/primitives/scoped_library.py
+++ b/pipelex/runtime_bridge/primitives/scoped_library.py
@@ -13,7 +13,7 @@ from pipelex.libraries.library_crate import LibraryCrate
@contextmanager
-def scoped_library_for_crate(library_crate: LibraryCrate | None, library_id_prefix: str) -> Generator[str | None, None, None]:
+def scoped_library_for_crate(library_crate: LibraryCrate | None, *, library_id_prefix: str) -> Generator[str | None, None, None]:
"""Open a per-call scoped library loaded from ``library_crate`` for the duration of the block.
When ``library_crate`` is None this is a no-op (yields None): callers fall back to the
diff --git a/pipelex/runtime_bridge/primitives/submitter_hydration.py b/pipelex/runtime_bridge/primitives/submitter_hydration.py
index ff6883802..83bf367c5 100644
--- a/pipelex/runtime_bridge/primitives/submitter_hydration.py
+++ b/pipelex/runtime_bridge/primitives/submitter_hydration.py
@@ -29,6 +29,7 @@ if TYPE_CHECKING:
def rehydrate_pipe_output_with_crate(
pipe_output: PipeOutput,
+ *,
library_crate: "LibraryCrate | None",
) -> PipeOutput:
"""Rehydrate `pipe_output.working_memory_raw` into a typed WorkingMemory.
diff --git a/pipelex/system/configuration/config_check.py b/pipelex/system/configuration/config_check.py
index 0cbdb0221..12cf96754 100644
--- a/pipelex/system/configuration/config_check.py
+++ b/pipelex/system/configuration/config_check.py
@@ -9,7 +9,7 @@ from pipelex.urls import URLs
PLXT_CONFIG_NAME = "plxt.toml"
-def check_is_initialized(print_warning_if_not: bool = True) -> bool:
+def check_is_initialized(*, print_warning_if_not: bool = True) -> bool:
# Use resolve_config_file for all checks — consistent with how backends and routing are resolved
config_exists = path_exists(config_manager.resolve_config_file(CONFIG_NAME)) and path_exists(config_manager.resolve_config_file(PLXT_CONFIG_NAME))
backends_exists = path_exists(config_manager.backends_file_path)
diff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.py
index 51a522a33..4f3624a36 100644
--- a/pipelex/system/configuration/config_loader.py
+++ b/pipelex/system/configuration/config_loader.py
@@ -87,7 +87,7 @@ class ConfigLoader:
return project_dir
return self.global_config_dir
- def resolve_config_file(self, relative_path: str, config_dir: Path | None = None) -> Path:
+ def resolve_config_file(self, relative_path: str, *, config_dir: Path | None = None) -> Path:
"""Resolve a config file path with layered resolution.
When config_dir is provided (e.g. for --global override), the file is
@@ -147,7 +147,7 @@ class ConfigLoader:
config_template_dir = Path(str(get_kit_configs_dir()))
global_dir.mkdir(parents=True, exist_ok=True)
- def copy_directory_structure(src_dir: Path, dst_dir: Path) -> None:
+ def copy_directory_structure(*, src_dir: Path, dst_dir: Path) -> None:
"""Recursively copy directory structure from kit templates."""
for item in src_dir.iterdir():
if item.name in GIT_IGNORED_CONFIG_FILES or item.name == ".DS_Store":
@@ -155,7 +155,7 @@ class ConfigLoader:
dst_item = dst_dir / item.name
if item.is_dir():
dst_item.mkdir(parents=True, exist_ok=True)
- copy_directory_structure(item, dst_item)
+ copy_directory_structure(src_dir=item, dst_dir=dst_item)
else:
shutil.copy2(item, dst_item)
@@ -165,10 +165,10 @@ class ConfigLoader:
# Imported lazily to avoid a circular import — config_loader is loaded very early.
from pipelex.cogt.models.deck_manifest import compute_kit_manifest, write_manifest # noqa: PLC0415
- write_manifest(global_dir / "inference" / "deck", compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=global_dir / "inference" / "deck")
@classmethod
- def _override_files_for_dir(cls, config_dir: Path, include_run_mode: bool) -> list[Path]:
+ def _override_files_for_dir(cls, config_dir: Path, *, include_run_mode: bool) -> list[Path]:
"""Build the override file sequence for a single config dir.
Order matters: later files win on key collisions during deep-merge.
@@ -192,7 +192,7 @@ class ConfigLoader:
files.append(config_dir / "pipelex_temporary_override.toml")
return files
- def load_config(self, extra_overrides: dict[str, Any] | None = None, config_dir: Path | None = None) -> dict[str, Any]:
+ def load_config(self, *, extra_overrides: dict[str, Any] | None = None, config_dir: Path | None = None) -> dict[str, Any]:
"""Load and merge configurations from pipelex and local config files.
When ``config_dir`` is provided, the load is scoped to a single directory
@@ -261,7 +261,7 @@ class ConfigLoader:
merged = load_toml_from_path_and_merge_with_overrides(paths=list_of_configs)
if extra_overrides:
- deep_update(merged, extra_overrides)
+ deep_update(merged, updates=extra_overrides)
return merged
diff --git a/pipelex/system/configuration/config_model.py b/pipelex/system/configuration/config_model.py
index f5c05f8e4..0056a1767 100644
--- a/pipelex/system/configuration/config_model.py
+++ b/pipelex/system/configuration/config_model.py
@@ -14,6 +14,7 @@ class ConfigModel(BaseModel):
@staticmethod
def transform_dict_str_to_enum(
input_dict: dict[str, str],
+ *,
key_enum_cls: type[StrEnumType] | None = None,
value_enum_cls: type[StrEnumType] | None = None,
) -> dict[str, StrEnumType] | dict[StrEnumType, str] | dict[StrEnumType, StrEnumType]:
@@ -41,6 +42,7 @@ class ConfigModel(BaseModel):
@staticmethod
def transform_dict_of_floats_str_to_enum(
input_dict: dict[str, float],
+ *,
key_enum_cls: type[StrEnumType],
) -> dict[StrEnumType, float]:
"""Transforms a dictionary with str keys and float values into a dictionary with enum keys and float values.
@@ -58,6 +60,7 @@ class ConfigModel(BaseModel):
@staticmethod
def transform_dict_keys_str_to_enum(
input_dict: dict[str, Any],
+ *,
key_enum_cls: type[StrEnumType],
) -> dict[StrEnumType, Any]:
"""Transforms a dictionary with str keys and Any values into a dictionary with enum keys and Any values.
@@ -75,6 +78,7 @@ class ConfigModel(BaseModel):
@staticmethod
def transform_list_of_str_to_enum(
input_list: list[str],
+ *,
enum_cls: type[StrEnumType],
) -> list[StrEnumType]:
return [enum_cls(item) for item in input_list]
diff --git a/pipelex/system/configuration/configs.py b/pipelex/system/configuration/configs.py
index 71eada30a..ec250eb5f 100644
--- a/pipelex/system/configuration/configs.py
+++ b/pipelex/system/configuration/configs.py
@@ -162,6 +162,7 @@ class PipelineExecutionConfig(ConfigModel):
def with_execution_overrides(
self,
+ *,
generate_graph: bool | None = None,
generate_usage: bool | None = None,
force_include_full_data: bool | None = None,
@@ -230,13 +231,13 @@ class Pipelex(ConfigModel):
class MigrationConfig(ConfigModel):
migration_maps: dict[str, dict[str, str]]
- def text_in_renaming_keys(self, category: str, text: str) -> list[tuple[str, str]]:
+ def text_in_renaming_keys(self, text: str, *, category: str) -> list[tuple[str, str]]:
renaming_map = self.migration_maps.get(category)
if not renaming_map:
return []
return [(key, value) for key, value in renaming_map.items() if text in key]
- def text_in_renaming_values(self, category: str, text: str) -> list[tuple[str, str]]:
+ def text_in_renaming_values(self, text: str, *, category: str) -> list[tuple[str, str]]:
renaming_map = self.migration_maps.get(category)
if not renaming_map:
return []
diff --git a/pipelex/system/pipelex_service/gateway_config_merger.py b/pipelex/system/pipelex_service/gateway_config_merger.py
index a8ee43eae..b733305c3 100644
--- a/pipelex/system/pipelex_service/gateway_config_merger.py
+++ b/pipelex/system/pipelex_service/gateway_config_merger.py
@@ -21,6 +21,7 @@ class GatewayConfigMerger:
def merge(
cls,
gateway_model_specs: BackendModelSpecs,
+ *,
local_overrides: BackendModelSpecs,
) -> dict[str, Any]:
"""Merge remote config with local overrides.
@@ -67,6 +68,7 @@ class GatewayConfigMerger:
@classmethod
def _apply_overrides_to_model(
cls,
+ *,
model_name: str,
gateway_model_specs: BackendModelSpecs,
local_model_config: BackendModelSpecs,
diff --git a/pipelex/system/pipelex_service/pipelex_service_agreement.py b/pipelex/system/pipelex_service/pipelex_service_agreement.py
index 1e273fd32..c6ed0429f 100644
--- a/pipelex/system/pipelex_service/pipelex_service_agreement.py
+++ b/pipelex/system/pipelex_service/pipelex_service_agreement.py
@@ -26,7 +26,7 @@ class PipelexServiceOnboarding(ConfigModel):
)
-def update_service_terms_acceptance(accepted: bool, config_dir: Path | None = None) -> None:
+def update_service_terms_acceptance(*, accepted: bool, config_dir: Path | None = None) -> None:
"""Update the service terms acceptance in pipelex_service.toml.
Args:
@@ -47,10 +47,10 @@ def update_service_terms_acceptance(accepted: bool, config_dir: Path | None = No
toml_doc["agreement"]["terms_accepted"] = accepted # type: ignore[index]
resolved_config_dir.mkdir(parents=True, exist_ok=True)
- save_toml_to_path(toml_doc, service_config_path)
+ save_toml_to_path(toml_doc, path=service_config_path)
-def update_inference_setup_completed(completed: bool, config_dir: Path | None = None) -> None:
+def update_inference_setup_completed(*, completed: bool, config_dir: Path | None = None) -> None:
"""Update the inference setup completed flag in pipelex_service.toml.
Args:
@@ -74,4 +74,4 @@ def update_inference_setup_completed(completed: bool, config_dir: Path | None =
toml_doc["onboarding"]["inference_setup_completed"] = completed # type: ignore[index]
resolved_config_dir.mkdir(parents=True, exist_ok=True)
- save_toml_to_path(toml_doc, service_config_path)
+ save_toml_to_path(toml_doc, path=service_config_path)
diff --git a/pipelex/system/pipelex_service/remote_config_fetcher.py b/pipelex/system/pipelex_service/remote_config_fetcher.py
index 2b588a56b..76eb0b6cb 100644
--- a/pipelex/system/pipelex_service/remote_config_fetcher.py
+++ b/pipelex/system/pipelex_service/remote_config_fetcher.py
@@ -167,6 +167,7 @@ class RemoteConfigFetcher:
def _build_unavailable_error(
cls,
fetch_error: RemoteConfigFetchError,
+ *,
cache_refused: bool = False,
) -> RemoteConfigUnavailableError:
"""Build the user-facing offline-mode error with a clear remediation hint.
diff --git a/pipelex/system/registries/class_registry_utils.py b/pipelex/system/registries/class_registry_utils.py
index 63bdd74f7..55172e4cf 100644
--- a/pipelex/system/registries/class_registry_utils.py
+++ b/pipelex/system/registries/class_registry_utils.py
@@ -21,6 +21,7 @@ class ClassRegistryUtils:
def register_classes_in_file(
cls,
file_path: Path,
+ *,
base_class: type[Any] | None,
is_include_imported: bool,
) -> None:
@@ -40,6 +41,7 @@ class ClassRegistryUtils:
def register_classes_in_folder(
cls,
folder_path: Path,
+ *,
base_class: type[Any] | None = None,
is_recursive: bool = True,
is_include_imported: bool = False,
@@ -75,6 +77,7 @@ class ClassRegistryUtils:
def import_modules_in_folder(
cls,
folder_path: Path,
+ *,
force_include_dirs: list[Path] | None = None,
is_recursive: bool = True,
base_class_names: list[str] | None = None,
diff --git a/pipelex/system/registries/func_registry.py b/pipelex/system/registries/func_registry.py
index c2db76751..956f2fd9c 100644
--- a/pipelex/system/registries/func_registry.py
+++ b/pipelex/system/registries/func_registry.py
@@ -99,6 +99,7 @@ class FuncRegistry(RootModel[FuncRegistryDict]):
def register_function(
self,
func: Callable[..., Any],
+ *,
name: str | None = None,
) -> None:
"""Registers a function in the registry with a name if it meets eligibility criteria."""
@@ -196,7 +197,7 @@ class FuncRegistry(RootModel[FuncRegistryDict]):
return hasattr(func, PIPE_FUNC_MARKER) and getattr(func, PIPE_FUNC_MARKER) is True
# TODO: refactor this into a subclass of FuncRegistry dedicated to pipe funcs, avoid the circular import issue, avoid the code-smell
- def is_eligible_function(self, func: Any, require_decorator: bool = False) -> bool:
+ def is_eligible_function(self, func: Any, *, require_decorator: bool = False) -> bool:
"""Checks if a function matches the criteria for PipeFunc registration:
- Must be callable
- Exactly 1 parameter named "working_memory" with type WorkingMemory
@@ -346,6 +347,7 @@ class FuncRegistry(RootModel[FuncRegistryDict]):
def register_ineligible_function(
self,
func: Callable[..., Any],
+ *,
reason: str,
source_file: str | None = None,
) -> None:
diff --git a/pipelex/system/registries/func_registry_utils.py b/pipelex/system/registries/func_registry_utils.py
index 5aee824e1..97fa22380 100644
--- a/pipelex/system/registries/func_registry_utils.py
+++ b/pipelex/system/registries/func_registry_utils.py
@@ -15,7 +15,7 @@ from pipelex.tools.typing.module_inspector import import_module_from_file_if_has
class FuncRegistryUtils:
@classmethod
- def register_pipe_funcs_from_package(cls, package_name: str, package: Any) -> int:
+ def register_pipe_funcs_from_package(cls, package_name: str, *, package: Any) -> int:
"""Register all @pipe_func decorated functions from a package.
Args:
@@ -75,6 +75,7 @@ class FuncRegistryUtils:
def register_funcs_in_folder(
cls,
folder_path: Path,
+ *,
force_include_dirs: list[Path] | None = None,
is_recursive: bool = True,
) -> None:
diff --git a/pipelex/system/telemetry/exception_capture.py b/pipelex/system/telemetry/exception_capture.py
index b029968e0..47e4bd132 100644
--- a/pipelex/system/telemetry/exception_capture.py
+++ b/pipelex/system/telemetry/exception_capture.py
@@ -42,7 +42,7 @@ class DualClientExceptionCapture:
sys.excepthook = self._original_excepthook
threading.excepthook = self._original_threading_excepthook
- def _exception_handler(
+ def _exception_handler( # kw-only: ignore — installed as sys.excepthook; interpreter calls it positionally
self,
exc_type: type[BaseException],
exc_value: BaseException,
diff --git a/pipelex/system/telemetry/otel_factory.py b/pipelex/system/telemetry/otel_factory.py
index 85a24fc01..1bef5d3c0 100644
--- a/pipelex/system/telemetry/otel_factory.py
+++ b/pipelex/system/telemetry/otel_factory.py
@@ -29,7 +29,7 @@ if TYPE_CHECKING:
class OtelFactory:
@classmethod
- def make_truncated_content(cls, content: str, max_length: int | None) -> str:
+ def make_truncated_content(cls, content: str, *, max_length: int | None) -> str:
"""Truncate content for telemetry capture if it exceeds max length.
Args:
@@ -61,6 +61,7 @@ class OtelFactory:
def make_inputs_json(
cls,
working_memory: WorkingMemory,
+ *,
needed_input_names: set[str],
max_length: int | None,
) -> str:
@@ -89,6 +90,7 @@ class OtelFactory:
def make_output_json(
cls,
pipe_output: PipeOutput,
+ *,
max_length: int | None,
) -> str:
"""Serialize pipe output to JSON for telemetry.
@@ -128,7 +130,7 @@ class OtelFactory:
return hash_md5_to_int(pipeline_run_id)
@classmethod
- def make_trace_names(cls, pipeline_run_id: str, pipe_code: str) -> tuple[str, str]:
+ def make_trace_names(cls, pipeline_run_id: str, *, pipe_code: str) -> tuple[str, str]:
"""Create both full and redacted trace names from pipeline run ID and pipe code.
Args:
@@ -196,6 +198,7 @@ class OtelFactory:
def make_ai_tracer(
cls,
user_id: str | None,
+ *,
custom_posthog_client: "Posthog | None",
custom_redaction_config: TelemetryRedactionConfig,
pipelex_posthog_client: "Posthog | None",
diff --git a/pipelex/system/telemetry/posthog_span_exporter.py b/pipelex/system/telemetry/posthog_span_exporter.py
index bb394eef0..d83bac707 100644
--- a/pipelex/system/telemetry/posthog_span_exporter.py
+++ b/pipelex/system/telemetry/posthog_span_exporter.py
@@ -40,7 +40,7 @@ class PostHogSpanExporter(SpanExporter):
self.distinct_id = distinct_id
self.redaction_config = redaction_config
- def _capture_event(self, event: PostHogEvent, properties: dict[str, Any]) -> None:
+ def _capture_event(self, event: PostHogEvent, *, properties: dict[str, Any]) -> None:
"""Capture an event to PostHog, handling anonymous vs identified users.
PostHog requires a valid distinct_id - passing None will cause the event to be rejected.
@@ -99,6 +99,7 @@ class PostHogSpanExporter(SpanExporter):
def _build_redacted_pipe_span_name(
self,
original_span_name: str,
+ *,
pipe_type: str | None,
) -> str:
"""Build a redacted span name for pipe spans.
@@ -126,6 +127,7 @@ class PostHogSpanExporter(SpanExporter):
def _build_redacted_generation_span_name(
self,
original_span_name: str,
+ *,
pipe_code: str | None,
unit_job_id: str | None,
model_name: str | None,
@@ -193,7 +195,7 @@ class PostHogSpanExporter(SpanExporter):
return output_class_name
return OTelConstants.PIPE_CODE_REDACTED if output_class_name else None
- def _get_base_properties(self, span: ReadableSpan, attributes: Mapping[str, AttributeValue]) -> dict[str, Any]:
+ def _get_base_properties(self, span: ReadableSpan, *, attributes: Mapping[str, AttributeValue]) -> dict[str, Any]:
"""Get common properties for all span types."""
properties: dict[str, Any] = {}
if span.end_time and span.start_time:
@@ -217,7 +219,7 @@ class PostHogSpanExporter(SpanExporter):
return properties
- def _export_generation_span(self, span: ReadableSpan, attributes: Mapping[str, AttributeValue]) -> None:
+ def _export_generation_span(self, span: ReadableSpan, *, attributes: Mapping[str, AttributeValue]) -> None:
"""Export a GenAI generation span."""
properties = self._get_base_properties(span=span, attributes=attributes)
provider_operation_combo = f"{attributes.get(GenAISpanAttr.PROVIDER_NAME)}:{attributes.get(GenAISpanAttr.OPERATION_NAME)}"
@@ -283,7 +285,7 @@ class PostHogSpanExporter(SpanExporter):
self._capture_event(event=PostHogEvent.GENERATION, properties=properties)
- def _export_pipe_span(self, span: ReadableSpan, attributes: Mapping[str, AttributeValue]) -> None:
+ def _export_pipe_span(self, span: ReadableSpan, *, attributes: Mapping[str, AttributeValue]) -> None:
"""Export a pipe execution span."""
properties = self._get_base_properties(span=span, attributes=attributes)
diff --git a/pipelex/system/telemetry/telemetry_config.py b/pipelex/system/telemetry/telemetry_config.py
index a37d165a2..af9290b42 100644
--- a/pipelex/system/telemetry/telemetry_config.py
+++ b/pipelex/system/telemetry/telemetry_config.py
@@ -280,7 +280,7 @@ def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> Telemetr
# Apply variable substitution to all string values (keep placeholders for missing vars)
substitute_vars_with_provider = partial(substitute_vars, secrets_provider=secrets_provider, raise_on_missing_var=False)
try:
- telemetry_config_toml = apply_to_strings_recursive(telemetry_config_toml_raw, substitute_vars_with_provider)
+ telemetry_config_toml = apply_to_strings_recursive(telemetry_config_toml_raw, transform_func=substitute_vars_with_provider)
except UnknownVarPrefixError as exc:
paths_str = "\n".join(str(path) for path in telemetry_config_paths)
msg = f"Variable substitution failed in telemetry configuration based on '{paths_str}': {exc}"
diff --git a/pipelex/system/telemetry/telemetry_factory.py b/pipelex/system/telemetry/telemetry_factory.py
index 7c0c272eb..4baa90862 100644
--- a/pipelex/system/telemetry/telemetry_factory.py
+++ b/pipelex/system/telemetry/telemetry_factory.py
@@ -23,6 +23,7 @@ class TelemetryFactory:
def make_telemetry_manager(
cls,
secrets_provider: SecretsProviderAbstract,
+ *,
integration_mode: IntegrationMode,
remote_config: RemoteConfig | None,
is_pipelex_telemetry_enabled: bool = False,
diff --git a/pipelex/system/telemetry/telemetry_manager.py b/pipelex/system/telemetry/telemetry_manager.py
index 771237617..85925a924 100644
--- a/pipelex/system/telemetry/telemetry_manager.py
+++ b/pipelex/system/telemetry/telemetry_manager.py
@@ -128,7 +128,9 @@ class TelemetryManager(TelemetryManagerAbstract):
pipelex_distinct_id=self._pipelex_distinct_id,
)
- def _handle_transmission_error(self, error: Exception | None, _items: list[dict[str, Any]]) -> None:
+ def _handle_transmission_error( # kw-only: ignore — PostHog on_error callback, invoked positionally as (error, items)
+ self, error: Exception | None, _items: list[dict[str, Any]]
+ ) -> None:
"""Handle errors that occur during custom telemetry transmission.
Args:
@@ -138,7 +140,9 @@ class TelemetryManager(TelemetryManagerAbstract):
if error:
log.error(f"Telemetry transmission error: {error}")
- def _handle_pipelex_transmission_error(self, error: Exception | None, _items: list[dict[str, Any]]) -> None:
+ def _handle_pipelex_transmission_error( # kw-only: ignore — PostHog on_error callback, invoked positionally as (error, items)
+ self, error: Exception | None, _items: list[dict[str, Any]]
+ ) -> None:
"""Handle errors that occur during Pipelex telemetry transmission.
Args:
@@ -231,7 +235,7 @@ class TelemetryManager(TelemetryManagerAbstract):
TelemetryManagerAbstract.clear_instance()
@override
- def track_event(self, event_name: EventName, properties: dict[EventProperty, Any] | None = None):
+ def track_event(self, event_name: EventName, *, properties: dict[EventProperty, Any] | None = None):
# We copy the incoming properties to avoid modifying the original dictionary
# and to convert the keys to str
# and to remove the properties that are in the redact list
@@ -262,7 +266,7 @@ class TelemetryManager(TelemetryManagerAbstract):
if self._pipelex_telemetry_enabled:
self._track_to_pipelex(event_name=event_name, properties=tracked_properties)
- def _track_anonymous_event(self, event_name: str, properties: dict[str, Any]):
+ def _track_anonymous_event(self, event_name: str, *, properties: dict[str, Any]):
if not self.custom_posthog_client:
log.error("Could not track event to custom telemetry because custom_posthog_client is not set")
return
@@ -270,14 +274,14 @@ class TelemetryManager(TelemetryManagerAbstract):
self.custom_posthog_client.capture(event_name, properties=properties)
log.verbose(f"Tracked anonymous event '{event_name}' with properties: {properties}")
- def _track_identified_event(self, event_name: str, properties: dict[str, Any], user_id: str):
+ def _track_identified_event(self, event_name: str, *, properties: dict[str, Any], user_id: str):
if not self.custom_posthog_client:
log.error("Could not track event to custom telemetry because custom_posthog_client is not set")
return
self.custom_posthog_client.capture(event_name, distinct_id=user_id, properties=properties)
log.verbose(f"Tracked identified event '{event_name}' with properties: {properties}")
- def _track_to_pipelex(self, event_name: str, properties: dict[str, Any]):
+ def _track_to_pipelex(self, event_name: str, *, properties: dict[str, Any]):
"""Track event to Pipelex's PostHog (always identified)."""
if not self.pipelex_posthog_client or not self._pipelex_distinct_id:
log.error("Could not track event to Pipelex telemetry because pipelex_posthog_client or _pipelex_distinct_id is not set")
@@ -386,7 +390,7 @@ class TelemetryManager(TelemetryManagerAbstract):
return self._pipelex_telemetry_enabled
@override
- def handle_trace_start(self, trace_name: str, trace_name_redacted: str, trace_id: int) -> None:
+ def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None:
"""Hook to do something when a trace starts.
Emits a trace start event to establish the trace name in PostHog.
diff --git a/pipelex/system/telemetry/telemetry_manager_abstract.py b/pipelex/system/telemetry/telemetry_manager_abstract.py
index cb0f97576..c01537d95 100644
--- a/pipelex/system/telemetry/telemetry_manager_abstract.py
+++ b/pipelex/system/telemetry/telemetry_manager_abstract.py
@@ -94,7 +94,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
pass
@abstractmethod
- def track_event(self, event_name: EventName, properties: dict[EventProperty, Any] | None = None):
+ def track_event(self, event_name: EventName, *, properties: dict[EventProperty, Any] | None = None):
pass
@abstractmethod
@@ -153,7 +153,7 @@ class TelemetryManagerAbstract(metaclass=ABCSingletonMeta):
"""Whether Pipelex internal telemetry is enabled (for gateway usage)."""
@abstractmethod
- def handle_trace_start(self, trace_name: str, trace_name_redacted: str, trace_id: int) -> None:
+ def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None:
"""Hook to do something when a trace starts.
Args:
@@ -174,7 +174,7 @@ class TelemetryManagerNoOp(TelemetryManagerAbstract):
TelemetryManagerAbstract.clear_instance()
@override
- def track_event(self, event_name: EventName, properties: dict[EventProperty, Any] | None = None):
+ def track_event(self, event_name: EventName, *, properties: dict[EventProperty, Any] | None = None):
pass
@override
@@ -234,5 +234,5 @@ class TelemetryManagerNoOp(TelemetryManagerAbstract):
return False
@override
- def handle_trace_start(self, trace_name: str, trace_name_redacted: str, trace_id: int) -> None:
+ def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None:
pass
diff --git a/pipelex/temporal/codec/codec_server.py b/pipelex/temporal/codec/codec_server.py
index d23533725..d2e51700f 100644
--- a/pipelex/temporal/codec/codec_server.py
+++ b/pipelex/temporal/codec/codec_server.py
@@ -28,7 +28,7 @@ if TYPE_CHECKING:
from pipelex.temporal.codec.storage_payload_codec import StoragePayloadCodec
-def _set_cors_headers(response: web.Response, request_origin: str, cors_origins: list[str]) -> None:
+def _set_cors_headers(response: web.Response, *, request_origin: str, cors_origins: list[str]) -> None:
"""Set CORS headers on the response if the request origin is allowed."""
if request_origin in cors_origins:
response.headers[hdrs.ACCESS_CONTROL_ALLOW_ORIGIN] = request_origin
@@ -41,52 +41,52 @@ def _make_cors_handler(cors_origins: list[str]) -> Callable[[web.Request], Await
async def cors_options(request: web.Request) -> web.Response: # noqa: RUF029 — must be async for aiohttp
response = web.Response()
- _set_cors_headers(response, request.headers.get(hdrs.ORIGIN, ""), cors_origins)
+ _set_cors_headers(response, request_origin=request.headers.get(hdrs.ORIGIN, ""), cors_origins=cors_origins)
return response
return cors_options
-def _error_response(request: web.Request, cors_origins: list[str], status: int, text: str) -> web.Response:
+def _error_response(request: web.Request, *, cors_origins: list[str], status: int, text: str) -> web.Response:
"""Build an error response with CORS headers so browsers see the diagnostic message."""
response = web.Response(status=status, text=text)
- _set_cors_headers(response, request.headers.get(hdrs.ORIGIN, ""), cors_origins)
+ _set_cors_headers(response, request_origin=request.headers.get(hdrs.ORIGIN, ""), cors_origins=cors_origins)
return response
-async def _apply(
+async def _apply( # kw-only: ignore — aiohttp route handler; aiohttp passes `request` positionally via partial(_apply, codec_fn, cors_origins)
codec_fn: Callable[[Sequence[Payload]], Awaitable[list[Payload]]],
cors_origins: list[str],
request: web.Request,
) -> web.Response:
"""Generic handler: parse Payloads JSON, apply codec function, return Payloads JSON."""
if request.content_type != "application/json":
- return _error_response(request, cors_origins, 415, "Expected application/json")
+ return _error_response(request, cors_origins=cors_origins, status=415, text="Expected application/json")
try:
payloads_proto = json_format.Parse(await request.read(), Payloads())
except json_format.ParseError:
- return _error_response(request, cors_origins, 400, "Malformed Payloads JSON")
+ return _error_response(request, cors_origins=cors_origins, status=400, text="Malformed Payloads JSON")
try:
result_payloads = await codec_fn(payloads_proto.payloads)
except StorageFileNotFoundError as exc:
log.error(f"Codec storage lookup failed: {exc}")
- return _error_response(request, cors_origins, 404, "Storage object not found")
+ return _error_response(request, cors_origins=cors_origins, status=404, text="Storage object not found")
except (OSError, FileNotFoundError) as exc:
log.error(f"Codec I/O error: {exc}")
- return _error_response(request, cors_origins, 502, "Storage I/O error")
+ return _error_response(request, cors_origins=cors_origins, status=502, text="Storage I/O error")
result_proto = Payloads(payloads=result_payloads)
response = web.Response()
- _set_cors_headers(response, request.headers.get(hdrs.ORIGIN, ""), cors_origins)
+ _set_cors_headers(response, request_origin=request.headers.get(hdrs.ORIGIN, ""), cors_origins=cors_origins)
response.content_type = "application/json"
response.text = json_format.MessageToJson(result_proto)
return response
-def build_codec_server(codec: StoragePayloadCodec, cors_origins: list[str]) -> web.Application:
+def build_codec_server(codec: StoragePayloadCodec, *, cors_origins: list[str]) -> web.Application:
"""Build an aiohttp application implementing the Temporal codec server protocol.
Args:
diff --git a/pipelex/temporal/codec/storage_payload_codec.py b/pipelex/temporal/codec/storage_payload_codec.py
index 315641bec..48e4be421 100644
--- a/pipelex/temporal/codec/storage_payload_codec.py
+++ b/pipelex/temporal/codec/storage_payload_codec.py
@@ -76,7 +76,7 @@ class StoragePayloadCodec(PayloadCodec):
"""Sanitize a path segment to prevent traversal and encoding issues."""
return re.sub(r"[^A-Za-z0-9_\-]", "_", segment)
- def _build_storage_key(self, payload: Payload, hash_hex: str) -> str:
+ def _build_storage_key(self, payload: Payload, *, hash_hex: str) -> str:
"""Build a storage key, structured by job routing when available."""
routing = self._extract_job_routing(payload)
if routing:
@@ -95,7 +95,7 @@ class StoragePayloadCodec(PayloadCodec):
encoded.append(payload)
continue
hash_hex = sha256(serialized).hexdigest()
- key = self._build_storage_key(payload, hash_hex)
+ key = self._build_storage_key(payload, hash_hex=hash_hex)
uri = await self._storage.store(data=serialized, key=key)
log.dev(f"Payload offloaded to storage: key='{key}'")
ref_payload = Payload(
diff --git a/pipelex/temporal/config_temporal.py b/pipelex/temporal/config_temporal.py
index c80be1475..f17424302 100644
--- a/pipelex/temporal/config_temporal.py
+++ b/pipelex/temporal/config_temporal.py
@@ -466,7 +466,7 @@ class WorkerConfig(ConfigModel):
result.update(handle_opts.retry_policy_config.non_retryable_error_types_extra)
return result
- def resolve_queue(self, activity_name: str, routing_key: str | None = None) -> str | None:
+ def resolve_queue(self, activity_name: str, *, routing_key: str | None = None) -> str | None:
"""Resolve which task queue an activity should dispatch to.
Hybrid fallback semantic. When ``activity_queues`` is fully empty
@@ -508,6 +508,7 @@ class WorkerConfig(ConfigModel):
def resolve_dispatch(
self,
activity_name: str,
+ *,
routing_key: str | None = None,
queue_options_by_queue: dict[str, "QueueOptions"] | None = None,
is_traced: bool = False,
diff --git a/pipelex/temporal/task_manager.py b/pipelex/temporal/task_manager.py
index 77b59fe5e..046d9b4dd 100644
--- a/pipelex/temporal/task_manager.py
+++ b/pipelex/temporal/task_manager.py
@@ -15,6 +15,7 @@ class TaskManager(Protocol):
def complement_catalog(
self,
extra_catalog: dict[str, TaskPack],
+ *,
extra_workflows: list[WorkflowType],
extra_activities: list[ActivityType],
): ...
@@ -22,6 +23,7 @@ class TaskManager(Protocol):
def make_worker(
self,
temporal_client: TemporalClient,
+ *,
task_queue: str,
is_not_sandboxed: bool = False,
scope: WorkerScope | None = None,
@@ -33,6 +35,7 @@ class TaskManager(Protocol):
async def run_worker(
self,
+ *,
is_not_sandboxed: bool,
is_unit_testing: bool,
task_queue: str | None = None,
@@ -45,6 +48,7 @@ class TaskManager(Protocol):
def workflows_and_activities(
self,
scope: WorkerScope | None = None,
+ *,
test_workflows: WorkflowList | None = None,
test_activities: ActivityList | None = None,
substitute_activities: dict[ActivityType, ActivityType] | None = None,
diff --git a/pipelex/temporal/temporal_connect.py b/pipelex/temporal/temporal_connect.py
index 886238f10..27359eeb5 100644
--- a/pipelex/temporal/temporal_connect.py
+++ b/pipelex/temporal/temporal_connect.py
@@ -15,7 +15,7 @@ if TYPE_CHECKING:
from temporalio.converter import DataConverter
-async def connect_to_temporal_server(server_config: TemporalServerConfig, name: str | None = None) -> TemporalClient:
+async def connect_to_temporal_server(server_config: TemporalServerConfig, *, name: str | None = None) -> TemporalClient:
"""Connect to Temporal using the provided server config."""
api_key: str | None
match server_config.api_key_method:
diff --git a/pipelex/temporal/temporal_data_converter.py b/pipelex/temporal/temporal_data_converter.py
index efe5276b1..7cd8132f7 100644
--- a/pipelex/temporal/temporal_data_converter.py
+++ b/pipelex/temporal/temporal_data_converter.py
@@ -61,7 +61,7 @@ class BaseModelPayloadConverter(JSONPlainPayloadConverter):
"""
return isinstance(value, BaseModel) or is_pydantic_dataclass(type(value))
- def _kajson_to_payload(self, value: object, source_type_holder: object) -> Payload:
+ def _kajson_to_payload(self, value: object, *, source_type_holder: object) -> Payload:
"""Serialize a kajson wire value (or list of them) to a Payload.
``source_type_holder`` is the object whose type may carry a dynamic-class ``__kajson_class_source__``
@@ -94,7 +94,7 @@ class BaseModelPayloadConverter(JSONPlainPayloadConverter):
return self._kajson_to_payload(value, source_type_holder=list_head)
return super().to_payload(value)
- def _restore_class_source(self, value: BaseModel, class_source_code: str) -> None:
+ def _restore_class_source(self, value: BaseModel, *, class_source_code: str) -> None:
value_class = cast("Any", type(value))
value_class.__kajson_class_source__ = class_source_code
@@ -121,11 +121,11 @@ class BaseModelPayloadConverter(JSONPlainPayloadConverter):
if class_source_code is not None:
if isinstance(pydantic_gizmo, BaseModel):
- self._restore_class_source(pydantic_gizmo, class_source_code)
+ self._restore_class_source(pydantic_gizmo, class_source_code=class_source_code)
elif isinstance(pydantic_gizmo, list):
for item in cast("list[Any]", pydantic_gizmo):
if isinstance(item, BaseModel):
- self._restore_class_source(item, class_source_code)
+ self._restore_class_source(item, class_source_code=class_source_code)
log.verbose(f"unijson_deserialize_payload — pydantic_gizmo: {pydantic_gizmo}")
return cast("Any", pydantic_gizmo)
diff --git a/pipelex/temporal/temporal_manager.py b/pipelex/temporal/temporal_manager.py
index eff5621f5..d4b54e532 100644
--- a/pipelex/temporal/temporal_manager.py
+++ b/pipelex/temporal/temporal_manager.py
@@ -47,6 +47,7 @@ class TemporalManager:
async def connect_temporal(
self,
temporal_client: TemporalClient | None = None,
+ *,
temporal_server_config: TemporalServerConfig | None = None,
temporal_selected_server: str | None = None,
) -> TemporalClient:
diff --git a/pipelex/temporal/temporal_task_manager.py b/pipelex/temporal/temporal_task_manager.py
index 714e46f88..51597f45a 100644
--- a/pipelex/temporal/temporal_task_manager.py
+++ b/pipelex/temporal/temporal_task_manager.py
@@ -69,6 +69,7 @@ class TemporalTaskManager(TaskManager):
def complement_catalog(
self,
extra_catalog: dict[str, TaskPack],
+ *,
extra_workflows: list[WorkflowType],
extra_activities: list[ActivityType],
):
@@ -82,6 +83,7 @@ class TemporalTaskManager(TaskManager):
def make_worker(
self,
temporal_client: TemporalClient,
+ *,
task_queue: str,
is_not_sandboxed: bool = False,
scope: WorkerScope | None = None,
@@ -162,6 +164,7 @@ class TemporalTaskManager(TaskManager):
@override
async def run_worker(
self,
+ *,
is_not_sandboxed: bool,
is_unit_testing: bool,
task_queue: str | None = None,
@@ -255,6 +258,7 @@ class TemporalTaskManager(TaskManager):
def workflows_and_activities(
self,
scope: WorkerScope | None = None,
+ *,
test_workflows: WorkflowList | None = None,
test_activities: ActivityList | None = None,
substitute_activities: dict[ActivityType, ActivityType] | None = None,
diff --git a/pipelex/temporal/temporal_tasks.py b/pipelex/temporal/temporal_tasks.py
index 273c70b27..06d0d82d2 100644
--- a/pipelex/temporal/temporal_tasks.py
+++ b/pipelex/temporal/temporal_tasks.py
@@ -19,6 +19,7 @@ class TemporalTasks:
def complement_catalog(
self,
extra_catalog: dict[str, TaskPack],
+ *,
extra_workflows: list[WorkflowType],
extra_activities: list[ActivityType],
):
@@ -37,6 +38,7 @@ class TemporalTasks:
def replace_catalog(
self,
new_catalog: dict[str, TaskPack],
+ *,
new_workflows: list[WorkflowType],
new_activities: list[ActivityType],
):
@@ -63,7 +65,7 @@ class TemporalTasks:
return all_workflows, all_activities
@classmethod
- def _register_workflow(cls, all_workflows: dict[str, WorkflowType], workflow: WorkflowType, source: str) -> None:
+ def _register_workflow(cls, all_workflows: dict[str, WorkflowType], *, workflow: WorkflowType, source: str) -> None:
existing = all_workflows.get(workflow.__name__)
if existing is not None and existing is not workflow:
msg = (
@@ -74,7 +76,7 @@ class TemporalTasks:
all_workflows[workflow.__name__] = workflow
@classmethod
- def _register_activity(cls, all_activities: dict[str, ActivityType], activity: ActivityType, source: str) -> None:
+ def _register_activity(cls, all_activities: dict[str, ActivityType], *, activity: ActivityType, source: str) -> None:
existing = all_activities.get(activity.__name__)
if existing is not None and existing is not activity:
msg = (
@@ -87,6 +89,7 @@ class TemporalTasks:
def workflows_and_activities(
self,
scope: WorkerScope | None = None,
+ *,
test_workflows: WorkflowList | None = None,
test_activities: ActivityList | None = None,
substitute_activities: dict[ActivityType, ActivityType] | None = None,
@@ -119,6 +122,7 @@ class TemporalTasks:
def _resolve_scope(
self,
scope: WorkerScope,
+ *,
all_workflows: dict[str, WorkflowType],
all_activities: dict[str, ActivityType],
) -> tuple[set[WorkflowType], set[ActivityType]]:
diff --git a/pipelex/temporal/tprl/namespace_check.py b/pipelex/temporal/tprl/namespace_check.py
index 3174b79c1..551dfcbfe 100644
--- a/pipelex/temporal/tprl/namespace_check.py
+++ b/pipelex/temporal/tprl/namespace_check.py
@@ -68,7 +68,7 @@ class RegistrationFailure(BaseModel):
rpc_error_message: str
-def format_temporal_cli_command(missing: Sequence[str], namespace: str) -> str:
+def format_temporal_cli_command(missing: Sequence[str], *, namespace: str) -> str:
"""Format the exact ``temporal operator search-attribute create`` invocation
so an operator with raw ``temporal`` CLI access can copy-paste it.
"""
@@ -81,7 +81,7 @@ def format_temporal_cli_command(missing: Sequence[str], namespace: str) -> str:
return " \\\n".join(parts)
-def format_tcld_cli_command(missing: Sequence[str], namespace: str) -> str:
+def format_tcld_cli_command(missing: Sequence[str], *, namespace: str) -> str:
"""Format the Temporal Cloud ``tcld`` invocation a namespace admin runs
when the worker API key lacks ``OperatorService.AddSearchAttributes``
permission. Used both as a hint in the dry-run output and as part of the
@@ -93,6 +93,7 @@ def format_tcld_cli_command(missing: Sequence[str], namespace: str) -> str:
async def check_required_search_attributes(
temporal_client: TemporalClient,
+ *,
namespace: str,
configured_attributes: Sequence[str],
) -> None:
@@ -153,6 +154,7 @@ async def check_required_search_attributes(
async def ensure_required_search_attributes_registered(
temporal_client: TemporalClient,
+ *,
namespace: str,
configured_attributes: Sequence[str],
) -> RegistrationFailure | tuple[str, ...]:
diff --git a/pipelex/temporal/tprl/observability.py b/pipelex/temporal/tprl/observability.py
index 0cabdee63..9aeb9a42f 100644
--- a/pipelex/temporal/tprl/observability.py
+++ b/pipelex/temporal/tprl/observability.py
@@ -35,7 +35,7 @@ USER_ID_KEY: Final[SearchAttributeKey[str]] = SearchAttributeKey.for_keyword("Us
DOMAIN_CODE_KEY: Final[SearchAttributeKey[str]] = SearchAttributeKey.for_keyword("DomainCode")
-def _truncate_utf8(text: str, max_bytes: int) -> str:
+def _truncate_utf8(text: str, *, max_bytes: int) -> str:
"""Return ``text`` truncated so its UTF-8 encoding fits in ``max_bytes``.
A trailing ellipsis is appended when truncation occurs. The slice is decoded
@@ -131,7 +131,7 @@ def build_static_summary(pipe: PipeAbstract) -> str:
text = f"{pipe.code} — {pipe.description}"
else:
text = pipe.code
- return _truncate_utf8(text, _MAX_SUMMARY_BYTES)
+ return _truncate_utf8(text, max_bytes=_MAX_SUMMARY_BYTES)
def build_static_details(pipe_job: PipeJob) -> str:
@@ -157,11 +157,12 @@ def build_static_details(pipe_job: PipeJob) -> str:
lines: list[str] = ["| Field | Value |", "|---|---|"]
for field, value in rows:
lines.append(f"| {field} | {value} |")
- return _truncate_utf8("\n".join(lines), _MAX_DETAILS_BYTES)
+ return _truncate_utf8("\n".join(lines), max_bytes=_MAX_DETAILS_BYTES)
def build_activity_summary(
method_label: str,
+ *,
job_metadata: JobMetadata,
extras: Mapping[str, str] | None = None,
) -> str:
@@ -181,4 +182,4 @@ def build_activity_summary(
for key, value in extras.items():
parts.append(f"{key}={value}")
text = " · ".join(parts)
- return _truncate_utf8(text, _MAX_SUMMARY_BYTES)
+ return _truncate_utf8(text, max_bytes=_MAX_SUMMARY_BYTES)
diff --git a/pipelex/temporal/tprl/temporal_error.py b/pipelex/temporal/tprl/temporal_error.py
index cf20ec444..5dc919977 100644
--- a/pipelex/temporal/tprl/temporal_error.py
+++ b/pipelex/temporal/tprl/temporal_error.py
@@ -229,7 +229,7 @@ class TemporalError(ApplicationError):
)
@classmethod
- def from_message_exception(cls, exc: PipelexError, force_non_retryable: bool = False) -> Self:
+ def from_message_exception(cls, exc: PipelexError, *, force_non_retryable: bool = False) -> Self:
"""Convert a Pipelex exception into a ``TemporalError``.
**Activity-side (default).** Retryability is derived from the ``__cause__``
@@ -267,7 +267,7 @@ class TemporalError(ApplicationError):
)
@classmethod
- def _is_non_retryable(cls, exc: PipelexError, error_type: str) -> bool:
+ def _is_non_retryable(cls, exc: PipelexError, *, error_type: str) -> bool:
"""Decide retryability — category-aware for ``CogtError``, name-list fallback otherwise.
A categorized ``CogtError`` is usually wrapped — ``PipeRunError`` ->
diff --git a/pipelex/temporal/tprl/workflow_caller.py b/pipelex/temporal/tprl/workflow_caller.py
index ef63b9a93..a41053760 100644
--- a/pipelex/temporal/tprl/workflow_caller.py
+++ b/pipelex/temporal/tprl/workflow_caller.py
@@ -91,6 +91,7 @@ class WorkflowExecutor(WorkflowCaller, Generic[WorkflowInput, WorkflowOutput]):
async def execute_workflow(
self,
workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]],
+ *,
workflow_arg: WorkflowInput,
workflow_id: str,
search_attributes: TypedSearchAttributes | None = None,
@@ -139,6 +140,7 @@ class WorkflowExecutor(WorkflowCaller, Generic[WorkflowInput, WorkflowOutput]):
async def start_workflow(
self,
workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]],
+ *,
workflow_arg: WorkflowInput,
workflow_id: str,
callbacks: Sequence[Callback] | None = None,
@@ -178,6 +180,7 @@ class WorkflowExecutor(WorkflowCaller, Generic[WorkflowInput, WorkflowOutput]):
async def execute_child_workflow(
self,
workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]],
+ *,
workflow_arg: WorkflowInput,
workflow_id: str,
child_task_queue: str | None = None,
@@ -243,6 +246,7 @@ class WorkflowExecutor(WorkflowCaller, Generic[WorkflowInput, WorkflowOutput]):
async def start_child_workflow(
self,
workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]],
+ *,
workflow_arg: WorkflowInput,
workflow_id: str,
child_task_queue: str | None = None,
@@ -293,6 +297,7 @@ class WorkflowExecutorFactory(Generic[WorkflowInput, WorkflowOutput]):
@classmethod
def create_executor(
cls,
+ *,
task_queue: str | None = None,
workflow_execution_timeout: timedelta | None = None,
retry_policy: RetryPolicy | None = None,
diff --git a/pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py b/pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py
index a46c5d5f7..d292211f3 100644
--- a/pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py
+++ b/pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py
@@ -50,8 +50,8 @@ from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
def _revalidate_against_object_class(
raw_obj: BaseModel,
- object_class: type[BaseModelTypeVar],
*,
+ object_class: type[BaseModelTypeVar],
is_mock_built: bool,
) -> BaseModelTypeVar:
"""Re-validate an activity-boundary object against the original ``object_class``.
@@ -95,6 +95,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@update_job_metadata
async def make_llm_text(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
llm_setting_main: LLMSetting,
@@ -120,7 +121,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
generated_text: str = await workflow.execute_activity(
act_llm_gen_text,
arg=llm_assignment,
- summary=build_activity_summary("LLM text", job_metadata, extras={"model": llm_assignment.llm_handle}),
+ summary=build_activity_summary("LLM text", job_metadata=job_metadata, extras={"model": llm_assignment.llm_handle}),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -135,6 +136,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@update_job_metadata
async def make_object(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
object_class: type[BaseModelTypeVar],
@@ -163,7 +165,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
obj: BaseModel = await workflow.execute_activity(
act_llm_gen_object,
arg=object_assignment,
- summary=build_activity_summary("LLM object", job_metadata, extras={"class": object_class.__name__}),
+ summary=build_activity_summary("LLM object", job_metadata=job_metadata, extras={"class": object_class.__name__}),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -172,12 +174,13 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
raise TemporalError.from_app_error(exc=exc.cause) from exc
raise
log.verbose(f"ContentGeneratorInWorkflow generated object direct: {obj}")
- return _revalidate_against_object_class(obj, object_class, is_mock_built=cogt_run_params.run_mode.is_dry)
+ return _revalidate_against_object_class(obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)
@override
@update_job_metadata
async def make_object_list(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
object_class: type[BaseModelTypeVar],
@@ -207,7 +210,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
obj_list: list[BaseModel] = await workflow.execute_activity(
act_llm_gen_object_list,
arg=object_assignment,
- summary=build_activity_summary("LLM object list", job_metadata, extras={"class": object_class.__name__}),
+ summary=build_activity_summary("LLM object list", job_metadata=job_metadata, extras={"class": object_class.__name__}),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -216,12 +219,16 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
raise TemporalError.from_app_error(exc=exc.cause) from exc
raise
log.verbose(f"ContentGeneratorInWorkflow generated object list direct: {obj_list}")
- return [_revalidate_against_object_class(raw_obj, object_class, is_mock_built=cogt_run_params.run_mode.is_dry) for raw_obj in obj_list]
+ return [
+ _revalidate_against_object_class(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)
+ for raw_obj in obj_list
+ ]
@override
@update_job_metadata
async def make_single_image(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
img_gen_handle: str,
@@ -250,7 +257,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
image_content_list: list[ImageContent] = await workflow.execute_activity(
act_img_gen_images,
arg=img_gen_assignment,
- summary=build_activity_summary("Img gen 1×", job_metadata, extras={"model": img_gen_handle}),
+ summary=build_activity_summary("Img gen 1×", job_metadata=job_metadata, extras={"model": img_gen_handle}),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -269,6 +276,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@update_job_metadata
async def make_image_list(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
img_gen_handle: str,
@@ -298,7 +306,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
image_content_list: list[ImageContent] = await workflow.execute_activity(
act_img_gen_images,
arg=img_gen_assignment,
- summary=build_activity_summary("Img gen N×", job_metadata, extras={"model": img_gen_handle, "n": str(nb_images)}),
+ summary=build_activity_summary("Img gen N×", job_metadata=job_metadata, extras={"model": img_gen_handle, "n": str(nb_images)}),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -313,6 +321,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@update_job_metadata
async def make_templated_text(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
context: dict[str, Any],
@@ -338,7 +347,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
jinja2_text: str = await workflow.execute_activity(
act_jinja2_gen_text,
arg=templating_assignment,
- summary=build_activity_summary("Templated text", job_metadata),
+ summary=build_activity_summary("Templated text", job_metadata=job_metadata),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -353,6 +362,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@update_job_metadata
async def make_render_page_views(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
extract_input: ExtractInput,
@@ -381,7 +391,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
image_content_list: list[ImageContent] = await workflow.execute_activity(
act_render_page_views,
arg=render_assignment,
- summary=build_activity_summary("Render page views", job_metadata),
+ summary=build_activity_summary("Render page views", job_metadata=job_metadata),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -396,6 +406,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@update_job_metadata
async def make_extract_pages(
self,
+ *,
job_metadata: JobMetadata,
cogt_run_params: CogtRunParams,
extract_input: ExtractInput,
@@ -422,7 +433,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
page_contents: list[PageContent] = await workflow.execute_activity(
act_extract_gen_extract_pages,
arg=extract_assignment,
- summary=build_activity_summary("Extract pages", job_metadata, extras={"handle": extract_handle}),
+ summary=build_activity_summary("Extract pages", job_metadata=job_metadata, extras={"handle": extract_handle}),
**dispatch_kwargs,
)
except ActivityError as exc:
@@ -451,7 +462,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
page_view_contents = await workflow.execute_activity(
act_render_page_views,
arg=render_assignment,
- summary=build_activity_summary("Render page views (extract)", job_metadata),
+ summary=build_activity_summary("Render page views (extract)", job_metadata=job_metadata),
**render_dispatch_kwargs,
)
except ActivityError as exc:
@@ -486,7 +497,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
act_search_gen_sourced_answer,
arg=search_assignment,
summary=build_activity_summary(
- "Search sourced answer", search_assignment.job_metadata, extras={"model": search_assignment.search_handle}
+ "Search sourced answer", job_metadata=search_assignment.job_metadata, extras={"model": search_assignment.search_handle}
),
**dispatch_kwargs,
)
@@ -501,6 +512,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
@override
async def make_search_structured(
self,
+ *,
output_structure_class: type[BaseModelTypeVar],
search_assignment: SearchAssignment,
) -> BaseModelTypeVar:
@@ -520,7 +532,7 @@ class ContentGeneratorInWorkflow(ContentGeneratorProtocol):
act_search_gen_structured,
arg=search_object_assignment,
summary=build_activity_summary(
- "Search structured", search_assignment.job_metadata, extras={"class": output_structure_class.__name__}
+ "Search structured", job_metadata=search_assignment.job_metadata, extras={"class": output_structure_class.__name__}
),
**dispatch_kwargs,
)
diff --git a/pipelex/temporal/tprl_pipe/act_dry_validate.py b/pipelex/temporal/tprl_pipe/act_dry_validate.py
index 5e07ca95d..4906034ee 100644
--- a/pipelex/temporal/tprl_pipe/act_dry_validate.py
+++ b/pipelex/temporal/tprl_pipe/act_dry_validate.py
@@ -63,6 +63,10 @@ class DryValidateArg(BaseModel):
"""Input for the dry-run+validation activity (serializable across the Temporal boundary)."""
mthds_contents: list[str] | None = None
+ # Optional per-content sources threaded onto `blueprint.source` so the worker's
+ # categorized `ValidateBundleError` carries a real `source` (length must match
+ # `mthds_contents` — `validate_bundle` enforces it). `None` keeps `source=None`.
+ mthds_sources: list[str] | None = None
allow_signatures: bool = False
# Optional explicit pipe selection for the graph arm; defaults to the bundle's declared
# main_pipe (qualified from the first blueprint declaring one). The sweep always covers the
@@ -100,9 +104,10 @@ async def act_dry_validate(arg: DryValidateArg) -> DryValidateResult:
"""Run the validation sweep + the in-memory graph dry-run against one library, in-process.
Raises (crossing as structured ``ErrorReport``s via ``convert_pipelex_errors``):
- ValidateBundleError: any validation failure — blueprint/factory/wiring errors, unexpected
- dry-run pipe failures, strict-mode signature refusals (the same categorized cascade
- the direct-mode route surfaces).
+ ValidateBundleError: any validation failure — blueprint/factory/wiring errors and unexpected
+ dry-run pipe failures (the same categorized cascade the direct-mode route surfaces).
+ Signatures are NOT a failure (D-B): an unsatisfied ``PipeSignature`` rides the result's
+ ``pending_signatures`` / ``is_runnable``, it does not raise.
PipeIOContractError: a JSON-Schema rendering failure while building `pipe_io_contracts`
(non-retryable at the workflow tier, like ValidateBundleError — deterministic).
PipelexError: non-validation failures (config, library, tracing infra).
@@ -112,6 +117,7 @@ async def act_dry_validate(arg: DryValidateArg) -> DryValidateResult:
# Success → the library is left loaded + current (D6) and THIS activity owns the teardown.
validate_result = await validate_bundle(
mthds_contents=arg.mthds_contents,
+ mthds_sources=arg.mthds_sources,
allow_signatures=arg.allow_signatures,
)
library_id = get_current_library_id_or_none()
diff --git a/pipelex/temporal/tprl_pipe/temporal_pipe_router.py b/pipelex/temporal/tprl_pipe/temporal_pipe_router.py
index d10a8c77c..eb2a03027 100644
--- a/pipelex/temporal/tprl_pipe/temporal_pipe_router.py
+++ b/pipelex/temporal/tprl_pipe/temporal_pipe_router.py
@@ -121,10 +121,11 @@ class TemporalPipeRouter(WorkflowExecutor[PipeJob, PipeOutput], PipeRouterProtoc
# Rehydrate PipeOutput: reconstruct typed WorkingMemory from raw dict.
# Uses a per-call scoped library when the pipe_job carries a crate so the
# submitter does not need to have pre-loaded the bundle into its global registry.
- return rehydrate_pipe_output_with_crate(pipe_output, pipe_job.library_crate)
+ return rehydrate_pipe_output_with_crate(pipe_output, library_crate=pipe_job.library_crate)
def make_temporal_pipe_router(
+ *,
task_queue: str | None = None,
workflow_execution_timeout: timedelta | None = None,
retry_policy: RetryPolicy | None = None,
diff --git a/pipelex/temporal/tprl_pipe/temporal_pipe_run.py b/pipelex/temporal/tprl_pipe/temporal_pipe_run.py
index d526d78b2..e4b874c61 100644
--- a/pipelex/temporal/tprl_pipe/temporal_pipe_run.py
+++ b/pipelex/temporal/tprl_pipe/temporal_pipe_run.py
@@ -49,6 +49,7 @@ class TemporalPipeRun(WorkflowExecutor[PipeRunArg, PipeOutput], PipeRunProtocol)
async def run(
self,
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None = None,
) -> PipeOutput:
"""Execute a pipe run via Temporal (blocking — waits for completion).
@@ -85,12 +86,13 @@ class TemporalPipeRun(WorkflowExecutor[PipeRunArg, PipeOutput], PipeRunProtocol)
# Rehydrate PipeOutput on the submitter. When the pipe_job carries a crate,
# the helper opens a per-call scoped library so the submitter does not need
# the bundle pre-loaded in its global registry.
- return rehydrate_pipe_output_with_crate(pipe_output, pipe_job.library_crate)
+ return rehydrate_pipe_output_with_crate(pipe_output, library_crate=pipe_job.library_crate)
@with_conditional_worker
async def start(
self,
pipe_job: PipeJob,
+ *,
delivery_assignment: DeliveryAssignment | None = None,
) -> tuple[str, WorkflowHandle[WorkflowClass[PipeRunArg, PipeOutput], PipeOutput]]:
"""Start a pipe run without waiting for completion.
@@ -127,6 +129,7 @@ class TemporalPipeRun(WorkflowExecutor[PipeRunArg, PipeOutput], PipeRunProtocol)
def make_temporal_pipe_run(
+ *,
task_queue: str | None = None,
workflow_execution_timeout: timedelta | None = None,
retry_policy: RetryPolicy | None = None,
diff --git a/pipelex/temporal/tprl_pipe/wf_dry_validate.py b/pipelex/temporal/tprl_pipe/wf_dry_validate.py
index 65aecc31e..ebbbacd94 100644
--- a/pipelex/temporal/tprl_pipe/wf_dry_validate.py
+++ b/pipelex/temporal/tprl_pipe/wf_dry_validate.py
@@ -28,7 +28,7 @@ class WfDryValidate(WorkflowClass[DryValidateArg, DryValidateResult]):
# D-C5: explicit timeout + retry bounds, deterministic in workflow code (no config reads).
# Validation is deterministic — its failures must NOT retry. The deterministic-failure
# surface crosses the boundary as TWO types: validate_bundle wraps
- # SignaturesNotAllowedError / DryRunError / PipelexInterpreterError into
+ # DryRunError / PipeRunError / PipelexInterpreterError into
# ValidateBundleError before they escape, and build_pipe_io_contracts wraps a
# JSON-Schema rendering failure into PipeIOContractError; the activity-boundary
# TemporalError carries the OUTER PipelexError class name as the ApplicationError
diff --git a/pipelex/temporal/worker_cli.py b/pipelex/temporal/worker_cli.py
index 7326db74c..e388b6c58 100644
--- a/pipelex/temporal/worker_cli.py
+++ b/pipelex/temporal/worker_cli.py
@@ -23,6 +23,7 @@ app = typer.Typer()
async def run_worker(
+ *,
project: str | None = None,
is_not_sandboxed: bool = False,
is_unit_testing: bool = False,
@@ -94,7 +95,16 @@ def configure(
updated_temporal = get_config().temporal.model_copy(update={"is_enabled": True})
get_config().temporal = updated_temporal
- asyncio.run(run_worker(project, is_not_sandboxed, is_unit_testing, task_queue, scope, profile))
+ asyncio.run(
+ run_worker(
+ project=project,
+ is_not_sandboxed=is_not_sandboxed,
+ is_unit_testing=is_unit_testing,
+ task_queue=task_queue,
+ scope_name=scope,
+ profile_name=profile,
+ )
+ )
if __name__ == "__main__":
diff --git a/pipelex/test_extras/shared_pytest_plugins.py b/pipelex/test_extras/shared_pytest_plugins.py
index d38c671ef..e366b1b2b 100644
--- a/pipelex/test_extras/shared_pytest_plugins.py
+++ b/pipelex/test_extras/shared_pytest_plugins.py
@@ -206,7 +206,9 @@ def setup_ci_environment():
_cleanup_placeholder_env_vars(env_var_keys=env_var_keys)
-def pytest_collection_modifyitems(config: Config, items: list[pytest.Item]) -> None:
+def pytest_collection_modifyitems( # kw-only: ignore — pytest hookimpl, invoked by pluggy as a framework entrypoint
+ config: Config, items: list[pytest.Item]
+) -> None:
"""Auto-skip non-dry-runnable inference tests when --disable-inference is set.
This hook runs after test collection and adds skip markers to tests that:
diff --git a/pipelex/tools/jinja2/image_renderable.py b/pipelex/tools/jinja2/image_renderable.py
index 8862a26c1..6a04e9118 100644
--- a/pipelex/tools/jinja2/image_renderable.py
+++ b/pipelex/tools/jinja2/image_renderable.py
@@ -36,6 +36,7 @@ class ImageRenderable(Protocol):
def render_with_images(
self,
registry: ImageRegistry,
+ *,
text_format: TextFormat,
) -> str:
"""Render to string, registering images to the registry.
diff --git a/pipelex/tools/jinja2/jinja2_environment.py b/pipelex/tools/jinja2/jinja2_environment.py
index a52435ef0..a46180104 100644
--- a/pipelex/tools/jinja2/jinja2_environment.py
+++ b/pipelex/tools/jinja2/jinja2_environment.py
@@ -7,9 +7,9 @@ from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
def make_jinja2_env_from_loader(
+ *,
template_category: TemplateCategory,
loader: BaseLoader,
- *,
enable_async: bool = True,
) -> Environment:
autoescape: bool
@@ -56,8 +56,8 @@ def make_jinja2_env_from_loader(
def _register_filters(
jinja2_env: Environment,
- template_category: TemplateCategory,
*,
+ template_category: TemplateCategory,
enable_async: bool,
) -> None:
"""Register template category filters on the Jinja2 environment.
@@ -90,7 +90,7 @@ def make_jinja2_env_without_loader(
enable_async=enable_async,
)
- _register_filters(jinja2_env, template_category, enable_async=enable_async)
+ _register_filters(jinja2_env, template_category=template_category, enable_async=enable_async)
return jinja2_env
@@ -119,5 +119,5 @@ def make_jinja2_env_from_registry(
enable_async=enable_async,
)
- _register_filters(jinja2_env, template_category, enable_async=enable_async)
+ _register_filters(jinja2_env, template_category=template_category, enable_async=enable_async)
return jinja2_env
diff --git a/pipelex/tools/jinja2/jinja2_filters.py b/pipelex/tools/jinja2/jinja2_filters.py
index 8b06b1cce..8c9cf8a3e 100644
--- a/pipelex/tools/jinja2/jinja2_filters.py
+++ b/pipelex/tools/jinja2/jinja2_filters.py
@@ -104,10 +104,10 @@ async def tag(context: Context, value: Any, tag_name: str | None = None) -> str:
else:
rendered_value = str(value)
- return apply_tag_style(context, rendered_value, final_tag_name)
+ return apply_tag_style(context=context, value=rendered_value, tag_name=final_tag_name)
-def apply_tag_style(context: Context, value: str, tag_name: str | None = None) -> str:
+def apply_tag_style(*, context: Context, value: str, tag_name: str | None = None) -> str:
"""Apply tag style wrapping to content.
Args:
diff --git a/pipelex/tools/jinja2/jinja2_parsing.py b/pipelex/tools/jinja2/jinja2_parsing.py
index 31a4fff80..cae2b6956 100644
--- a/pipelex/tools/jinja2/jinja2_parsing.py
+++ b/pipelex/tools/jinja2/jinja2_parsing.py
@@ -7,6 +7,7 @@ from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_without_load
def check_jinja2_parsing(
template_source: str,
+ *,
template_category: TemplateCategory = TemplateCategory.LLM_PROMPT,
):
jinja2_env = make_jinja2_env_without_loader(template_category=template_category)
diff --git a/pipelex/tools/jinja2/jinja2_rendering.py b/pipelex/tools/jinja2/jinja2_rendering.py
index ee61cf986..1a0642502 100644
--- a/pipelex/tools/jinja2/jinja2_rendering.py
+++ b/pipelex/tools/jinja2/jinja2_rendering.py
@@ -21,7 +21,7 @@ from pipelex.tools.jinja2.jinja2_environment import (
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
-def _add_to_templating_context(templating_context: dict[str, Any], jinja2_context_key: Jinja2ContextKey, value: Any) -> None:
+def _add_to_templating_context(templating_context: dict[str, Any], *, jinja2_context_key: Jinja2ContextKey, value: Any) -> None:
if jinja2_context_key in templating_context:
msg = f"Jinja2 context key '{jinja2_context_key}' already in templating_context"
raise Jinja2StuffError(msg)
@@ -36,8 +36,8 @@ class _Jinja2Template(Protocol):
def _compile_jinja2_template(
template_source: str,
- template_category: TemplateCategory,
*,
+ template_category: TemplateCategory,
use_registry: bool = False,
enable_async: bool = True,
finalize: Callable[[Any], Any] | None = None,
@@ -65,6 +65,7 @@ def _compile_jinja2_template(
def _prepare_templating_context(
templating_context: dict[str, Any],
+ *,
templating_style: TemplatingStyle | None,
) -> dict[str, Any]:
# Create a copy to avoid mutating the caller's original dictionary
@@ -83,7 +84,7 @@ def _prepare_templating_context(
return prepared_templating_context
-def _make_type_error_msg(template_source: str, templating_context: dict[str, Any], type_error: TypeError) -> str:
+def _make_type_error_msg(template_source: str, *, templating_context: dict[str, Any], type_error: TypeError) -> str:
context_vars = ", ".join(f"'{key}'" for key in templating_context)
return (
f"Jinja2 render — type error: '{type_error}'. "
@@ -95,13 +96,14 @@ def _make_type_error_msg(template_source: str, templating_context: dict[str, Any
def _make_non_type_error_msg(
template_source: str,
+ *,
error_label: str,
error: Jinja2StuffError | TemplateSyntaxError | UndefinedError | Jinja2ContextError,
) -> str:
return f"Jinja2 render — {error_label}: '{error}', template_source:\n{template_source}"
-def _render_template_sync(template_source: str, template: _Jinja2Template, templating_context: dict[str, Any]) -> str:
+def _render_template_sync(template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any]) -> str:
try:
generated_text: str = template.render(**templating_context)
except Jinja2StuffError as exc:
@@ -122,7 +124,7 @@ def _render_template_sync(template_source: str, template: _Jinja2Template, templ
return generated_text
-async def _render_template_async(template_source: str, template: _Jinja2Template, templating_context: dict[str, Any]) -> str:
+async def _render_template_async(template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any]) -> str:
try:
generated_text: str = await template.render_async(**templating_context)
except Jinja2StuffError as exc:
@@ -145,10 +147,10 @@ async def _render_template_async(template_source: str, template: _Jinja2Template
def render_jinja2_sync(
template_source: str,
+ *,
template_category: TemplateCategory,
templating_context: dict[str, Any],
templating_style: TemplatingStyle | None = None,
- *,
use_registry: bool = False,
) -> str:
template = _compile_jinja2_template(
@@ -170,10 +172,10 @@ def render_jinja2_sync(
async def render_jinja2_async(
template_source: str,
+ *,
template_category: TemplateCategory,
templating_context: dict[str, Any],
templating_style: TemplatingStyle | None = None,
- *,
use_registry: bool = False,
finalize: Callable[[Any], Any] | None = None,
) -> str:
diff --git a/pipelex/tools/jinja2/jinja2_required_variables.py b/pipelex/tools/jinja2/jinja2_required_variables.py
index 892d6e260..492f597b1 100644
--- a/pipelex/tools/jinja2/jinja2_required_variables.py
+++ b/pipelex/tools/jinja2/jinja2_required_variables.py
@@ -63,7 +63,7 @@ def _collect_declarations_from_body(body: list[nodes.Node]) -> set[str]:
return declarations
-def _collect_full_variable_paths(node: nodes.Node, paths: set[str], declared_names: set[str]) -> None:
+def _collect_full_variable_paths(node: nodes.Node, *, paths: set[str], declared_names: set[str]) -> None:
"""Recursively walk the AST and collect full variable paths.
This function collects only the FULL (leaf) paths for each variable access chain.
@@ -115,10 +115,11 @@ def _collect_full_variable_paths(node: nodes.Node, paths: set[str], declared_nam
# Recurse into child nodes (only for non-Name/Getattr nodes)
for child in node.iter_child_nodes():
- _collect_full_variable_paths(child, paths, new_declared)
+ _collect_full_variable_paths(child, paths=paths, declared_names=new_declared)
def detect_jinja2_required_variables(
+ *,
template_category: TemplateCategory,
template_source: str,
) -> set[str]:
@@ -155,7 +156,7 @@ def detect_jinja2_required_variables(
raise Jinja2DetectVariablesError(msg) from undef_error
paths: set[str] = set()
- _collect_full_variable_paths(parsed_ast, paths, set())
+ _collect_full_variable_paths(parsed_ast, paths=paths, declared_names=set())
return paths
@@ -183,6 +184,7 @@ def _extract_filters_and_variable(node: nodes.Node) -> tuple[list[str], nodes.No
def _collect_variable_references(
node: nodes.Node,
+ *,
references: dict[str, VariableReference],
declared_names: set[str],
) -> None:
@@ -247,10 +249,11 @@ def _collect_variable_references(
# Recurse into child nodes
for child in node.iter_child_nodes():
- _collect_variable_references(child, references, new_declared)
+ _collect_variable_references(child, references=references, declared_names=new_declared)
def detect_jinja2_variable_references(
+ *,
template_category: TemplateCategory,
template_source: str,
) -> list[VariableReference]:
@@ -288,5 +291,5 @@ def detect_jinja2_variable_references(
raise Jinja2DetectVariablesError(msg) from undef_error
references: dict[str, VariableReference] = {}
- _collect_variable_references(parsed_ast, references, set())
+ _collect_variable_references(parsed_ast, references=references, declared_names=set())
return list(references.values())
diff --git a/pipelex/tools/jinja2/jinja2_template_loader.py b/pipelex/tools/jinja2/jinja2_template_loader.py
index 39177f183..cb1e7b2cb 100644
--- a/pipelex/tools/jinja2/jinja2_template_loader.py
+++ b/pipelex/tools/jinja2/jinja2_template_loader.py
@@ -31,7 +31,7 @@ from pipelex.tools.jinja2.jinja2_template_registry import TemplateRegistry
_template_cache: dict[str, str] = {}
-def load_template(package: str, template_name: str) -> str:
+def load_template(*, package: str, template_name: str) -> str:
"""Load a template file from a Python package.
Uses importlib.resources.files() for package-safe file access.
@@ -93,6 +93,7 @@ class TemplateLoader:
@classmethod
def register_set(
cls,
+ *,
name: str,
package: str,
templates: list[tuple[str, str]],
@@ -139,7 +140,7 @@ class TemplateLoader:
for filename, registry_key in templates:
template_path = package_files / filename
template_source = template_path.read_text(encoding="utf-8")
- TemplateRegistry.register(registry_key, template_source)
+ TemplateRegistry.register(key=registry_key, template_source=template_source)
cls._loaded.add(name)
diff --git a/pipelex/tools/jinja2/jinja2_template_registry.py b/pipelex/tools/jinja2/jinja2_template_registry.py
index 46c2ea81e..865ae6a59 100644
--- a/pipelex/tools/jinja2/jinja2_template_registry.py
+++ b/pipelex/tools/jinja2/jinja2_template_registry.py
@@ -24,7 +24,7 @@ class TemplateRegistry:
Usage:
# At module import time (outside sandbox):
- TemplateRegistry.register("myapp/base.html.jinja2", template_source)
+ TemplateRegistry.register(key="myapp/base.html.jinja2", template_source=template_source)
# At render time (inside sandbox):
template_source = TemplateRegistry.get("myapp/base.html.jinja2")
@@ -34,7 +34,7 @@ class TemplateRegistry:
_templates: ClassVar[dict[str, str]] = {}
@classmethod
- def register(cls, key: str, template_source: str) -> None:
+ def register(cls, *, key: str, template_source: str) -> None:
"""Register a template string under a key.
Args:
diff --git a/pipelex/tools/jinja2/jinja2_with_images_filter.py b/pipelex/tools/jinja2/jinja2_with_images_filter.py
index ed5fb15f9..10908c0d5 100644
--- a/pipelex/tools/jinja2/jinja2_with_images_filter.py
+++ b/pipelex/tools/jinja2/jinja2_with_images_filter.py
@@ -59,11 +59,11 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
# Protocol-based rendering
if isinstance(value, ImageRenderable):
- return value.render_with_images(registry, text_format)
+ return value.render_with_images(registry, text_format=text_format)
# Handle plain lists/tuples (structural types that may contain ImageRenderable items)
if isinstance(value, (list, tuple)):
- return _render_sequence_with_images(value, registry, text_format) # pyright: ignore[reportUnknownArgumentType]
+ return _render_sequence_with_images(value, registry=registry, text_format=text_format) # pyright: ignore[reportUnknownArgumentType]
# Type cannot be rendered with images
msg = (
@@ -77,6 +77,7 @@ def with_images(context: Context, value: Any, _: Any = None) -> str:
def _render_sequence_with_images(
sequence: list[Any] | tuple[Any, ...],
+ *,
registry: ImageRegistry,
text_format: TextFormat,
) -> str:
@@ -93,7 +94,7 @@ def _render_sequence_with_images(
parts: list[str] = []
for item in sequence:
if isinstance(item, ImageRenderable):
- rendered = item.render_with_images(registry, text_format)
+ rendered = item.render_with_images(registry, text_format=text_format)
else:
rendered = str(item)
if rendered:
diff --git a/pipelex/tools/log/log.py b/pipelex/tools/log/log.py
index f82959e0c..a177e544a 100644
--- a/pipelex/tools/log/log.py
+++ b/pipelex/tools/log/log.py
@@ -200,7 +200,7 @@ class Log:
"""
self.set_level_by_int(level_int=level.int_logging_level)
- def set_level_for_package(self, package_name: str, level: LogLevel):
+ def set_level_for_package(self, package_name: str, *, level: LogLevel):
"""Set the log level for a specific package.
Args:
@@ -224,6 +224,7 @@ class Log:
def verbose(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
):
@@ -242,6 +243,7 @@ class Log:
def debug(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
):
@@ -260,6 +262,7 @@ class Log:
def dev(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
):
@@ -278,6 +281,7 @@ class Log:
def info(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
):
@@ -296,6 +300,7 @@ class Log:
def warning(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
problem_id: str | None = None,
@@ -318,6 +323,7 @@ class Log:
def error(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
include_exception: bool = False,
@@ -348,6 +354,7 @@ class Log:
def critical(
self,
content: str | Any,
+ *,
title: str | None = None,
inline: str | None = None,
include_exception: bool = False,
diff --git a/pipelex/tools/log/log_dispatch.py b/pipelex/tools/log/log_dispatch.py
index 1353ad3b5..9f4c03f10 100644
--- a/pipelex/tools/log/log_dispatch.py
+++ b/pipelex/tools/log/log_dispatch.py
@@ -66,6 +66,7 @@ class LogDispatch:
def dispatch(
self,
content: str | Any,
+ *,
severity: int,
title: str | None = None,
inline: str | None = None,
@@ -124,6 +125,7 @@ class LogDispatch:
def _log_message(
self,
message: str,
+ *,
severity: int,
caller_info_str: str | None,
title: str | None = None,
@@ -158,6 +160,7 @@ class LogDispatch:
def _log_data(
self,
data: Any,
+ *,
severity: int,
caller_info_str: str | None,
title: str | None = None,
@@ -228,7 +231,7 @@ class LogDispatch:
message += f"\n{traceback.format_exc()}"
self._log_to_console(message=message, severity=severity)
- def _log_to_console(self, message: str, severity: int):
+ def _log_to_console(self, message: str, *, severity: int):
"""Logs a message to the console.
Args:
diff --git a/pipelex/tools/mermaid/mermaid_utils.py b/pipelex/tools/mermaid/mermaid_utils.py
index 2b89dde74..d36b544e1 100644
--- a/pipelex/tools/mermaid/mermaid_utils.py
+++ b/pipelex/tools/mermaid/mermaid_utils.py
@@ -61,7 +61,7 @@ def make_mermaid_url(mermaid_code: str) -> str:
return f"https://mermaid.ink/svg/{encoded}"
-def print_mermaid_url(url: str, title: str) -> None:
+def print_mermaid_url(url: str, *, title: str) -> None:
"""Print a Mermaid URL with a privacy warning.
Args:
diff --git a/pipelex/tools/misc/async_utils.py b/pipelex/tools/misc/async_utils.py
index 15c3bbc55..699b7578b 100644
--- a/pipelex/tools/misc/async_utils.py
+++ b/pipelex/tools/misc/async_utils.py
@@ -18,6 +18,7 @@ async def _invoke(factory: Callable[[], Awaitable[_T]]) -> _T:
async def gather_bounded(
task_factories: Sequence[Callable[[], Awaitable[_T]]],
+ *,
max_concurrency: int | None,
) -> list[_T]:
"""Run `task_factories` in chunks with at most `max_concurrency` awaitables in flight at once.
diff --git a/pipelex/tools/misc/attribute_utils.py b/pipelex/tools/misc/attribute_utils.py
index 2eb4ce9a3..8b53bcc37 100644
--- a/pipelex/tools/misc/attribute_utils.py
+++ b/pipelex/tools/misc/attribute_utils.py
@@ -9,14 +9,14 @@ class AttributePolisher:
truncate_suffix: ClassVar[str] = "…"
@classmethod
- def _truncate_string(cls, value: str, max_length: int) -> str:
+ def _truncate_string(cls, value: str, *, max_length: int) -> str:
"""Truncate a string to the specified maximum length and append the truncate suffix."""
if len(value) > max_length:
return value[:max_length] + cls.truncate_suffix
return value
@classmethod
- def _truncate_bytes(cls, value: bytes, max_length: int) -> bytes:
+ def _truncate_bytes(cls, value: bytes, *, max_length: int) -> bytes:
"""Truncate a bytes to the specified maximum length and append the truncate suffix."""
if len(value) > max_length:
return value[:max_length]
@@ -39,14 +39,14 @@ class AttributePolisher:
def get_truncated_value(cls, value: Any) -> Any:
"""Get the truncated value based on the field name and value type."""
if isinstance(value, bytes):
- return cls._truncate_bytes(value, cls.bytes_truncate_length)
+ return cls._truncate_bytes(value, max_length=cls.bytes_truncate_length)
elif isinstance(value, str):
if value.startswith("http"):
- return cls._truncate_string(value, cls.url_truncate_length)
+ return cls._truncate_string(value, max_length=cls.url_truncate_length)
elif value.startswith("data:") or cls._looks_like_base64(value):
- return cls._truncate_string(value, cls.base64_truncate_length)
+ return cls._truncate_string(value, max_length=cls.base64_truncate_length)
else:
- return cls._truncate_string(value, cls.text_truncate_length)
+ return cls._truncate_string(value, max_length=cls.text_truncate_length)
return value
@classmethod
@@ -62,7 +62,7 @@ class AttributePolisher:
return non_base64_count < len(sample) * 0.05
@classmethod
- def apply_truncation_recursive(cls, obj: Any, name: str | None = None) -> Any:
+ def apply_truncation_recursive(cls, obj: Any, *, name: str | None = None) -> Any:
"""Recursively apply truncation logic to a data structure.
Args:
diff --git a/pipelex/tools/misc/base64_utils.py b/pipelex/tools/misc/base64_utils.py
index cbb82870d..d990e301f 100644
--- a/pipelex/tools/misc/base64_utils.py
+++ b/pipelex/tools/misc/base64_utils.py
@@ -37,6 +37,7 @@ def make_base64_url_from_bytes(raw_bytes: bytes) -> str:
def make_base64_url(
base64_data: str,
+ *,
file_type: FileType,
) -> str:
"""Create a data: URL from base64 string and file type."""
diff --git a/pipelex/tools/misc/context_provider_abstract.py b/pipelex/tools/misc/context_provider_abstract.py
index b07d3c0e4..483227133 100644
--- a/pipelex/tools/misc/context_provider_abstract.py
+++ b/pipelex/tools/misc/context_provider_abstract.py
@@ -8,7 +8,7 @@ class ContextProviderAbstract(ABC):
"""
@abstractmethod
- def get_typed_object_or_attribute(self, name: str, wanted_type: type[Any] | None = None, accept_list: bool = False) -> Any:
+ def get_typed_object_or_attribute(self, name: str, *, wanted_type: type[Any] | None = None, accept_list: bool = False) -> Any:
pass
@abstractmethod
diff --git a/pipelex/tools/misc/dict_utils.py b/pipelex/tools/misc/dict_utils.py
index 7de76ca59..26b1a6621 100644
--- a/pipelex/tools/misc/dict_utils.py
+++ b/pipelex/tools/misc/dict_utils.py
@@ -11,7 +11,7 @@ K = TypeVar("K")
V = TypeVar("V")
-def insert_before(dictionary: dict[K, V], target_key: K, new_key: K, new_value: V) -> dict[K, V]:
+def insert_before(dictionary: dict[K, V], *, target_key: K, new_key: K, new_value: V) -> dict[K, V]:
"""Insert a new key-value pair before a target key in a dictionary.
Creates a new dictionary with the new item positioned before the target key.
@@ -28,7 +28,7 @@ def insert_before(dictionary: dict[K, V], target_key: K, new_key: K, new_value:
Example:
>>> d = {'a': 1, 'c': 3}
- >>> insert_before(d, 'c', 'b', 2)
+ >>> insert_before(d, target_key='c', new_key='b', new_value=2)
{'a': 1, 'b': 2, 'c': 3}
"""
@@ -48,7 +48,7 @@ def insert_before(dictionary: dict[K, V], target_key: K, new_key: K, new_value:
return result
-def apply_to_strings_recursive(data: Any, transform_func: Callable[[str], str]) -> dict[str, Any]:
+def apply_to_strings_recursive(data: Any, *, transform_func: Callable[[str], str]) -> dict[str, Any]:
"""Recursively traverse a data structure and apply a transformation function to all string values.
This function walks through dictionaries, lists, and other nested structures,
@@ -64,17 +64,17 @@ def apply_to_strings_recursive(data: Any, transform_func: Callable[[str], str])
Example:
>>> data = {'a': 'hello ${USER}', 'b': [1, 'world ${HOME}'], 'c': {'d': 'test ${PATH}'}}
- >>> result = apply_to_strings_recursive(data, lambda s: s.replace('${USER}', 'john'))
+ >>> result = apply_to_strings_recursive(data, transform_func=lambda s: s.replace('${USER}', 'john'))
>>> # Returns: {'a': 'hello john', 'b': [1, 'world ${HOME}'], 'c': {'d': 'test ${PATH}'}}
"""
result: dict[str, Any] = {}
for key, value in data.items():
if isinstance(value, dict):
- result[key] = apply_to_strings_recursive(value, transform_func)
+ result[key] = apply_to_strings_recursive(value, transform_func=transform_func)
elif isinstance(value, list):
list_value: list[Any] = cast("list[Any]", value)
- result[key] = apply_to_strings_in_list(list_value, transform_func)
+ result[key] = apply_to_strings_in_list(list_value, transform_func=transform_func)
elif isinstance(value, str):
result[key] = transform_func(value)
else:
@@ -83,15 +83,15 @@ def apply_to_strings_recursive(data: Any, transform_func: Callable[[str], str])
return result
-def apply_to_strings_in_list(data: list[Any], transform_func: Callable[[str], str]) -> list[Any]:
+def apply_to_strings_in_list(data: list[Any], *, transform_func: Callable[[str], str]) -> list[Any]:
"""Helper function to apply string transformation to items in a list."""
result: list[Any] = []
for item in data:
if isinstance(item, dict):
- result.append(apply_to_strings_recursive(item, transform_func))
+ result.append(apply_to_strings_recursive(item, transform_func=transform_func))
elif isinstance(item, list):
list_item: list[Any] = cast("list[Any]", item)
- result.append(apply_to_strings_in_list(list_item, transform_func))
+ result.append(apply_to_strings_in_list(list_item, transform_func=transform_func))
elif isinstance(item, str):
result.append(transform_func(item))
else:
@@ -99,7 +99,7 @@ def apply_to_strings_in_list(data: list[Any], transform_func: Callable[[str], st
return result
-def substitute_nested_in_context(context: dict[str, Any], extra_params: dict[str, Any] | None = None) -> dict[str, Any]:
+def substitute_nested_in_context(context: dict[str, Any], *, extra_params: dict[str, Any] | None = None) -> dict[str, Any]:
"""Substitute nested values in context dict using dotted key notation.
This function processes keys from extra_params that contain dots (e.g., "foo.bar.blip")
@@ -120,7 +120,7 @@ def substitute_nested_in_context(context: dict[str, Any], extra_params: dict[str
Example:
>>> context = {}
>>> extra_params = {"foo.bar.blip": "hello"}
- >>> substitute_nested_in_context(context, extra_params)
+ >>> substitute_nested_in_context(context, extra_params=extra_params)
>>> context
{'foo': {'bar': {'blip': 'hello'}}}
diff --git a/pipelex/tools/misc/diff.py b/pipelex/tools/misc/diff.py
index 8700f51ec..729874818 100644
--- a/pipelex/tools/misc/diff.py
+++ b/pipelex/tools/misc/diff.py
@@ -19,6 +19,7 @@ if TYPE_CHECKING:
def has_diff_dirs(
+ *,
dir1: str | Path,
dir2: str | Path,
exclude_files: AbstractSet[str] | None = None,
@@ -93,7 +94,7 @@ def diff_files(path1: str | Path, path2: str | Path) -> str:
# TODO: improve using toml reader/writer?
-def _generate_diff_summary(diff_content: str, left_is_newer: bool) -> str | None:
+def _generate_diff_summary(diff_content: str, *, left_is_newer: bool) -> str | None:
"""Generate a concise summary of what changes would be applied to sync files.
Parses unified diff content and generates a human-readable summary explaining
@@ -208,6 +209,7 @@ def _generate_diff_summary(diff_content: str, left_is_newer: bool) -> str | None
def make_diff_dirs_pretty(
+ *,
dir1: str | Path,
dir2: str | Path,
exclude_files: AbstractSet[str] | None = None,
@@ -236,7 +238,7 @@ def make_diff_dirs_pretty(
def _filter_excluded_files(file_list: list[str]) -> list[str]:
return [file for file in file_list if file not in exclude_files]
- def _collect_diffs(dir_comparison: filecmp.dircmp[str], relative_path: str = "") -> None:
+ def _collect_diffs(dir_comparison: filecmp.dircmp[str], *, relative_path: str = "") -> None:
# Files only in left directory (excluding excluded files and directories)
left_only_filtered = _filter_excluded_files([item for item in dir_comparison.left_only if item not in exclude_dirs])
if left_only_filtered:
@@ -323,7 +325,7 @@ def make_diff_dirs_pretty(
if diff_content:
# Parse the diff to provide a summary
- summary = _generate_diff_summary(diff_content, left_is_newer)
+ summary = _generate_diff_summary(diff_content, left_is_newer=left_is_newer)
if summary:
summary_text = Text(summary, style="dim yellow")
sections.append(summary_text)
@@ -341,7 +343,7 @@ def make_diff_dirs_pretty(
if subdir_name in exclude_dirs:
continue
new_relative_path = str(Path(relative_path, subdir_name)) if relative_path else subdir_name
- _collect_diffs(sub, new_relative_path)
+ _collect_diffs(sub, relative_path=new_relative_path)
_collect_diffs(filecmp.dircmp(str(dir1), str(dir2)))
@@ -360,7 +362,7 @@ def diff_dirs(dir1: str | Path, dir2: str | Path) -> None:
dir1 = Path(dir1)
dir2 = Path(dir2)
- pretty_diff = make_diff_dirs_pretty(dir1, dir2)
+ pretty_diff = make_diff_dirs_pretty(dir1=dir1, dir2=dir2)
PrettyPrinter.pretty_print(
content=pretty_diff,
title=f"Directory Diff: {dir1} ↔ {dir2}",
diff --git a/pipelex/tools/misc/file_fetch_utils.py b/pipelex/tools/misc/file_fetch_utils.py
index d867ba67f..4e62c0642 100644
--- a/pipelex/tools/misc/file_fetch_utils.py
+++ b/pipelex/tools/misc/file_fetch_utils.py
@@ -6,6 +6,7 @@ from pipelex.tools.misc.http_utils import get_user_agent
async def fetch_file_from_url_httpx(
url: str,
+ *,
request_timeout: int | None = None,
) -> bytes:
user_agent = get_user_agent()
diff --git a/pipelex/tools/misc/file_utils.py b/pipelex/tools/misc/file_utils.py
index a62376148..c0856b696 100644
--- a/pipelex/tools/misc/file_utils.py
+++ b/pipelex/tools/misc/file_utils.py
@@ -35,12 +35,12 @@ def reject_bare_str_or_path(value: object, *, param_name: str) -> None:
########################################################
-def save_bytes_to_binary_file(file_path: Path, byte_data: bytes, create_directory: bool = False) -> Path:
+def save_bytes_to_binary_file(byte_data: bytes, *, file_path: Path, create_directory: bool = False) -> Path:
"""Write binary data to a file.
Args:
- file_path (Path): Path where the binary data will be saved
byte_data (bytes): Binary data to be written
+ file_path (Path): Path where the binary data will be saved
create_directory (bool, optional): Whether to create the directory if it doesn't exist.
Defaults to False.
@@ -56,7 +56,7 @@ def save_bytes_to_binary_file(file_path: Path, byte_data: bytes, create_director
return file_path
-def save_text_to_path(text: str, path: Path, create_directory: bool = False):
+def save_text_to_path(text: str, *, path: Path, create_directory: bool = False):
"""Writes text content to a file at the specified path.
This function opens a file in write mode and writes the provided text to it.
@@ -130,7 +130,7 @@ async def load_binary_async(path: Path) -> bytes:
########################################################
-def copy_file(source_path: Path, target_path: Path, overwrite: bool = True) -> None:
+def copy_file(*, source_path: Path, target_path: Path, overwrite: bool = True) -> None:
"""Copies a file from the source path to the target path.
Creates any necessary parent directories for the target path if they don't exist.
@@ -150,6 +150,7 @@ def copy_file(source_path: Path, target_path: Path, overwrite: bool = True) -> N
def copy_file_from_package(
package_name: str,
+ *,
file_path_in_package: str,
target_path: Path,
overwrite: bool = True,
@@ -165,6 +166,7 @@ def copy_file_from_package(
def copy_folder_from_package(
package_name: str,
+ *,
folder_path_in_package: str,
target_dir: Path,
overwrite: bool = True,
@@ -274,6 +276,7 @@ def _reraise_walk_error(walk_error: OSError) -> None:
def mirror_dir(
+ *,
source_dir: Path,
target_dir: Path,
exclude_files: frozenset[str] | None = None,
@@ -454,7 +457,7 @@ def path_exists(path_str: str | Path) -> bool:
return Path(path_str).exists()
-def get_incremental_directory_path(base_path: Path, base_name: str, start_at: int = 1) -> Path:
+def get_incremental_directory_path(base_path: Path, *, base_name: str, start_at: int = 1) -> Path:
"""Generates a unique directory path by incrementing a counter until an unused path is found.
This function creates a directory path in the format 'base_path/base_name_XX' where XX
@@ -482,6 +485,7 @@ def get_incremental_directory_path(base_path: Path, base_name: str, start_at: in
def get_incremental_file_path(
base_path: Path,
+ *,
base_name: str,
extension: str,
start_at: int = 1,
@@ -527,6 +531,7 @@ def get_incremental_file_path(
def find_files_in_dir(
dir_path: Path,
+ *,
pattern: str,
is_recursive: bool = True,
excluded_dirs: list[str] | None = None,
diff --git a/pipelex/tools/misc/hash_utils.py b/pipelex/tools/misc/hash_utils.py
index becc199ff..e5a0e76a2 100644
--- a/pipelex/tools/misc/hash_utils.py
+++ b/pipelex/tools/misc/hash_utils.py
@@ -1,7 +1,7 @@
import hashlib
-def hash_sha256(data: str | bytes, length: int | None = None) -> str:
+def hash_sha256(data: str | bytes, *, length: int | None = None) -> str:
"""Hash the data using truncated SHA256.
Uses the first `length` characters of SHA256 hex digest, which provides
diff --git a/pipelex/tools/misc/image_utils.py b/pipelex/tools/misc/image_utils.py
index 366b0132c..564265ba1 100644
--- a/pipelex/tools/misc/image_utils.py
+++ b/pipelex/tools/misc/image_utils.py
@@ -92,7 +92,7 @@ class ImageFormat(StrEnum):
raise ValueError(msg)
-def pil_image_to_bytes(pil_image: Image.Image, image_format: ImageFormat | None) -> bytes:
+def pil_image_to_bytes(pil_image: Image.Image, *, image_format: ImageFormat | None) -> bytes:
"""Convert a PIL Image to bytes in the specified format.
Args:
diff --git a/pipelex/tools/misc/json_utils.py b/pipelex/tools/misc/json_utils.py
index 117faf9a3..f9bb00a6b 100644
--- a/pipelex/tools/misc/json_utils.py
+++ b/pipelex/tools/misc/json_utils.py
@@ -68,7 +68,7 @@ def clean_json_content(content: Any) -> Any:
# TODO: make this more powerful using kajson
-def clean_json_dumps(data: Any, indent: int | None = None) -> str:
+def clean_json_dumps(data: Any, *, indent: int | None = None) -> str:
"""Serialize data to a JSON string, producing clean output without metadata.
Unlike kajson.dumps (which adds ``__class__``/``__module__`` metadata for
@@ -89,7 +89,7 @@ def clean_json_dumps(data: Any, indent: int | None = None) -> str:
return json.dumps(clean_json_content(data), indent=indent)
-def json_str(some_object: Any, title: str | None = None, is_spaced: bool = False) -> str:
+def json_str(some_object: Any, *, title: str | None = None, is_spaced: bool = False) -> str:
"""Creates a formatted JSON string representation of any Python object with optional title and spacing.
This function is a higher-level wrapper around purify_json that provides additional formatting
@@ -127,6 +127,7 @@ def json_str(some_object: Any, title: str | None = None, is_spaced: bool = False
def save_as_json_to_path(
object_to_save: Any,
+ *,
path: Path,
indent: int | None = 4,
is_warning_enabled: bool = True,
@@ -149,7 +150,7 @@ def save_as_json_to_path(
"""
_, json_string = purify_json(object_to_save, indent=indent, is_warning_enabled=is_warning_enabled)
- save_text_to_path(json_string, path, create_directory=create_directory)
+ save_text_to_path(json_string, path=path, create_directory=create_directory)
def load_json_from_path(path: Path) -> JsonContent:
@@ -223,7 +224,7 @@ def load_json_list_from_path(path: Path) -> list[Any]:
raise JsonTypeError(msg)
-def deep_update(target_dict: dict[str, Any], updates: Mapping[str, Any]):
+def deep_update(target_dict: dict[str, Any], *, updates: Mapping[str, Any]):
"""Recursively updates a dictionary with values from another mapping.
This function performs a deep merge, handling nested mappings (``dict`` or any
@@ -244,14 +245,14 @@ def deep_update(target_dict: dict[str, Any], updates: Mapping[str, Any]):
Example:
>>> base = {"a": 1, "b": {"x": 2, "y": 3}, "c": [1, 2]}
>>> updates = {"b": {"y": 4, "z": 5}, "c": [3, 4]}
- >>> deep_update(base, updates)
+ >>> deep_update(base, updates=updates)
>>> print(base)
{'a': 1, 'b': {'x': 2, 'y': 4, 'z': 5}, 'c': [3, 4]}
"""
for key, value in updates.items():
if isinstance(value, Mapping) and key in target_dict and isinstance(target_dict[key], dict):
- deep_update(target_dict[key], value) # pyright: ignore[reportUnknownArgumentType]
+ deep_update(target_dict[key], updates=value) # pyright: ignore[reportUnknownArgumentType]
elif isinstance(value, Mapping) and not isinstance(value, dict):
target_dict[key] = dict(value) # pyright: ignore[reportUnknownArgumentType]
else:
@@ -313,6 +314,7 @@ def remove_none_values_from_dict(data: Mapping[str, Any]) -> dict[str, Any]:
def purify_json(
data: Any,
+ *,
indent: int | None = None,
is_truncate_bytes_enabled: bool = False,
is_warning_enabled: bool = True,
@@ -392,6 +394,7 @@ def purify_json(
def purify_json_list(
data: list[Any],
+ *,
indent: int | None = None,
is_truncate_bytes_enabled: bool = False,
) -> tuple[list[Any], str]:
@@ -447,7 +450,7 @@ def purify_json_list(
return pure_list, list_string
-def purify_json_dict(data: Any, indent: int | None = None, is_warning_enabled: bool = True) -> tuple[dict[str, Any], str]:
+def purify_json_dict(data: Any, *, indent: int | None = None, is_warning_enabled: bool = True) -> tuple[dict[str, Any], str]:
"""Converts any Python object into a JSON-serializable dictionary and its string representation.
This function specifically handles dictionary-like objects and Pydantic BaseModel instances,
@@ -502,7 +505,7 @@ def purify_json_dict(data: Any, indent: int | None = None, is_warning_enabled: b
return pure_dict, dict_string
-def pure_json_str(data: Any, indent: int | None = None, is_warning_enabled: bool = True) -> str:
+def pure_json_str(data: Any, *, indent: int | None = None, is_warning_enabled: bool = True) -> str:
"""Converts any Python object directly to its JSON string representation.
This is a convenience wrapper around purify_json that returns only the string
diff --git a/pipelex/tools/misc/markdown_utils.py b/pipelex/tools/misc/markdown_utils.py
index 8af5b9260..28322b771 100644
--- a/pipelex/tools/misc/markdown_utils.py
+++ b/pipelex/tools/misc/markdown_utils.py
@@ -4,7 +4,7 @@ from pipelex.tools.misc.json_utils import purify_json_dict
from pipelex.tools.misc.string_utils import snake_to_capitalize_first_letter
-def convert_to_markdown(data: Any, level: int = 1, is_pretty: bool = False) -> str:
+def convert_to_markdown(data: Any, *, level: int = 1, is_pretty: bool = False) -> str:
"""Convert arbitrary JSON-compatible Python data to a Markdown string
without needing to specify the markdown type explicitly.
"""
diff --git a/pipelex/tools/misc/pretty.py b/pipelex/tools/misc/pretty.py
index 01a52e1fa..20646876d 100644
--- a/pipelex/tools/misc/pretty.py
+++ b/pipelex/tools/misc/pretty.py
@@ -60,10 +60,10 @@ PrettyPrintable = Markdown | Text | JSON | Table | Group | Syntax | Pretty
class PrettyRenderable(ABC):
@abstractmethod
- def rendered_pretty(self, title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def rendered_pretty(self, *, title: str | None = None, depth: int = 0) -> PrettyPrintable:
pass
- def rendered_pretty_text(self, title: str | None = None, width: int = PRETTY_WIDTH_FOR_EXPORT) -> str:
+ def rendered_pretty_text(self, *, title: str | None = None, width: int = PRETTY_WIDTH_FOR_EXPORT) -> str:
"""Render as plain ASCII text string.
Args:
@@ -76,7 +76,7 @@ class PrettyRenderable(ABC):
pretty = self.rendered_pretty(title=title, depth=0)
return PrettyPrinter.pretty_text(pretty, width=width)
- def rendered_pretty_html(self, title: str | None = None, width: int | None = None) -> str:
+ def rendered_pretty_html(self, *, title: str | None = None, width: int | None = None) -> str:
"""Render as HTML string.
Args:
@@ -98,6 +98,7 @@ class PrettyPrintMode(StrEnum):
def pretty_print(
content: str | Any,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -118,6 +119,7 @@ def pretty_print(
def pretty_print_md(
content: str,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -140,6 +142,7 @@ def pretty_print_md(
def pretty_print_url(
url: str,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -167,6 +170,7 @@ class PrettyPrinter:
def pretty_print(
cls,
content: str | Any,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -194,6 +198,7 @@ class PrettyPrinter:
def pretty_print_using_rich(
cls,
content: str | Any,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -214,7 +219,7 @@ class PrettyPrinter:
Console(width=console_width).print("", panel, "", sep="\n")
@classmethod
- def pretty_width(cls, width: int | None = None, depth: int | None = None) -> int:
+ def pretty_width(cls, width: int | None = None, *, depth: int | None = None) -> int:
terminal_width = shutil.get_terminal_size().columns
absolute_width = width or min(max(PRETTY_WIDTH_MIN, terminal_width // 2), terminal_width)
if depth is not None:
@@ -229,6 +234,7 @@ class PrettyPrinter:
def make_pretty_panel(
cls,
content: str | Any,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -253,6 +259,7 @@ class PrettyPrinter:
def wrap_in_panel(
cls,
pretty: PrettyPrintable,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
border_style: StyleType | None = None,
@@ -275,6 +282,7 @@ class PrettyPrinter:
def pretty_text(
cls,
pretty: PrettyPrintable,
+ *,
width: int = PRETTY_WIDTH_FOR_EXPORT,
) -> str:
"""Export a PrettyPrintable as plain ASCII text without styling.
@@ -295,6 +303,7 @@ class PrettyPrinter:
def pretty_html(
cls,
pretty: PrettyPrintable,
+ *,
width: int = PRETTY_WIDTH_FOR_EXPORT,
) -> str:
buf = StringIO()
@@ -303,14 +312,14 @@ class PrettyPrinter:
return console.export_html(inline_styles=False, clear=False, theme=EXPORT_THEME)
@classmethod
- def pretty_svg(cls, pretty: PrettyPrintable, width: int = PRETTY_WIDTH_FOR_EXPORT) -> str:
+ def pretty_svg(cls, pretty: PrettyPrintable, *, width: int = PRETTY_WIDTH_FOR_EXPORT) -> str:
buf = StringIO()
console = Console(record=True, file=buf, width=width, force_terminal=False)
console.print(pretty)
return console.export_svg()
@classmethod
- def make_pretty(cls, value: Any, inner_title: str | None = None, depth: int = 0) -> PrettyPrintable:
+ def make_pretty(cls, value: Any, *, inner_title: str | None = None, depth: int = 0) -> PrettyPrintable:
pretty: PrettyPrintable
# Format the value
if isinstance(value, PrettyPrintable):
@@ -372,6 +381,7 @@ class PrettyPrinter:
def pretty_print_without_rich(
cls,
content: str | Any,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
inner_title: str | None = None,
@@ -428,6 +438,7 @@ class PrettyPrinter:
def pretty_print_url_without_rich(
cls,
content: str | Any,
+ *,
title: TextType | None = None,
subtitle: TextType | None = None,
):
diff --git a/pipelex/tools/misc/semver.py b/pipelex/tools/misc/semver.py
index ea99486a3..99a79636d 100644
--- a/pipelex/tools/misc/semver.py
+++ b/pipelex/tools/misc/semver.py
@@ -56,7 +56,7 @@ def parse_constraint(constraint_str: str) -> SimpleSpec:
raise SemVerError(msg) from exc
-def version_satisfies(version: Version, constraint: SimpleSpec) -> bool:
+def version_satisfies(version: Version, *, constraint: SimpleSpec) -> bool:
"""Check whether a version satisfies a constraint.
Args:
@@ -72,6 +72,7 @@ def version_satisfies(version: Version, constraint: SimpleSpec) -> bool:
def select_minimum_version(
available_versions: list[Version],
+ *,
constraint: SimpleSpec,
) -> Version | None:
"""Select the minimum version that satisfies a constraint (MVS).
@@ -94,6 +95,7 @@ def select_minimum_version(
def select_minimum_version_for_multiple_constraints(
available_versions: list[Version],
+ *,
constraints: list[SimpleSpec],
) -> Version | None:
"""Select the minimum version that satisfies ALL constraints simultaneously.
diff --git a/pipelex/tools/misc/string_utils.py b/pipelex/tools/misc/string_utils.py
index 7c050e888..4b42e16ad 100644
--- a/pipelex/tools/misc/string_utils.py
+++ b/pipelex/tools/misc/string_utils.py
@@ -332,7 +332,7 @@ def get_root_from_dotted_path(dotted_path: str) -> str:
return dotted_path.split(".", 1)[0]
-def matches_wildcard_pattern(text: str, pattern: str) -> bool:
+def matches_wildcard_pattern(text: str, *, pattern: str) -> bool:
"""Check if a text matches a wildcard pattern.
Supports wildcards (*) at the beginning, end, or both.
@@ -346,15 +346,15 @@ def matches_wildcard_pattern(text: str, pattern: str) -> bool:
True if the text matches the pattern
Examples:
- >>> matches_wildcard_pattern("claude-3-sonnet", "claude-*")
+ >>> matches_wildcard_pattern("claude-3-sonnet", pattern="claude-*")
True
- >>> matches_wildcard_pattern("gpt-4o-mini", "*mini")
+ >>> matches_wildcard_pattern("gpt-4o-mini", pattern="*mini")
True
- >>> matches_wildcard_pattern("mistral-large", "*large*")
+ >>> matches_wildcard_pattern("mistral-large", pattern="*large*")
True
- >>> matches_wildcard_pattern("any-model", "*")
+ >>> matches_wildcard_pattern("any-model", pattern="*")
True
- >>> matches_wildcard_pattern("exact-match", "exact-match")
+ >>> matches_wildcard_pattern("exact-match", pattern="exact-match")
True
"""
diff --git a/pipelex/tools/misc/toml_sync.py b/pipelex/tools/misc/toml_sync.py
index 98581081c..9ba205e38 100644
--- a/pipelex/tools/misc/toml_sync.py
+++ b/pipelex/tools/misc/toml_sync.py
@@ -39,7 +39,7 @@ class TomlSyncResult(BaseModel):
return len(self.unchanged_keys)
-def get_nested_value(doc: TOMLDocument | Table | dict[str, Any], key_path: str) -> tuple[bool, Any]:
+def get_nested_value(doc: TOMLDocument | Table | dict[str, Any], *, key_path: str) -> tuple[bool, Any]:
"""Traverse TOML document by key path (dot-separated).
Args:
@@ -66,7 +66,7 @@ def get_nested_value(doc: TOMLDocument | Table | dict[str, Any], key_path: str)
return True, result_value # pyright: ignore[reportUnknownVariableType]
-def set_nested_value(doc: TOMLDocument | Table | dict[str, Any], key_path: str, value: Any) -> bool:
+def set_nested_value(doc: TOMLDocument | Table | dict[str, Any], *, key_path: str, value: Any) -> bool:
"""Set value in TOML document by key path (dot-separated).
Only sets the value if the key already exists. Preserves inline comments
@@ -117,7 +117,7 @@ def set_nested_value(doc: TOMLDocument | Table | dict[str, Any], key_path: str,
return False
-def collect_leaf_key_paths(doc: TOMLDocument | Table | dict[str, Any], prefix: str = "") -> list[str]:
+def collect_leaf_key_paths(doc: TOMLDocument | Table | dict[str, Any], *, prefix: str = "") -> list[str]:
"""Collect all leaf node key paths from a TOML document.
Args:
@@ -137,7 +137,7 @@ def collect_leaf_key_paths(doc: TOMLDocument | Table | dict[str, Any], prefix: s
if isinstance(value, (dict, Table)):
# Recurse into nested tables
nested_doc: dict[str, Any] = cast("dict[str, Any]", value)
- paths.extend(collect_leaf_key_paths(nested_doc, current_path))
+ paths.extend(collect_leaf_key_paths(nested_doc, prefix=current_path))
else:
# This is a leaf node
paths.append(current_path)
@@ -145,7 +145,7 @@ def collect_leaf_key_paths(doc: TOMLDocument | Table | dict[str, Any], prefix: s
return paths
-def sync_toml_values(source_path: Path, target_path: Path, dry_run: bool = False) -> TomlSyncResult:
+def sync_toml_values(*, source_path: Path, target_path: Path, dry_run: bool = False) -> TomlSyncResult:
"""Sync values from source TOML to target TOML, preserving target's structure and comments.
For each leaf key in the target:
@@ -169,8 +169,8 @@ def sync_toml_values(source_path: Path, target_path: Path, dry_run: bool = False
target_keys = collect_leaf_key_paths(target_doc)
for key_path in target_keys:
- source_found, source_value = get_nested_value(source_doc, key_path)
- target_found, target_value = get_nested_value(target_doc, key_path)
+ source_found, source_value = get_nested_value(source_doc, key_path=key_path)
+ target_found, target_value = get_nested_value(target_doc, key_path=key_path)
if not target_found:
# Should not happen since we got keys from target, but be safe
@@ -180,7 +180,7 @@ def sync_toml_values(source_path: Path, target_path: Path, dry_run: bool = False
if source_value != target_value:
# Value differs, update it
if not dry_run:
- set_nested_value(target_doc, key_path, source_value)
+ set_nested_value(target_doc, key_path=key_path, value=source_value)
result.updated_keys.append(key_path)
result.changes.append(
TomlKeyChange(
@@ -198,6 +198,6 @@ def sync_toml_values(source_path: Path, target_path: Path, dry_run: bool = False
# Save if not dry run and there were changes
if not dry_run and result.updated_keys:
- save_toml_to_path(target_doc, target_path)
+ save_toml_to_path(target_doc, path=target_path)
return result
diff --git a/pipelex/tools/misc/toml_utils.py b/pipelex/tools/misc/toml_utils.py
index 64659ed3d..64628679a 100644
--- a/pipelex/tools/misc/toml_utils.py
+++ b/pipelex/tools/misc/toml_utils.py
@@ -64,7 +64,7 @@ def load_toml_with_tomlkit(path: str | Path) -> tomlkit.TOMLDocument:
return tomlkit.load(file)
-def save_toml_to_path(data: dict[str, Any] | tomlkit.TOMLDocument, path: str | Path) -> None:
+def save_toml_to_path(data: dict[str, Any] | tomlkit.TOMLDocument, *, path: str | Path) -> None:
"""Save dictionary as TOML to path, preserving formatting and comments.
Args:
@@ -86,6 +86,6 @@ def load_toml_from_path_and_merge_with_overrides(paths: Sequence[str | Path]) ->
merged_dict: dict[str, Any] = {}
for path in paths:
if one_dict := load_toml_from_path_if_exists(path):
- deep_update(merged_dict, one_dict)
+ deep_update(merged_dict, updates=one_dict)
return merged_dict
diff --git a/pipelex/tools/network/ssrf_guard.py b/pipelex/tools/network/ssrf_guard.py
index 298ba9747..492065f1a 100644
--- a/pipelex/tools/network/ssrf_guard.py
+++ b/pipelex/tools/network/ssrf_guard.py
@@ -36,6 +36,7 @@ if TYPE_CHECKING:
async def resolve_to_allowed_ips(
host: str,
+ *,
port: int,
timeout: float | None = None, # noqa: ASYNC109 — propagates httpcore's connect timeout to bound DNS resolution
) -> list[str]:
@@ -110,7 +111,7 @@ class SsrfGuardedBackend(httpcore.AsyncNetworkBackend):
# monotonic deadline and hand each step only the time left in the budget.
loop = asyncio.get_running_loop()
deadline = None if timeout is None else loop.time() + timeout
- vetted_ips = await resolve_to_allowed_ips(host, port, timeout=timeout)
+ vetted_ips = await resolve_to_allowed_ips(host, port=port, timeout=timeout)
# Every IP is pre-vetted, so dialing any literal is rebind-safe (getaddrinfo
# on an IP literal does no DNS). Try them in order and fall back on connect
# failure, restoring the multi-address resilience (dual-stack / multiple A
diff --git a/pipelex/tools/pdf/pypdfium2_renderer.py b/pipelex/tools/pdf/pypdfium2_renderer.py
index 963c67e1f..62ce42200 100644
--- a/pipelex/tools/pdf/pypdfium2_renderer.py
+++ b/pipelex/tools/pdf/pypdfium2_renderer.py
@@ -67,6 +67,7 @@ async def _resolve_pdf_uri_to_input(pdf_uri: str) -> PdfInput:
def _extract_image_from_pdf_object(
image_obj: PdfImage,
+ *,
output_format: ImageFormat | None,
) -> ExtractedImageFromPage:
"""Extract an image from a PdfImage object, preferring direct extraction when possible.
@@ -155,7 +156,7 @@ class PyPdfium2Renderer:
# ---- internal blocking helper ------------------------------------
# TODO: Needs UT
@staticmethod
- def _render_pdf_pages_sync(pdf_input: PdfInput, scale: float) -> list[Image.Image]:
+ def _render_pdf_pages_sync(pdf_input: PdfInput, *, scale: float) -> list[Image.Image]:
pdf_doc = pdfium.PdfDocument(pdf_input)
images: list[Image.Image] = []
for index in range(len(pdf_doc)):
@@ -188,6 +189,7 @@ class PyPdfium2Renderer:
@staticmethod
def _extract_embedded_images_from_page_sync(
pdf_input: PdfInput,
+ *,
page_index: int,
max_depth: int = DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH,
output_format: ImageFormat | None = None,
@@ -224,6 +226,7 @@ class PyPdfium2Renderer:
@staticmethod
def _extract_embedded_images_from_pdf_sync(
pdf_input: PdfInput,
+ *,
max_depth: int = DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH,
output_format: ImageFormat | None = None,
) -> dict[int, list[ExtractedImageFromPage]]:
@@ -261,18 +264,18 @@ class PyPdfium2Renderer:
return all_images
# ---- public async façade -----------------------------------------
- async def render_pdf_pages(self, pdf_input: PdfInput, dpi: int) -> list[Image.Image]:
+ async def render_pdf_pages(self, pdf_input: PdfInput, *, dpi: int) -> list[Image.Image]:
scale = dpi / PDFIUM2_REFERENCE_DPI
"""Render *one* page and return PNG bytes."""
async with self._pdfium_lock:
- return await asyncio.to_thread(self._render_pdf_pages_sync, pdf_input, scale)
+ return await asyncio.to_thread(self._render_pdf_pages_sync, pdf_input, scale=scale)
async def extract_text_from_pdf_pages(self, pdf_input: PdfInput) -> list[str]:
"""Extract text from all pages of a PDF."""
async with self._pdfium_lock:
return await asyncio.to_thread(self._extract_text_from_pdf_pages_sync, pdf_input)
- async def render_pdf_pages_from_uri(self, pdf_uri: str, dpi: int) -> list[Image.Image]:
+ async def render_pdf_pages_from_uri(self, pdf_uri: str, *, dpi: int) -> list[Image.Image]:
pdf_input = await _resolve_pdf_uri_to_input(pdf_uri)
return await self.render_pdf_pages(pdf_input=pdf_input, dpi=dpi)
@@ -284,6 +287,7 @@ class PyPdfium2Renderer:
async def extract_embedded_images_from_page(
self,
pdf_input: PdfInput,
+ *,
page_index: int,
max_depth: int = DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH,
output_format: ImageFormat | None = None,
@@ -304,14 +308,15 @@ class PyPdfium2Renderer:
return await asyncio.to_thread(
self._extract_embedded_images_from_page_sync,
pdf_input,
- page_index,
- max_depth,
- output_format,
+ page_index=page_index,
+ max_depth=max_depth,
+ output_format=output_format,
)
async def extract_embedded_images_from_pdf(
self,
pdf_input: PdfInput,
+ *,
max_depth: int = DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH,
output_format: ImageFormat | None = None,
) -> dict[int, list[ExtractedImageFromPage]]:
@@ -330,13 +335,14 @@ class PyPdfium2Renderer:
return await asyncio.to_thread(
self._extract_embedded_images_from_pdf_sync,
pdf_input,
- max_depth,
- output_format,
+ max_depth=max_depth,
+ output_format=output_format,
)
async def extract_embedded_images_from_pdf_uri(
self,
pdf_uri: str,
+ *,
max_depth: int = DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH,
output_format: ImageFormat | None = None,
) -> dict[int, list[ExtractedImageFromPage]]:
diff --git a/pipelex/tools/secrets/env_secrets_provider.py b/pipelex/tools/secrets/env_secrets_provider.py
index 104f39f06..2eddc304e 100644
--- a/pipelex/tools/secrets/env_secrets_provider.py
+++ b/pipelex/tools/secrets/env_secrets_provider.py
@@ -20,15 +20,15 @@ class EnvSecretsProvider(SecretsProviderAbstract):
return get_optional_env(key=secret_id)
@override
- def get_required_secret_specific_version(self, secret_id: str, version_id: str) -> str:
+ def get_required_secret_specific_version(self, secret_id: str, *, version_id: str) -> str:
msg = "EnvSecretsProvider does not support specific versions"
raise NotImplementedError(msg)
@override
- def get_optional_secret_specific_version(self, secret_id: str, version_id: str) -> str | None:
+ def get_optional_secret_specific_version(self, secret_id: str, *, version_id: str) -> str | None:
msg = "EnvSecretsProvider does not support specific versions"
raise NotImplementedError(msg)
@override
- def set_secret_as_env_var(self, secret_id: str, version_id: str = "latest"):
+ def set_secret_as_env_var(self, secret_id: str, *, version_id: str = "latest"):
pass
diff --git a/pipelex/tools/secrets/secrets_provider_abstract.py b/pipelex/tools/secrets/secrets_provider_abstract.py
index dd83a6733..57e7022af 100644
--- a/pipelex/tools/secrets/secrets_provider_abstract.py
+++ b/pipelex/tools/secrets/secrets_provider_abstract.py
@@ -11,13 +11,13 @@ class SecretsProviderAbstract(ABC):
def get_optional_secret(self, secret_id: str) -> str | None: ...
@abstractmethod
- def get_required_secret_specific_version(self, secret_id: str, version_id: str) -> str: ...
+ def get_required_secret_specific_version(self, secret_id: str, *, version_id: str) -> str: ...
@abstractmethod
- def get_optional_secret_specific_version(self, secret_id: str, version_id: str) -> str | None: ...
+ def get_optional_secret_specific_version(self, secret_id: str, *, version_id: str) -> str | None: ...
@abstractmethod
- def set_secret_as_env_var(self, secret_id: str, version_id: str = LATEST_SECRET_VERSION_NAME): ...
+ def set_secret_as_env_var(self, secret_id: str, *, version_id: str = LATEST_SECRET_VERSION_NAME): ...
def get_secret(self, secret_id: str) -> str:
return self.get_required_secret(secret_id=secret_id)
diff --git a/pipelex/tools/secrets/secrets_utils.py b/pipelex/tools/secrets/secrets_utils.py
index ae55a7dd2..f6235b237 100644
--- a/pipelex/tools/secrets/secrets_utils.py
+++ b/pipelex/tools/secrets/secrets_utils.py
@@ -21,6 +21,7 @@ class VarPrefix(StrEnum):
def substitute_vars(
content: str,
+ *,
secrets_provider: SecretsProviderAbstract,
raise_on_missing_var: bool = True,
) -> str:
@@ -53,7 +54,7 @@ def substitute_vars(
try:
# Check if it's a fallback pattern (contains |)
if "|" in var_spec:
- return _handle_fallback_pattern(var_spec, secrets_provider)
+ return _handle_fallback_pattern(var_spec, secrets_provider=secrets_provider)
# Check if it has a prefix (env: or secret:)
if ":" in var_spec:
@@ -73,10 +74,10 @@ def substitute_vars(
case VarPrefix.ENV:
return _get_env_var(var_name)
case VarPrefix.SECRET:
- return _get_secret(var_name, secrets_provider)
+ return _get_secret(var_name, secrets_provider=secrets_provider)
else:
# Default behavior: use secrets provider
- return _get_secret(var_spec, secrets_provider)
+ return _get_secret(var_spec, secrets_provider=secrets_provider)
except (VarNotFoundError, VarFallbackPatternError):
if raise_on_missing_var:
raise
@@ -88,7 +89,7 @@ def substitute_vars(
return re.sub(pattern, replace_var, content)
-def _handle_fallback_pattern(var_spec: str, secrets_provider: SecretsProviderAbstract) -> str:
+def _handle_fallback_pattern(var_spec: str, *, secrets_provider: SecretsProviderAbstract) -> str:
"""Handle fallback pattern like 'env:VAR|secret:VAR'."""
parts = [part.strip() for part in var_spec.split("|")]
@@ -135,7 +136,7 @@ def _get_env_var(var_name: str) -> str:
raise VarNotFoundError(message=msg, var_name=var_name) from exc
-def _get_secret(secret_name: str, secrets_provider: SecretsProviderAbstract) -> str:
+def _get_secret(secret_name: str, *, secrets_provider: SecretsProviderAbstract) -> str:
"""Get secret, raising VarNotFoundError if not found."""
try:
return secrets_provider.get_secret(secret_id=secret_name)
diff --git a/pipelex/tools/storage/gcp_storage_provider.py b/pipelex/tools/storage/gcp_storage_provider.py
index ee0f26157..5001459c9 100644
--- a/pipelex/tools/storage/gcp_storage_provider.py
+++ b/pipelex/tools/storage/gcp_storage_provider.py
@@ -131,7 +131,7 @@ class GcpStorageProvider(StorageProviderAbstract):
"""
return await asyncio.to_thread(self._load_with_metadata_sync, key)
- def _store_sync(self, data: bytes, key: str, content_type: str | None) -> None:
+ def _store_sync(self, data: bytes, *, key: str, content_type: str | None) -> None:
"""Synchronous implementation of store for use with to_thread.
Args:
@@ -165,7 +165,7 @@ class GcpStorageProvider(StorageProviderAbstract):
Raises:
StorageGcpError: If the GCS operation fails.
"""
- await asyncio.to_thread(self._store_sync, data, key, content_type)
+ await asyncio.to_thread(self._store_sync, data, key=key, content_type=content_type)
def _make_public_url(self, key: str) -> str:
"""Build a public URL for a GCS object.
diff --git a/pipelex/tools/storage/storage_provider_abstract.py b/pipelex/tools/storage/storage_provider_abstract.py
index 238b7178a..b858c5778 100644
--- a/pipelex/tools/storage/storage_provider_abstract.py
+++ b/pipelex/tools/storage/storage_provider_abstract.py
@@ -94,7 +94,7 @@ class StorageProviderAbstract(ABC):
StoredData containing bytes and optional MIME type.
"""
- async def store(self, data: bytes, key: str, content_type: str | None = None) -> str:
+ async def store(self, data: bytes, *, key: str, content_type: str | None = None) -> str:
"""Store data and return full URI with scheme.
Args:
diff --git a/pipelex/tools/tabular/csv_codec.py b/pipelex/tools/tabular/csv_codec.py
index e6fa84e9f..7eeb0898d 100644
--- a/pipelex/tools/tabular/csv_codec.py
+++ b/pipelex/tools/tabular/csv_codec.py
@@ -138,7 +138,7 @@ def _assert_single_char_delimiter(delimiter: str) -> None:
raise CsvError(msg)
-def _validate_header(header: list[str], path: Path) -> None:
+def _validate_header(header: list[str], *, path: Path) -> None:
"""Reject an empty header, or a header with a blank or duplicate column."""
if not header:
# An empty first row (a leading blank line, or a file that is just a newline) names no
@@ -199,7 +199,7 @@ def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str]
raise CsvReadError(msg)
header = numbered_rows[0][1]
- _validate_header(header, path)
+ _validate_header(header, path=path)
data_rows: list[tuple[int, list[str]]] = []
for line_number, row in numbered_rows[1:]:
@@ -216,7 +216,7 @@ def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str]
return header, data_rows
-def _row_to_dict(header: list[str], data_row: list[str]) -> dict[str, str]:
+def _row_to_dict(data_row: list[str], *, header: list[str]) -> dict[str, str]:
"""Map a raw data row onto the header, padding a short row with empty cells."""
return {column: (data_row[index] if index < len(data_row) else "") for index, column in enumerate(header)}
@@ -229,14 +229,14 @@ def read_rows(path: Path, *, delimiter: str = DEFAULT_DELIMITER, encoding: str =
``CsvColumnError`` for a duplicate/blank header cell or a data row wider than the header.
"""
header, data_rows = _read_table(path, delimiter=delimiter, encoding=encoding)
- return [_row_to_dict(header, row) for _, row in data_rows]
+ return [_row_to_dict(row, header=header) for _, row in data_rows]
def write_rows(
+ *,
path: Path,
headers: list[str],
rows: list[dict[str, str]],
- *,
delimiter: str = DEFAULT_DELIMITER,
encoding: str = DEFAULT_ENCODING,
) -> None:
@@ -311,8 +311,8 @@ def assert_supported_table_suffix(path: Path) -> None:
def list_content_from_csv(
path: Path,
- row_model: type[StuffContentType],
*,
+ row_model: type[StuffContentType],
delimiter: str = DEFAULT_DELIMITER,
encoding: str = DEFAULT_READ_ENCODING,
) -> ListContent[StuffContentType]:
@@ -355,7 +355,7 @@ def list_content_from_csv(
items: list[StuffContentType] = []
for row_number, data_row in data_rows:
- cell_map = _row_to_dict(header, data_row)
+ cell_map = _row_to_dict(data_row, header=header)
# Empty cell -> None BEFORE validation (so it targets an optional field, or fails required).
row_data: dict[str, str | None] = {column: (value or None) for column, value in cell_map.items()}
for omitted_field in omitted_nullable_fields:
@@ -378,9 +378,9 @@ def list_content_from_csv(
def csv_from_list_content(
list_content: ListContent[StuffContentType],
+ *,
row_model: type[StuffContentType],
path: Path,
- *,
delimiter: str = DEFAULT_DELIMITER,
encoding: str = DEFAULT_ENCODING,
) -> None:
@@ -401,7 +401,7 @@ def csv_from_list_content(
raise CsvError(msg)
dumped = item.model_dump(mode="json")
rows.append({field_name: _to_cell(dumped.get(field_name)) for field_name in headers})
- write_rows(path, headers, rows, delimiter=delimiter, encoding=encoding)
+ write_rows(path=path, headers=headers, rows=rows, delimiter=delimiter, encoding=encoding)
def _validation_error_label(error: "ErrorDetails") -> str:
diff --git a/pipelex/tools/typing/class_utils.py b/pipelex/tools/typing/class_utils.py
index 5f13b5ad7..136081abc 100644
--- a/pipelex/tools/typing/class_utils.py
+++ b/pipelex/tools/typing/class_utils.py
@@ -119,12 +119,12 @@ def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool:
return True
-def has_compatible_field(class_1: type[Any], class_2: type[Any]) -> bool:
- """Check if class_1 has a field whose (possibly wrapped) type matches/subclasses class_2 or is structurally equivalent."""
- if not hasattr(class_1, "model_fields"):
+def has_compatible_field(model_cls: type[Any], *, target_type: type[Any]) -> bool:
+ """Check if model_cls has a field whose (possibly wrapped) type matches/subclasses target_type or is structurally equivalent."""
+ if not hasattr(model_cls, "model_fields"):
return False
- fields: dict[str, FieldInfo] = class_1.model_fields # type: ignore[attr-defined]
+ fields: dict[str, FieldInfo] = model_cls.model_fields # type: ignore[attr-defined]
def _is_compatible(type_param: Any) -> bool:
# Unwrap Annotated[T, ...]
@@ -144,7 +144,7 @@ def has_compatible_field(class_1: type[Any], class_2: type[Any]) -> bool:
# Base case: direct match / subclass
try:
- if type_param is class_2 or (isinstance(type_param, type) and issubclass(type_param, class_2)):
+ if type_param is target_type or (isinstance(type_param, type) and issubclass(type_param, target_type)):
return True
except TypeError:
# Not a class type (e.g., typing constructs you don't care about)
@@ -152,7 +152,7 @@ def has_compatible_field(class_1: type[Any], class_2: type[Any]) -> bool:
# Also check for structural equivalence (same JSON schema)
if isinstance(type_param, type) and hasattr(type_param, "model_fields"):
- if are_classes_equivalent(type_param, class_2):
+ if are_classes_equivalent(type_param, class_2=target_type):
return True
return False
diff --git a/pipelex/tools/typing/module_inspector.py b/pipelex/tools/typing/module_inspector.py
index 4f33fd091..947c7c2d7 100644
--- a/pipelex/tools/typing/module_inspector.py
+++ b/pipelex/tools/typing/module_inspector.py
@@ -97,7 +97,7 @@ def convert_file_path_to_module_path(file_path: Path) -> str:
return result
-def find_class_names_in_file(file_path: Path, base_class_names: list[str] | None = None) -> list[str]:
+def find_class_names_in_file(file_path: Path, *, base_class_names: list[str] | None = None) -> list[str]:
"""Find class names in a Python file without executing it using AST parsing.
This is useful when you want to discover classes without running module-level code.
@@ -160,6 +160,7 @@ def find_class_names_in_file(file_path: Path, base_class_names: list[str] | None
def find_decorated_function_names_in_file(
file_path: Path,
+ *,
decorator_names: list[str],
) -> list[str]:
"""Find function names decorated with specific decorators without executing the file.
@@ -224,6 +225,7 @@ def find_decorated_function_names_in_file(
def import_module_from_file_if_has_decorated_functions(
file_path: Path,
+ *,
decorator_names: list[str],
) -> Any | None:
"""Import a module only if it contains functions with specific decorators.
@@ -244,7 +246,7 @@ def import_module_from_file_if_has_decorated_functions(
"""
# First, use AST to check if file has decorated functions
- function_names = find_decorated_function_names_in_file(file_path, decorator_names)
+ function_names = find_decorated_function_names_in_file(file_path, decorator_names=decorator_names)
# If no decorated functions found, skip import
if not function_names:
@@ -256,6 +258,7 @@ def import_module_from_file_if_has_decorated_functions(
def import_module_from_file_if_has_classes(
file_path: Path,
+ *,
base_class_names: list[str] | None = None,
) -> Any | None:
"""Import a module only if it contains classes (optionally filtered by base class).
@@ -278,7 +281,7 @@ def import_module_from_file_if_has_classes(
"""
# First, use AST to check if file has relevant classes
- class_names = find_class_names_in_file(file_path, base_class_names)
+ class_names = find_class_names_in_file(file_path, base_class_names=base_class_names)
# If no relevant classes found, skip import
if not class_names:
@@ -290,6 +293,7 @@ def import_module_from_file_if_has_classes(
def find_classes_in_module(
module: Any,
+ *,
base_class: type[Any] | None,
include_imported: bool,
) -> list[type[Any]]:
diff --git a/pipelex/tools/typing/pydantic_utils.py b/pipelex/tools/typing/pydantic_utils.py
index 28c778f02..d0eb24121 100644
--- a/pipelex/tools/typing/pydantic_utils.py
+++ b/pipelex/tools/typing/pydantic_utils.py
@@ -28,7 +28,7 @@ def empty_list_factory_of(_: type[T]) -> Callable[[], list[T]]:
return _factory
-def empty_dict_factory_of(_key: type[K], _val: type[V] | None = None) -> Callable[[], dict[K, Any]]:
+def empty_dict_factory_of(_key: type[K], *, _val: type[V] | None = None) -> Callable[[], dict[K, Any]]:
"""Create a typed empty dict factory.
Args:
@@ -316,6 +316,7 @@ def clean_model_to_dict(obj: BaseModel) -> dict[str, Any]:
def serialize_model(
obj: Any,
+ *,
field_visibility: FieldVisibility = FieldVisibility.NO_HIDDEN_FIELDS,
is_stringify_enums: bool = True,
) -> dict[str, Any] | list[Any] | Any:
diff --git a/pipelex/tools/typing/structure_printer.py b/pipelex/tools/typing/structure_printer.py
index ac45e775d..885c58738 100644
--- a/pipelex/tools/typing/structure_printer.py
+++ b/pipelex/tools/typing/structure_printer.py
@@ -69,6 +69,7 @@ class StructurePrinter:
def get_type_structure(
self,
tp: type[Any],
+ *,
seen_types: set[str] | None = None,
collected_types: dict[str, type[Any]] | None = None,
collected_enums: dict[str, type[Enum]] | None = None,
diff --git a/pipelex/tools/typing/validation_utils.py b/pipelex/tools/typing/validation_utils.py
index 447df6d62..edf73f933 100644
--- a/pipelex/tools/typing/validation_utils.py
+++ b/pipelex/tools/typing/validation_utils.py
@@ -1,7 +1,7 @@
from typing import Any
-def has_exactly_one_among_attributes_from_list(obj: Any, attributes_list: list[str]) -> bool:
+def has_exactly_one_among_attributes_from_list(obj: Any, *, attributes_list: list[str]) -> bool:
"""Checks if exactly one attribute from a list of attributes is non-None in an object.
This function is useful for validating mutually exclusive attributes in data models
@@ -20,7 +20,7 @@ def has_exactly_one_among_attributes_from_list(obj: Any, attributes_list: list[s
return len(provided_attributes) == 1
-def has_more_than_one_among_attributes_from_list(obj: Any, attributes_list: list[str]) -> bool:
+def has_more_than_one_among_attributes_from_list(obj: Any, *, attributes_list: list[str]) -> bool:
"""Checks if more than one attribute from a list of attributes is non-None in an object.
This function is useful for detecting conflicts in configurations or data models
@@ -39,7 +39,7 @@ def has_more_than_one_among_attributes_from_list(obj: Any, attributes_list: list
return len(provided_attributes) > 1
-def has_more_than_one_among_attributes_from_lists(obj: Any, attributes_lists: list[list[str]]) -> list[str] | None:
+def has_more_than_one_among_attributes_from_lists(obj: Any, *, attributes_lists: list[list[str]]) -> list[str] | None:
"""Checks if more than one attribute from lists (plural) of attributes is non-None in an object.
This function is useful for detecting conflicts in configurations or data models
@@ -54,6 +54,6 @@ def has_more_than_one_among_attributes_from_lists(obj: Any, attributes_lists: li
"""
for attributes_list in attributes_lists:
- if has_more_than_one_among_attributes_from_list(obj, attributes_list):
+ if has_more_than_one_among_attributes_from_list(obj, attributes_list=attributes_list):
return attributes_list
return None
diff --git a/pipelex/tools/uri/uri_resolver.py b/pipelex/tools/uri/uri_resolver.py
index 824888a09..ccbaca78c 100644
--- a/pipelex/tools/uri/uri_resolver.py
+++ b/pipelex/tools/uri/uri_resolver.py
@@ -159,6 +159,7 @@ def _resolve_base64_data_url(uri: str) -> ResolvedBase64DataUrl:
async def make_base64_url_from_any_uri(
uri: str,
+ *,
storage_provider: StorageProviderAbstract | None = None,
) -> str:
"""Convert a URI to a base64 data URL.
diff --git a/pipelex/tracing/activity_event_log.py b/pipelex/tracing/activity_event_log.py
index 7df6165b8..bd550caf0 100644
--- a/pipelex/tracing/activity_event_log.py
+++ b/pipelex/tracing/activity_event_log.py
@@ -77,7 +77,7 @@ class ActivityEventLogCache:
return cls._cached_event_log
@classmethod
- def log_once_runner_fallback_engaged(cls, workflow_id: str, writer_id: str) -> None:
+ def log_once_runner_fallback_engaged(cls, workflow_id: str, *, writer_id: str) -> None:
"""Log a single INFO the first time activity-side emission engages.
The log is per-process; subsequent emissions from the same process are
diff --git a/pipelex/tracing/dynamodb_event_log.py b/pipelex/tracing/dynamodb_event_log.py
index 9a9fe2c13..3dcca945a 100644
--- a/pipelex/tracing/dynamodb_event_log.py
+++ b/pipelex/tracing/dynamodb_event_log.py
@@ -96,7 +96,7 @@ class DynamoDBEventLog(EventLogProtocol):
return f"PIPELINE_RUN#{pipeline_run_id}"
@staticmethod
- def _make_sk(workflow_id: str, writer_id: str, sequence: int) -> str:
+ def _make_sk(workflow_id: str, *, writer_id: str, sequence: int) -> str:
return f"EVENT#{workflow_id}#{writer_id}#{sequence:010d}"
def _key_condition(self, pipeline_run_id: str) -> Any:
@@ -108,7 +108,7 @@ class DynamoDBEventLog(EventLogProtocol):
"""Write a single event to DynamoDB. Synchronous and idempotent."""
item: dict[str, Any] = {
"PK": self._make_pk(event.pipeline_run_id),
- "SK": self._make_sk(event.workflow_id, event.writer_id, event.sequence),
+ "SK": self._make_sk(event.workflow_id, writer_id=event.writer_id, sequence=event.sequence),
"pipeline_run_id": event.pipeline_run_id,
"workflow_id": event.workflow_id,
"writer_id": event.writer_id,
diff --git a/pipelex/tracing/event_log_factory.py b/pipelex/tracing/event_log_factory.py
index d4715f03c..e8976735c 100644
--- a/pipelex/tracing/event_log_factory.py
+++ b/pipelex/tracing/event_log_factory.py
@@ -7,7 +7,7 @@ from pipelex.tracing.event_log_protocol import EventLogProtocol
from pipelex.tracing.ndjson_event_log import NdjsonEventLog
-def make_event_log(tracing_config: TracingConfig, writer_id: str = "primary") -> EventLogProtocol:
+def make_event_log(tracing_config: TracingConfig, *, writer_id: str = "primary") -> EventLogProtocol:
"""Create an event log backend from tracing configuration.
The writer_id is stamped on every TraceEvent emitted through the resulting
diff --git a/pipelex/tracing/graphspec_assembler.py b/pipelex/tracing/graphspec_assembler.py
index 7d3b75d76..ef23bc969 100644
--- a/pipelex/tracing/graphspec_assembler.py
+++ b/pipelex/tracing/graphspec_assembler.py
@@ -115,6 +115,7 @@ class GraphSpecAssembler:
@staticmethod
def assemble(
events: Sequence[TraceEvent],
+ *,
graph_id: str,
pipeline_ref: PipelineRef | None = None,
) -> GraphSpec:
@@ -358,6 +359,7 @@ class _AssemblerState:
def _add_generated_edge(
self,
+ *,
source_node_id: str,
target_node_id: str,
edge_kind: EdgeKind,
diff --git a/pipelex/tracing/ndjson_event_log.py b/pipelex/tracing/ndjson_event_log.py
index c830d5087..d2dae0df9 100644
--- a/pipelex/tracing/ndjson_event_log.py
+++ b/pipelex/tracing/ndjson_event_log.py
@@ -70,7 +70,7 @@ class NdjsonEventLog(EventLogProtocol):
return seq
@staticmethod
- def _file_name_for(workflow_id: str, writer_id: str) -> str:
+ def _file_name_for(workflow_id: str, *, writer_id: str) -> str:
"""File name for a (workflow_id, writer_id) pair.
Workflow ids use ``_`` as their separator and so should not contain
@@ -107,7 +107,7 @@ class NdjsonEventLog(EventLogProtocol):
if handle is None:
run_dir = self._traces_dir / event.pipeline_run_id
run_dir.mkdir(parents=True, exist_ok=True)
- file_path = run_dir / self._file_name_for(event.workflow_id, event.writer_id)
+ file_path = run_dir / self._file_name_for(event.workflow_id, writer_id=event.writer_id)
handle = open(file_path, "a", encoding="utf-8") # noqa: SIM115
self._file_handles[cache_key] = handle
diff --git a/tests/e2e/agent_cli/test_stdout_is_clean_json.py b/tests/e2e/agent_cli/test_stdout_is_clean_json.py
index d7cb736a6..9b513a91b 100644
--- a/tests/e2e/agent_cli/test_stdout_is_clean_json.py
+++ b/tests/e2e/agent_cli/test_stdout_is_clean_json.py
@@ -54,7 +54,7 @@ def _set_package_log_level(pipelex_toml_path: Path, *, package_name: str, level:
"""
doc = load_toml_with_tomlkit(pipelex_toml_path)
doc["pipelex"]["log_config"]["package_log_levels"][package_name] = level # type: ignore[index]
- save_toml_to_path(doc, pipelex_toml_path)
+ save_toml_to_path(doc, path=pipelex_toml_path)
def _set_pipelex_package_log_level_to_debug(pipelex_toml_path: Path) -> None:
diff --git a/tests/e2e/pipelex/cli/test_init_cmd_edge_cases.py b/tests/e2e/pipelex/cli/test_init_cmd_edge_cases.py
index 3aaab1094..7108767de 100644
--- a/tests/e2e/pipelex/cli/test_init_cmd_edge_cases.py
+++ b/tests/e2e/pipelex/cli/test_init_cmd_edge_cases.py
@@ -97,12 +97,12 @@ class TestEdgeCases:
backends_path = env.inference_dir / "backends.toml"
toml_doc = load_toml_with_tomlkit(str(backends_path))
toml_doc[PipelexBackend.GATEWAY]["enabled"] = True # type: ignore[index]
- save_toml_to_path(toml_doc, str(backends_path))
+ save_toml_to_path(toml_doc, path=str(backends_path))
telemetry_path = env.pipelex_dir / "telemetry.toml"
toml_doc_tel = load_toml_with_tomlkit(str(telemetry_path))
toml_doc_tel["custom_posthog"]["mode"] = "identified" # type: ignore[index]
- save_toml_to_path(toml_doc_tel, str(telemetry_path))
+ save_toml_to_path(toml_doc_tel, path=str(telemetry_path))
# Get index for anthropic
kit_backends = Path(str(get_kit_configs_dir())) / "inference" / "backends.toml"
diff --git a/tests/e2e/pipelex/cli/test_init_cmd_focused.py b/tests/e2e/pipelex/cli/test_init_cmd_focused.py
index 6a7560247..ae719e915 100644
--- a/tests/e2e/pipelex/cli/test_init_cmd_focused.py
+++ b/tests/e2e/pipelex/cli/test_init_cmd_focused.py
@@ -76,7 +76,7 @@ class TestFocusedInitialization:
backends_path = env.inference_dir / "backends.toml"
toml_doc = load_toml_with_tomlkit(str(backends_path))
toml_doc[PipelexBackend.GATEWAY]["enabled"] = True # type: ignore[index]
- save_toml_to_path(toml_doc, str(backends_path))
+ save_toml_to_path(toml_doc, path=str(backends_path))
# Get index for mistral
kit_backends = Path(str(get_kit_configs_dir())) / "inference" / "backends.toml"
@@ -113,7 +113,7 @@ class TestFocusedInitialization:
if backend_key == "internal":
continue
toml_doc[backend_key]["enabled"] = backend_key in enabled_set # type: ignore[index]
- save_toml_to_path(toml_doc, str(backends_path))
+ save_toml_to_path(toml_doc, path=str(backends_path))
# User inputs for routing - need to confirm reconfigure since routing already exists
env.add_confirm_input(True) # Confirm "Would you like to reconfigure routing?"
@@ -143,7 +143,7 @@ class TestFocusedInitialization:
if backend_key == "internal":
continue
toml_doc[backend_key]["enabled"] = backend_key == "openai" # type: ignore[index]
- save_toml_to_path(toml_doc, str(backends_path))
+ save_toml_to_path(toml_doc, path=str(backends_path))
# User inputs
env.add_confirm_input(True) # Confirm "Would you like to reconfigure routing?"
@@ -185,7 +185,7 @@ class TestFocusedInitialization:
telemetry_path = env.pipelex_dir / "telemetry.toml"
toml_doc = load_toml_with_tomlkit(str(telemetry_path))
toml_doc["custom_posthog"]["mode"] = "identified" # type: ignore[index]
- save_toml_to_path(toml_doc, str(telemetry_path))
+ save_toml_to_path(toml_doc, path=str(telemetry_path))
# User inputs - confirm reconfigure
env.add_confirm_input(True) # Confirm reconfigure
@@ -211,13 +211,13 @@ class TestFocusedInitialization:
if backend_key == "internal":
continue
toml_doc[backend_key]["enabled"] = backend_key == PipelexBackend.GATEWAY # type: ignore[index]
- save_toml_to_path(toml_doc, str(backends_path))
+ save_toml_to_path(toml_doc, path=str(backends_path))
# Modify routing to have wrong config (simulating the bug scenario)
routing_path = env.inference_dir / "routing_profiles.toml"
routing_doc = load_toml_with_tomlkit(str(routing_path))
routing_doc["active"] = "wrong_profile" # type: ignore[index]
- save_toml_to_path(routing_doc, str(routing_path))
+ save_toml_to_path(routing_doc, path=str(routing_path))
# User inputs - need to confirm reset initialization
env.add_confirm_input(True) # Confirm "Continue with initialization?" (reset mode)
diff --git a/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py b/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py
index c03097337..f7f1b0b8a 100644
--- a/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py
+++ b/tests/e2e/pipelex/concepts/nested_concepts/test_nested_concepts_pipe.py
@@ -55,7 +55,7 @@ class TestNestedConceptsPipe:
assert pipe_output.main_stuff.concept.domain_code == "nested_concepts_test"
# Get the typed invoice using working_memory.get_stuff_as()
- invoice = pipe_output.working_memory.get_stuff_as("main_stuff", Invoice)
+ invoice = pipe_output.working_memory.get_stuff_as("main_stuff", content_type=Invoice)
assert isinstance(invoice, Invoice)
# Log output for debugging
diff --git a/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py b/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py
index 24271f3f6..caacf1089 100644
--- a/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py
+++ b/tests/e2e/pipelex/graph/test_graph_renderers_from_json.py
@@ -29,7 +29,7 @@ def _get_next_output_folder() -> Path:
Creates folders like: temp/test_outputs/graph_renderers/run_01, run_02, etc.
"""
base_dir = Path(TEST_OUTPUTS_DIR) / "graph_renderers"
- return get_incremental_directory_path(base_dir, "run")
+ return get_incremental_directory_path(base_dir, base_name="run")
@pytest.mark.asyncio(loop_scope="class")
@@ -83,7 +83,7 @@ class TestGraphRenderersFromJson:
# ==================== MERMAID OUTPUTS ====================
# Mermaidflow with data
- mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config, direction=FlowchartDirection.TOP_DOWN)
+ mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config=graph_config, direction=FlowchartDirection.TOP_DOWN)
(output_dir / "mermaidflow.mmd").write_text(mermaidflow.mermaid_code, encoding="utf-8")
has_mermaidflow_data = mermaidflow.stuff_data or mermaidflow.stuff_data_text or mermaidflow.stuff_data_html
if has_mermaidflow_data:
@@ -104,7 +104,7 @@ class TestGraphRenderersFromJson:
# Generate ReactFlow HTML directly from GraphSpec
reactflow_html = await generate_reactflow_html_async(
graph_spec,
- graph_config.reactflow_config,
+ config=graph_config.reactflow_config,
title=f"ReactFlow: {topic}",
)
reactflow_path = output_dir / "reactflow.html"
diff --git a/tests/e2e/pipelex/graph/test_graph_with_full_data.py b/tests/e2e/pipelex/graph/test_graph_with_full_data.py
index 59fec47d0..a60f50c40 100644
--- a/tests/e2e/pipelex/graph/test_graph_with_full_data.py
+++ b/tests/e2e/pipelex/graph/test_graph_with_full_data.py
@@ -33,7 +33,7 @@ def _get_next_output_folder() -> Path:
Creates folders like: temp/test_outputs/graph_full_data/run_01, run_02, etc.
"""
base_dir = Path(TEST_OUTPUTS_DIR) / "graph_full_data"
- return get_incremental_directory_path(base_dir, "run")
+ return get_incremental_directory_path(base_dir, base_name="run")
async def _save_graph_outputs(graph_spec: GraphSpec, output_dir: Path) -> dict[str, int]:
@@ -55,12 +55,12 @@ async def _save_graph_outputs(graph_spec: GraphSpec, output_dir: Path) -> dict[s
# Save graph.json
graph_json_path = output_dir / "graph.json"
graph_json = graph_spec.to_json()
- save_text_to_path(graph_json, graph_json_path)
+ save_text_to_path(graph_json, path=graph_json_path)
log.info(f"Saved graph.json to: {graph_json_path}")
# Generate and save mermaid files
# Mermaidflow with data
- mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config, direction=FlowchartDirection.TOP_DOWN)
+ mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config=graph_config, direction=FlowchartDirection.TOP_DOWN)
(output_dir / "mermaidflow.mmd").write_text(mermaidflow.mermaid_code, encoding="utf-8")
log.info(f"Mermaidflow stuff_data keys: {list(mermaidflow.stuff_data.keys()) if mermaidflow.stuff_data else []}")
@@ -258,7 +258,7 @@ class TestGraphWithFullData:
# Generate ReactFlow HTML
rf_config = get_config().pipelex.pipeline_execution_config.graph_config.reactflow_config
- reactflow_html = await generate_reactflow_html_async(graph_spec, rf_config, title="Graph: cv_job_matcher")
+ reactflow_html = await generate_reactflow_html_async(graph_spec, config=rf_config, title="Graph: cv_job_matcher")
reactflow_path = output_dir / "reactflow.html"
reactflow_path.write_text(reactflow_html, encoding="utf-8")
log.info(f"Saved ReactFlow HTML to: {reactflow_path}")
diff --git a/tests/e2e/pipelex/graph/test_mermaid_from_json.py b/tests/e2e/pipelex/graph/test_mermaid_from_json.py
index fc680ad41..b3455288a 100644
--- a/tests/e2e/pipelex/graph/test_mermaid_from_json.py
+++ b/tests/e2e/pipelex/graph/test_mermaid_from_json.py
@@ -28,7 +28,7 @@ def _get_next_output_folder() -> Path:
Creates folders like: temp/test_outputs/mermaid_from_json/run_01, run_02, etc.
"""
base_dir = Path(TEST_OUTPUTS_DIR) / "mermaid_from_json"
- return get_incremental_directory_path(base_dir, "run")
+ return get_incremental_directory_path(base_dir, base_name="run")
@pytest.mark.asyncio(loop_scope="class")
@@ -77,7 +77,7 @@ class TestMermaidFromJson:
graph_config = self._get_graph_config_with_data()
# Generate mermaidflow Mermaid with data
- mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config, direction=FlowchartDirection.TOP_DOWN)
+ mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config=graph_config, direction=FlowchartDirection.TOP_DOWN)
assert mermaidflow.mermaid_code.startswith("flowchart TD")
mermaidflow_mmd_path = output_dir / "mermaidflow.mmd"
@@ -122,7 +122,7 @@ class TestMermaidFromJson:
json_str = load_text_from_path(Path(graph_json_path))
graph_spec = GraphSpec.model_validate_json(json_str)
graph_config = self._get_graph_config_with_data()
- mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config)
+ mermaidflow = MermaidflowFactory.make_from_graphspec(graph_spec, graph_config=graph_config)
mermaid_code = mermaidflow.mermaid_code
diff --git a/tests/e2e/pipelex/graph/test_reactflow_from_json.py b/tests/e2e/pipelex/graph/test_reactflow_from_json.py
index e4f3ecb14..dedd0e664 100644
--- a/tests/e2e/pipelex/graph/test_reactflow_from_json.py
+++ b/tests/e2e/pipelex/graph/test_reactflow_from_json.py
@@ -23,7 +23,7 @@ def _get_next_output_folder() -> Path:
Creates folders like: temp/test_outputs/reactflow_from_json/run_01, run_02, etc.
"""
base_dir = Path(TEST_OUTPUTS_DIR) / "reactflow_from_json"
- return get_incremental_directory_path(base_dir, "run")
+ return get_incremental_directory_path(base_dir, base_name="run")
class TestReactFlowFromJson:
@@ -57,7 +57,7 @@ class TestReactFlowFromJson:
# Generate ReactFlow HTML directly from GraphSpec
rf_config = get_config().pipelex.pipeline_execution_config.graph_config.reactflow_config
- reactflow_html = await generate_reactflow_html_async(graph_spec, rf_config, title=f"Graph: {topic}")
+ reactflow_html = await generate_reactflow_html_async(graph_spec, config=rf_config, title=f"Graph: {topic}")
# Save outputs to TEST_OUTPUTS_DIR
output_dir = _get_next_output_folder()
@@ -98,7 +98,7 @@ class TestReactFlowFromJson:
# Generate ReactFlow HTML
rf_config = get_config().pipelex.pipeline_execution_config.graph_config.reactflow_config
- reactflow_html = await generate_reactflow_html_async(graph_spec, rf_config, title="Test Graph")
+ reactflow_html = await generate_reactflow_html_async(graph_spec, config=rf_config, title="Test Graph")
# Verify GraphSpec is embedded
assert '<script type="application/json" id="pipelex-graphspec">' in reactflow_html
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py
index b91291a6f..0b3f7391c 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_batch/test_pipe_batch_graph.py
@@ -21,7 +21,7 @@ from tests.e2e.pipelex.pipes.pipe_controller.pipe_batch.test_data import JokeBat
def _get_next_output_folder() -> Path:
"""Get the next numbered output folder for batch graph outputs."""
base_dir = Path(TEST_OUTPUTS_DIR) / "pipe_batch_graph"
- return get_incremental_directory_path(base_dir, "run")
+ return get_incremental_directory_path(base_dir, base_name="run")
@pytest.mark.dry_runnable
@@ -129,7 +129,7 @@ class TestPipeBatchGraph:
output_dir = _get_next_output_folder()
graph_json_path = output_dir / "graph.json"
graph_json = graph_spec.to_json()
- save_text_to_path(graph_json, graph_json_path)
+ save_text_to_path(graph_json, path=graph_json_path)
log.info(f"Saved graph.json to: {graph_json_path}")
# Pretty print the graph summary
@@ -212,21 +212,21 @@ class TestPipeBatchGraph:
# Save outputs to folder
output_dir = Path(TEST_OUTPUTS_DIR) / "joke_batch_graph"
- output_dir = get_incremental_directory_path(output_dir, "run")
+ output_dir = get_incremental_directory_path(output_dir, base_name="run")
if graph_outputs.graphspec_json:
graph_json_path = output_dir / "graph.json"
- save_text_to_path(graph_outputs.graphspec_json, graph_json_path)
+ save_text_to_path(graph_outputs.graphspec_json, path=graph_json_path)
log.info(f"Saved graph.json to: {graph_json_path}")
if graph_outputs.mermaidflow_html:
mermaid_path = output_dir / "mermaidflow.html"
- save_text_to_path(graph_outputs.mermaidflow_html, mermaid_path)
+ save_text_to_path(graph_outputs.mermaidflow_html, path=mermaid_path)
log.info(f"Saved mermaidflow.html to: {mermaid_path}")
if graph_outputs.reactflow_html:
reactflow_path = output_dir / "reactflow.html"
- save_text_to_path(graph_outputs.reactflow_html, reactflow_path)
+ save_text_to_path(graph_outputs.reactflow_html, path=reactflow_path)
log.info(f"Saved reactflow.html to: {reactflow_path}")
# Log edge counts
diff --git a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py
index 639c13bbf..221ed96ad 100644
--- a/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py
+++ b/tests/e2e/pipelex/pipes/pipe_controller/pipe_parallel/test_pipe_parallel_graph.py
@@ -25,7 +25,7 @@ from tests.e2e.pipelex.pipes.pipe_controller.pipe_parallel.test_data import (
def _get_next_output_folder(subfolder: str) -> Path:
"""Get the next numbered output folder for parallel graph outputs."""
base_dir = Path(TEST_OUTPUTS_DIR) / f"pipe_parallel_graph_{subfolder}"
- return get_incremental_directory_path(base_dir, "run")
+ return get_incremental_directory_path(base_dir, base_name="run")
@pytest.mark.dry_runnable
@@ -146,11 +146,11 @@ class TestPipeParallelGraph:
output_dir = _get_next_output_folder("add_each")
if graph_outputs.graphspec_json:
- save_text_to_path(graph_outputs.graphspec_json, output_dir / "graph.json")
+ save_text_to_path(graph_outputs.graphspec_json, path=output_dir / "graph.json")
if graph_outputs.mermaidflow_html:
- save_text_to_path(graph_outputs.mermaidflow_html, output_dir / "mermaidflow.html")
+ save_text_to_path(graph_outputs.mermaidflow_html, path=output_dir / "mermaidflow.html")
if graph_outputs.reactflow_html:
- save_text_to_path(graph_outputs.reactflow_html, output_dir / "reactflow.html")
+ save_text_to_path(graph_outputs.reactflow_html, path=output_dir / "reactflow.html")
pretty_print(
{
@@ -271,13 +271,13 @@ class TestPipeParallelGraph:
output_dir = _get_next_output_folder(pipe_code)
if graph_outputs.graphspec_json:
- save_text_to_path(graph_outputs.graphspec_json, output_dir / "graph.json")
+ save_text_to_path(graph_outputs.graphspec_json, path=output_dir / "graph.json")
if graph_outputs.mermaidflow_html:
- save_text_to_path(graph_outputs.mermaidflow_html, output_dir / "mermaidflow.html")
+ save_text_to_path(graph_outputs.mermaidflow_html, path=output_dir / "mermaidflow.html")
if graph_outputs.mermaidflow_mmd:
- save_text_to_path(graph_outputs.mermaidflow_mmd, output_dir / "mermaidflow.mmd")
+ save_text_to_path(graph_outputs.mermaidflow_mmd, path=output_dir / "mermaidflow.mmd")
if graph_outputs.reactflow_html:
- save_text_to_path(graph_outputs.reactflow_html, output_dir / "reactflow.html")
+ save_text_to_path(graph_outputs.reactflow_html, path=output_dir / "reactflow.html")
pretty_print(
{
diff --git a/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py b/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py
index 6ff0a1d49..762b9d8e4 100644
--- a/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py
+++ b/tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/test_pipe_img_gen_validation.py
@@ -41,7 +41,7 @@ def pipelex_routed_to_openai_for_e2e() -> Iterator[None]:
routing_profiles_doc["active"] = routing_profile_name
routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-pipe-img-gen-e2e-validation-"))
routing_override_path = routing_override_dir / routing_profiles_path.name
- save_toml_to_path(routing_profiles_doc, str(routing_override_path))
+ save_toml_to_path(routing_profiles_doc, path=str(routing_override_path))
routing_monkeypatch.setattr(
type(config_manager),
"routing_profiles_file_path",
diff --git a/tests/e2e/test_signature_validation_mthds.py b/tests/e2e/test_signature_validation_mthds.py
index 61c8e6c9c..af01d8f9d 100644
--- a/tests/e2e/test_signature_validation_mthds.py
+++ b/tests/e2e/test_signature_validation_mthds.py
@@ -6,11 +6,11 @@ import pytest
from pipelex.core.stuffs.text_content import TextContent
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError, SignaturesNotAllowedError
+from pipelex.pipe_signature.exceptions import PipeSignatureNotExecutableError
from pipelex.pipeline.bundle_validator import DryRunStatus
from pipelex.pipeline.exceptions import PipelineExecutionError
from pipelex.pipeline.runner import PipelexMTHDSProtocol
-from pipelex.pipeline.validate_bundle import ValidateBundleError, validate_bundle
+from pipelex.pipeline.validate_bundle import validate_bundle
_FIXTURE_DIR = Path(__file__).parent / "fixtures" / "signature_bundles"
_SIGNATURE_ONLY = _FIXTURE_DIR / "signature_only.mthds"
@@ -21,29 +21,28 @@ _STRUCTURED = _FIXTURE_DIR / "signature_with_structured_output.mthds"
@pytest.mark.asyncio
class TestSignatureValidationE2E:
- async def test_signature_only_bundle_strict_fails(self) -> None:
- with pytest.raises(ValidateBundleError) as exc_info:
- await validate_bundle(mthds_file_path=_SIGNATURE_ONLY)
- sig_error = exc_info.value.signature_check_error
- assert sig_error is not None
- assert isinstance(sig_error, SignaturesNotAllowedError)
- assert "signature_demo.summarize_doc" in sig_error.signature_refs
+ async def test_signature_only_bundle_strict_reports_pending(self) -> None:
+ # Signatures are never an error (D-B): strict validation does not raise — it reports the
+ # outstanding signature via pending_signatures and excludes the signature pipe from the sweep.
+ result = await validate_bundle(mthds_file_path=_SIGNATURE_ONLY)
+ assert "signature_demo.summarize_doc" in result.pending_signatures
+ assert "signature_demo.summarize_doc" not in result.dry_run_result
async def test_signature_only_bundle_lenient_passes(self) -> None:
result = await validate_bundle(mthds_file_path=_SIGNATURE_ONLY, allow_signatures=True)
assert "signature_demo.summarize_doc" in result.dry_run_result
assert result.dry_run_result["signature_demo.summarize_doc"].status is DryRunStatus.SUCCESS
+ # The placeholder is still an unsatisfied forward declaration even when mock-run in lenient mode.
+ assert "signature_demo.summarize_doc" in result.pending_signatures
- async def test_mixed_bundle_strict_fails_with_dep_path(self) -> None:
- with pytest.raises(ValidateBundleError) as exc_info:
- await validate_bundle(mthds_file_path=_MIXED)
- sig_error = exc_info.value.signature_check_error
- assert sig_error is not None
- signature_ref = "signature_mixed.summarize_extracted"
- assert signature_ref in sig_error.signature_refs
- assert signature_ref in sig_error.dep_paths
- chain = sig_error.dep_paths[signature_ref]
- assert "signature_mixed.process_doc" in chain
+ async def test_mixed_bundle_strict_reports_pending_signature(self) -> None:
+ # Strict mode no longer raises on the reached signature. The non-signature caller (process_doc)
+ # is still swept and dry-runs trivially (its signature sub-pipe mints a mock); the signature pipe
+ # itself is excluded from the sweep and reported via pending_signatures.
+ result = await validate_bundle(mthds_file_path=_MIXED)
+ assert "signature_mixed.summarize_extracted" in result.pending_signatures
+ assert result.dry_run_result["signature_mixed.process_doc"].status is DryRunStatus.SUCCESS
+ assert "signature_mixed.summarize_extracted" not in result.dry_run_result
async def test_mixed_bundle_lenient_passes_and_produces_mock(self) -> None:
result = await validate_bundle(mthds_file_path=_MIXED, allow_signatures=True)
diff --git a/tests/integration/pipelex/cli/test_agent_validate_defaults_strict.py b/tests/integration/pipelex/cli/test_agent_validate_defaults_strict.py
index e2c15812c..e25775204 100644
--- a/tests/integration/pipelex/cli/test_agent_validate_defaults_strict.py
+++ b/tests/integration/pipelex/cli/test_agent_validate_defaults_strict.py
@@ -8,7 +8,6 @@ from typing import TYPE_CHECKING
import pytest
from pipelex.cli.agent_cli.commands.validate._validate_core import validate_bundle_core # noqa: PLC2701
-from pipelex.pipeline.validate_bundle import ValidateBundleError
if TYPE_CHECKING:
from collections.abc import Iterator
@@ -45,16 +44,21 @@ def agent_signature_bundle_dir() -> Iterator[Path]:
class TestAgentValidateDefaultsStrict:
def test_agent_validate_defaults_to_strict(self, agent_signature_bundle_dir: Path) -> None:
- # The agent CLI's validate_bundle_core defaults to strict — same as `pipelex validate`.
- # A bundle whose dependency graph reaches a signature is rejected.
- with pytest.raises(ValidateBundleError) as exc_info:
- asyncio.run(
- validate_bundle_core(
- bundle_path=agent_signature_bundle_dir / "bundle.mthds",
- library_dirs=[agent_signature_bundle_dir],
- )
+ # Signatures are never an error (D-B): the strict agent CLI core does not raise on a reached
+ # signature — it returns a valid-but-not-runnable envelope. The bundle command's exit-code gate
+ # (not this core) turns is_runnable=False into a non-zero exit unless --allow-signatures.
+ result = asyncio.run(
+ validate_bundle_core(
+ bundle_path=agent_signature_bundle_dir / "bundle.mthds",
+ library_dirs=[agent_signature_bundle_dir],
)
- assert exc_info.value.signature_check_error is not None
+ )
+ assert result["is_valid"] is True
+ assert result["pending_signatures"] == ["agent_sigcli.agent_sig"]
+ assert result["is_runnable"] is False
+ # Strict mode excludes the signature pipe from the sweep — it is absent from validated_pipes.
+ pipe_refs = {entry["pipe_ref"] for entry in result["validated_pipes"]}
+ assert "agent_sigcli.agent_sig" not in pipe_refs
def test_agent_validate_allow_signatures_succeeds(self, agent_signature_bundle_dir: Path) -> None:
# With allow_signatures=True the same bundle validates — signatures dry-run as mocks.
diff --git a/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py b/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py
index 622587d46..3bc852529 100644
--- a/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py
+++ b/tests/integration/pipelex/cli/test_agent_validate_pipe_in_bundle.py
@@ -12,7 +12,6 @@ from pipelex.cli.agent_cli.commands.validate._validate_core import (
validate_pipe_in_bundle_core, # noqa: PLC2701
)
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
-from pipelex.pipeline.validate_bundle import ValidateBundleError
if TYPE_CHECKING:
from collections.abc import Iterator
@@ -138,36 +137,46 @@ class TestAgentValidatePipeInBundle:
assert "slice_bundle.draft_pipe" in result["pending_signatures"]
assert result["is_runnable"] is False
- def test_whole_bundle_strict_still_rejects_unrelated_signature(
+ def test_whole_bundle_strict_reports_unrelated_signature_as_pending(
self,
implemented_plus_signature_dir: Path,
) -> None:
- # The whole-bundle path keeps strict semantics: a bundle that merely *contains* a signature
- # is rejected (by design), even when the signature is unreached.
- with pytest.raises(ValidateBundleError) as exc_info:
- asyncio.run(
- validate_bundle_core(
- bundle_path=implemented_plus_signature_dir / "bundle.mthds",
- library_dirs=[implemented_plus_signature_dir],
- )
+ # Signatures are never an error (D-B): whole-bundle strict no longer rejects a bundle that merely
+ # contains a standalone signature. It returns a valid-but-not-runnable envelope listing the
+ # signature in pending_signatures; the bundle command's exit-code gate enforces the verdict.
+ result = asyncio.run(
+ validate_bundle_core(
+ bundle_path=implemented_plus_signature_dir / "bundle.mthds",
+ library_dirs=[implemented_plus_signature_dir],
)
- assert exc_info.value.signature_check_error is not None
+ )
+ assert result["is_valid"] is True
+ assert "slice_bundle.draft_pipe" in result["pending_signatures"]
+ assert result["is_runnable"] is False
+ # The implemented pipe is swept; the standalone signature pipe is excluded from the strict sweep.
+ pipe_refs = {entry["pipe_ref"] for entry in result["validated_pipes"]}
+ assert "slice_bundle.implemented_pipe" in pipe_refs
+ assert "slice_bundle.draft_pipe" not in pipe_refs
- def test_pipe_slice_strict_rejects_pipe_that_reaches_signature(
+ def test_pipe_slice_strict_reports_reached_signature_as_pending(
self,
caller_of_signature_dir: Path,
) -> None:
- # --pipe does NOT loosen strict mode for the *selected* pipe: if the requested pipe itself
- # reaches a signature, strict validation still fails.
- with pytest.raises(ValidateBundleError) as exc_info:
- asyncio.run(
- validate_pipe_in_bundle_core(
- bundle_path=caller_of_signature_dir / "bundle.mthds",
- pipe_code="caller_seq",
- library_dirs=[caller_of_signature_dir],
- )
+ # The requested pipe reaches a signature through its dependency graph. Signatures are never an
+ # error (D-B): the slice is swept and dry-runs trivially (the signature sub-pipe mints a mock);
+ # the reached signature is reported library-wide via pending_signatures, leaving it not-runnable.
+ result = asyncio.run(
+ validate_pipe_in_bundle_core(
+ bundle_path=caller_of_signature_dir / "bundle.mthds",
+ pipe_code="caller_seq",
+ library_dirs=[caller_of_signature_dir],
)
- assert exc_info.value.signature_check_error is not None
+ )
+ assert result["is_valid"] is True
+ assert "slice_caller.summary_sig" in result["pending_signatures"]
+ assert result["is_runnable"] is False
+ pipe_refs = {entry["pipe_ref"] for entry in result["validated_pipes"]}
+ assert "slice_caller.caller_seq" in pipe_refs
def test_pipe_slice_unknown_pipe_raises_not_found(
self,
diff --git a/tests/integration/pipelex/cli/test_init_cmd_integration.py b/tests/integration/pipelex/cli/test_init_cmd_integration.py
index b1947ebae..ea105914b 100644
--- a/tests/integration/pipelex/cli/test_init_cmd_integration.py
+++ b/tests/integration/pipelex/cli/test_init_cmd_integration.py
@@ -215,7 +215,7 @@ class TestInitCommandIntegration:
telemetry_path = env.pipelex_dir / "telemetry.toml"
toml_doc = load_toml_with_tomlkit(str(telemetry_path))
toml_doc["custom_posthog"]["mode"] = "identified" # type: ignore[index]
- save_toml_to_path(toml_doc, str(telemetry_path))
+ save_toml_to_path(toml_doc, path=str(telemetry_path))
# Get index for mistral
kit_backends = Path(str(get_kit_configs_dir())) / "inference" / "backends.toml"
@@ -247,7 +247,7 @@ class TestInitCommandIntegration:
backends_path = env.inference_dir / "backends.toml"
toml_doc = load_toml_with_tomlkit(str(backends_path))
toml_doc[PipelexBackend.GATEWAY]["enabled"] = True # type: ignore[index]
- save_toml_to_path(toml_doc, str(backends_path))
+ save_toml_to_path(toml_doc, path=str(backends_path))
# Get index for openai
kit_backends = Path(str(get_kit_configs_dir())) / "inference" / "backends.toml"
diff --git a/tests/integration/pipelex/cli/test_validate_signatures_cli.py b/tests/integration/pipelex/cli/test_validate_signatures_cli.py
index 7b517c007..bffe11544 100644
--- a/tests/integration/pipelex/cli/test_validate_signatures_cli.py
+++ b/tests/integration/pipelex/cli/test_validate_signatures_cli.py
@@ -93,36 +93,37 @@ class TestValidateSignaturesCli:
)
)
- def test_validate_all_strict_default_passes_with_orphan_signature(self, orphan_signature_dir: Path) -> None:
- # Orphan signature (no caller): strict --all should still succeed since signatures are filtered out.
- do_validate_all_libraries_and_dry_run(library_dirs=[orphan_signature_dir])
-
- def test_validate_all_strict_fails_with_caller_of_signature(self, signature_caller_dir: Path) -> None:
- # Non-signature pipe reaching a signature: strict --all must wrap SignaturesNotAllowedError
- # as a friendly typer.Exit(1) (consistent with the bundle/pipe paths), not bubble a raw
- # traceback to the user.
+ def test_validate_all_strict_default_fails_with_orphan_signature(self, orphan_signature_dir: Path) -> None:
+ # `validate --all` is strict by default (D-B consumer gate): an unimplemented PipeSignature in the
+ # library — even an orphan with no caller — makes the library NOT runnable, so it exits 1.
+ with pytest.raises(typer.Exit) as exc_info:
+ do_validate_all_libraries_and_dry_run(library_dirs=[orphan_signature_dir])
+ assert exc_info.value.exit_code == 1
+
+ def test_validate_all_strict_default_fails_with_caller_of_signature(self, signature_caller_dir: Path) -> None:
+ # Strict `validate --all` gates on the library-wide pending_signatures: a non-signature pipe reaching
+ # an unimplemented signature leaves that signature pending, so the library is NOT runnable → exit 1.
with pytest.raises(typer.Exit) as exc_info:
do_validate_all_libraries_and_dry_run(library_dirs=[signature_caller_dir])
assert exc_info.value.exit_code == 1
def test_validate_all_allow_signatures_passes(self, signature_caller_dir: Path) -> None:
- # Lenient mode: --all succeeds even when a non-signature pipe reaches a signature.
+ # Lenient mode: --allow-signatures tolerates the pending placeholders, so --all completes without raising.
do_validate_all_libraries_and_dry_run(library_dirs=[signature_caller_dir], allow_signatures=True)
- def test_validate_pipe_strict_default_fails_with_friendly_exit(
+ def test_validate_pipe_strict_default_passes_with_caller_of_signature(
self,
signature_caller_dir: Path,
) -> None:
- # Regression (issue 6 / greptile): single-pipe validation must wrap SignaturesNotAllowedError
- # as typer.Exit(1) with a Rich error message, not bubble a raw traceback to the user.
- with pytest.raises(typer.Exit) as exc_info:
- asyncio.run(
- _validate_pipe_or_bundle(
- pipe_code="sigcli_caller.caller_seq",
- library_dirs=[signature_caller_dir],
- )
+ # Signatures are never an error (D-B): single-pipe validation reaching a signature dry-runs
+ # trivially (the signature sub-pipe mints a mock) and completes — `validate pipe` makes no
+ # runnability claim, so there is no gate and no raise.
+ asyncio.run(
+ _validate_pipe_or_bundle(
+ pipe_code="sigcli_caller.caller_seq",
+ library_dirs=[signature_caller_dir],
)
- assert exc_info.value.exit_code == 1
+ )
def test_validate_pipe_allow_signatures_passes(
self,
diff --git a/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py b/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py
index 99e7f74ff..e0eada7cb 100644
--- a/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py
+++ b/tests/integration/pipelex/concepts/refines_custom_concept/test_refines_custom_concept.py
@@ -100,4 +100,4 @@ class TestRefinesCustomConcept:
vip_customer_concept = library.concept_library.get_required_concept("refines_custom_test.VIPCustomer")
# VIPCustomer should be compatible with Customer (it refines Customer)
- assert Concept.are_concept_compatible(vip_customer_concept, customer_concept)
+ assert Concept.are_concept_compatible(concept_1=vip_customer_concept, concept_2=customer_concept)
diff --git a/tests/integration/pipelex/core/concepts/test_concept_representation_generator.py b/tests/integration/pipelex/core/concepts/test_concept_representation_generator.py
index 4ac878054..1ce54b5d2 100644
--- a/tests/integration/pipelex/core/concepts/test_concept_representation_generator.py
+++ b/tests/integration/pipelex/core/concepts/test_concept_representation_generator.py
@@ -75,7 +75,7 @@ class TestComplexNestedStructuresJson:
def test_attachment_json(self) -> None:
"""Test simple Attachment generates correct JSON."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.Attachment", Attachment)
+ result = generator.generate_representation("test.Attachment", structure_class=Attachment)
assert result["concept"] == "test.Attachment"
assert result["content"]["name"] == "name_value"
assert result["content"]["url"].startswith("https://mock-")
@@ -83,7 +83,7 @@ class TestComplexNestedStructuresJson:
def test_embed_json(self) -> None:
"""Test Embed with multiple string fields generates correct JSON."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.Embed", Embed)
+ result = generator.generate_representation("test.Embed", structure_class=Embed)
expected = {
"concept": "test.Embed",
"content": {
@@ -97,7 +97,7 @@ class TestComplexNestedStructuresJson:
def test_message_json_recursive(self) -> None:
"""Test Message with nested Attachment and Embed lists generates correct recursive JSON."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.Message", Message)
+ result = generator.generate_representation("test.Message", structure_class=Message)
content = result["content"]
assert content["author"] == "author_value"
assert content["content"] == "content_value"
@@ -110,7 +110,7 @@ class TestComplexNestedStructuresJson:
def test_channel_json_deeply_nested(self) -> None:
"""Test Channel with deeply nested messages generates correct JSON."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.Channel", Channel)
+ result = generator.generate_representation("test.Channel", structure_class=Channel)
content = result["content"]
assert content["name"] == "name_value"
assert content["position"] == 0
@@ -123,7 +123,7 @@ class TestComplexNestedStructuresJson:
def test_newsletter_json_multiple_lists(self) -> None:
"""Test Newsletter with multiple list fields generates correct JSON."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.Newsletter", Newsletter)
+ result = generator.generate_representation("test.Newsletter", structure_class=Newsletter)
expected = {
"concept": "test.Newsletter",
"content": {
@@ -146,14 +146,14 @@ class TestComplexNestedStructuresPython:
def test_attachment_python(self) -> None:
"""Test simple Attachment generates correct Python instantiation."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- result = generator.generate_representation("test.Attachment", Attachment)
+ result = generator.generate_representation("test.Attachment", structure_class=Attachment)
assert result["concept"] == "test.Attachment"
assert 'Attachment(name="name_value", url="https://mock-' in result["content"]
def test_message_python_recursive(self) -> None:
"""Test Message with nested structures generates correct Python."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- result = generator.generate_representation("test.Message", Message)
+ result = generator.generate_representation("test.Message", structure_class=Message)
content = result["content"]
assert content.startswith(
'Message(author="author_value", content="content_value", attachments=[Attachment(name="name_value", url="https://mock-'
@@ -164,7 +164,7 @@ class TestComplexNestedStructuresPython:
def test_channel_python_deeply_nested(self) -> None:
"""Test Channel with deeply nested structures generates correct Python."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- result = generator.generate_representation("test.Channel", Channel)
+ result = generator.generate_representation("test.Channel", structure_class=Channel)
content = result["content"]
assert content.startswith('Channel(name="name_value", position=0, messages=[Message(')
assert 'Attachment(name="name_value", url="https://mock-' in content
@@ -176,7 +176,7 @@ class TestImportsTrackingIntegration:
def test_channel_tracks_all_nested_imports(self) -> None:
"""Test that Channel tracks imports for all nested classes."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- generator.generate_representation("test.Channel", Channel)
+ generator.generate_representation("test.Channel", structure_class=Channel)
expected_imports = {"Channel", "Message", "Attachment", "Embed"}
assert generator.imports_needed == expected_imports
@@ -184,7 +184,7 @@ class TestImportsTrackingIntegration:
def test_newsletter_tracks_all_imports(self) -> None:
"""Test that Newsletter tracks imports for all nested classes."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- generator.generate_representation("test.Newsletter", Newsletter)
+ generator.generate_representation("test.Newsletter", structure_class=Newsletter)
expected_imports = {"Newsletter", "ChannelSummary"}
assert generator.imports_needed == expected_imports
@@ -195,7 +195,7 @@ class TestConvenienceFunctionsIntegration:
def test_generate_json_representation_complex(self) -> None:
"""Test generate_json_representation with complex structure."""
- result = generate_json_representation("test.Message", Message)
+ result = generate_json_representation("test.Message", structure_class=Message)
assert result["concept"] == "test.Message"
assert "attachments" in result["content"]
assert len(result["content"]["attachments"]) == 1
@@ -204,7 +204,7 @@ class TestConvenienceFunctionsIntegration:
def test_generate_python_representation_complex(self) -> None:
"""Test generate_python_representation with complex structure."""
- result, imports = generate_python_representation("test.Message", Message)
+ result, imports = generate_python_representation("test.Message", structure_class=Message)
assert result["concept"] == "test.Message"
assert "Message(" in result["content"]
assert "Attachment(" in result["content"]
diff --git a/tests/integration/pipelex/csv/test_csv_input_detection.py b/tests/integration/pipelex/csv/test_csv_input_detection.py
index d693929d9..81560403b 100644
--- a/tests/integration/pipelex/csv/test_csv_input_detection.py
+++ b/tests/integration/pipelex/csv/test_csv_input_detection.py
@@ -75,7 +75,7 @@ class TestCsvInputDetection:
# rewritten into a local-looking path (which would defeat the remote guard) — the rejection
# must still fire end to end.
raw_inputs: dict[str, Any] = {"people": {"concept": "csv_demo.Person", "content": {"url": "s3://bucket/people.csv"}}}
- resolved = resolve_inputs_paths(raw_inputs, Path("/some/base/dir"))
+ resolved = resolve_inputs_paths(raw_inputs, base_dir=Path("/some/base/dir"))
assert resolved["people"]["content"]["url"] == "s3://bucket/people.csv" # not rewritten
inputs = cast("PipelineInputs", resolved)
with pytest.raises(CsvError) as exc_info:
diff --git a/tests/integration/pipelex/fixtures/combo_fixtures.py b/tests/integration/pipelex/fixtures/combo_fixtures.py
index 1ab00b405..81aff787e 100644
--- a/tests/integration/pipelex/fixtures/combo_fixtures.py
+++ b/tests/integration/pipelex/fixtures/combo_fixtures.py
@@ -63,7 +63,7 @@ def _setup_routing_for_backend(backend_name: str) -> tuple[MonkeyPatch, Path]:
routing_profiles_doc["active"] = routing_profile_name
routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-override-"))
routing_override_path = routing_override_dir / routing_profiles_path.name
- save_toml_to_path(routing_profiles_doc, str(routing_override_path))
+ save_toml_to_path(routing_profiles_doc, path=str(routing_override_path))
routing_monkeypatch.setattr(
type(config_manager),
"routing_profiles_file_path",
diff --git a/tests/integration/pipelex/kit/test_cursor_rules_update.py b/tests/integration/pipelex/kit/test_cursor_rules_update.py
index c4b08538d..1f76c3718 100644
--- a/tests/integration/pipelex/kit/test_cursor_rules_update.py
+++ b/tests/integration/pipelex/kit/test_cursor_rules_update.py
@@ -12,7 +12,7 @@ class TestUpdateCursorRules:
kit_index = load_index()
repo_root = tmp_path
- update_cursor_rules(repo_root, kit_index, agent_set=agent_set)
+ update_cursor_rules(repo_root, kit_index=kit_index, agent_set=agent_set)
cursor_rules_dir = repo_root / ".cursor" / "rules"
assert cursor_rules_dir.exists()
@@ -23,7 +23,7 @@ class TestUpdateCursorRules:
kit_index = load_index()
repo_root = tmp_path
- update_cursor_rules(repo_root, kit_index, agent_set=agent_set)
+ update_cursor_rules(repo_root, kit_index=kit_index, agent_set=agent_set)
# Check first .mdc file for front-matter
cursor_rules_dir = repo_root / ".cursor" / "rules"
@@ -37,7 +37,7 @@ class TestUpdateCursorRules:
kit_index = load_index()
repo_root = tmp_path
- update_cursor_rules(repo_root, kit_index, agent_set=agent_set)
+ update_cursor_rules(repo_root, kit_index=kit_index, agent_set=agent_set)
cursor_rules_dir = repo_root / ".cursor" / "rules"
exported_files: set[str] = set()
@@ -52,4 +52,4 @@ class TestUpdateCursorRules:
kit_index = load_index()
with pytest.raises(KitError, match=r"Agent set 'unknown' not found in index.toml"):
- update_cursor_rules(tmp_path, kit_index, agent_set="unknown")
+ update_cursor_rules(tmp_path, kit_index=kit_index, agent_set="unknown")
diff --git a/tests/integration/pipelex/kit/test_merged_rules.py b/tests/integration/pipelex/kit/test_merged_rules.py
index 0ab6c993b..a04392caa 100644
--- a/tests/integration/pipelex/kit/test_merged_rules.py
+++ b/tests/integration/pipelex/kit/test_merged_rules.py
@@ -13,7 +13,7 @@ class TestMergedRules:
"""Test building merged rules with default set."""
idx = load_index()
- merged = build_merged_rules(idx)
+ merged = build_merged_rules(kit_index=idx)
assert merged is not None
assert len(merged) > 0
assert merged.endswith("\n")
@@ -23,7 +23,7 @@ class TestMergedRules:
idx = load_index()
# Test with 'all' set
- merged = build_merged_rules(idx, agent_set="all")
+ merged = build_merged_rules(kit_index=idx, agent_set="all")
assert merged is not None
assert len(merged) > 0
@@ -32,13 +32,13 @@ class TestMergedRules:
idx = load_index()
with pytest.raises(ValueError, match="Agent set 'nonexistent' not found"):
- build_merged_rules(idx, agent_set="nonexistent")
+ build_merged_rules(kit_index=idx, agent_set="nonexistent")
def test_merged_rules_contain_demoted_headings(self):
"""Test that merged rules have demoted headings."""
idx = load_index()
- merged = build_merged_rules(idx)
+ merged = build_merged_rules(kit_index=idx)
# If demote is 1, check that we have ## headings (demoted from #)
if idx.agent_rules.demote > 0:
diff --git a/tests/integration/pipelex/kit/test_target_set_overrides.py b/tests/integration/pipelex/kit/test_target_set_overrides.py
index 5d9e0733c..3862a5154 100644
--- a/tests/integration/pipelex/kit/test_target_set_overrides.py
+++ b/tests/integration/pipelex/kit/test_target_set_overrides.py
@@ -14,7 +14,7 @@ class TestTargetSetOverrides:
claude_target = idx.agent_rules.targets["claude"]
assert claude_target.sets is not None
- merged = build_merged_rules(idx, agent_set="all", file_list=claude_target.sets["all"])
+ merged = build_merged_rules(kit_index=idx, agent_set="all", file_list=claude_target.sets["all"])
assert PYTHON_STANDARDS_HEADING not in merged
assert PYTEST_STANDARDS_HEADING_LOWER not in merged.lower()
@@ -25,7 +25,7 @@ class TestTargetSetOverrides:
claude_target = idx.agent_rules.targets["claude"]
assert claude_target.sets is not None
- merged = build_merged_rules(idx, agent_set="standalone", file_list=claude_target.sets["standalone"])
+ merged = build_merged_rules(kit_index=idx, agent_set="standalone", file_list=claude_target.sets["standalone"])
assert PYTHON_STANDARDS_HEADING in merged
assert "writing tests" in merged.lower()
@@ -36,7 +36,7 @@ class TestTargetSetOverrides:
agents_target = idx.agent_rules.targets["agents"]
assert agents_target.sets is not None
- merged = build_merged_rules(idx, agent_set="all", file_list=agents_target.sets["all"])
+ merged = build_merged_rules(kit_index=idx, agent_set="all", file_list=agents_target.sets["all"])
assert PYTHON_STANDARDS_HEADING in merged
assert "writing tests" in merged.lower()
@@ -46,5 +46,5 @@ class TestTargetSetOverrides:
idx = load_index()
assert "tdd.md" not in idx.agent_rules.sets["all"]
- merged = build_merged_rules(idx, agent_set="all")
+ merged = build_merged_rules(kit_index=idx, agent_set="all")
assert TDD_HEADING_LOWER not in merged.lower()
diff --git a/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py b/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py
index ca810227b..7cdb9a702 100644
--- a/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py
+++ b/tests/integration/pipelex/pipe_signature/test_dry_run_strict_mode.py
@@ -12,11 +12,10 @@ from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequen
from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
from pipelex.pipe_operators.llm.pipe_llm import PipeLLM
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipe_signature.pipe_signature import PipeSignature
from pipelex.pipe_signature.pipe_signature_blueprint import PipeSignatureBlueprint
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
-from pipelex.pipeline.validate_bundle import ValidateBundleError, validate_bundle
+from pipelex.pipeline.validate_bundle import validate_bundle
from tests.integration.pipelex.pipe_signature.conftest import SIGNATURES_DOMAIN_CODE
@@ -46,6 +45,15 @@ def _make_bundle_with_signature() -> PipelexBundleBlueprint:
@pytest.mark.asyncio(loop_scope="class")
class TestDryRunStrictMode:
+ """Signatures are never an error (D-B): strict validation never raises on a reached signature.
+
+ ``allow_signatures`` is a sweep-mechanics flag, not a verdict: in strict mode signature pipes are
+ excluded from the dry-run sweep (absent from the returned status map / ``validated_pipes``); a
+ non-signature caller that reaches a signature is still swept and dry-runs trivially (the signature
+ sub-pipe mints a mock). The unsatisfied set is reported library-wide via ``pending_signatures`` at
+ the ``validate_bundle`` level; the "is this a failure?" decision is the consumer's.
+ """
+
async def test_strict_default_passes_when_no_signatures(
self,
setup_signature_library: Callable[[], None],
@@ -80,11 +88,14 @@ class TestDryRunStrictMode:
results = await BundleValidator().validate_pipes([seq_pipe], library_id=get_current_library())
assert results[seq_pipe.pipe_ref].status is DryRunStatus.SUCCESS
- async def test_strict_fails_on_signature_in_sequence(
+ async def test_strict_sweeps_caller_but_excludes_signature(
self,
setup_signature_library: Callable[[], None],
make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
) -> None:
+ # Strict mode does not raise on the reached signature. The signature pipe is excluded from the
+ # sweep (absent from the status map); the sequence that reaches it is still swept and SUCCEEDS
+ # (the signature sub-pipe mints a mock during the dry run).
setup_signature_library()
sig_pipe = PipeFactory[PipeSignature].make_from_blueprint(
domain_code=SIGNATURES_DOMAIN_CODE,
@@ -106,9 +117,10 @@ class TestDryRunStrictMode:
)
get_pipe_library().add_new_pipe(pipe=seq_pipe)
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes([seq_pipe], library_id=get_current_library())
- assert sig_pipe.pipe_ref in exc_info.value.signature_refs
+ results = await BundleValidator().validate_pipes([sig_pipe, seq_pipe], library_id=get_current_library())
+ assert results[seq_pipe.pipe_ref].status is DryRunStatus.SUCCESS
+ # The signature pipe itself is excluded from the strict sweep — never an error, never SUCCESS.
+ assert sig_pipe.pipe_ref not in results
async def test_lenient_succeeds_on_signature_in_sequence(
self,
@@ -139,217 +151,37 @@ class TestDryRunStrictMode:
results = await BundleValidator().validate_pipes([seq_pipe], library_id=get_current_library(), allow_signatures=True)
assert results[seq_pipe.pipe_ref].status is DryRunStatus.SUCCESS
- async def test_strict_error_lists_all_signatures(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- setup_signature_library()
- sig_a = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="multi_sig_a",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- sig_b = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="multi_sig_b",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_pipes(pipes=[sig_a, sig_b])
-
- seq_pipe = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="seq_multi_sig",
- blueprint=PipeSequenceBlueprint(
- description="Sequence containing two signatures.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[
- SubPipeBlueprint(pipe="multi_sig_a", result="summary_a"),
- SubPipeBlueprint(pipe="multi_sig_b", result="summary_b"),
- ],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=seq_pipe)
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes([seq_pipe], library_id=get_current_library())
- assert exc_info.value.signature_refs == {sig_a.pipe_ref, sig_b.pipe_ref}
-
- async def test_strict_error_includes_dep_paths(
+ async def test_lone_signature_excluded_in_strict_but_swept_in_lenient(
self,
setup_signature_library: Callable[[], None],
make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
) -> None:
+ # A signature validated on its own: excluded from the strict sweep (empty status map), but
+ # mock-run as a SUCCESS in lenient mode (allow_signatures is sweep mechanics).
setup_signature_library()
sig_pipe = PipeFactory[PipeSignature].make_from_blueprint(
domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="dep_sig",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=sig_pipe)
- inner_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="dep_inner_seq",
- blueprint=PipeSequenceBlueprint(
- description="Inner sequence wrapping the signature.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="dep_sig", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=inner_seq)
- outer_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="dep_outer_seq",
- blueprint=PipeSequenceBlueprint(
- description="Outer sequence calling inner sequence.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="dep_inner_seq", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=outer_seq)
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes([outer_seq], library_id=get_current_library())
- error = exc_info.value
- assert sig_pipe.pipe_ref in error.dep_paths
- chain = error.dep_paths[sig_pipe.pipe_ref]
- assert outer_seq.pipe_ref in chain
- assert inner_seq.pipe_ref in chain
- for entry in chain:
- assert "." in entry, f"dep chain entries must be qualified pipe_refs, got: {entry}"
-
- async def test_validate_bundle_strict_fails_on_signature(self) -> None:
- mthds_content = MthdsFactory.make_mthds_content(blueprint=_make_bundle_with_signature())
- with pytest.raises(ValidateBundleError) as exc_info:
- await validate_bundle(mthds_contents=[mthds_content])
- sig_error = exc_info.value.signature_check_error
- assert sig_error is not None
- assert "bundle_strict_domain.bundle_sig_step" in sig_error.signature_refs
- assert "bundle_strict_domain.bundle_sig_step" in sig_error.dep_paths
-
- async def test_dry_run_pipes_aggregates_signatures_across_pipes(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- # Regression: when multiple pipes in the batch each reach distinct signatures, the strict
- # pre-check must surface every offender in a single error, not short-circuit on the first.
- setup_signature_library()
- sig_a = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="agg_sig_a",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- sig_b = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="agg_sig_b",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_pipes(pipes=[sig_a, sig_b])
-
- seq_a = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="agg_seq_a",
- blueprint=PipeSequenceBlueprint(
- description="Sequence reaching sig_a.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="agg_sig_a", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- seq_b = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="agg_seq_b",
- blueprint=PipeSequenceBlueprint(
- description="Sequence reaching sig_b.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="agg_sig_b", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_pipes(pipes=[seq_a, seq_b])
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes(pipes=[seq_a, seq_b], library_id=get_current_library())
- # Both signatures must appear — not just the one from the first pipe.
- assert exc_info.value.signature_refs == {sig_a.pipe_ref, sig_b.pipe_ref}
-
- async def test_aggregated_dep_path_prefers_longest_across_callers(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- # Two callers reach the SAME signature by chains of different length: a short caller
- # (short_seq -> S) and a long caller (long_seq -> mid_seq -> S). The aggregated error must
- # render the longest chain regardless of batch order (exercises the len(path) > len(existing)
- # branch that distinct-signature aggregation tests never hit).
- setup_signature_library()
- sig_pipe = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="lp_sig",
+ pipe_code="lone_sig",
blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
)
get_pipe_library().add_new_pipe(pipe=sig_pipe)
- mid_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="lp_mid_seq",
- blueprint=PipeSequenceBlueprint(
- description="Middle hop of the long caller.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="lp_sig", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=mid_seq)
+ strict_results = await BundleValidator().validate_pipes([sig_pipe], library_id=get_current_library())
+ assert strict_results == {}
- short_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="lp_short_seq",
- blueprint=PipeSequenceBlueprint(
- description="Short caller straight to the signature.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="lp_sig", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- long_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="lp_long_seq",
- blueprint=PipeSequenceBlueprint(
- description="Long caller via the middle hop.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="lp_mid_seq", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_pipes(pipes=[short_seq, long_seq])
+ lenient_results = await BundleValidator().validate_pipes([sig_pipe], library_id=get_current_library(), allow_signatures=True)
+ assert lenient_results[sig_pipe.pipe_ref].status is DryRunStatus.SUCCESS
- # Longest chain must win regardless of batch order (short-first then long-first).
- longest_chain = [long_seq.pipe_ref, mid_seq.pipe_ref]
- with pytest.raises(SignaturesNotAllowedError) as short_first:
- await BundleValidator().validate_pipes(pipes=[short_seq, long_seq], library_id=get_current_library())
- assert short_first.value.dep_paths[sig_pipe.pipe_ref] == longest_chain
- with pytest.raises(SignaturesNotAllowedError) as long_first:
- await BundleValidator().validate_pipes(pipes=[long_seq, short_seq], library_id=get_current_library())
- assert long_first.value.dep_paths[sig_pipe.pipe_ref] == longest_chain
+ async def test_validate_bundle_strict_reports_pending_signature(self) -> None:
+ # Strict validate_bundle no longer raises: it returns a result whose library-wide
+ # pending_signatures lists the unsatisfied signature, while the non-signature caller is swept.
+ mthds_content = MthdsFactory.make_mthds_content(blueprint=_make_bundle_with_signature())
+ result = await validate_bundle(mthds_contents=[mthds_content])
+ assert "bundle_strict_domain.bundle_sig_step" in result.pending_signatures
+ assert result.dry_run_result["bundle_strict_domain.bundle_seq"].status is DryRunStatus.SUCCESS
+ # The signature pipe itself is excluded from the strict sweep.
+ assert "bundle_strict_domain.bundle_sig_step" not in result.dry_run_result
async def test_validate_bundle_lenient_passes_on_signature(self) -> None:
mthds_content = MthdsFactory.make_mthds_content(blueprint=_make_bundle_with_signature())
@@ -358,167 +190,5 @@ class TestDryRunStrictMode:
assert "bundle_strict_domain.bundle_seq" in result.dry_run_result
for entry in result.dry_run_result.values():
assert entry.status is DryRunStatus.SUCCESS
-
- async def test_aggregated_error_names_actual_offender_not_first_pipe(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- # Regression: when pipes[0] is clean and a later pipe reaches a signature, the aggregated
- # error must name the offender — not pipes[0]. The previous code used pipes[0].pipe_ref
- # unconditionally for the message header.
- setup_signature_library()
- innocent_op = PipeFactory[PipeLLM].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="innocent_first_op",
- blueprint=PipeLLMBlueprint(
- description="Real LLM step with no signature deps.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- prompt="Summarize $doc.",
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=innocent_op)
-
- hidden_sig = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="hidden_sig",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=hidden_sig)
- offender_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="offender_seq",
- blueprint=PipeSequenceBlueprint(
- description="Sequence reaching a signature.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="hidden_sig", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=offender_seq)
-
- # Iterate innocent FIRST, offender SECOND — exposes the pipes[0] bug.
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes(pipes=[innocent_op, offender_seq], library_id=get_current_library())
- error = exc_info.value
- assert offender_seq.pipe_ref in error.offending_pipe_refs
- assert innocent_op.pipe_ref not in error.offending_pipe_refs
- assert offender_seq.pipe_ref in str(error)
- assert f"'{innocent_op.pipe_ref}' depends on" not in str(error)
-
- async def test_aggregated_error_lists_all_offenders_when_multiple(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- # Regression: when multiple pipes each reach distinct signatures, all offenders must be
- # reported — not just one. Multi-offender message uses a plural header.
- setup_signature_library()
- sig_a = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="multi_off_sig_a",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- sig_b = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="multi_off_sig_b",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_pipes(pipes=[sig_a, sig_b])
- seq_a = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="multi_off_seq_a",
- blueprint=PipeSequenceBlueprint(
- description="Sequence reaching sig_a.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="multi_off_sig_a", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- seq_b = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="multi_off_seq_b",
- blueprint=PipeSequenceBlueprint(
- description="Sequence reaching sig_b.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="multi_off_sig_b", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_pipes(pipes=[seq_a, seq_b])
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes(pipes=[seq_a, seq_b], library_id=get_current_library())
- error = exc_info.value
- assert error.offending_pipe_refs == {seq_a.pipe_ref, seq_b.pipe_ref}
- message = str(error)
- assert "The following pipes depend on" in message
- assert seq_a.pipe_ref in message
- assert seq_b.pipe_ref in message
-
- async def test_lone_signature_not_listed_as_offender(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- # A signature validated on its own is the placeholder itself, not a pipe that
- # "depends on" one: it belongs in signature_refs, never in offending_pipe_refs.
- setup_signature_library()
- sig_pipe = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="lone_sig",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=sig_pipe)
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes([sig_pipe], library_id=get_current_library())
- error = exc_info.value
- assert sig_pipe.pipe_ref in error.signature_refs
- assert sig_pipe.pipe_ref not in error.offending_pipe_refs
- assert error.offending_pipe_refs == set()
- assert "Validation found PipeSignature placeholders" in str(error)
-
- async def test_dry_run_pipes_excludes_signature_from_offenders(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- # When the pipe list contains both a signature and a controller that reaches it,
- # only the controller is an offender — the signature is the placeholder itself.
- setup_signature_library()
- sig_pipe = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="listed_sig",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=sig_pipe)
- seq_pipe = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="listed_seq",
- blueprint=PipeSequenceBlueprint(
- description="Sequence calling the signature.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="listed_sig", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=seq_pipe)
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await BundleValidator().validate_pipes(pipes=[sig_pipe, seq_pipe], library_id=get_current_library())
- error = exc_info.value
- assert error.offending_pipe_refs == {seq_pipe.pipe_ref}
- assert sig_pipe.pipe_ref not in error.offending_pipe_refs
- assert sig_pipe.pipe_ref in error.signature_refs
+ # The placeholder is still an unsatisfied forward declaration even when mock-run.
+ assert "bundle_strict_domain.bundle_sig_step" in result.pending_signatures
diff --git a/tests/integration/pipelex/pipe_signature/test_signatures_not_allowed_error_message.py b/tests/integration/pipelex/pipe_signature/test_signatures_not_allowed_error_message.py
deleted file mode 100644
index 5b4a6abf6..000000000
--- a/tests/integration/pipelex/pipe_signature/test_signatures_not_allowed_error_message.py
+++ /dev/null
@@ -1,109 +0,0 @@
-from typing import Callable
-
-from pipelex.core.pipes.pipe_factory import PipeFactory
-from pipelex.hub import get_pipe_library
-from pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequence
-from pipelex.pipe_controllers.sequence.pipe_sequence_blueprint import PipeSequenceBlueprint
-from pipelex.pipe_controllers.sub_pipe_blueprint import SubPipeBlueprint
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
-from pipelex.pipe_signature.pipe_signature import PipeSignature
-from pipelex.pipe_signature.pipe_signature_blueprint import PipeSignatureBlueprint
-from pipelex.pipe_signature.signature_walk import collect_signature_paths, collect_signature_refs
-from tests.integration.pipelex.pipe_signature.conftest import SIGNATURES_DOMAIN_CODE
-
-
-class TestSignaturesNotAllowedErrorMessage:
- def _build_sequence_with_signature(
- self,
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> tuple[PipeSignature, PipeSequence]:
- sig_pipe = PipeFactory[PipeSignature].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="msg_inner_sig",
- blueprint=make_signature_blueprint(inputs={"doc": "SigTestDoc"}, output="SigTestSummary"),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=sig_pipe)
-
- inner_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="msg_inner_seq",
- blueprint=PipeSequenceBlueprint(
- description="Inner sequence wrapping the signature.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="msg_inner_sig", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=inner_seq)
-
- outer_seq = PipeFactory[PipeSequence].make_from_blueprint(
- domain_code=SIGNATURES_DOMAIN_CODE,
- pipe_code="msg_outer_seq",
- blueprint=PipeSequenceBlueprint(
- description="Outer sequence calling the inner sequence.",
- inputs={"doc": "SigTestDoc"},
- output="SigTestSummary",
- steps=[SubPipeBlueprint(pipe="msg_inner_seq", result="summary")],
- ),
- concept_codes_from_the_same_domain=["SigTestDoc", "SigTestSummary"],
- )
- get_pipe_library().add_new_pipe(pipe=outer_seq)
- return sig_pipe, outer_seq
-
- def test_dep_paths_keys_are_qualified_pipe_refs(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- setup_signature_library()
- sig_pipe, outer_seq = self._build_sequence_with_signature(make_signature_blueprint)
-
- error = SignaturesNotAllowedError(
- offending_pipe_refs={outer_seq.pipe_ref},
- signature_refs=collect_signature_refs(pipe=outer_seq),
- dep_paths=collect_signature_paths(pipe=outer_seq),
- )
- assert sig_pipe.pipe_ref in error.dep_paths
- for key in error.dep_paths:
- assert "." in key, f"dep_paths keys must be qualified pipe_refs, got: {key}"
- dep_chain = error.dep_paths[sig_pipe.pipe_ref]
- assert outer_seq.pipe_ref in dep_chain
- for entry in dep_chain:
- assert "." in entry, f"dep_paths values must list qualified pipe_refs, got: {entry}"
-
- def test_message_lists_each_signature_with_dep_path(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- setup_signature_library()
- sig_pipe, outer_seq = self._build_sequence_with_signature(make_signature_blueprint)
-
- error = SignaturesNotAllowedError(
- offending_pipe_refs={outer_seq.pipe_ref},
- signature_refs=collect_signature_refs(pipe=outer_seq),
- dep_paths=collect_signature_paths(pipe=outer_seq),
- )
- message = str(error)
- assert sig_pipe.pipe_ref in message
- assert outer_seq.pipe_ref in message
-
- def test_message_includes_fix_suggestion(
- self,
- setup_signature_library: Callable[[], None],
- make_signature_blueprint: Callable[..., PipeSignatureBlueprint],
- ) -> None:
- setup_signature_library()
- sig_pipe, outer_seq = self._build_sequence_with_signature(make_signature_blueprint)
-
- error = SignaturesNotAllowedError(
- offending_pipe_refs={outer_seq.pipe_ref},
- signature_refs=collect_signature_refs(pipe=outer_seq),
- dep_paths=collect_signature_paths(pipe=outer_seq),
- )
- message = str(error)
- assert "--allow-signatures" in message
- assert "real" in message.lower() or "implement" in message.lower()
- assert sig_pipe.pipe_ref in message
diff --git a/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py b/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py
index 0394522ba..330d19077 100644
--- a/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py
+++ b/tests/integration/pipelex/pipeline/test_pipeline_run_id_resubmission.py
@@ -83,7 +83,7 @@ class _FailingPipeRun(PipeRunProtocol):
"""
@override
- async def run(self, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
+ async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
msg = "Injected pipe-run failure to exercise registry-entry removal."
raise PipeRouterError(
message=msg,
diff --git a/tests/integration/pipelex/pipeline/test_protocol_validate.py b/tests/integration/pipelex/pipeline/test_protocol_validate.py
index d0818797a..3c603a8a1 100644
--- a/tests/integration/pipelex/pipeline/test_protocol_validate.py
+++ b/tests/integration/pipelex/pipeline/test_protocol_validate.py
@@ -204,13 +204,19 @@ class TestProtocolValidate:
with pytest.raises(ValidateBundleError, match="must not be empty"):
await runner.validate(mthds_contents=[])
- async def test_strict_mode_raises_on_unsatisfied_signature(self, load_empty_library: Callable[[], str]) -> None:
- """With the strict default (``allow_signatures=False``), an unsatisfied signature raises instead of reporting."""
+ async def test_strict_mode_reports_unsatisfied_signature(self, load_empty_library: Callable[[], str]) -> None:
+ """Signatures are never an error (D-B): with the strict default (``allow_signatures=False``) an
+ unsatisfied signature is reported as pending — not yet runnable — exactly as the lenient path
+ does (strict ≡ lenient in the report body). The "is this a failure?" decision moves to the consumer.
+ """
load_empty_library()
try:
runner = PipelexMTHDSProtocol()
- with pytest.raises(ValidateBundleError):
- await runner.validate(mthds_contents=_signature_only_contents())
+ report = await runner.validate(mthds_contents=_signature_only_contents())
+
+ assert isinstance(report, PipelexValidationReport)
+ assert report.pending_signatures == ["research.find_key_findings"]
+ assert report.is_runnable is False
finally:
clear_current_library()
@@ -288,7 +294,7 @@ class TestProtocolValidate:
try:
library_manager = get_library_manager()
mocker.patch(
- "pipelex.pipeline.runner.build_pipe_io_contracts",
+ "pipelex.pipeline.validate_in_process.build_pipe_io_contracts",
side_effect=PipeIOContractError(message="simulated render failure"),
)
mocker.patch.object(library_manager, "teardown", side_effect=LibraryError("simulated teardown failure"))
diff --git a/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py b/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py
index db8007e1f..df2df32a3 100644
--- a/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py
+++ b/tests/integration/pipelex/pipeline/test_runner_library_lifecycle.py
@@ -75,7 +75,7 @@ class _FailingPipeRun(PipeRunProtocol):
"""
@override
- async def run(self, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
+ async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
msg = "Injected pipe-run failure to exercise library teardown."
raise PipeRouterError(
message=msg,
diff --git a/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
new file mode 100644
index 000000000..c0b3ed26f
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_validate_bundle_source_threading.py
@@ -0,0 +1,121 @@
+"""Integration: ``validate_bundle`` threads per-content ``mthds_sources`` into ``blueprint.source``.
+
+The API submits sourceless bundle text (``mthds_contents: list[str]``), so without
+a per-item source the in-memory load path sets ``blueprint.source = None`` and
+cross-file diagnostics misfire. ``validate_bundle(mthds_sources=...)`` pairs each
+content with its logical source, so the loaded blueprint — and any
+``ValidateBundleError`` it raises — carries a real ``source`` the consumer can map
+to the owning file. The CLI's on-disk path keeps using real file paths and is
+unaffected.
+"""
+
+from collections.abc import Callable
+
+import pytest
+
+from pipelex.base_exceptions import PipelexUnexpectedError, ValidationErrorCategory
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validate_bundle import validate_bundle
+
+_VALID_MTHDS = """
+domain = "testapp"
+description = "Test domain"
+
+[concept.Customer]
+description = "A customer"
+"""
+
+# An invalid ``main_pipe`` deterministically fails blueprint validation, producing a
+# categorized blueprint-validation error that carries the blueprint's ``source``.
+_INVALID_MAIN_PIPE_MTHDS = """
+domain = "testapp"
+description = "Test domain"
+main_pipe = "Not A Valid Pipe Code!"
+
+[concept.Customer]
+description = "A customer"
+"""
+
+# An unclosed table header is a TOML *syntax* error: it fails in the interpreter before any
+# blueprint dict exists, so the ``PipelexInterpreterError`` carries only a message — no
+# categorized error data and (crucially) no chance to seed the threaded ``source``.
+_MALFORMED_TOML_MTHDS = """
+domain = "testapp"
+[concept.Customer
+description = "the table header above is never closed"
+"""
+
+
[email protected](loop_scope="class")
+class TestValidateBundleSourceThreading:
+ async def test_valid_bundle_blueprint_carries_threaded_source(
+ self,
+ load_empty_library: Callable[[], str],
+ ) -> None:
+ """A valid bundle's loaded blueprint records the threaded per-content source as ``source``."""
+ load_empty_library()
+ result = await validate_bundle(mthds_contents=[_VALID_MTHDS], mthds_sources=["api://bundle-0.mthds"])
+ assert result.blueprints[0].source == "api://bundle-0.mthds"
+
+ async def test_source_none_without_names(
+ self,
+ load_empty_library: Callable[[], str],
+ ) -> None:
+ """Without ``mthds_sources`` the in-memory path leaves ``source`` unset (unchanged behavior)."""
+ load_empty_library()
+ result = await validate_bundle(mthds_contents=[_VALID_MTHDS])
+ assert result.blueprints[0].source is None
+
+ async def test_invalid_bundle_validation_errors_carry_source(
+ self,
+ load_empty_library: Callable[[], str],
+ ) -> None:
+ """An invalid bundle's structured ``validation_errors`` carry the threaded ``source``.
+
+ Pins that the carrier is the *blueprint-validation* item produced by the dict-seeded
+ ``source`` (the failure happens before the post-validate object exists), not some
+ coincidental other item — so a regression that silently stopped seeding would fail here.
+ """
+ load_empty_library()
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[_INVALID_MAIN_PIPE_MTHDS], mthds_sources=["broken.mthds"])
+ report = exc_info.value.to_error_report()
+ assert report.validation_errors is not None
+ seeded_items = [item for item in report.validation_errors if item.source == "broken.mthds"]
+ assert seeded_items, "no validation_errors item carried the threaded source"
+ assert any(item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in seeded_items)
+
+ async def test_parse_level_failure_yields_a_sourceless_residual_item(
+ self,
+ load_empty_library: Callable[[], str],
+ ) -> None:
+ """A TOML-syntax error still surfaces a non-empty ``validation_errors`` — the invariant is total.
+
+ Parse-level failures (TOML syntax, an empty blueprint, a bundle elaborator) are raised by
+ the interpreter with only a message — no per-error data, and (since they fail before the
+ blueprint dict is seeded) no threaded ``source``. The shared builder's last-resort residual
+ still emits one ``blueprint_validation`` item, so an invalid verdict never rides a bare
+ message with an empty ``validation_errors[]``. Being parse-level, the residual carries no
+ ``source`` — even though one was threaded in — which this contrasts against the categorized
+ cases above.
+ """
+ load_empty_library()
+ with pytest.raises(ValidateBundleError) as exc_info:
+ await validate_bundle(mthds_contents=[_MALFORMED_TOML_MTHDS], mthds_sources=["broken.mthds"])
+ report = exc_info.value.to_error_report()
+ assert report.validation_errors, "a parse-level failure must still carry a non-empty validation_errors[]"
+ assert all(item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in report.validation_errors)
+ assert all(item.source is None for item in report.validation_errors)
+
+ async def test_length_mismatch_is_a_host_contract_error(
+ self,
+ load_empty_library: Callable[[], str],
+ ) -> None:
+ """A ``mthds_sources``/``mthds_contents`` length mismatch is a host wiring bug, not user input.
+
+ It must raise an internal error (→ 500, redacted under STRICT), not a caller-facing
+ ``ValidateBundleError`` (→ 422) — ``mthds_sources`` is never supplied by the end caller.
+ """
+ load_empty_library()
+ with pytest.raises(PipelexUnexpectedError, match="must be a per-item source list matching mthds_contents"):
+ await validate_bundle(mthds_contents=[_VALID_MTHDS], mthds_sources=["a.mthds", "b.mthds"])
diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py
index 6be29b4ff..fdd47a56a 100644
--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py
+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_blueprint_validation.py
@@ -49,7 +49,7 @@ def pipelex_routed_to_openai() -> Iterator[None]:
routing_profiles_doc["active"] = routing_profile_name
routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-pipe-img-gen-validation-"))
routing_override_path = routing_override_dir / routing_profiles_path.name
- save_toml_to_path(routing_profiles_doc, str(routing_override_path))
+ save_toml_to_path(routing_profiles_doc, path=str(routing_override_path))
routing_monkeypatch.setattr(
type(config_manager),
"routing_profiles_file_path",
diff --git a/tests/integration/pipelex/plugins/test_external_plugin.py b/tests/integration/pipelex/plugins/test_external_plugin.py
index e26b88ee5..3f04f9d3c 100644
--- a/tests/integration/pipelex/plugins/test_external_plugin.py
+++ b/tests/integration/pipelex/plugins/test_external_plugin.py
@@ -56,6 +56,7 @@ class MockExternalLLMWorker(LLMWorkerAbstract):
async def _gen_object(
self,
llm_job: LLMJob,
+ *,
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
class ObjectFactory(ModelFactory[schema]): # type: ignore[valid-type]
diff --git a/tests/integration/pipelex/system/test_load_config.py b/tests/integration/pipelex/system/test_load_config.py
index af5f6dfe0..962e572bf 100644
--- a/tests/integration/pipelex/system/test_load_config.py
+++ b/tests/integration/pipelex/system/test_load_config.py
@@ -31,7 +31,7 @@ class TestLoadConfig:
# Load and apply the kit config
kit_config_path = "pipelex/kit/configs/pipelex.toml"
kit_config = load_toml_from_path(kit_config_path)
- deep_update(base_config_copy, kit_config)
+ deep_update(base_config_copy, updates=kit_config)
# The kit config should not change anything - all values should match defaults
assert base_config_copy == base_config, (
diff --git a/tests/integration/pipelex/temporal/data_converter/test_data_conv_enum_roundtrip.py b/tests/integration/pipelex/temporal/data_converter/test_data_conv_enum_roundtrip.py
index 4fe56bd13..26e0fbf61 100644
--- a/tests/integration/pipelex/temporal/data_converter/test_data_conv_enum_roundtrip.py
+++ b/tests/integration/pipelex/temporal/data_converter/test_data_conv_enum_roundtrip.py
@@ -31,7 +31,7 @@ class TestEnumRoundTrip:
deserializer cannot resolve the dynamic class and the round-trip fails.
"""
schema = Pet.model_json_schema()
- dynamic_pet_cls = SchemaToModelFactory.make_from_json_schema(schema, "Pet")
+ dynamic_pet_cls = SchemaToModelFactory.make_from_json_schema(schema, class_name="Pet")
instance = dynamic_pet_cls(name="Rex", species=PetSpecies.DOG)
pretty_print(instance, title="instance")
diff --git a/tests/integration/pipelex/temporal/library_crate/helpers.py b/tests/integration/pipelex/temporal/library_crate/helpers.py
index bc419d6b7..0eb165673 100644
--- a/tests/integration/pipelex/temporal/library_crate/helpers.py
+++ b/tests/integration/pipelex/temporal/library_crate/helpers.py
@@ -50,7 +50,7 @@ def rehydrate_pipe_output(pipe_output: PipeOutput, pipe_job: PipeJob | None = No
that production submitters use.
"""
library_crate = pipe_job.library_crate if pipe_job is not None else None
- return rehydrate_pipe_output_with_crate(pipe_output, library_crate)
+ return rehydrate_pipe_output_with_crate(pipe_output, library_crate=library_crate)
async def execute_workflow(
diff --git a/tests/integration/pipelex/temporal/test_dry_validate_activity_in_memory.py b/tests/integration/pipelex/temporal/test_dry_validate_activity_in_memory.py
index ddddd73cd..c39385df5 100644
--- a/tests/integration/pipelex/temporal/test_dry_validate_activity_in_memory.py
+++ b/tests/integration/pipelex/temporal/test_dry_validate_activity_in_memory.py
@@ -12,8 +12,8 @@ Phase-3 contract (TODOS.md):
- tracing stays in memory: no NDJSON partition appears, ``make_event_log`` is never called;
- the graph is best-effort (D5): an expected dry-run failure yields ``graph_spec=None`` with
validation still successful, while a non-Pipelex programming bug propagates and fails the run;
-- a validation failure crosses back as a structured ``ErrorReport`` whose offending-signature
- data survives the crossing (D3/T3);
+- a validation failure crosses back as a structured ``ErrorReport`` whose per-error
+ ``validation_errors`` data survives the crossing (D3/T3);
- concurrent invocations don't cross-contaminate the scoped overrides.
"""
@@ -29,6 +29,7 @@ from temporalio.client import WorkflowFailureError
from temporalio.common import RetryPolicy
from temporalio.worker import UnsandboxedWorkflowRunner, Worker
+from pipelex.base_exceptions import ValidationErrorCategory
from pipelex.config import get_config
from pipelex.hub import clear_current_library, get_current_library_id_or_none, get_library_manager
from pipelex.pipe_run.exceptions import DryRunError
@@ -120,6 +121,15 @@ inputs = { doc = "Text" }
output = "Text"
"""
+_INVALID_MTHDS = """
+domain = "dry_validate_invalid"
+description = "Bundle with a real validation error: an invalid main_pipe code fails blueprint validation"
+main_pipe = "Not A Valid Pipe Code!"
+
+[concept.InvalidDoc]
+description = "A document for the invalid-bundle test"
+"""
+
@pytest.mark.temporal
@pytest.mark.asyncio(loop_scope="class")
@@ -250,23 +260,24 @@ class TestDryValidateActivityInMemory:
await self._execute(temporal_client, DryValidateArg(mthds_contents=[_ALPHA_MTHDS]))
async def test_validation_failure_crosses_as_structured_error_report(self, temporal_client: TemporalClient) -> None:
- """D3/T3: a strict-mode signature refusal raises, and the structured offending-signature
+ """D3/T3: a genuine validation failure raises, and the structured per-error ``validation_errors``
data survives the ErrorReport crossing (it must not degrade to a plain message).
- The sweep goes through ``validate_bundle``'s cascade, so the crossing report carries the
- SAME identity the direct-mode route's 422 carries — ``ValidateBundleError``,
- ``error_domain=input`` — with the offender and signature refs in the caller-facing
- message (the API problem document is built from exactly these ErrorReport fields).
+ Signatures are never an error (D-B), so the trigger is a real validation fault — an invalid
+ ``main_pipe`` code that fails blueprint validation. The sweep goes through ``validate_bundle``'s
+ cascade, so the crossing report carries the SAME identity the direct-mode route's body carries —
+ ``ValidateBundleError``, ``error_domain=input`` — with the per-error items in
+ ``validation_errors`` (the API ``InvalidReport`` is built from exactly these ErrorReport fields).
"""
with pytest.raises(WorkflowFailureError) as exc_info:
- await self._execute(temporal_client, DryValidateArg(mthds_contents=[_SIGNATURE_MTHDS], allow_signatures=False))
+ await self._execute(temporal_client, DryValidateArg(mthds_contents=[_INVALID_MTHDS]))
error_report = recover_error_report(exc_info.value)
assert error_report.error_type == "ValidateBundleError"
assert error_report.error_domain == "input"
- # The structured signature data — offender and signature refs — survives in the report.
- assert "dry_validate_sig.sig_caller" in error_report.message
- assert "dry_validate_sig.unimplemented_sig" in error_report.message
+ # The structured per-error data survives the crossing (not a bare message).
+ assert error_report.validation_errors is not None
+ assert any(item.category == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in error_report.validation_errors)
async def test_signatures_allowed_in_lenient_mode(self, temporal_client: TemporalClient) -> None:
"""The same signature bundle validates in lenient mode (allow_signatures=True), and the
@@ -292,7 +303,7 @@ class TestDryValidateActivityInMemory:
wraps=validate_bundle,
)
with pytest.raises(WorkflowFailureError):
- await self._execute(temporal_client, DryValidateArg(mthds_contents=[_SIGNATURE_MTHDS], allow_signatures=False))
+ await self._execute(temporal_client, DryValidateArg(mthds_contents=[_INVALID_MTHDS]))
assert sweep_spy.call_count == 1
async def test_pipe_io_contracts_failure_does_not_retry_activity(self, temporal_client: TemporalClient, mocker: MockerFixture) -> None:
diff --git a/tests/integration/pipelex/tools/misc/test_json_utils.py b/tests/integration/pipelex/tools/misc/test_json_utils.py
index 76d7005d5..81c31bbc6 100644
--- a/tests/integration/pipelex/tools/misc/test_json_utils.py
+++ b/tests/integration/pipelex/tools/misc/test_json_utils.py
@@ -8,35 +8,35 @@ class TestDeepUpdate:
"""Test updating simple key-value pairs."""
target = {"key_a": 1, "key_b": 2}
updates = {"key_b": 3}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": 1, "key_b": 3}
def test_add_new_key(self):
"""Test adding new keys to target dictionary."""
target = {"key_a": 1}
updates = {"key_b": 2, "key_c": 3}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": 1, "key_b": 2, "key_c": 3}
def test_nested_dict_update(self):
"""Test deep update of nested dictionaries."""
target = {"key_a": 1, "key_b": {"key_x": 2, "key_y": 3}}
updates = {"key_b": {"key_y": 4, "key_z": 5}}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": 1, "key_b": {"key_x": 2, "key_y": 4, "key_z": 5}}
def test_list_override(self):
"""Test that lists are overridden, not concatenated."""
target = {"key_a": [1, 2, 3]}
updates = {"key_a": [4, 5]}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": [4, 5]}
def test_list_override_in_nested_dict(self):
"""Test that lists in nested dictionaries are overridden."""
target = {"key_a": {"key_b": [1, 2, 3]}}
updates = {"key_a": {"key_b": [4, 5]}}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": {"key_b": [4, 5]}}
def test_deeply_nested_dict_update(self):
@@ -61,7 +61,7 @@ class TestDeepUpdate:
}
}
}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
expected = {
"level_1": {
"level_2": {
@@ -89,7 +89,7 @@ class TestDeepUpdate:
"nested": {"key_b": 2},
"array": [3, 4, 5],
}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
expected = {
"string": "new",
"number": 2,
@@ -102,63 +102,63 @@ class TestDeepUpdate:
"""Test that empty updates dictionary doesn't change target."""
target = {"key_a": 1, "key_b": 2}
updates: dict[str, Any] = {}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": 1, "key_b": 2}
def test_empty_target(self):
"""Test updating an empty target dictionary."""
target: dict[str, Any] = {}
updates = {"key_a": 1, "key_b": {"key_c": 2}}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": 1, "key_b": {"key_c": 2}}
def test_replace_dict_with_primitive(self):
"""Test replacing a dictionary value with a primitive."""
target = {"key_a": {"key_b": 1}}
updates = {"key_a": "string"}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": "string"}
def test_replace_primitive_with_dict(self):
"""Test replacing a primitive value with a dictionary."""
target = {"key_a": "string"}
updates = {"key_a": {"key_b": 1}}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": {"key_b": 1}}
def test_replace_list_with_primitive(self):
"""Test replacing a list with a primitive value."""
target = {"key_a": [1, 2, 3]}
updates = {"key_a": "string"}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": "string"}
def test_replace_primitive_with_list(self):
"""Test replacing a primitive value with a list."""
target = {"key_a": "string"}
updates = {"key_a": [1, 2, 3]}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": [1, 2, 3]}
def test_none_values(self):
"""Test handling of None values."""
target = {"key_a": 1, "key_b": None}
updates = {"key_a": None, "key_b": 2}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": None, "key_b": 2}
def test_empty_list_override(self):
"""Test that empty lists override non-empty lists."""
target = {"key_a": [1, 2, 3]}
updates: dict[str, Any] = {"key_a": []}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"key_a": []}
def test_empty_dict_merge(self):
"""Test merging with empty nested dictionaries."""
target = {"key_a": {"key_b": 1}}
updates: dict[str, Any] = {"key_a": {}}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
# Empty dict should merge but not change existing keys
assert target == {"key_a": {"key_b": 1}}
@@ -190,7 +190,7 @@ class TestDeepUpdate:
},
"version": "1.1.0",
}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
expected = {
"config": {
"database": {
@@ -212,21 +212,21 @@ class TestDeepUpdate:
"""Test handling of boolean values."""
target = {"flag_a": True, "flag_b": False}
updates = {"flag_a": False, "flag_b": True}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"flag_a": False, "flag_b": True}
def test_numeric_types(self):
"""Test handling of different numeric types."""
target = {"int_val": 1, "float_val": 1.5}
updates = {"int_val": 2.5, "float_val": 3}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"int_val": 2.5, "float_val": 3}
def test_list_of_dicts(self):
"""Test that lists of dictionaries are overridden, not merged."""
target = {"items": [{"id": 1, "name": "item1"}, {"id": 2, "name": "item2"}]}
updates = {"items": [{"id": 3, "name": "item3"}]}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
assert target == {"items": [{"id": 3, "name": "item3"}]}
def test_multiple_level_additions(self):
@@ -239,7 +239,7 @@ class TestDeepUpdate:
},
"new_top": "value",
}
- deep_update(target, updates)
+ deep_update(target, updates=updates)
expected = {
"level_1": {
"level_2": {"existing": "value", "new_key": "new_value"},
diff --git a/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py b/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
index 9ba7cd1c5..7c02390e1 100644
--- a/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
+++ b/tests/unit/pipelex/builder/operations/test_parse_pipe_spec.py
@@ -31,29 +31,29 @@ class TestParsePipeSpec:
def test_unknown_type_raises(self) -> None:
with pytest.raises(ValueError, match="Invalid pipe type"):
- parse_pipe_spec("PipeNonExistent", {"pipe_code": "x", "description": "x"})
+ parse_pipe_spec({"pipe_code": "x", "description": "x"}, pipe_type="PipeNonExistent")
def test_error_lists_valid_types(self) -> None:
with pytest.raises(ValueError, match="PipeLLM"):
- parse_pipe_spec("PipeBogus", {"pipe_code": "x", "description": "x"})
+ parse_pipe_spec({"pipe_code": "x", "description": "x"}, pipe_type="PipeBogus")
# -- pipe_code aliases ------------------------------------------------
def test_canonical_pipe_code(self) -> None:
- result = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
+ result = parse_pipe_spec({**_BASE_LLM}, pipe_type="PipeLLM")
assert result.pipe_code == "test_pipe"
@pytest.mark.parametrize("alias", ["the_pipe_code", "code", "name", "pipe_name", "pipe_ref"])
def test_pipe_code_alias_accepted(self, alias: str) -> None:
spec = {key: val for key, val in _BASE_LLM.items() if key != "pipe_code"}
spec[alias] = "via_alias"
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.pipe_code == "via_alias"
def test_canonical_pipe_code_takes_precedence_over_alias(self) -> None:
"""When pipe_code is present, aliases are ignored and cleaned up."""
spec = {**_BASE_LLM, "code": "alias_value", "name": "another_alias"}
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.pipe_code == "test_pipe"
def test_first_alias_wins_when_no_canonical(self) -> None:
@@ -62,32 +62,32 @@ class TestParsePipeSpec:
spec["code"] = "second"
spec["the_pipe_code"] = "first"
spec["name"] = "third"
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.pipe_code == "first"
# -- output dict tolerance --------------------------------------------
def test_output_as_string(self) -> None:
- result = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "output": "Article"})
+ result = parse_pipe_spec({**_BASE_LLM, "output": "Article"}, pipe_type="PipeLLM")
assert result.output == "Article"
def test_output_dict_with_type_key(self) -> None:
- result = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "output": {"type": "Article"}})
+ result = parse_pipe_spec({**_BASE_LLM, "output": {"type": "Article"}}, pipe_type="PipeLLM")
assert result.output == "Article"
def test_output_single_item_dict(self) -> None:
"""A single-item dict is unambiguous — extract the value."""
- result = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "output": {"result": "Article"}})
+ result = parse_pipe_spec({**_BASE_LLM, "output": {"result": "Article"}}, pipe_type="PipeLLM")
assert result.output == "Article"
def test_output_multi_item_dict_raises(self) -> None:
"""A multi-item dict is ambiguous — validation fails."""
with pytest.raises(ValidationError):
- parse_pipe_spec("PipeLLM", {**_BASE_LLM, "output": {"a": "Text", "b": "Image"}})
+ parse_pipe_spec({**_BASE_LLM, "output": {"a": "Text", "b": "Image"}}, pipe_type="PipeLLM")
def test_output_type_key_takes_precedence_in_dict(self) -> None:
"""When 'type' key is present in output dict, it wins even if other keys exist."""
- result = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "output": {"type": "Article", "extra": "ignored"}})
+ result = parse_pipe_spec({**_BASE_LLM, "output": {"type": "Article", "extra": "ignored"}}, pipe_type="PipeLLM")
assert result.output == "Article"
# -- output field aliases -----------------------------------------------
@@ -97,14 +97,14 @@ class TestParsePipeSpec:
"""Each output alias resolves to the correct output value."""
spec = {key: val for key, val in _BASE_LLM.items() if key != "output"}
spec[alias] = "Article"
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.output == "Article"
@pytest.mark.parametrize("alias", ["output_concept", "output_type"])
def test_output_alias_tried_first_when_canonical_present(self, alias: str) -> None:
"""When both output and an alias exist, alias value is tried first."""
spec = {**_BASE_LLM, alias: "AliasValue"}
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.output == "AliasValue"
def test_first_output_alias_wins(self) -> None:
@@ -112,7 +112,7 @@ class TestParsePipeSpec:
spec = {key: val for key, val in _BASE_LLM.items() if key != "output"}
spec["output_type"] = "SecondAlias"
spec["output_concept"] = "FirstAlias"
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.output == "FirstAlias"
# -- prompt aliases ---------------------------------------------------
@@ -121,14 +121,14 @@ class TestParsePipeSpec:
"""`prompt_template` alone is promoted to `prompt` for PipeLLM."""
spec = {key: val for key, val in _BASE_LLM.items() if key != "prompt"}
spec["prompt_template"] = "Write about $text"
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert isinstance(result, PipeLLMSpec)
assert result.prompt == "Write about $text"
def test_canonical_prompt_takes_precedence_over_alias(self) -> None:
"""When both `prompt` and `prompt_template` are present, canonical wins and alias is dropped."""
spec = {**_BASE_LLM, "prompt_template": "alias_value"}
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert isinstance(result, PipeLLMSpec)
assert result.prompt == _BASE_LLM["prompt"]
@@ -141,7 +141,7 @@ class TestParsePipeSpec:
"output": "Image",
"prompt_template": "Generate: $prompt_text",
}
- result = parse_pipe_spec("PipeImgGen", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeImgGen")
assert isinstance(result, PipeImgGenSpec)
assert result.prompt == "Generate: $prompt_text"
@@ -155,7 +155,7 @@ class TestParsePipeSpec:
"output": "Text",
"steps": [{"pipe_code": "step_one", "result": "intermediate"}],
}
- result = parse_pipe_spec("PipeSequence", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeSequence")
assert isinstance(result, PipeSequenceSpec)
assert result.steps[0].pipe_code == "step_one"
@@ -172,7 +172,7 @@ class TestParsePipeSpec:
{alias: "step_two", "result": "final"},
],
}
- result = parse_pipe_spec("PipeSequence", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeSequence")
assert isinstance(result, PipeSequenceSpec)
assert result.steps[0].pipe_code == "step_one"
assert result.steps[1].pipe_code == "step_two"
@@ -191,7 +191,7 @@ class TestParsePipeSpec:
{alias: "branch_b", "result": "result_b"},
],
}
- result = parse_pipe_spec("PipeParallel", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeParallel")
assert isinstance(result, PipeParallelSpec)
assert result.branches[0].pipe_code == "branch_a"
assert result.branches[1].pipe_code == "branch_b"
@@ -211,7 +211,7 @@ class TestParsePipeSpec:
{"pipe": "analyze_match", "result": "match_analysis"},
],
}
- result = parse_pipe_spec("PipeSequence", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeSequence")
assert isinstance(result, PipeSequenceSpec)
assert result.steps[0].pipe_code == "extract_cv"
assert result.steps[1].pipe_code == "extract_job_offer"
@@ -227,7 +227,7 @@ class TestParsePipeSpec:
{"pipe": "branch_a", "inputs": {"doc": "doc"}, "result": "result_a"},
],
}
- result = parse_pipe_spec("PipeParallel", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeParallel")
assert isinstance(result, PipeParallelSpec)
assert result.branches[0].pipe_code == "branch_a"
@@ -238,32 +238,32 @@ class TestParsePipeSpec:
"""A non-list ``steps`` is a caller-input fault, surfaced as a typed PipeSpecError."""
spec: dict[str, Any] = {"pipe_code": "my_seq", "description": "d", "output": "Text", "steps": bad_steps}
with pytest.raises(PipeSpecError, match="'steps' must be a list of step mappings"):
- parse_pipe_spec("PipeSequence", spec)
+ parse_pipe_spec(spec, pipe_type="PipeSequence")
@pytest.mark.parametrize("bad_entry", [42, "astring", [1, 2]])
def test_non_mapping_step_entry_raises_pipe_spec_error(self, bad_entry: Any) -> None:
"""A step entry that is not a mapping is a typed input error, not a bare TypeError."""
spec: dict[str, Any] = {"pipe_code": "my_seq", "description": "d", "output": "Text", "steps": [bad_entry]}
with pytest.raises(PipeSpecError, match="entry in pipe spec 'steps' must be a mapping"):
- parse_pipe_spec("PipeSequence", spec)
+ parse_pipe_spec(spec, pipe_type="PipeSequence")
@pytest.mark.parametrize("bad_branches", ["notalist", 42, {"a": "b"}])
def test_non_list_branches_raises_pipe_spec_error(self, bad_branches: Any) -> None:
spec: dict[str, Any] = {"pipe_code": "my_par", "description": "d", "output": "Text", "branches": bad_branches}
with pytest.raises(PipeSpecError, match="'branches' must be a list of step mappings"):
- parse_pipe_spec("PipeParallel", spec)
+ parse_pipe_spec(spec, pipe_type="PipeParallel")
@pytest.mark.parametrize("bad_entry", [42, "astring", [1, 2]])
def test_non_mapping_branch_entry_raises_pipe_spec_error(self, bad_entry: Any) -> None:
spec: dict[str, Any] = {"pipe_code": "my_par", "description": "d", "output": "Text", "branches": [bad_entry]}
with pytest.raises(PipeSpecError, match="entry in pipe spec 'branches' must be a mapping"):
- parse_pipe_spec("PipeParallel", spec)
+ parse_pipe_spec(spec, pipe_type="PipeParallel")
def test_malformed_steps_classifies_as_input_domain(self) -> None:
"""The raised error carries the INPUT domain so HTTP consumers render it as a 422."""
spec: dict[str, Any] = {"pipe_code": "my_seq", "description": "d", "output": "Text", "steps": "notalist"}
with pytest.raises(PipeSpecError) as exc_info:
- parse_pipe_spec("PipeSequence", spec)
+ parse_pipe_spec(spec, pipe_type="PipeSequence")
assert error_domain_is_input(exc_info.value.error_domain)
# -- malformed top-level shape (typed, not bare TypeError/ValueError) --
@@ -272,11 +272,11 @@ class TestParsePipeSpec:
def test_non_mapping_top_level_raises_pipe_spec_error(self, bad_spec: Any) -> None:
"""A non-mapping top-level spec leaks a bare TypeError/ValueError from dict() without the guard."""
with pytest.raises(PipeSpecError, match="must be a mapping"):
- parse_pipe_spec("PipeLLM", bad_spec)
+ parse_pipe_spec(bad_spec, pipe_type="PipeLLM")
def test_non_mapping_top_level_classifies_as_input_domain(self) -> None:
with pytest.raises(PipeSpecError) as exc_info:
- parse_pipe_spec("PipeLLM", "not a mapping")
+ parse_pipe_spec("not a mapping", pipe_type="PipeLLM")
assert error_domain_is_input(exc_info.value.error_domain)
# -- PipeCondition expression alias -----------------------------------
@@ -292,19 +292,19 @@ class TestParsePipeSpec:
def test_condition_expression_alias(self) -> None:
spec = {**self._BASE_CONDITION, "expression": "{{ status }}"}
- result = parse_pipe_spec("PipeCondition", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeCondition")
assert isinstance(result, PipeConditionSpec)
assert result.jinja2_expression_template == "{{ status }}"
def test_condition_canonical_jinja2_field(self) -> None:
spec = {**self._BASE_CONDITION, "jinja2_expression_template": "{{ status }}"}
- result = parse_pipe_spec("PipeCondition", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeCondition")
assert isinstance(result, PipeConditionSpec)
assert result.jinja2_expression_template == "{{ status }}"
def test_condition_canonical_takes_precedence(self) -> None:
spec = {**self._BASE_CONDITION, "jinja2_expression_template": "{{ canonical }}", "expression": "{{ alias }}"}
- result = parse_pipe_spec("PipeCondition", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeCondition")
assert isinstance(result, PipeConditionSpec)
assert result.jinja2_expression_template == "{{ canonical }}"
@@ -320,7 +320,7 @@ class TestParsePipeSpec:
"prompt": "Write about $text",
}
snapshot = dict(original)
- parse_pipe_spec("PipeLLM", original)
+ parse_pipe_spec(original, pipe_type="PipeLLM")
assert original == snapshot
def test_nested_step_dicts_not_mutated(self) -> None:
@@ -333,7 +333,7 @@ class TestParsePipeSpec:
"steps": [step],
}
step_snapshot = dict(step)
- parse_pipe_spec("PipeSequence", spec)
+ parse_pipe_spec(spec, pipe_type="PipeSequence")
assert step == step_snapshot
# -- returns correct subclass -----------------------------------------
@@ -394,5 +394,5 @@ class TestParsePipeSpec:
],
)
def test_correct_subclass(self, pipe_type: str, spec_data: dict[str, Any], expected_class: type) -> None:
- result = parse_pipe_spec(pipe_type, spec_data)
+ result = parse_pipe_spec(spec_data, pipe_type=pipe_type)
assert isinstance(result, expected_class)
diff --git a/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py b/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py
index b829eee65..a65b0697a 100644
--- a/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py
+++ b/tests/unit/pipelex/builder/operations/test_pipe_spec_to_toml.py
@@ -14,7 +14,7 @@ class TestPipeSpecToToml:
# -- PipeLLM ----------------------------------------------------------
def test_llm_basic_structure(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
+ spec = parse_pipe_spec({**_BASE_LLM}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert "[pipe.test_pipe]" in toml
assert 'type = "PipeLLM"' in toml
@@ -22,29 +22,29 @@ class TestPipeSpecToToml:
assert 'output = "Text"' in toml
def test_llm_inputs_as_inline_table(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
+ spec = parse_pipe_spec({**_BASE_LLM}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert 'inputs = {text = "Text"}' in toml
def test_llm_model_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
+ spec = parse_pipe_spec({**_BASE_LLM}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert 'model = "$writing-creative"' in toml
def test_llm_no_model_omits_field(self) -> None:
data = {key: val for key, val in _BASE_LLM.items() if key != "model"}
- spec = parse_pipe_spec("PipeLLM", data)
+ spec = parse_pipe_spec(data, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert "model" not in toml
def test_llm_system_prompt_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "system_prompt": "You are a helpful writer."})
+ spec = parse_pipe_spec({**_BASE_LLM, "system_prompt": "You are a helpful writer."}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert "system_prompt" in toml
assert "You are a helpful writer." in toml
def test_llm_prompt_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
+ spec = parse_pipe_spec({**_BASE_LLM}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert "prompt" in toml
assert "Write about $text" in toml
@@ -52,29 +52,29 @@ class TestPipeSpecToToml:
def test_llm_no_inputs_omits_inputs(self) -> None:
empty_inputs: dict[str, str] = {}
data = {**_BASE_LLM, "inputs": empty_inputs}
- spec = parse_pipe_spec("PipeLLM", data)
+ spec = parse_pipe_spec(data, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert "inputs" not in toml
def test_llm_multiple_inputs(self) -> None:
data = {**_BASE_LLM, "inputs": {"text": "Text", "context": "Document"}}
- spec = parse_pipe_spec("PipeLLM", data)
+ spec = parse_pipe_spec(data, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert 'text = "Text"' in toml
assert 'context = "Document"' in toml
def test_llm_structuring_method_preliminary_text_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "structuring_method": "preliminary_text"})
+ spec = parse_pipe_spec({**_BASE_LLM, "structuring_method": "preliminary_text"}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert 'structuring_method = "preliminary_text"' in toml
def test_llm_structuring_method_direct_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM, "structuring_method": "direct"})
+ spec = parse_pipe_spec({**_BASE_LLM, "structuring_method": "direct"}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert 'structuring_method = "direct"' in toml
def test_llm_no_structuring_method_omits_field(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**_BASE_LLM})
+ spec = parse_pipe_spec({**_BASE_LLM}, pipe_type="PipeLLM")
toml = pipe_spec_to_toml(spec)
assert "structuring_method" not in toml
@@ -82,13 +82,13 @@ class TestPipeSpecToToml:
def test_structure_basic_structure(self) -> None:
spec = parse_pipe_spec(
- "PipeStructure",
{
"pipe_code": "structure_review",
"description": "Structure a review",
"inputs": {"draft_text": "Text"},
"output": "RestaurantReview",
},
+ pipe_type="PipeStructure",
)
toml = pipe_spec_to_toml(spec)
assert "[pipe.structure_review]" in toml
@@ -98,7 +98,6 @@ class TestPipeSpecToToml:
def test_structure_model_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeStructure",
{
"pipe_code": "structure_review",
"description": "Structure a review",
@@ -106,19 +105,20 @@ class TestPipeSpecToToml:
"output": "RestaurantReview",
"model": "$structuring-fast",
},
+ pipe_type="PipeStructure",
)
toml = pipe_spec_to_toml(spec)
assert 'model = "$structuring-fast"' in toml
def test_structure_no_model_omits_field(self) -> None:
spec = parse_pipe_spec(
- "PipeStructure",
{
"pipe_code": "structure_review",
"description": "Structure a review",
"inputs": {"draft_text": "Text"},
"output": "RestaurantReview",
},
+ pipe_type="PipeStructure",
)
toml = pipe_spec_to_toml(spec)
assert "model" not in toml
@@ -128,8 +128,14 @@ class TestPipeSpecToToml:
def test_func_function_name_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeFunc",
- {"pipe_code": "my_func", "description": "Run a function", "inputs": {"data": "Text"}, "output": "Text", "function_name": "process_data"},
+ {
+ "pipe_code": "my_func",
+ "description": "Run a function",
+ "inputs": {"data": "Text"},
+ "output": "Text",
+ "function_name": "process_data",
+ },
+ pipe_type="PipeFunc",
)
toml = pipe_spec_to_toml(spec)
assert 'function_name = "process_data"' in toml
@@ -139,7 +145,6 @@ class TestPipeSpecToToml:
def test_img_gen_model_and_prompt_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeImgGen",
{
"pipe_code": "gen_image",
"description": "Generate image",
@@ -148,6 +153,7 @@ class TestPipeSpecToToml:
"model": "$gen-image",
"prompt": "Generate: $prompt_text",
},
+ pipe_type="PipeImgGen",
)
toml = pipe_spec_to_toml(spec)
assert 'model = "$gen-image"' in toml
@@ -155,7 +161,6 @@ class TestPipeSpecToToml:
def test_img_gen_no_model_omits_field(self) -> None:
spec = parse_pipe_spec(
- "PipeImgGen",
{
"pipe_code": "gen_image",
"description": "Generate image",
@@ -163,6 +168,7 @@ class TestPipeSpecToToml:
"output": "Image",
"prompt": "Generate: $prompt_text",
},
+ pipe_type="PipeImgGen",
)
toml = pipe_spec_to_toml(spec)
assert "model" not in toml
@@ -171,7 +177,6 @@ class TestPipeSpecToToml:
def test_extract_model_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeExtract",
{
"pipe_code": "my_extract",
"description": "Extract text",
@@ -179,13 +184,13 @@ class TestPipeSpecToToml:
"output": "Page[]",
"model": "@default-extract-document",
},
+ pipe_type="PipeExtract",
)
toml = pipe_spec_to_toml(spec)
assert 'model = "@default-extract-document"' in toml
def test_extract_max_page_images_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeExtract",
{
"pipe_code": "my_extract",
"description": "Extract text",
@@ -193,13 +198,13 @@ class TestPipeSpecToToml:
"output": "Page[]",
"max_page_images": 5,
},
+ pipe_type="PipeExtract",
)
toml = pipe_spec_to_toml(spec)
assert "max_page_images = 5" in toml
def test_extract_page_views_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeExtract",
{
"pipe_code": "my_extract",
"description": "Extract text",
@@ -207,14 +212,14 @@ class TestPipeSpecToToml:
"output": "Page[]",
"page_views": True,
},
+ pipe_type="PipeExtract",
)
toml = pipe_spec_to_toml(spec)
assert "page_views = true" in toml
def test_extract_no_optional_fields_omits_them(self) -> None:
spec = parse_pipe_spec(
- "PipeExtract",
- {"pipe_code": "my_extract", "description": "Extract text", "inputs": {"doc": "Document"}, "output": "Page[]"},
+ {"pipe_code": "my_extract", "description": "Extract text", "inputs": {"doc": "Document"}, "output": "Page[]"}, pipe_type="PipeExtract"
)
toml = pipe_spec_to_toml(spec)
assert "model" not in toml
@@ -225,7 +230,6 @@ class TestPipeSpecToToml:
def test_search_all_fields_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeSearch",
{
"pipe_code": "web_search",
"description": "Search the web",
@@ -239,6 +243,7 @@ class TestPipeSpecToToml:
"exclude_domains": ["spam.com"],
"max_results": 10,
},
+ pipe_type="PipeSearch",
)
toml = pipe_spec_to_toml(spec)
assert 'model = "$search-model"' in toml
@@ -251,8 +256,14 @@ class TestPipeSpecToToml:
def test_search_minimal(self) -> None:
spec = parse_pipe_spec(
- "PipeSearch",
- {"pipe_code": "web_search", "description": "Search", "inputs": {"query_text": "Text"}, "output": "Text", "prompt": "Find $query_text"},
+ {
+ "pipe_code": "web_search",
+ "description": "Search",
+ "inputs": {"query_text": "Text"},
+ "output": "Text",
+ "prompt": "Find $query_text",
+ },
+ pipe_type="PipeSearch",
)
toml = pipe_spec_to_toml(spec)
assert "Find $query_text" in toml
@@ -267,7 +278,6 @@ class TestPipeSpecToToml:
def test_sequence_steps_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeSequence",
{
"pipe_code": "my_seq",
"description": "A sequence",
@@ -278,6 +288,7 @@ class TestPipeSpecToToml:
{"pipe_code": "step_two", "result": "final"},
],
},
+ pipe_type="PipeSequence",
)
toml = pipe_spec_to_toml(spec)
assert 'type = "PipeSequence"' in toml
@@ -288,7 +299,6 @@ class TestPipeSpecToToml:
def test_sequence_step_with_batch_over(self) -> None:
spec = parse_pipe_spec(
- "PipeSequence",
{
"pipe_code": "my_seq",
"description": "A sequence with batch",
@@ -298,6 +308,7 @@ class TestPipeSpecToToml:
{"pipe_code": "process", "result": "processed", "batch_over": "items", "batch_as": "item"},
],
},
+ pipe_type="PipeSequence",
)
toml = pipe_spec_to_toml(spec)
assert "batch_over" in toml
@@ -308,7 +319,6 @@ class TestPipeSpecToToml:
def test_parallel_branches_and_add_each_output(self) -> None:
spec = parse_pipe_spec(
- "PipeParallel",
{
"pipe_code": "my_par",
"description": "Parallel branches",
@@ -320,6 +330,7 @@ class TestPipeSpecToToml:
{"pipe_code": "branch_b", "result": "result_b"},
],
},
+ pipe_type="PipeParallel",
)
toml = pipe_spec_to_toml(spec)
assert 'type = "PipeParallel"' in toml
@@ -329,7 +340,6 @@ class TestPipeSpecToToml:
def test_parallel_combined_output_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeParallel",
{
"pipe_code": "my_par",
"description": "Parallel with combined output",
@@ -341,6 +351,7 @@ class TestPipeSpecToToml:
{"pipe_code": "branch_a", "result": "result_a"},
],
},
+ pipe_type="PipeParallel",
)
toml = pipe_spec_to_toml(spec)
assert 'combined_output = "MergedResult"' in toml
@@ -349,7 +360,6 @@ class TestPipeSpecToToml:
def test_condition_expression_outcomes_default(self) -> None:
spec = parse_pipe_spec(
- "PipeCondition",
{
"pipe_code": "my_cond",
"description": "Route by status",
@@ -359,6 +369,7 @@ class TestPipeSpecToToml:
"outcomes": {"high": "handle_high", "low": "handle_low"},
"default_outcome": "handle_default",
},
+ pipe_type="PipeCondition",
)
toml = pipe_spec_to_toml(spec)
assert 'type = "PipeCondition"' in toml
@@ -371,7 +382,6 @@ class TestPipeSpecToToml:
def test_batch_fields_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeBatch",
{
"pipe_code": "my_batch",
"description": "Batch process",
@@ -381,6 +391,7 @@ class TestPipeSpecToToml:
"input_list_name": "items",
"input_item_name": "item",
},
+ pipe_type="PipeBatch",
)
toml = pipe_spec_to_toml(spec)
assert 'type = "PipeBatch"' in toml
@@ -392,7 +403,6 @@ class TestPipeSpecToToml:
def test_compose_template_mode_fields(self) -> None:
spec = parse_pipe_spec(
- "PipeCompose",
{
"pipe_code": "render_greeting",
"description": "Render a greeting",
@@ -401,6 +411,7 @@ class TestPipeSpecToToml:
"target_format": "markdown",
"template": "Hello $name!",
},
+ pipe_type="PipeCompose",
)
toml = pipe_spec_to_toml(spec)
assert 'type = "PipeCompose"' in toml
@@ -409,7 +420,6 @@ class TestPipeSpecToToml:
def test_compose_no_construct_in_template_mode(self) -> None:
spec = parse_pipe_spec(
- "PipeCompose",
{
"pipe_code": "render_greeting",
"description": "Render a greeting",
@@ -418,6 +428,7 @@ class TestPipeSpecToToml:
"target_format": "markdown",
"template": "Hello $name!",
},
+ pipe_type="PipeCompose",
)
toml = pipe_spec_to_toml(spec)
assert "construct" not in toml
@@ -426,7 +437,6 @@ class TestPipeSpecToToml:
def test_compose_construct_with_from_mappings(self) -> None:
spec = parse_pipe_spec(
- "PipeCompose",
{
"pipe_code": "compose_sheet",
"description": "Compose interview sheet",
@@ -437,6 +447,7 @@ class TestPipeSpecToToml:
"questions": {"from": "questions"},
},
},
+ pipe_type="PipeCompose",
)
toml = pipe_spec_to_toml(spec)
assert "[pipe.compose_sheet.construct]" in toml
@@ -444,7 +455,6 @@ class TestPipeSpecToToml:
def test_compose_construct_with_static_values(self) -> None:
spec = parse_pipe_spec(
- "PipeCompose",
{
"pipe_code": "compose_report",
"description": "Compose a report",
@@ -456,6 +466,7 @@ class TestPipeSpecToToml:
"page_count": 42,
},
},
+ pipe_type="PipeCompose",
)
toml = pipe_spec_to_toml(spec)
assert 'version = "1.0"' in toml
@@ -463,7 +474,6 @@ class TestPipeSpecToToml:
def test_compose_no_template_in_construct_mode(self) -> None:
spec = parse_pipe_spec(
- "PipeCompose",
{
"pipe_code": "compose_report",
"description": "Compose a report",
@@ -471,6 +481,7 @@ class TestPipeSpecToToml:
"output": "Report",
"construct": {"title": {"from": "title"}},
},
+ pipe_type="PipeCompose",
)
toml = pipe_spec_to_toml(spec)
assert "target_format" not in toml
diff --git a/tests/unit/pipelex/builder/test_runner_generator.py b/tests/unit/pipelex/builder/test_runner_generator.py
index 7c0a936c3..9f1202df8 100644
--- a/tests/unit/pipelex/builder/test_runner_generator.py
+++ b/tests/unit/pipelex/builder/test_runner_generator.py
@@ -22,7 +22,7 @@ class TestConceptGenerateInputRepresentationJson:
def test_native_text_json(self) -> None:
"""Test JSON representation for native Text concept."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.TEXT)
- result, _ = concept.render_concept_representation(ConceptRepresentationFormat.JSON)
+ result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON)
assert result["concept"] == "native.Text"
assert "content" in result
assert "text" in result["content"]
@@ -30,7 +30,7 @@ class TestConceptGenerateInputRepresentationJson:
def test_native_image_json(self) -> None:
"""Test JSON representation for native Image concept."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.IMAGE)
- result, _ = concept.render_concept_representation(ConceptRepresentationFormat.JSON)
+ result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON)
assert result["concept"] == "native.Image"
assert "content" in result
assert "url" in result["content"]
@@ -38,7 +38,7 @@ class TestConceptGenerateInputRepresentationJson:
def test_native_number_json(self) -> None:
"""Test JSON representation for native Number concept."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.NUMBER)
- result, _ = concept.render_concept_representation(ConceptRepresentationFormat.JSON)
+ result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON)
assert result["concept"] == "native.Number"
assert "content" in result
assert "number" in result["content"]
@@ -46,7 +46,7 @@ class TestConceptGenerateInputRepresentationJson:
def test_native_document_json_with_multiplicity(self) -> None:
"""Test JSON representation for Document with multiplicity - content should be a list."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.DOCUMENT)
- result, _ = concept.render_concept_representation(ConceptRepresentationFormat.JSON, is_multiple=True)
+ result, _ = concept.render_concept_representation(output_format=ConceptRepresentationFormat.JSON, is_multiple=True)
assert result["concept"] == "native.Document"
assert "content" in result
# Content should be a list
@@ -62,7 +62,7 @@ class TestConceptGenerateInputRepresentationPython:
def test_native_text_python(self) -> None:
"""Test Python representation for native Text concept."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.TEXT)
- result, imports = concept.render_concept_representation(ConceptRepresentationFormat.PYTHON)
+ result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON)
assert result["concept"] == "native.Text"
assert "TextContent" in result["content"]
assert "TextContent" in imports
@@ -70,7 +70,7 @@ class TestConceptGenerateInputRepresentationPython:
def test_native_image_python(self) -> None:
"""Test Python representation for native Image concept."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.IMAGE)
- result, imports = concept.render_concept_representation(ConceptRepresentationFormat.PYTHON)
+ result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON)
assert result["concept"] == "native.Image"
assert "ImageContent" in result["content"]
assert "ImageContent" in imports
@@ -84,7 +84,7 @@ class TestConceptGenerateInputRepresentationPython:
structure_class_name="TextContent",
refines="native.Text",
)
- result, imports = concept.render_concept_representation(ConceptRepresentationFormat.PYTHON)
+ result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON)
assert result["concept"] == "test_domain.Question"
assert "TextContent" in result["content"]
assert "TextContent" in imports
@@ -92,7 +92,7 @@ class TestConceptGenerateInputRepresentationPython:
def test_native_document_python_with_multiplicity(self) -> None:
"""Test Python representation for Document with multiplicity - for Python format, wrapping is handled by caller."""
concept = ConceptFactory.make_native_concept(NativeConceptCode.DOCUMENT)
- result, imports = concept.render_concept_representation(ConceptRepresentationFormat.PYTHON, is_multiple=True)
+ result, imports = concept.render_concept_representation(output_format=ConceptRepresentationFormat.PYTHON, is_multiple=True)
# For Python format, is_multiple doesn't wrap content (caller handles it)
assert result["concept"] == "native.Document"
assert "DocumentContent" in result["content"]
diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py
index 2afe24c18..358fdc166 100644
--- a/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py
+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py
@@ -29,7 +29,7 @@ class TestPlxtPassthrough:
mocker.patch("shutil.which", return_value=None)
with pytest.raises(typer.Exit) as exc_info:
- run_plxt("fmt", "file.mthds")
+ run_plxt("fmt", file_path="file.mthds")
assert exc_info.value.exit_code == 1
parsed = json.loads(capsys.readouterr().err)
@@ -44,7 +44,7 @@ class TestPlxtPassthrough:
mocker.patch("shutil.which", return_value=None)
with pytest.raises(typer.Exit):
- run_plxt("lint", "file.mthds")
+ run_plxt("lint", file_path="file.mthds")
parsed = json.loads(capsys.readouterr().err)
assert "uv tool install pipelex-tools" in parsed["message"]
@@ -71,7 +71,7 @@ class TestPlxtPassthrough:
)
with pytest.raises(typer.Exit) as exc_info:
- run_plxt("fmt", "file.mthds")
+ run_plxt("fmt", file_path="file.mthds")
assert exc_info.value.exit_code == exit_code
@@ -87,7 +87,7 @@ class TestPlxtPassthrough:
)
with pytest.raises(typer.Exit):
- run_plxt("fmt", "/path/to/file.mthds")
+ run_plxt("fmt", file_path="/path/to/file.mthds")
mock_run.assert_called_once_with(
["/usr/bin/plxt", "fmt", "/path/to/file.mthds"],
@@ -105,7 +105,7 @@ class TestPlxtPassthrough:
fmt_cmd("some/file.mthds")
- mock_run_plxt.assert_called_once_with("fmt", "some/file.mthds")
+ mock_run_plxt.assert_called_once_with("fmt", file_path="some/file.mthds")
def test_lint_cmd_delegates_to_plxt_with_lint_subcommand(
self,
@@ -118,4 +118,4 @@ class TestPlxtPassthrough:
lint_cmd("some/file.mthds")
- mock_run_plxt.assert_called_once_with("lint", "some/file.mthds")
+ mock_run_plxt.assert_called_once_with("lint", file_path="some/file.mthds")
diff --git a/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
index 69b57d035..7989f51d6 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
@@ -21,7 +21,7 @@ class TestAgentErrorFormat:
def test_agent_error_defaults_to_json(self, capsys: pytest.CaptureFixture[str]) -> None:
"""With no format opted in, agent_error keeps emitting JSON to stderr."""
with pytest.raises(typer.Exit):
- agent_error("something went wrong", "FooError")
+ agent_error("something went wrong", error_type="FooError")
parsed = json.loads(capsys.readouterr().err)
assert parsed["error"] is True
assert parsed["error_type"] == "FooError"
@@ -30,7 +30,7 @@ class TestAgentErrorFormat:
"""When markdown is the active error format, agent_error renders markdown to stderr."""
set_agent_cli_error_format(CliOutputFormat.MARKDOWN)
with pytest.raises(typer.Exit) as exc_info:
- agent_error("something went wrong", "FooError")
+ agent_error("something went wrong", error_type="FooError")
assert exc_info.value.exit_code == 1
captured = capsys.readouterr()
@@ -51,7 +51,7 @@ class TestAgentErrorFormat:
with pytest.raises(typer.Exit):
agent_error_markdown(
"model issue",
- "PipeOperatorModelChoiceError",
+ error_type="PipeOperatorModelChoiceError",
cause=cause,
pipe_code="my_pipe",
)
diff --git a/tests/unit/pipelex/cli/commands/build/test_structures_cmd.py b/tests/unit/pipelex/cli/commands/build/test_structures_cmd.py
index 479483443..5862ba6b4 100644
--- a/tests/unit/pipelex/cli/commands/build/test_structures_cmd.py
+++ b/tests/unit/pipelex/cli/commands/build/test_structures_cmd.py
@@ -67,7 +67,7 @@ class TestStructuresCmd:
),
]
- mapping = _build_concept_ref_to_class_info(blueprints, output_directory)
+ mapping = _build_concept_ref_to_class_info(blueprints, output_directory=output_directory)
assert set(mapping.keys()) == {"billing.Invoice", "billing.CustomName"}
assert mapping["billing.Invoice"].class_name == "billing__Invoice"
@@ -90,7 +90,7 @@ class TestStructuresCmd:
),
]
- mapping = _build_concept_ref_to_class_info(blueprints, outside_dir)
+ mapping = _build_concept_ref_to_class_info(blueprints, output_directory=outside_dir)
assert mapping["billing.Invoice"].module_path is None
@@ -100,7 +100,7 @@ class TestStructuresCmd:
PipelexBundleBlueprint(domain="notes", description="notes", concept={"QuickNote": "A short note"}),
]
- generated = generate_structures_from_blueprints(blueprints, tmp_path, skip_existing_check=True, quiet=True)
+ generated = generate_structures_from_blueprints(blueprints, output_directory=tmp_path, skip_existing_check=True, quiet=True)
assert generated == [("notes", "QuickNote")]
generated_code = (tmp_path / "notes__quick_note.py").read_text(encoding="utf-8")
@@ -122,7 +122,7 @@ class TestStructuresCmd:
),
]
- generated = generate_structures_from_blueprints(blueprints, tmp_path, skip_existing_check=True, quiet=True)
+ generated = generate_structures_from_blueprints(blueprints, output_directory=tmp_path, skip_existing_check=True, quiet=True)
assert generated == [("billing", "Invoice")]
generated_code = (tmp_path / "billing__invoice.py").read_text(encoding="utf-8")
@@ -140,7 +140,7 @@ class TestStructuresCmd:
),
]
- generated = generate_structures_from_blueprints(blueprints, tmp_path, skip_existing_check=True, quiet=True)
+ generated = generate_structures_from_blueprints(blueprints, output_directory=tmp_path, skip_existing_check=True, quiet=True)
assert generated == [("notes", "FancyText")]
generated_code = (tmp_path / "notes__fancy_text.py").read_text(encoding="utf-8")
@@ -156,7 +156,7 @@ class TestStructuresCmd:
),
]
- generated = generate_structures_from_blueprints(blueprints, tmp_path, skip_existing_check=True, quiet=True)
+ generated = generate_structures_from_blueprints(blueprints, output_directory=tmp_path, skip_existing_check=True, quiet=True)
assert generated == [("notes", "PlainThing")]
generated_code = (tmp_path / "notes__plain_thing.py").read_text(encoding="utf-8")
@@ -168,7 +168,7 @@ class TestStructuresCmd:
PipelexBundleBlueprint(domain="native", description="native stub", concept={"NativeStub": "native stub concept"}),
]
- generated = generate_structures_from_blueprints(blueprints, tmp_path, skip_existing_check=True, quiet=True)
+ generated = generate_structures_from_blueprints(blueprints, output_directory=tmp_path, skip_existing_check=True, quiet=True)
assert generated == []
assert not (tmp_path / "__init__.py").exists()
@@ -189,7 +189,7 @@ class TestStructuresCmd:
generated = generate_structures_from_blueprints(
blueprints,
- tmp_path,
+ output_directory=tmp_path,
target_path=tmp_path,
skip_existing_check=False,
quiet=True,
@@ -209,7 +209,7 @@ class TestStructuresCmd:
PipelexBundleBlueprint(domain="notes", description="notes", concept={"LoudNote": "A loud note"}),
]
- generate_structures_from_blueprints(blueprints, tmp_path, skip_existing_check=True, quiet=False)
+ generate_structures_from_blueprints(blueprints, output_directory=tmp_path, skip_existing_check=True, quiet=False)
echo_mock.assert_called_once()
secho_calls = [str(call.args[0]) for call in secho_mock.call_args_list]
diff --git a/tests/unit/pipelex/cli/commands/login/test_login_command.py b/tests/unit/pipelex/cli/commands/login/test_login_command.py
index a41d86d57..dd3c345b7 100644
--- a/tests/unit/pipelex/cli/commands/login/test_login_command.py
+++ b/tests/unit/pipelex/cli/commands/login/test_login_command.py
@@ -101,7 +101,7 @@ class TestLoginCommand:
def test_save_api_key_preserves_existing_entries(self, tmp_path: Path, mocker: MockerFixture) -> None:
"""save_api_key preserves existing .env entries when adding the API key."""
env_path = tmp_path / ".env"
- write_env_file(env_path, {"EXISTING_KEY": "existing_value"})
+ write_env_file(env_path, entries={"EXISTING_KEY": "existing_value"})
mocker.patch(
"pipelex.cli.commands.login.command.get_global_env_path",
@@ -116,7 +116,7 @@ class TestLoginCommand:
def test_save_api_key_updates_existing_key(self, tmp_path: Path, mocker: MockerFixture) -> None:
"""save_api_key overwrites an existing PIPELEX_GATEWAY_API_KEY."""
env_path = tmp_path / ".env"
- write_env_file(env_path, {PIPELEX_GATEWAY_API_KEY_VAR: "old_key"})
+ write_env_file(env_path, entries={PIPELEX_GATEWAY_API_KEY_VAR: "old_key"})
mocker.patch(
"pipelex.cli.commands.login.command.get_global_env_path",
diff --git a/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py
new file mode 100644
index 000000000..4eb05e6c9
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd.py
@@ -0,0 +1,362 @@
+"""Unit tests for the `pipelex-dev check-keyword-only` AST guard."""
+
+from __future__ import annotations
+
+import textwrap
+
+from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ Violation,
+ find_violations_in_source,
+)
+
+
+def _violate(source: str, *, module_qname: str = "pipelex.sample.module", relative_path: str = "pipelex/sample/module.py") -> list[Violation]:
+ """Run the guard over an inline snippet and return its violations."""
+ return find_violations_in_source(textwrap.dedent(source), module_qname=module_qname, relative_path=relative_path)
+
+
+def _keys(violations: list[Violation]) -> set[str]:
+ return {violation.key for violation in violations}
+
+
+class TestCheckKeywordOnly:
+ def test_compliant_with_bare_star(self) -> None:
+ """A subject followed by keyword-only options is compliant."""
+ violations = _violate(
+ """
+ def build_pipe(spec, *, dry_run, retries, validate):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_violation_two_positional_non_subject(self) -> None:
+ """Subject plus a second positional-or-keyword param is a violation."""
+ violations = _violate(
+ """
+ def build_pipe(spec, dry_run, retries, validate):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::build_pipe"}
+
+ def test_violation_single_extra_positional(self) -> None:
+ """Subject plus exactly one more bare positional param is already a violation."""
+ violations = _violate(
+ """
+ def copy_file(source_path, target_path):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::copy_file"}
+
+ def test_exception_1_subject_only_positional_compliant(self) -> None:
+ """A lone subject (single positional-or-keyword param) is compliant — Exception 1."""
+ violations = _violate(
+ """
+ def render(node):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_exception_1_subject_plus_one_keyword_only_compliant(self) -> None:
+ """Subject plus a single keyword-only option is compliant — Exception 1."""
+ violations = _violate(
+ """
+ def truncate(text, *, max_length=80):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_method_self_dropped_then_subject_only_compliant(self) -> None:
+ """`self` is dropped, leaving a lone subject — compliant."""
+ violations = _violate(
+ """
+ class Foo:
+ def render(self, node):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_method_self_dropped_then_violation(self) -> None:
+ """`self` dropped, subject + one more positional => violation, qualified by class name."""
+ violations = _violate(
+ """
+ class FooBuilder:
+ def build(self, spec, options):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::FooBuilder.build"}
+
+ def test_classmethod_cls_dropped(self) -> None:
+ """`cls` is dropped like `self`."""
+ violations = _violate(
+ """
+ class Bar:
+ @classmethod
+ def make(cls, source, target):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::Bar.make"}
+
+ def test_args_kwargs_do_not_count(self) -> None:
+ """A lone subject followed only by *args/**kwargs is compliant."""
+ violations = _violate(
+ """
+ def dispatch(subject, *args, **kwargs):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_exception_2_allowlisted_symmetric_tuple_skipped(self) -> None:
+ """An allowlisted symmetric tuple is exempt entirely."""
+ violations = _violate(
+ """
+ def set_env(key, value):
+ ...
+ """,
+ module_qname="pipelex.system.environment",
+ relative_path="pipelex/system/environment.py",
+ )
+ assert violations == []
+
+ def test_allowlist_requires_both_name_and_path(self) -> None:
+ """Same qualified name in the wrong file is NOT exempt by the allowlist."""
+ violations = _violate(
+ """
+ def set_env(key, value):
+ ...
+ """,
+ module_qname="pipelex.elsewhere",
+ relative_path="pipelex/elsewhere.py",
+ )
+ assert _keys(violations) == {"pipelex/elsewhere.py::set_env"}
+
+ def test_carveout_dunder_skipped(self) -> None:
+ """A dunder method is skipped regardless of its parameter shape."""
+ violations = _violate(
+ """
+ class Box:
+ def __setitem__(self, key, value):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_half_dunder_not_carved_out(self) -> None:
+ """A name-mangled half-dunder (no trailing __) is NOT carved out."""
+ violations = _violate(
+ """
+ class Box:
+ def __store(self, key, value):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::Box.__store"}
+
+ def test_degenerate_underscores_not_dunder(self) -> None:
+ """`____` must not match the dunder carve-out."""
+ violations = _violate(
+ """
+ def ____(subject, other):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::____"}
+
+ def test_carveout_pydantic_field_validator_skipped(self) -> None:
+ """A pydantic @field_validator is skipped."""
+ violations = _violate(
+ """
+ class Model:
+ @field_validator("name", mode="before")
+ def normalize(cls, value, info):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_pydantic_model_validator_bare_skipped(self) -> None:
+ """A bare (non-call) @model_validator is skipped."""
+ violations = _violate(
+ """
+ class Model:
+ @model_validator
+ def check(self, value, info):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_typer_command_decorator_skipped(self) -> None:
+ """A @app.command() Typer entrypoint is skipped (attr suffix match, any receiver)."""
+ violations = _violate(
+ """
+ @graph_app.command(name="show")
+ def show(path, fmt, output):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_temporal_activity_defn_in_stack_skipped(self) -> None:
+ """@activity.defn anywhere in the decorator stack is skipped (scan whole stack)."""
+ violations = _violate(
+ """
+ @activity.defn
+ @convert_pipelex_errors
+ def act_render(job, context, options):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_workflow_run_skipped(self) -> None:
+ """@workflow.run is skipped."""
+ violations = _violate(
+ """
+ class MyWorkflow:
+ @workflow.run
+ async def run(self, request, options):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_pytest_fixture_skipped(self) -> None:
+ """@pytest.fixture is skipped."""
+ violations = _violate(
+ """
+ @pytest.fixture(scope="session")
+ def my_fixture(request, config, tmp_path):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_bare_fixture_skipped(self) -> None:
+ """A bare @fixture (from pytest import fixture) is skipped like @pytest.fixture."""
+ violations = _violate(
+ """
+ @fixture(scope="session")
+ def my_fixture(request, config, tmp_path):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_jinja2_pass_context_skipped(self) -> None:
+ """@pass_context filters are invoked positionally by the Jinja2 engine — skipped."""
+ violations = _violate(
+ """
+ @pass_context
+ async def text_format(context, value, text_format=None):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_jinja2_attributed_pass_environment_skipped(self) -> None:
+ """The attributed @jinja2.pass_environment form is skipped like the bare form."""
+ violations = _violate(
+ """
+ @jinja2.pass_environment
+ def my_filter(environment, value, arg):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_override_skipped(self) -> None:
+ """@override defs are skipped — the convention lives on the base."""
+ violations = _violate(
+ """
+ class Impl:
+ @override
+ def _store(self, data, key, content_type):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_typer_annotated_argument_skipped(self) -> None:
+ """A call-style Typer command (no decorator) is detected via Annotated typer.Argument/Option."""
+ violations = _violate(
+ """
+ def serve(host: Annotated[str, typer.Argument(help="host")], port: Annotated[int, typer.Option()]):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_carveout_bare_typer_annotated_skipped(self) -> None:
+ """Bare Argument/Option (from typer import Argument, Option) are detected like the qualified form."""
+ violations = _violate(
+ """
+ def serve(host: Annotated[str, Argument(help="host")], port: Annotated[int, Option()]):
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_escape_hatch_suppresses(self) -> None:
+ """An inline `# kw-only: ignore` on the def line suppresses the violation."""
+ violations = _violate(
+ """
+ def build_pipe(spec, dry_run, retries): # kw-only: ignore
+ ...
+ """
+ )
+ assert violations == []
+
+ def test_escape_hatch_does_not_suppress_other_defs(self) -> None:
+ """The escape hatch is scoped to its own def line only."""
+ violations = _violate(
+ """
+ def safe(spec, dry_run): # kw-only: ignore
+ ...
+
+ def unsafe(spec, dry_run):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::unsafe"}
+
+ def test_escape_hatch_survives_form_feed_earlier_in_file(self) -> None:
+ r"""A form-feed before an escaped def must not shift line indexing off the marker.
+
+ ``str.splitlines()`` splits on ``\x0c`` but ``ast`` line numbers do not, so a form-feed earlier
+ in the file used to make the escape-hatch lookup read the marker off the wrong physical line — a
+ false-positive violation on an explicitly-suppressed def (which would wrongly block a hook edit).
+ """
+ source = 'page = "one\x0ctwo"\ndef safe(spec, dry_run): # kw-only: ignore\n return spec\n'
+ violations = find_violations_in_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert violations == []
+
+ def test_async_def_supported(self) -> None:
+ """Async functions are inspected too."""
+ violations = _violate(
+ """
+ async def fetch(url, retries, timeout):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::fetch"}
+
+ def test_nested_function_qualified_name(self) -> None:
+ """Nested defs are inspected and qualified through their enclosing scope."""
+ violations = _violate(
+ """
+ class Outer:
+ def method(self, subject):
+ def inner(first, second):
+ ...
+ """
+ )
+ assert _keys(violations) == {"pipelex/sample/module.py::Outer.method.inner"}
diff --git a/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py
new file mode 100644
index 000000000..b388e775b
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py
@@ -0,0 +1,99 @@
+"""Unit tests for the command-layer control flow of `check_keyword_only_cmd` / `_run_fix`.
+
+These pin the contract of the `--fix` path: it is **non-gating** — it auto-fixes, reports both what was
+fixed and what still needs a manual fix, and exits 0 even when unfixable violations remain (the read-only
+`check-keyword-only`, run last in `agent-check` and in `make check` / CI, is what enforces compliance).
+They also pin that `fix` takes precedence over `report` and that the "nothing to fix" branch trims to one
+line only in quiet mode. The filesystem scanning (`fix_all_violations` / `collect_all_violations`) is
+mocked so each branch is driven deterministically without touching the real `pipelex/` tree.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING
+
+import pytest
+from rich.console import Console
+
+from pipelex.cli.dev_cli.commands import check_keyword_only_cmd as cmd_mod
+from pipelex.cli.dev_cli.commands.check_keyword_only_cmd import check_keyword_only_cmd
+from pipelex.cli.dev_cli.commands.keyword_only_guard import Violation
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+
+def _violation(name: str) -> Violation:
+ return Violation(relative_path="pipelex/sample/module.py", qualified_name=name, lineno=7)
+
+
+class TestCheckKeywordOnlyCmdFix:
+ @pytest.fixture
+ def console_buffer(self, mocker: MockerFixture, tmp_path: Path) -> io.StringIO:
+ """Route every `get_console()` call to one StringIO-backed console, and point SOURCE_ROOT at a real dir."""
+ buffer = io.StringIO()
+ mocker.patch.object(cmd_mod, "get_console", return_value=Console(file=buffer, force_terminal=False, width=200))
+ # SOURCE_ROOT only needs to exist for the guard's pre-flight check; the scanners are mocked per test.
+ mocker.patch.object(cmd_mod, "SOURCE_ROOT", tmp_path)
+ return buffer
+
+ def test_fix_only_exits_zero_and_reports_fixed(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """Fixable-only run: files were rewritten, nothing remains — no SystemExit, the fix is surfaced."""
+ mocker.patch.object(cmd_mod, "fix_all_violations", return_value=([_violation("fixed_func")], []))
+ check_keyword_only_cmd(fix=True, quiet=True) # returns normally (exit 0)
+ output = console_buffer.getvalue()
+ assert "Auto-fixed 1 keyword-only violation(s)" in output
+ assert "pipelex/sample/module.py:7" in output
+ assert "fixed_func" in output
+
+ def test_unfixable_reports_but_does_not_gate(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """The fix path is non-gating: an unfixable violation is reported but exits 0 (the read-only check gates)."""
+ mocker.patch.object(cmd_mod, "fix_all_violations", return_value=([], [_violation("unfixable_func")]))
+ check_keyword_only_cmd(fix=True, quiet=True) # returns normally (exit 0) — does not raise SystemExit
+ output = console_buffer.getvalue()
+ assert "1 violation(s) need a manual fix" in output
+ assert "unfixable_func" in output
+ assert "nothing to fix" not in output # an unfixable violation is not the empty happy path
+
+ def test_fixed_and_unfixable_reports_both_without_gating(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """A run that both rewrites files AND leaves unfixable violations reports both — and still exits 0 (non-gating)."""
+ mocker.patch.object(
+ cmd_mod,
+ "fix_all_violations",
+ return_value=([_violation("fixed_func")], [_violation("unfixable_func")]),
+ )
+ check_keyword_only_cmd(fix=True, quiet=True) # returns normally (exit 0) — the read-only check enforces, not this
+ output = console_buffer.getvalue()
+ assert "Auto-fixed 1 keyword-only violation(s)" in output # files were written...
+ assert "1 violation(s) need a manual fix" in output # ...and the rest is reported for a manual fix
+ assert "fixed_func" in output
+ assert "unfixable_func" in output
+
+ def test_nothing_to_fix_quiet_is_one_line_and_exits_zero(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """No violations + quiet: the happy path trims to the single 'nothing to fix' line."""
+ mocker.patch.object(cmd_mod, "fix_all_violations", return_value=([], []))
+ check_keyword_only_cmd(fix=True, quiet=True) # returns normally (exit 0)
+ output = console_buffer.getvalue()
+ assert "Keyword-only auto-fix: nothing to fix" in output
+ assert "No keyword-only violations." not in output # the verbose panel is not used in quiet mode
+
+ def test_nothing_to_fix_verbose_prints_success_panel(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """No violations + verbose: the success panel is shown instead of the one-line message."""
+ mocker.patch.object(cmd_mod, "fix_all_violations", return_value=([], []))
+ check_keyword_only_cmd(fix=True, quiet=False) # returns normally (exit 0)
+ output = console_buffer.getvalue()
+ assert "No keyword-only violations." in output
+ assert "nothing to fix" not in output
+
+ def test_fix_takes_precedence_over_report(self, mocker: MockerFixture, console_buffer: io.StringIO) -> None:
+ """With both flags set, the fix path runs and the report path (collect_all_violations) is never reached."""
+ mocker.patch.object(cmd_mod, "fix_all_violations", return_value=([], []))
+ collect_spy = mocker.patch.object(cmd_mod, "collect_all_violations")
+ report_spy = mocker.patch.object(cmd_mod, "_print_report")
+ check_keyword_only_cmd(report=True, fix=True, quiet=True)
+ collect_spy.assert_not_called()
+ report_spy.assert_not_called()
+ assert "Keyword-only auto-fix: nothing to fix" in console_buffer.getvalue()
diff --git a/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py
new file mode 100644
index 000000000..7fc5c37e4
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py
@@ -0,0 +1,315 @@
+"""Unit tests for the auto-fix surface of the keyword-only guard (`fix_source` / `fix_all_violations`)."""
+
+from __future__ import annotations
+
+import textwrap
+from typing import TYPE_CHECKING
+
+from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ Violation,
+ find_violations_in_source,
+ fix_all_violations,
+ fix_source,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+def _fix(
+ source: str, *, module_qname: str = "pipelex.sample.module", relative_path: str = "pipelex/sample/module.py"
+) -> tuple[str, list[Violation], list[Violation]]:
+ """Run the auto-fixer over an inline snippet, returning (new_source, fixed, unfixable)."""
+ return fix_source(textwrap.dedent(source), module_qname=module_qname, relative_path=relative_path)
+
+
+def _names(violations: list[Violation]) -> list[str]:
+ return [violation.qualified_name for violation in violations]
+
+
+def _is_compliant(source: str) -> bool:
+ """Whether a (rewritten) source has no remaining violations."""
+ return find_violations_in_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py") == []
+
+
+class TestKeywordOnlyGuardFix:
+ def test_simple_function_gets_bare_star(self) -> None:
+ """The `*` lands as far left as possible, making every parameter keyword-only."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def f(a, b):
+ return a
+ """
+ )
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ assert "def f(*, a, b):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_method_star_lands_right_after_self(self) -> None:
+ """`self` stays positional; the `*` lands right after it, making every other param keyword-only."""
+ new_source, fixed, unfixable = _fix(
+ """
+ class C:
+ def m(self, a, b):
+ return a
+ """
+ )
+ assert _names(fixed) == ["C.m"]
+ assert unfixable == []
+ assert "def m(self, *, a, b):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_classmethod_cls_dropped(self) -> None:
+ """`cls` stays positional; the `*` lands right after it."""
+ new_source, fixed, unfixable = _fix(
+ """
+ class C:
+ @classmethod
+ def make(cls, source, target):
+ return source
+ """
+ )
+ assert _names(fixed) == ["C.make"]
+ assert unfixable == []
+ assert "def make(cls, *, source, target):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_single_defaulted_option_named(self) -> None:
+ """A lone subject plus an option: the `*` goes to the far left, making both keyword-only."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def truncate(text, max_length=80):
+ return text
+ """
+ )
+ assert _names(fixed) == ["truncate"]
+ assert unfixable == []
+ assert "def truncate(*, text, max_length=80):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_annotations_and_default_preserved(self) -> None:
+ """The `*` is inserted before the first parameter name, leaving annotations/defaults intact."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def f(a: int, b: str = "x") -> int:
+ return a
+ """
+ )
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ assert 'def f(*, a: int, b: str = "x") -> int:' in new_source
+ assert _is_compliant(new_source)
+
+ def test_multiline_signature_fixed_and_compliant(self) -> None:
+ """A signature spread across lines is fixed on the target parameter's own line."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def f(
+ a,
+ b,
+ ):
+ return a
+ """
+ )
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ assert _is_compliant(new_source)
+
+ def test_two_violations_in_one_source_both_fixed(self) -> None:
+ new_source, fixed, unfixable = _fix(
+ """
+ def f(a, b):
+ return a
+
+ def h(x, y, z):
+ return x
+ """
+ )
+ assert _names(fixed) == ["f", "h"]
+ assert unfixable == []
+ assert "def f(*, a, b):" in new_source
+ assert "def h(*, x, y, z):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_compliant_source_unchanged(self) -> None:
+ source = textwrap.dedent(
+ """
+ def g(subject, *, opt):
+ return opt
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert (fixed, unfixable) == ([], [])
+ assert new_source == source
+
+ def test_lone_subject_unchanged(self) -> None:
+ source = textwrap.dedent(
+ """
+ def render(node):
+ return node
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert (fixed, unfixable) == ([], [])
+ assert new_source == source
+
+ def test_varargs_reported_unfixable_and_unchanged(self) -> None:
+ """A `*args` signature cannot take a bare `*` — reported for a manual fix, source untouched."""
+ source = textwrap.dedent(
+ """
+ def f(a, b, *args):
+ return a
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert fixed == []
+ assert _names(unfixable) == ["f"]
+ assert new_source == source
+
+ def test_existing_keyword_only_section_reported_unfixable(self) -> None:
+ """A signature that already has a bare `*` (but a positional `b` before it) needs a manual merge."""
+ source = textwrap.dedent(
+ """
+ def f(a, b, *, c):
+ return a
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert fixed == []
+ assert _names(unfixable) == ["f"]
+ assert new_source == source
+
+ def test_positional_only_subject_fixed_after_slash(self) -> None:
+ """A single positional-only subject (before `/`) stays positional; the `*` goes right after the `/`."""
+ new_source, fixed, unfixable = _fix(
+ """
+ def f(a, /, b, c):
+ return a
+ """
+ )
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ assert "def f(a, /, *, b, c):" in new_source
+ assert _is_compliant(new_source)
+
+ def test_multiple_positional_only_reported_unfixable(self) -> None:
+ """Two+ positional-only params can't be made keyword-only by a bare `*` (it can't precede `/`) — manual fix."""
+ source = textwrap.dedent(
+ """
+ def f(a, b, /, c):
+ return a
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert fixed == []
+ assert _names(unfixable) == ["f"]
+ assert new_source == source
+
+ def test_carveouts_are_never_touched(self) -> None:
+ """Dunders, @override, pydantic validators and the escape hatch are not violations, so the fixer leaves them be."""
+ source = textwrap.dedent(
+ """
+ class Box:
+ def __setitem__(self, key, value):
+ ...
+
+ @override
+ def _store(self, data, key, content_type):
+ ...
+
+ @field_validator("name", mode="before")
+ def normalize(cls, value, info):
+ ...
+
+ def safe(spec, dry_run): # kw-only: ignore
+ ...
+ """
+ )
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert (fixed, unfixable) == ([], [])
+ assert new_source == source
+
+ def test_escape_hatch_carveout_survives_form_feed_in_fix_path(self) -> None:
+ r"""A `# kw-only: ignore` def must NOT be modified by the fixer, even with a form-feed earlier in the file.
+
+ The escape hatch is the one carve-out that reads source text (`_def_line_has_escape_hatch`), so it is
+ the carve-out at risk if `ast`-line indexing diverges from `str.splitlines()` (the F1/F2 bug). This pins
+ that the fixer rewrites only the genuine violation and leaves the suppressed def byte-for-byte intact —
+ a regression guard against reverting the tokenizer-accurate line split.
+ """
+ suppressed = "def suppressed(spec, dry_run): # kw-only: ignore"
+ source = f'BANNER = "page1\x0cpage2"\n{suppressed}\n return spec\n\ndef real(alpha, beta):\n return alpha\n'
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert _names(fixed) == ["real"]
+ assert unfixable == []
+ assert suppressed in new_source # the escape-hatched def is untouched
+ assert "def real(*, alpha, beta):" in new_source # only the genuine violation is fixed
+ assert _is_compliant(new_source)
+
+ def test_fix_is_idempotent(self) -> None:
+ """Re-fixing an already-fixed source produces no further change."""
+ once, fixed, unfixable = _fix(
+ """
+ def f(a, b, c):
+ return a
+ """
+ )
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ twice, fixed_again, unfixable_again = fix_source(once, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert (fixed_again, unfixable_again) == ([], [])
+ assert twice == once
+
+ def test_form_feed_in_string_neither_corrupts_nor_misreports(self) -> None:
+ r"""A form-feed (\x0c) in a string literal before a violation must not derail line indexing.
+
+ ``str.splitlines()`` splits on ``\x0c`` (and other exotic whitespace) but ``ast`` line numbers
+ count only ``\n``/``\r``/``\r\n``. The old splitlines-based indexing landed the inserted ``*``
+ on the wrong physical line — here it silently injects it INTO the triple-quoted string (which still
+ re-parses) while leaving the real violation untouched and wrongly reporting it as fixed. The fix
+ must insert the ``*`` into the def and leave the string byte-for-byte intact.
+ """
+ literal = '"""\naaaa\x0cbbbb\nxxxxxxxxxxxxxxxxxxxx"""'
+ source = f"page = {literal}\ndef f(a, b):\n return a\n"
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ assert "def f(*, a, b):" in new_source
+ assert literal in new_source # the string literal is untouched — no stray `*, ` injected into it
+ assert _is_compliant(new_source)
+
+ def test_crlf_line_endings_preserved_and_fixed(self) -> None:
+ r"""A CRLF (\r\n) file is fixed on the right line with its line endings preserved byte-for-byte.
+
+ ``_LINE_BREAK_RE`` matches ``\r\n``/``\r``/``\n`` and the capturing split rebuilds the file exactly;
+ this pins the CRLF half of that regex (the form-feed tests above cover the ``splitlines()``-divergence
+ half). A regression that broke CRLF reconstruction would corrupt every Windows-authored file the fixer
+ touches — most dangerously by emitting bare ``\n`` where the source had ``\r\n``.
+ """
+ source = "X = 1\r\ndef f(a, b):\r\n return a\r\n"
+ new_source, fixed, unfixable = fix_source(source, module_qname="pipelex.sample.module", relative_path="pipelex/sample/module.py")
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ # The `*` lands on the def line and every CRLF separator is preserved byte-for-byte.
+ assert new_source == "X = 1\r\ndef f(*, a, b):\r\n return a\r\n"
+ # No bare `\n` was introduced: every `\n` is still part of a `\r\n`.
+ assert new_source.count("\n") == new_source.count("\r\n")
+ assert _is_compliant(new_source)
+
+ def test_fix_all_violations_rewrites_in_place(self, tmp_path: Path) -> None:
+ """The filesystem entrypoint rewrites only the offending file and reports the fix."""
+ sample = tmp_path / "pipelex" / "sample"
+ sample.mkdir(parents=True)
+ bad = sample / "bad.py"
+ good = sample / "good.py"
+ good_text = "def g(subject, *, opt):\n return opt\n"
+ bad.write_text("def f(a, b):\n return a\n", encoding="utf-8")
+ good.write_text(good_text, encoding="utf-8")
+
+ fixed, unfixable = fix_all_violations(tmp_path / "pipelex")
+
+ assert _names(fixed) == ["f"]
+ assert unfixable == []
+ assert "def f(*, a, b):" in bad.read_text(encoding="utf-8")
+ assert good.read_text(encoding="utf-8") == good_text # compliant file left byte-for-byte untouched
diff --git a/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py
new file mode 100644
index 000000000..76e1eeec9
--- /dev/null
+++ b/tests/unit/pipelex/cli/dev/test_keyword_only_guard_single_file.py
@@ -0,0 +1,109 @@
+"""Unit tests for the single-file surface of the keyword-only guard (filesystem + lean CLI entry)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.cli.dev_cli.commands.keyword_only_guard import (
+ collect_all_violations,
+ collect_violations_for_files,
+ main,
+ relative_source_path,
+)
+
+_BAD_SOURCE = "def f(a, b):\n return a\n"
+_GOOD_SOURCE = "def g(subject, *, opt):\n return opt\n"
+
+
+def _make_tree(root: Path) -> None:
+ """Create a minimal pipelex source tree with one violating and one compliant module."""
+ sample = root / "pipelex" / "sample"
+ sample.mkdir(parents=True)
+ (sample / "bad.py").write_text(_BAD_SOURCE, encoding="utf-8")
+ (sample / "good.py").write_text(_GOOD_SOURCE, encoding="utf-8")
+
+
+class TestKeywordOnlyGuardSingleFile:
+ def test_single_file_matches_full_scan(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """A single-file scan is an exact subset of the full-tree scan for that file (the equivalence contract).
+
+ Mirrors production, where the full scan runs against the *relative* ``SOURCE_ROOT`` (``Path("pipelex")``),
+ so both sides report repo-root-relative paths.
+ """
+ _make_tree(tmp_path)
+ monkeypatch.chdir(tmp_path)
+ single = collect_violations_for_files([Path("pipelex/sample/bad.py")])
+ full = collect_all_violations(Path("pipelex"))
+ assert [violation.key for violation in single] == [violation.key for violation in full]
+ assert len(single) == 1
+ assert single[0].relative_path == "pipelex/sample/bad.py"
+ assert single[0].qualified_name == "f"
+
+ def test_compliant_file_has_no_violations(self, tmp_path: Path) -> None:
+ _make_tree(tmp_path)
+ assert collect_violations_for_files([Path("pipelex/sample/good.py")], root=tmp_path) == []
+
+ def test_absolute_path_is_handled(self, tmp_path: Path) -> None:
+ _make_tree(tmp_path)
+ abs_path = tmp_path / "pipelex" / "sample" / "bad.py"
+ result = collect_violations_for_files([abs_path], root=tmp_path)
+ assert len(result) == 1
+ assert result[0].qualified_name == "f"
+
+ def test_out_of_scope_path_skipped(self, tmp_path: Path) -> None:
+ """A .py file outside pipelex/ is not the guard's concern."""
+ (tmp_path / "tests").mkdir()
+ (tmp_path / "tests" / "thing.py").write_text(_BAD_SOURCE, encoding="utf-8")
+ assert collect_violations_for_files([Path("tests/thing.py")], root=tmp_path) == []
+
+ def test_syntax_error_file_skipped(self, tmp_path: Path) -> None:
+ """A mid-edit file that does not parse yet is skipped, never raised — the hook must not block on it."""
+ (tmp_path / "pipelex").mkdir()
+ (tmp_path / "pipelex" / "broken.py").write_text("def f(a, b\n", encoding="utf-8")
+ assert collect_violations_for_files([Path("pipelex/broken.py")], root=tmp_path) == []
+
+ def test_missing_file_skipped(self, tmp_path: Path) -> None:
+ (tmp_path / "pipelex").mkdir()
+ assert collect_violations_for_files([Path("pipelex/ghost.py")], root=tmp_path) == []
+
+ @pytest.mark.parametrize(
+ "relative",
+ [
+ "pipelex/sample/note.md", # non-.py
+ "tests/thing.py", # outside pipelex/
+ ],
+ )
+ def test_relative_source_path_rejects_out_of_scope(self, tmp_path: Path, relative: str) -> None:
+ assert relative_source_path(Path(relative), root=tmp_path) is None
+
+ def test_relative_source_path_accepts_in_scope(self, tmp_path: Path) -> None:
+ _make_tree(tmp_path)
+ resolved = relative_source_path(tmp_path / "pipelex" / "sample" / "bad.py", root=tmp_path)
+ assert resolved == Path("pipelex/sample/bad.py")
+
+ def test_relative_source_path_rejects_pycache(self, tmp_path: Path) -> None:
+ target = tmp_path / "pipelex" / "__pycache__" / "x.py"
+ target.parent.mkdir(parents=True)
+ target.write_text(_GOOD_SOURCE, encoding="utf-8")
+ assert relative_source_path(target, root=tmp_path) is None
+
+ def test_main_returns_2_and_prints_for_violation(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ _make_tree(tmp_path)
+ monkeypatch.chdir(tmp_path)
+ exit_code = main(["pipelex/sample/bad.py"])
+ captured = capsys.readouterr()
+ assert exit_code == 2
+ assert "pipelex/sample/bad.py:1" in captured.err
+ assert "f" in captured.err
+
+ def test_main_returns_0_for_compliant(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
+ _make_tree(tmp_path)
+ monkeypatch.chdir(tmp_path)
+ exit_code = main(["pipelex/sample/good.py"])
+ captured = capsys.readouterr()
+ assert exit_code == 0
+ assert captured.err == ""
diff --git a/tests/unit/pipelex/cli/test_agent_output.py b/tests/unit/pipelex/cli/test_agent_output.py
index 85459d73b..b27878a2b 100644
--- a/tests/unit/pipelex/cli/test_agent_output.py
+++ b/tests/unit/pipelex/cli/test_agent_output.py
@@ -26,10 +26,6 @@ from pipelex.cli.agent_cli.commands.agent_output import (
)
from pipelex.cogt.exceptions import CogtError, InferenceBackendCredentialsError, InferenceBackendCredentialsErrorType, InferenceErrorCategory
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
-from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData
-from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
-from pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorType
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipeline.exceptions import ValidateBundleError
if TYPE_CHECKING:
@@ -53,7 +49,7 @@ class TestAgentOutput:
def test_agent_error_outputs_json_to_stderr(self, capsys: pytest.CaptureFixture[str]) -> None:
"""agent_error should print valid JSON to stderr and exit with code 1."""
with pytest.raises(typer.Exit) as exc_info:
- agent_error("something went wrong", "TestError")
+ agent_error("something went wrong", error_type="TestError")
assert exc_info.value.exit_code == 1
captured = capsys.readouterr()
@@ -66,34 +62,16 @@ class TestAgentOutput:
def test_agent_error_includes_hint_for_known_type(self, capsys: pytest.CaptureFixture[str]) -> None:
"""agent_error should auto-add a hint for known error types."""
with pytest.raises(typer.Exit):
- agent_error("model issue", "PipeOperatorModelChoiceError")
+ agent_error("model issue", error_type="PipeOperatorModelChoiceError")
parsed = json.loads(capsys.readouterr().err)
assert "hint" in parsed
assert parsed["hint"] == AGENT_ERROR_HINTS["PipeOperatorModelChoiceError"]
- def test_agent_error_includes_signature_hint(self, capsys: pytest.CaptureFixture[str]) -> None:
- """A SignaturesNotAllowedError surfaced through the agent boundary must carry the --allow-signatures hint.
-
- The agent CLI's strict `validate pipe --all` / single-pipe paths surface this error through
- agent_error with the exception as cause. The hint still comes from the AGENT_ERROR_HINTS
- fallback (the class declares no class-level user_action), while error_domain now flows from the
- exception's class-level INPUT classification rather than the AGENT_ERROR_DOMAINS dict.
- """
- cause = SignaturesNotAllowedError(offending_pipe_refs={"d.caller"}, signature_refs={"d.summary_sig"}, dep_paths={})
- with pytest.raises(typer.Exit):
- agent_error("strict validation reached a PipeSignature", "SignaturesNotAllowedError", cause=cause)
-
- parsed = json.loads(capsys.readouterr().err)
- assert parsed["hint"] == AGENT_ERROR_HINTS["SignaturesNotAllowedError"]
- assert "--allow-signatures" in parsed["hint"]
- # error_domain is now sourced from the class-level metadata (INPUT), not the lookup dict.
- assert parsed["error_domain"] == "input"
-
def test_agent_error_no_hint_for_unknown_type(self, capsys: pytest.CaptureFixture[str]) -> None:
"""agent_error should not include hint for unregistered error types."""
with pytest.raises(typer.Exit):
- agent_error("oops", "CompletelyUnknownError")
+ agent_error("oops", error_type="CompletelyUnknownError")
parsed = json.loads(capsys.readouterr().err)
assert "hint" not in parsed
@@ -101,7 +79,7 @@ class TestAgentOutput:
def test_agent_error_includes_extra_fields(self, capsys: pytest.CaptureFixture[str]) -> None:
"""Extra kwargs should appear as top-level fields in the JSON output."""
with pytest.raises(typer.Exit):
- agent_error("fail", "SomeError", pipe_code="my_pipe", custom_data=[1, 2])
+ agent_error("fail", error_type="SomeError", pipe_code="my_pipe", custom_data=[1, 2])
parsed = json.loads(capsys.readouterr().err)
assert parsed["pipe_code"] == "my_pipe"
@@ -110,7 +88,7 @@ class TestAgentOutput:
def test_agent_error_extra_can_override_hint(self, capsys: pytest.CaptureFixture[str]) -> None:
"""An explicit hint kwarg should override the auto-looked-up hint."""
with pytest.raises(typer.Exit):
- agent_error("fail", "ValidateBundleError", hint="custom hint")
+ agent_error("fail", error_type="ValidateBundleError", hint="custom hint")
parsed = json.loads(capsys.readouterr().err)
assert parsed["hint"] == "custom hint"
@@ -125,54 +103,11 @@ class TestAgentOutput:
assert parsed["success"] is True
assert parsed["value"] == 42
- def test_extract_validation_errors_all_categories(self) -> None:
- """extract_validation_errors should return entries from all 4 categories."""
- exc = ValidateBundleError(
- message="validation failed",
- pipelex_bundle_blueprint_validation_errors=[
- PipelexBundleBlueprintValidationErrorData(
- error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
- pipe_code="pipe_a",
- message="missing var x",
- variable_names=["x"],
- ),
- ],
- pipe_factory_errors=[
- PipeFactoryErrorData(
- error_type=PipeFactoryErrorType.UNKNOWN_CONCEPT,
- pipe_code="pipe_b",
- message="concept Foo not found",
- missing_concept_code="Foo",
- declared_concepts=["Bar", "Baz"],
- ),
- ],
- pipe_validation_errors=[
- PipesAndConceptValidationErrorData(
- error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,
- pipe_code="pipe_c",
- message="extra var y",
- field_path="pipe_c.inputs.y",
- variable_names=["y"],
- ),
- ],
- )
-
- result = extract_validation_errors(exc)
- assert len(result) == 3
-
- categories = [entry["category"] for entry in result]
- assert "blueprint_validation" in categories
- assert "pipe_factory" in categories
- assert "pipe_validation" in categories
-
- # Check factory error has extra fields
- factory_entry = next(entry for entry in result if entry["category"] == "pipe_factory")
- assert factory_entry["missing_concept_code"] == "Foo"
- assert factory_entry["declared_concepts"] == ["Bar", "Baz"]
-
- # Check blueprint entry has variable_names
- blueprint_entry = next(entry for entry in result if entry["category"] == "blueprint_validation")
- assert blueprint_entry["variable_names"] == ["x"]
+ # NOTE: the per-category projection of ``extract_validation_errors`` is now pinned
+ # thoroughly (including CLI↔API shape parity) by the shared-builder suite in
+ # tests/unit/pipelex/pipeline/test_validation_errors.py — the former
+ # ``test_extract_validation_errors_all_categories`` here duplicated it with weaker
+ # asserts and a stale "4 categories" docstring, so it was removed.
# -------------------------------------------------------------------------
# Datetime serialization tests (regression for "Object of type datetime is
@@ -225,7 +160,7 @@ class TestAgentOutput:
with pytest.raises(typer.Exit):
agent_error(
"pipeline failed",
- "PipelineExecutionError",
+ error_type="PipelineExecutionError",
failed_at=datetime.datetime(2026, 2, 9, 14, 0, 0),
)
@@ -233,11 +168,16 @@ class TestAgentOutput:
assert parsed["error"] is True
assert parsed["failed_at"] == "2026-02-09T14:00:00"
- def test_extract_validation_errors_empty(self) -> None:
- """extract_validation_errors should return empty list when no errors."""
+ def test_extract_validation_errors_message_only(self) -> None:
+ """A message-only error yields one ``blueprint_validation`` residual — the structured-info invariant is total.
+
+ A parse-level failure (TOML syntax, an empty blueprint, a bundle elaborator) carries no
+ categorized data, but the builder's last-resort ``fallback_message`` residual still emits
+ one item so the CLI's ``validation_errors[]`` is never empty on an invalid verdict.
+ """
exc = ValidateBundleError(message="no details")
result = extract_validation_errors(exc)
- assert result == []
+ assert result == [{"category": "blueprint_validation", "message": "no details"}]
# -------------------------------------------------------------------------
# _build_error_source tests
@@ -287,7 +227,7 @@ class TestAgentOutput:
assert cause.__traceback__ is None
with pytest.raises(typer.Exit) as exc_info:
- agent_error("something broke", "RuntimeError", cause=cause)
+ agent_error("something broke", error_type="RuntimeError", cause=cause)
assert exc_info.value.exit_code == 1
parsed = json.loads(capsys.readouterr().err)
@@ -307,7 +247,7 @@ class TestAgentOutput:
user_action=UserAction(kind=UserActionKind.CHECK_CREDENTIALS, detail="Check your API key and try again"),
)
with pytest.raises(typer.Exit):
- agent_error("inference failed", "CogtError", cause=cause)
+ agent_error("inference failed", error_type="CogtError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["hint"] == "Check your API key and try again"
@@ -316,7 +256,7 @@ class TestAgentOutput:
"""agent_error should set retryable=True when error_category is TRANSIENT."""
cause = CogtError("rate limited", error_category=InferenceErrorCategory.TRANSIENT)
with pytest.raises(typer.Exit):
- agent_error("rate limited", "CogtError", cause=cause)
+ agent_error("rate limited", error_type="CogtError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["retryable"] is True
@@ -325,7 +265,7 @@ class TestAgentOutput:
"""agent_error should include error_category from to_error_report()."""
cause = CogtError("bad config", error_category=InferenceErrorCategory.CONFIGURATION)
with pytest.raises(typer.Exit):
- agent_error("bad config", "CogtError", cause=cause)
+ agent_error("bad config", error_type="CogtError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["error_category"] == "configuration"
@@ -334,7 +274,7 @@ class TestAgentOutput:
"""agent_error should use lookup dicts when cause is not a PipelexError."""
cause = FileNotFoundError("missing.mthds")
with pytest.raises(typer.Exit):
- agent_error("file not found", "FileNotFoundError", cause=cause)
+ agent_error("file not found", error_type="FileNotFoundError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["hint"] == AGENT_ERROR_HINTS["FileNotFoundError"]
@@ -344,7 +284,7 @@ class TestAgentOutput:
"""agent_error should fall back to lookup when PipelexError has no category/user_action."""
cause = PipelexError("something failed")
with pytest.raises(typer.Exit):
- agent_error("something failed", "PipeExecutionError", cause=cause)
+ agent_error("something failed", error_type="PipeExecutionError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
# hint should come from AGENT_ERROR_HINTS since PipelexError has no user_action
@@ -358,7 +298,7 @@ class TestAgentOutput:
user_action=UserAction(kind=UserActionKind.CHANGE_MODEL, detail="Use pipelex-agent models to list available models"),
)
with pytest.raises(typer.Exit):
- agent_error("model not found", "ModelChoiceNotFoundError", cause=cause)
+ agent_error("model not found", error_type="ModelChoiceNotFoundError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["hint"] == "Use pipelex-agent models to list available models"
@@ -371,7 +311,7 @@ class TestAgentOutput:
user_action=UserAction(kind=UserActionKind.UNKNOWN, detail="from report"),
)
with pytest.raises(typer.Exit):
- agent_error("failed", "CogtError", cause=cause, hint="custom override")
+ agent_error("failed", error_type="CogtError", cause=cause, hint="custom override")
parsed = json.loads(capsys.readouterr().err)
assert parsed["hint"] == "custom override"
@@ -385,7 +325,7 @@ class TestAgentOutput:
key_name="OPENAI_API_KEY",
)
with pytest.raises(typer.Exit):
- agent_error("OPENAI_API_KEY not set", "InferenceBackendCredentialsError", cause=cause)
+ agent_error("OPENAI_API_KEY not set", error_type="InferenceBackendCredentialsError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["provider"] == "openai"
@@ -394,7 +334,7 @@ class TestAgentOutput:
"""Non-retryable errors should not include retryable field in JSON output."""
cause = CogtError("bad config", error_category=InferenceErrorCategory.CONFIGURATION)
with pytest.raises(typer.Exit):
- agent_error("bad config", "CogtError", cause=cause)
+ agent_error("bad config", error_type="CogtError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert "retryable" not in parsed
@@ -407,7 +347,7 @@ class TestAgentOutput:
cause = CogtError("model not found", error_category=InferenceErrorCategory.CONFIGURATION)
with pytest.raises(typer.Exit):
- agent_error("model not found", error_type, cause=cause)
+ agent_error("model not found", error_type=error_type, cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["error_domain"] == AGENT_ERROR_DOMAINS[error_type]
@@ -417,7 +357,7 @@ class TestAgentOutput:
"""agent_error should include error_domain from to_error_report() for a PipelexError cause."""
cause = PipelexConfigError("bad config")
with pytest.raises(typer.Exit):
- agent_error("bad config", "PipelexConfigError", cause=cause)
+ agent_error("bad config", error_type="PipelexConfigError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["error_domain"] == "config"
@@ -426,7 +366,7 @@ class TestAgentOutput:
"""agent_error should read error_domain from the lookup dict for a non-PipelexError cause."""
cause = FileNotFoundError("missing.mthds")
with pytest.raises(typer.Exit):
- agent_error("file not found", "FileNotFoundError", cause=cause)
+ agent_error("file not found", error_type="FileNotFoundError", cause=cause)
parsed = json.loads(capsys.readouterr().err)
assert parsed["error_domain"] == "input"
diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.py
index 3df19de42..3159d3483 100644
--- a/tests/unit/pipelex/cli/test_error_handlers_more.py
+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py
@@ -24,7 +24,6 @@ from pipelex.cli.error_handlers import (
handle_model_deck_preset_error,
handle_remote_config_unavailable_error,
handle_remote_config_validation_error,
- handle_signatures_not_allowed_error,
handle_telemetry_config_validation_error,
handle_validate_bundle_error,
)
@@ -34,7 +33,6 @@ from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData
from pipelex.core.exceptions import PipesAndConceptValidationErrorData
from pipelex.core.pipes.exceptions import PipeValidationErrorType
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.system.pipelex_service.exceptions import (
GatewayApiKeyMissingError,
@@ -146,7 +144,7 @@ class TestErrorHandlersExtended:
assert "Enabled Backends:" not in output
def test_handle_validate_bundle_error_renders_all_sections(self, console: Console) -> None:
- """Blueprint, pipe, dry-run and signature sections all render with their details."""
+ """Blueprint, pipe, and dry-run sections all render with their details."""
blueprint_error = PipelexBundleBlueprintValidationErrorData(
error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
domain_code="demo",
@@ -165,17 +163,11 @@ class TestErrorHandlersExtended:
field_path="pipes.other_pipe.output",
variable_names=["report"],
)
- signature_error = SignaturesNotAllowedError(
- offending_pipe_refs={"stub_pipe"},
- signature_refs={"stub_pipe"},
- dep_paths={"stub_pipe": ["main_pipe", "stub_pipe"]},
- )
exc = ValidateBundleError(
message="validation failed",
pipelex_bundle_blueprint_validation_errors=[blueprint_error],
pipe_validation_errors=[pipe_error],
dry_run_error_message="dry run exploded",
- signature_check_error=signature_error,
)
with pytest.raises(typer.Exit) as exc_info:
@@ -195,7 +187,6 @@ class TestErrorHandlersExtended:
assert "└─ Path: pipes.other_pipe.output" in output
assert "Dry Run Error:" in output
assert "dry run exploded" in output
- assert "Unimplemented Signatures:" in output
def test_handle_validate_bundle_error_minimal_skips_sections(self, console: Console) -> None:
"""With no detail lists and no bundle path, only the banner and tip render."""
@@ -210,24 +201,11 @@ class TestErrorHandlersExtended:
assert "Blueprint Validation Errors:" not in output
assert "Pipe Validation Errors:" not in output
assert "Dry Run Error:" not in output
- assert "Unimplemented Signatures:" not in output
assert "💡 Tip:" in output
-
- def test_handle_signatures_not_allowed_error(self, console: Console) -> None:
- """The signature handler explains the strict-mode refusal and the opt-out flag."""
- exc = SignaturesNotAllowedError(
- offending_pipe_refs={"stub_pipe"},
- signature_refs={"stub_pipe"},
- dep_paths={"stub_pipe": ["main_pipe", "stub_pipe"]},
- )
-
- with pytest.raises(typer.Exit) as exc_info:
- handle_signatures_not_allowed_error(exc, context=ErrorContext.VALIDATION)
-
- assert exc_info.value.exit_code == 1
- output = console.export_text()
- assert "unimplemented PipeSignature placeholders" in output
- assert "--allow-signatures" in output
+ # A non-signature bundle error must NOT advertise the signature opt-out: signatures are a
+ # runnability fact reported via pending_signatures, not a ValidateBundleError (the old
+ # signature-specific tip used to leak here from the deleted handle_signatures_not_allowed_error).
+ assert "--allow-signatures" not in output
def test_handle_telemetry_config_validation_error(self, console: Console) -> None:
"""The telemetry handler explains the format migration."""
diff --git a/tests/unit/pipelex/cli/test_init_credentials.py b/tests/unit/pipelex/cli/test_init_credentials.py
index 5f48ffe4d..c14546931 100644
--- a/tests/unit/pipelex/cli/test_init_credentials.py
+++ b/tests/unit/pipelex/cli/test_init_credentials.py
@@ -57,7 +57,7 @@ class TestInitCredentials:
def test_write_env_file_creates_file_with_header(self, tmp_path: Path) -> None:
"""Write creates the file with a header comment and entries."""
env_path = tmp_path / ".env"
- write_env_file(env_path, {"FOO": "bar", "BAZ": "qux"})
+ write_env_file(env_path, entries={"FOO": "bar", "BAZ": "qux"})
content = env_path.read_text()
assert "# Pipelex credentials" in content
assert "FOO=bar" in content
@@ -66,32 +66,32 @@ class TestInitCredentials:
def test_write_env_file_sets_permissions(self, tmp_path: Path) -> None:
"""Written file has 0600 permissions."""
env_path = tmp_path / ".env"
- write_env_file(env_path, {"KEY": "value"})
+ write_env_file(env_path, entries={"KEY": "value"})
mode = env_path.stat().st_mode & 0o777
assert mode == stat.S_IRUSR | stat.S_IWUSR
def test_write_env_file_creates_parent_dirs(self, tmp_path: Path) -> None:
"""Parent directories are created if they don't exist."""
env_path = tmp_path / "sub" / "dir" / ".env"
- write_env_file(env_path, {"KEY": "value"})
+ write_env_file(env_path, entries={"KEY": "value"})
assert env_path.is_file()
def test_write_then_read_roundtrip(self, tmp_path: Path) -> None:
"""Data survives a write/read cycle."""
env_path = tmp_path / ".env"
entries = {"ALPHA": "one", "BETA": "two"}
- write_env_file(env_path, entries)
+ write_env_file(env_path, entries=entries)
result = read_env_file(env_path)
assert result == entries
def test_write_env_file_merges_with_existing(self, tmp_path: Path) -> None:
"""Writing merges: new keys added, existing keys updated."""
env_path = tmp_path / ".env"
- write_env_file(env_path, {"OLD": "original", "SHARED": "old_val"})
+ write_env_file(env_path, entries={"OLD": "original", "SHARED": "old_val"})
existing = read_env_file(env_path)
existing["SHARED"] = "new_val"
existing["NEW"] = "fresh"
- write_env_file(env_path, existing)
+ write_env_file(env_path, entries=existing)
result = read_env_file(env_path)
assert result == {"OLD": "original", "SHARED": "new_val", "NEW": "fresh"}
@@ -130,7 +130,7 @@ class TestInitCredentials:
)
mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml)
+ prompt_credentials(mock_console, backends_toml_path=backends_toml)
# Should print "already set" message, no Prompt.ask calls
mock_console.print.assert_called()
mock_prompt.assert_not_called()
@@ -152,7 +152,7 @@ class TestInitCredentials:
return_value="sk-test-value",
)
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml)
+ prompt_credentials(mock_console, backends_toml_path=backends_toml)
# Verify .env was written
env_path = tmp_path / ".env"
@@ -182,7 +182,7 @@ class TestInitCredentials:
return_value="",
)
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml)
+ prompt_credentials(mock_console, backends_toml_path=backends_toml)
# Verify .env was NOT written (no values entered)
env_path = tmp_path / ".env"
@@ -191,7 +191,7 @@ class TestInitCredentials:
def test_prompt_credentials_preserves_existing_env_entries(self, tmp_path: Path, mocker: MockerFixture) -> None:
"""Existing entries in .env are preserved when new ones are added."""
env_path = tmp_path / ".env"
- write_env_file(env_path, {"EXISTING_KEY": "existing_value"})
+ write_env_file(env_path, entries={"EXISTING_KEY": "existing_value"})
backends_toml = tmp_path / "backends.toml"
backends_toml.write_text('[openai]\nenabled = true\napi_key = "${OPENAI_API_KEY}"\n\n[internal]\nenabled = true\n')
@@ -207,7 +207,7 @@ class TestInitCredentials:
return_value="sk-new",
)
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml)
+ prompt_credentials(mock_console, backends_toml_path=backends_toml)
result = read_env_file(env_path)
assert result["EXISTING_KEY"] == "existing_value"
@@ -226,5 +226,5 @@ class TestInitCredentials:
)
mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")
mock_console: MagicMock = mocker.MagicMock()
- prompt_credentials(mock_console, backends_toml)
+ prompt_credentials(mock_console, backends_toml_path=backends_toml)
mock_prompt.assert_not_called()
diff --git a/tests/unit/pipelex/cli/test_inputs_path_resolver.py b/tests/unit/pipelex/cli/test_inputs_path_resolver.py
index 6d62d84c0..866fb528e 100644
--- a/tests/unit/pipelex/cli/test_inputs_path_resolver.py
+++ b/tests/unit/pipelex/cli/test_inputs_path_resolver.py
@@ -227,9 +227,9 @@ class TestInputsPathResolver:
def test_resolve_url_in_value_string_passthrough(self) -> None:
"""Non-dict, non-list values pass through unchanged."""
- assert resolve_url_in_value("hello", Path("/base")) == "hello"
- assert resolve_url_in_value(42, Path("/base")) == 42
- assert resolve_url_in_value(None, Path("/base")) is None
+ assert resolve_url_in_value("hello", base_dir=Path("/base")) == "hello"
+ assert resolve_url_in_value(42, base_dir=Path("/base")) == 42
+ assert resolve_url_in_value(None, base_dir=Path("/base")) is None
# ---- resolve_inputs_paths ----
@@ -250,5 +250,5 @@ class TestInputsPathResolver:
)
def test_resolve_inputs_paths(self, topic: str, inputs_dict: dict[str, Any], expected: dict[str, Any]) -> None: # noqa: ARG002
"""Resolves relative url paths in various input structures."""
- result = resolve_inputs_paths(inputs_dict, _ResolveInputsPathsCases.BASE_DIR)
+ result = resolve_inputs_paths(inputs_dict, base_dir=_ResolveInputsPathsCases.BASE_DIR)
assert result == expected
diff --git a/tests/unit/pipelex/cli/test_pipe_cmd.py b/tests/unit/pipelex/cli/test_pipe_cmd.py
index e14723fe0..2e079b8a6 100644
--- a/tests/unit/pipelex/cli/test_pipe_cmd.py
+++ b/tests/unit/pipelex/cli/test_pipe_cmd.py
@@ -43,24 +43,23 @@ class TestCliPipeCmd:
"prompt": "Write about $text",
}
pipe_type = spec.pop("type")
- result = parse_pipe_spec(pipe_type, spec)
+ result = parse_pipe_spec(spec, pipe_type=pipe_type)
assert result.pipe_code == "test"
# -- CLI TOML serialization (uses format_toml_string) -----------------
def test_llm_model_appears_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**self._BASE_LLM})
+ spec = parse_pipe_spec({**self._BASE_LLM}, pipe_type="PipeLLM")
toml = _pipe_spec_to_toml(spec)
assert 'model = "$writing-creative"' in toml
def test_llm_different_model_in_toml(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**self._BASE_LLM, "model": "$engineering-structured"})
+ spec = parse_pipe_spec({**self._BASE_LLM, "model": "$engineering-structured"}, pipe_type="PipeLLM")
toml = _pipe_spec_to_toml(spec)
assert 'model = "$engineering-structured"' in toml
def test_extract_model_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeExtract",
{
"pipe_code": "my_extract",
"description": "Extract pipe",
@@ -68,13 +67,13 @@ class TestCliPipeCmd:
"output": "Page[]",
"model": "@default-extract-document",
},
+ pipe_type="PipeExtract",
)
toml = _pipe_spec_to_toml(spec)
assert 'model = "@default-extract-document"' in toml
def test_img_gen_model_in_toml(self) -> None:
spec = parse_pipe_spec(
- "PipeImgGen",
{
"pipe_code": "my_img_gen",
"description": "Image gen pipe",
@@ -83,24 +82,24 @@ class TestCliPipeCmd:
"model": "$gen-image",
"prompt": "Generate: $prompt_text",
},
+ pipe_type="PipeImgGen",
)
toml = _pipe_spec_to_toml(spec)
assert 'model = "$gen-image"' in toml
def test_toml_contains_pipe_section(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**self._BASE_LLM})
+ spec = parse_pipe_spec({**self._BASE_LLM}, pipe_type="PipeLLM")
toml = _pipe_spec_to_toml(spec)
assert "[pipe.my_llm_pipe]" in toml
assert 'type = "PipeLLM"' in toml
def test_toml_contains_prompt(self) -> None:
- spec = parse_pipe_spec("PipeLLM", {**self._BASE_LLM})
+ spec = parse_pipe_spec({**self._BASE_LLM}, pipe_type="PipeLLM")
toml = _pipe_spec_to_toml(spec)
assert 'prompt = "Write about $text"' in toml
def test_sequence_toml_has_steps(self) -> None:
spec = parse_pipe_spec(
- "PipeSequence",
{
"pipe_code": "my_seq",
"description": "A sequence",
@@ -111,6 +110,7 @@ class TestCliPipeCmd:
{"pipe": "step_two", "result": "final"},
],
},
+ pipe_type="PipeSequence",
)
toml = _pipe_spec_to_toml(spec)
assert "step_one" in toml
@@ -119,7 +119,6 @@ class TestCliPipeCmd:
def test_search_fields_appear_in_toml(self) -> None:
"""PipeSearch type-specific fields (prompt, model, filters) must round-trip to TOML."""
spec = parse_pipe_spec(
- "PipeSearch",
{
"pipe_code": "my_search",
"description": "Search pipe",
@@ -133,6 +132,7 @@ class TestCliPipeCmd:
"exclude_domains": ["example.com"],
"max_results": 5,
},
+ pipe_type="PipeSearch",
)
toml = _pipe_spec_to_toml(spec)
assert 'type = "PipeSearch"' in toml
@@ -148,7 +148,6 @@ class TestCliPipeCmd:
def test_search_optional_filters_omitted_in_toml(self) -> None:
"""Unset PipeSearch filters must not appear in the TOML (only prompt is required)."""
spec = parse_pipe_spec(
- "PipeSearch",
{
"pipe_code": "bare_search",
"description": "Minimal search pipe",
@@ -156,6 +155,7 @@ class TestCliPipeCmd:
"output": "Text",
"prompt": "About $topic",
},
+ pipe_type="PipeSearch",
)
toml = _pipe_spec_to_toml(spec)
assert 'prompt = "About $topic"' in toml
@@ -169,7 +169,6 @@ class TestCliPipeCmd:
def test_llm_no_model_omits_model_in_toml(self) -> None:
"""When model is None, no model line should appear in the TOML."""
spec = parse_pipe_spec(
- "PipeLLM",
{
"pipe_code": "my_pipe",
"description": "No model specified",
@@ -177,6 +176,7 @@ class TestCliPipeCmd:
"output": "Text",
"prompt": "Write about $text",
},
+ pipe_type="PipeLLM",
)
toml = _pipe_spec_to_toml(spec)
assert "model =" not in toml
@@ -193,7 +193,7 @@ class TestCliPipeCmd:
"output": {"type": "ImgGenPrompt"},
"prompt": "Generate a creative image prompt based on $idea",
}
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
assert result.model == "$writing-creative" # type: ignore[attr-defined]
assert result.output == "ImgGenPrompt"
@@ -207,7 +207,7 @@ class TestCliPipeCmd:
"output": {"type": "ImgGenPrompt"},
"prompt": "Generate a creative image prompt based on $idea",
}
- result = parse_pipe_spec("PipeLLM", spec)
+ result = parse_pipe_spec(spec, pipe_type="PipeLLM")
toml = _pipe_spec_to_toml(result)
assert 'model = "$writing-creative"' in toml
assert 'output = "ImgGenPrompt"' in toml
diff --git a/tests/unit/pipelex/cli/test_run_core_execution.py b/tests/unit/pipelex/cli/test_run_core_execution.py
index 6fa6fdc01..10098609c 100644
--- a/tests/unit/pipelex/cli/test_run_core_execution.py
+++ b/tests/unit/pipelex/cli/test_run_core_execution.py
@@ -177,7 +177,7 @@ class TestRunCoreExecution:
_run_async(_call_execute_run(inputs=str(inputs_file)))
- resolver_mock.assert_called_once_with({"topic": "dogs"}, tmp_path.resolve())
+ resolver_mock.assert_called_once_with({"topic": "dogs"}, base_dir=tmp_path.resolve())
execute_kwargs = runner_class_mock.return_value.execute.call_args.kwargs
assert execute_kwargs["inputs"] == {"topic": "dogs", "resolved": True}
diff --git a/tests/unit/pipelex/cli/test_update_cmd.py b/tests/unit/pipelex/cli/test_update_cmd.py
index 7767a8cb2..ab79f0c67 100644
--- a/tests/unit/pipelex/cli/test_update_cmd.py
+++ b/tests/unit/pipelex/cli/test_update_cmd.py
@@ -61,7 +61,8 @@ class TestUpdateCmd:
# Kit has moved on, but the install hasn't yet.
(kit_dir / "1_llm_deck.toml").write_text("v2-content", encoding="utf-8")
write_manifest(
- deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")})
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")}),
+ deck_dir=deck_dir,
)
self._patch_version(mocker, "1.1.0")
@@ -82,7 +83,8 @@ class TestUpdateCmd:
def test_clean_behind_overwrites_without_backup(self, mocker: MockerFixture, kit_and_deck: tuple[Path, Path]) -> None:
kit_dir, deck_dir = kit_and_deck
write_manifest(
- deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")})
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")}),
+ deck_dir=deck_dir,
)
(kit_dir / "1_llm_deck.toml").write_text("v2-content", encoding="utf-8")
self._patch_version(mocker, "1.1.0")
@@ -96,7 +98,8 @@ class TestUpdateCmd:
def test_locally_modified_creates_backup_and_overwrites(self, mocker: MockerFixture, kit_and_deck: tuple[Path, Path]) -> None:
kit_dir, deck_dir = kit_and_deck
write_manifest(
- deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")})
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")}),
+ deck_dir=deck_dir,
)
(deck_dir / "1_llm_deck.toml").write_text("user-edits", encoding="utf-8")
(kit_dir / "1_llm_deck.toml").write_text("v2-content", encoding="utf-8")
@@ -113,7 +116,8 @@ class TestUpdateCmd:
def test_no_backup_flag_skips_backup(self, mocker: MockerFixture, kit_and_deck: tuple[Path, Path]) -> None:
kit_dir, deck_dir = kit_and_deck
write_manifest(
- deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")})
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")}),
+ deck_dir=deck_dir,
)
(deck_dir / "1_llm_deck.toml").write_text("user-edits", encoding="utf-8")
(kit_dir / "1_llm_deck.toml").write_text("v2-content", encoding="utf-8")
@@ -127,7 +131,8 @@ class TestUpdateCmd:
def test_kit_added_installs_new_file(self, mocker: MockerFixture, kit_and_deck: tuple[Path, Path]) -> None:
kit_dir, deck_dir = kit_and_deck
write_manifest(
- deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")})
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")}),
+ deck_dir=deck_dir,
)
(kit_dir / "5_new_deck.toml").write_text("brand-new", encoding="utf-8")
self._patch_version(mocker, "1.1.0")
@@ -140,7 +145,6 @@ class TestUpdateCmd:
_, deck_dir = kit_and_deck
(deck_dir / "9_retired_deck.toml").write_text("retired-content", encoding="utf-8")
write_manifest(
- deck_dir,
DeckManifest(
kit_version="1.0.0",
files={
@@ -148,6 +152,7 @@ class TestUpdateCmd:
"9_retired_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "9_retired_deck.toml"),
},
),
+ deck_dir=deck_dir,
)
self._patch_version(mocker, "1.1.0")
@@ -171,7 +176,8 @@ class TestUpdateCmd:
def test_yes_flag_skips_confirm(self, mocker: MockerFixture, kit_and_deck: tuple[Path, Path]) -> None:
kit_dir, deck_dir = kit_and_deck
write_manifest(
- deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")})
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": deck_manifest.compute_file_sha256(deck_dir / "1_llm_deck.toml")}),
+ deck_dir=deck_dir,
)
(kit_dir / "1_llm_deck.toml").write_text("v2-content", encoding="utf-8")
self._patch_version(mocker, "1.1.0")
diff --git a/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py b/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py
index 3cb0c3a84..00e1caeb9 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_assignment_models_security.py
@@ -75,5 +75,5 @@ class TestAssignmentModelsSecurity:
)
restored = ObjectAssignment.model_validate_json(assignment.model_dump_json())
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(restored.object_class_schema, restored.object_class_name)
+ SchemaToModelFactory.make_from_json_schema(restored.object_class_schema, class_name=restored.object_class_name)
assert "x-python-import" in str(exc_info.value)
diff --git a/tests/unit/pipelex/cogt/content_generation/test_dry_run_factory_main_pipe.py b/tests/unit/pipelex/cogt/content_generation/test_dry_run_factory_main_pipe.py
new file mode 100644
index 000000000..25794d9d2
--- /dev/null
+++ b/tests/unit/pipelex/cogt/content_generation/test_dry_run_factory_main_pipe.py
@@ -0,0 +1,56 @@
+"""Unit tests for the `main_pipe` cross-field dependency in DryRunFactory."""
+
+from pydantic import BaseModel, Field
+
+from pipelex.cogt.content_generation.dry_run_factory import DryRunFactory
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+class PipeStub(BaseModel):
+ """Minimal stand-in for a pipe definition living inside the `pipe` dict."""
+
+ description: str = Field(..., description="A pipe definition stand-in")
+
+
+class BundleStub(BaseModel):
+ """Mirrors the real bundle shape (`PipelexBundleBlueprint` / builder `BundleSpec`).
+
+ The combination of a `pipe` dict and a `main_pipe` that must reference one of its
+ keys is exactly what makes `DryRunFactory.make_dry_run_factory` register the
+ `PostGenerated(_main_pipe_from_pipe_dict)` cross-field provider.
+ """
+
+ main_pipe: str = Field(..., description="The bundle's main pipe; must be a key in `pipe`")
+ pipe: dict[str, PipeStub] = Field(..., description="Pipe definitions keyed by pipe code")
+
+
+# =============================================================================
+# Tests
+# =============================================================================
+
+
+class TestDryRunFactoryMainPipe:
+ """Test that DryRunFactory resolves `main_pipe` against the generated `pipe` dict."""
+
+ def test_build_does_not_raise_for_main_pipe_postgenerated(self) -> None:
+ """Regression for the keyword-only refactor of `_main_pipe_from_pipe_dict`.
+
+ A model carrying both `main_pipe` and `pipe` registers the callback via
+ polyfactory `PostGenerated`, which invokes it positionally as `fn(name, values)`.
+ Making `values` keyword-only breaks the build with
+ `TypeError: _main_pipe_from_pipe_dict() takes 1 positional argument but 2 were given`.
+ """
+ factory = DryRunFactory.make_dry_run_factory(BundleStub)
+ instance = factory.build()
+ assert isinstance(instance.main_pipe, str)
+ assert instance.main_pipe, "main_pipe must be a non-empty string"
+
+ def test_main_pipe_references_a_generated_pipe_key(self) -> None:
+ """The callback's whole purpose: `main_pipe` must point at one of the generated pipe keys."""
+ factory = DryRunFactory.make_dry_run_factory(BundleStub)
+ instance = factory.build()
+ assert instance.pipe, "factory should generate at least one pipe entry"
+ assert instance.main_pipe in instance.pipe, f"main_pipe {instance.main_pipe!r} must be one of the generated pipe keys {list(instance.pipe)!r}"
diff --git a/tests/unit/pipelex/cogt/content_generation/test_dry_run_mock_build_error.py b/tests/unit/pipelex/cogt/content_generation/test_dry_run_mock_build_error.py
index 17998dc51..c68c421db 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_dry_run_mock_build_error.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_dry_run_mock_build_error.py
@@ -48,7 +48,7 @@ class TestDryRunMockBuildError:
def test_unbuildable_class_list_variant_raises_same_typed_error(self) -> None:
"""The list builder carries the same terminal-error contract as the single builder."""
with pytest.raises(DryRunMockBuildError):
- build_mock_objects(UnbuildableName, 2)
+ build_mock_objects(UnbuildableName, count=2)
def test_buildable_class_builds(self) -> None:
"""Control arm: an unconstrained class builds a valid instance."""
diff --git a/tests/unit/pipelex/cogt/content_generation/test_model_dump_subclass.py b/tests/unit/pipelex/cogt/content_generation/test_model_dump_subclass.py
index 1295a1c06..bc415cd64 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_model_dump_subclass.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_model_dump_subclass.py
@@ -24,7 +24,7 @@ class TestModelDumpSubclass:
def test_reconstructed_flat_model_roundtrip(self) -> None:
"""Flat reconstructed model roundtrips through model_dump(serialize_as_any=True) → model_validate."""
schema = InnerDetail.model_json_schema()
- reconstructed_class = SchemaToModelFactory.make_from_json_schema(schema, "InnerDetail")
+ reconstructed_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="InnerDetail")
raw_obj: BaseModel = reconstructed_class(label="score", value=42)
@@ -36,7 +36,7 @@ class TestModelDumpSubclass:
def test_reconstructed_nested_model_roundtrip(self) -> None:
"""Nested reconstructed model roundtrips through model_dump(serialize_as_any=True) → model_validate."""
schema = OuterModel.model_json_schema()
- reconstructed_class = SchemaToModelFactory.make_from_json_schema(schema, "OuterModel")
+ reconstructed_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="OuterModel")
raw_obj: BaseModel = reconstructed_class(
title="Test",
diff --git a/tests/unit/pipelex/cogt/content_generation/test_schema_to_model.py b/tests/unit/pipelex/cogt/content_generation/test_schema_to_model.py
index 81e40b0a1..4c8f1e5d6 100644
--- a/tests/unit/pipelex/cogt/content_generation/test_schema_to_model.py
+++ b/tests/unit/pipelex/cogt/content_generation/test_schema_to_model.py
@@ -82,7 +82,7 @@ class TestSchemaToModel:
unique_title = f"LiteralChoicesRepro_{uuid.uuid4().hex}"
schema["title"] = unique_title
- result_class = SchemaToModelFactory.make_from_json_schema(schema, unique_title)
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name=unique_title)
source = getattr(result_class, "__kajson_class_source__", "")
assert "class Recommendation(Enum)" not in source, (
@@ -120,7 +120,7 @@ class TestSchemaToModel:
unique_title = f"JsonObjectRepro_{uuid.uuid4().hex}"
schema["title"] = unique_title
- result_class = SchemaToModelFactory.make_from_json_schema(schema, unique_title)
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name=unique_title)
source = getattr(result_class, "__kajson_class_source__", "")
assert "from __future__ import annotations" in source, (
@@ -157,7 +157,7 @@ class TestSchemaToModel:
def test_simple_model_reconstruction(self) -> None:
"""A simple model can be reconstructed from its JSON schema."""
schema = SimpleModel.model_json_schema()
- result_class = SchemaToModelFactory.make_from_json_schema(schema, "SimpleModel")
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="SimpleModel")
assert result_class.__name__ == "SimpleModel"
assert "name" in result_class.model_fields
@@ -166,7 +166,7 @@ class TestSchemaToModel:
def test_reconstructed_model_can_validate(self) -> None:
"""The reconstructed model can validate data."""
schema = SimpleModel.model_json_schema()
- result_class = SchemaToModelFactory.make_from_json_schema(schema, "SimpleModel")
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="SimpleModel")
instance = result_class(name="Alice", age=30)
assert instance.name == "Alice" # type: ignore[attr-defined]
@@ -175,7 +175,7 @@ class TestSchemaToModel:
def test_nested_model_reconstruction(self) -> None:
"""A model with nested BaseModel fields (producing $defs) can be reconstructed."""
schema = PersonWithAddress.model_json_schema()
- result_class = SchemaToModelFactory.make_from_json_schema(schema, "PersonWithAddress")
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="PersonWithAddress")
instance = result_class(
name="Bob",
@@ -187,7 +187,7 @@ class TestSchemaToModel:
def test_kajson_class_source_attached(self) -> None:
"""The reconstructed class has __kajson_class_source__ with the generated Python source."""
schema = SimpleModel.model_json_schema()
- result_class = SchemaToModelFactory.make_from_json_schema(schema, "SimpleModel")
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="SimpleModel")
source = getattr(result_class, "__kajson_class_source__", None)
assert source is not None
@@ -197,8 +197,8 @@ class TestSchemaToModel:
def test_caching_returns_same_class(self) -> None:
"""Calling with the same schema returns the same class object (cached)."""
schema = SimpleModel.model_json_schema()
- class_1 = SchemaToModelFactory.make_from_json_schema(schema, "SimpleModel")
- class_2 = SchemaToModelFactory.make_from_json_schema(schema, "SimpleModel")
+ class_1 = SchemaToModelFactory.make_from_json_schema(schema, class_name="SimpleModel")
+ class_2 = SchemaToModelFactory.make_from_json_schema(schema, class_name="SimpleModel")
assert class_1 is class_2
@@ -207,15 +207,15 @@ class TestSchemaToModel:
schema_simple = SimpleModel.model_json_schema()
schema_nested = PersonWithAddress.model_json_schema()
- class_simple = SchemaToModelFactory.make_from_json_schema(schema_simple, "SimpleModel")
- class_nested = SchemaToModelFactory.make_from_json_schema(schema_nested, "PersonWithAddress")
+ class_simple = SchemaToModelFactory.make_from_json_schema(schema_simple, class_name="SimpleModel")
+ class_nested = SchemaToModelFactory.make_from_json_schema(schema_nested, class_name="PersonWithAddress")
assert class_simple is not class_nested
def test_json_roundtrip_with_reconstructed_class(self) -> None:
"""An instance of the reconstructed class survives JSON round-trip."""
schema = SimpleModel.model_json_schema()
- result_class = SchemaToModelFactory.make_from_json_schema(schema, "SimpleModel")
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="SimpleModel")
instance = result_class(name="Charlie", age=25)
json_str = instance.model_dump_json()
@@ -228,7 +228,7 @@ class TestSchemaToModel:
schema = SimpleModel.model_json_schema()
# Override the title to simulate a dynamic concept code like "my_namespace__Greeting"
schema["title"] = "my_namespace__Greeting"
- result_class = SchemaToModelFactory.make_from_json_schema(schema, "my_namespace__Greeting")
+ result_class = SchemaToModelFactory.make_from_json_schema(schema, class_name="my_namespace__Greeting")
assert "name" in result_class.model_fields
assert "age" in result_class.model_fields
@@ -255,7 +255,7 @@ class TestSchemaToModel:
def worker() -> None:
barrier.wait()
- result = SchemaToModelFactory.make_from_json_schema(schema, unique_title)
+ result = SchemaToModelFactory.make_from_json_schema(schema, class_name=unique_title)
with results_lock:
results.append(result)
@@ -291,7 +291,7 @@ class TestSchemaToModel:
title = f"BoundedCacheTest_{uuid.uuid4().hex}_{index}"
schema["title"] = title
schemas.append((title, schema))
- SchemaToModelFactory.make_from_json_schema(schema, title)
+ SchemaToModelFactory.make_from_json_schema(schema, class_name=title)
assert len(SchemaToModelFactory._schema_cache) <= 3 # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
assert spy.call_count == 4
@@ -299,12 +299,12 @@ class TestSchemaToModel:
# Oldest schema (index 0) must have been evicted: re-requesting it triggers fresh codegen.
oldest_title, oldest_schema = schemas[0]
- SchemaToModelFactory.make_from_json_schema(oldest_schema, oldest_title)
+ SchemaToModelFactory.make_from_json_schema(oldest_schema, class_name=oldest_title)
assert spy.call_count == 5
# Most-recently-used schema (index 3) must still be cached: no fresh codegen.
recent_title, recent_schema = schemas[3]
- SchemaToModelFactory.make_from_json_schema(recent_schema, recent_title)
+ SchemaToModelFactory.make_from_json_schema(recent_schema, class_name=recent_title)
assert spy.call_count == 5
finally:
SchemaToModelFactory._schema_cache.clear() # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
@@ -314,7 +314,7 @@ class TestSchemaToModel:
"""The restricted exec namespace blocks open(), eval(), exec(), and compile()."""
malicious_source = "from pydantic import BaseModel\nclass Innocent(BaseModel):\n name: str = 'ok'\nleaked = open('/etc/passwd')\n"
with pytest.raises(NameError, match="open"):
- SchemaToModelFactory._exec_and_extract_class(malicious_source, "Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ SchemaToModelFactory._exec_and_extract_class(malicious_source, class_name="Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
# ---- Layer 1: schema sanitization (x-python-* extensions are rejected) ----
@@ -323,7 +323,7 @@ class TestSchemaToModel:
schema = _benign_object_schema()
schema["x-python-import"] = {"module": "subprocess", "name": "run"}
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Innocent")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Innocent")
assert "x-python-import" in str(exc_info.value)
def test_x_python_import_in_defs_is_rejected(self) -> None:
@@ -339,7 +339,7 @@ class TestSchemaToModel:
"$defs": {"Run": {"x-python-import": {"module": "subprocess", "name": "run"}}},
}
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Innocent")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Innocent")
assert "x-python-import" in str(exc_info.value)
def test_x_python_type_is_rejected(self) -> None:
@@ -347,7 +347,7 @@ class TestSchemaToModel:
schema = _benign_object_schema()
schema["properties"]["x"]["x-python-type"] = "subprocess.Popen"
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Innocent")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Innocent")
assert "x-python-type" in str(exc_info.value)
@pytest.mark.parametrize(
@@ -364,7 +364,7 @@ class TestSchemaToModel:
schema = _benign_object_schema()
schema[extension_key] = "anything"
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Innocent")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Innocent")
assert extension_key in str(exc_info.value)
def test_deeply_nested_x_python_import_is_rejected(self) -> None:
@@ -388,7 +388,7 @@ class TestSchemaToModel:
},
}
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Outer")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Outer")
assert "x-python-import" in str(exc_info.value)
def test_unsafe_schema_error_names_the_offending_path(self) -> None:
@@ -400,7 +400,7 @@ class TestSchemaToModel:
"$defs": {"Run": {"x-python-import": {"module": "subprocess", "name": "run"}}},
}
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Innocent")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Innocent")
message = str(exc_info.value)
assert "$defs" in message
assert "Run" in message
@@ -416,7 +416,7 @@ class TestSchemaToModel:
},
}
with pytest.raises(UnsafeSchemaError) as exc_info:
- SchemaToModelFactory.make_from_json_schema(schema, "Innocent")
+ SchemaToModelFactory.make_from_json_schema(schema, class_name="Innocent")
message = str(exc_info.value)
assert "x-python-import" in message
assert "x-python-type" in message
@@ -427,13 +427,13 @@ class TestSchemaToModel:
"""Even bypassing Layer 1, the restricted __import__ blocks `import subprocess`."""
malicious_source = "from pydantic import BaseModel\nimport subprocess\nclass Innocent(BaseModel):\n name: str = 'ok'\n"
with pytest.raises(ImportError, match="subprocess"):
- SchemaToModelFactory._exec_and_extract_class(malicious_source, "Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ SchemaToModelFactory._exec_and_extract_class(malicious_source, class_name="Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
def test_exec_blocks_direct_dunder_import_call(self) -> None:
"""A direct __import__('subprocess') call is also blocked."""
malicious_source = "from pydantic import BaseModel\nclass Innocent(BaseModel):\n name: str = 'ok'\n_leak = __import__('subprocess')\n"
with pytest.raises(ImportError, match="subprocess"):
- SchemaToModelFactory._exec_and_extract_class(malicious_source, "Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ SchemaToModelFactory._exec_and_extract_class(malicious_source, class_name="Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
@pytest.mark.parametrize(
("import_line", "expected_module"),
@@ -448,7 +448,7 @@ class TestSchemaToModel:
"""A range of dangerous stdlib imports is blocked by the allowlist."""
malicious_source = f"from pydantic import BaseModel\n{import_line}\nclass Innocent(BaseModel):\n name: str = 'ok'\n"
with pytest.raises(ImportError, match=expected_module):
- SchemaToModelFactory._exec_and_extract_class(malicious_source, "Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ SchemaToModelFactory._exec_and_extract_class(malicious_source, class_name="Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
@pytest.mark.parametrize(
"import_line",
@@ -468,5 +468,5 @@ class TestSchemaToModel:
def test_exec_allowlisted_imports_succeed(self, import_line: str) -> None:
"""Allowlisted imports required by datamodel-code-generator output continue to work."""
source = f"{import_line}\nfrom pydantic import BaseModel\nclass Innocent(BaseModel):\n name: str = 'ok'\n"
- result_class = SchemaToModelFactory._exec_and_extract_class(source, "Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ result_class = SchemaToModelFactory._exec_and_extract_class(source, class_name="Innocent") # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
assert result_class.__name__ == "Innocent"
diff --git a/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py b/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py
index a3a8542d5..c8e957818 100644
--- a/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py
+++ b/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py
@@ -89,20 +89,20 @@ class TestLLMConfigReasoning:
def test_get_reasoning_budget_valid(self):
config = _make_llm_config()
- assert config.get_reasoning_budget("anthropic", ReasoningEffort.HIGH) == 16384
+ assert config.get_reasoning_budget("anthropic", effort=ReasoningEffort.HIGH) == 16384
def test_get_reasoning_budget_none_effort(self):
config = _make_llm_config()
- assert config.get_reasoning_budget("gemini", ReasoningEffort.NONE) == 0
+ assert config.get_reasoning_budget("gemini", effort=ReasoningEffort.NONE) == 0
def test_get_reasoning_budget_max_effort(self):
config = _make_llm_config()
- assert config.get_reasoning_budget("anthropic", ReasoningEffort.MAX) == 65536
+ assert config.get_reasoning_budget("anthropic", effort=ReasoningEffort.MAX) == 65536
def test_get_reasoning_budget_unknown_target_raises(self):
config = _make_llm_config()
with pytest.raises(ConfigValidationError, match="No effort-to-budget map found"):
- config.get_reasoning_budget("unknown_target", ReasoningEffort.HIGH)
+ config.get_reasoning_budget("unknown_target", effort=ReasoningEffort.HIGH)
def test_validator_missing_effort_level_raises(self):
incomplete_maps = {
@@ -152,7 +152,7 @@ class TestLLMConfigReasoning:
)
def test_all_effort_levels_retrievable(self, effort: ReasoningEffort):
config = _make_llm_config()
- budget = config.get_reasoning_budget("anthropic", effort)
+ budget = config.get_reasoning_budget("anthropic", effort=effort)
assert isinstance(budget, int)
assert budget >= 0
diff --git a/tests/unit/pipelex/cogt/models/test_deck_manifest.py b/tests/unit/pipelex/cogt/models/test_deck_manifest.py
index 24768499c..91b551358 100644
--- a/tests/unit/pipelex/cogt/models/test_deck_manifest.py
+++ b/tests/unit/pipelex/cogt/models/test_deck_manifest.py
@@ -45,7 +45,7 @@ class TestDeckManifest:
def test_manifest_round_trip(self, tmp_path: Path) -> None:
manifest = DeckManifest(kit_version="1.2.3", files={"1_llm_deck.toml": "hash-a", "2_img_gen_deck.toml": "hash-b"})
deck_dir = tmp_path / "deck"
- write_manifest(deck_dir, manifest)
+ write_manifest(manifest, deck_dir=deck_dir)
assert manifest_path(deck_dir).is_file()
reloaded = read_manifest(deck_dir)
@@ -141,7 +141,7 @@ class TestDeckManifest:
self._seed_kit(mocker, kit_dir, contents)
self._seed_installed(deck_dir, contents)
mocker.patch.object(deck_manifest, "get_package_version", return_value="1.0.0")
- write_manifest(deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=deck_dir)
report = compute_deck_sync_report(deck_dir)
assert report.is_clean()
@@ -153,7 +153,7 @@ class TestDeckManifest:
self._seed_kit(mocker, kit_dir, {"1_llm_deck.toml": "old"})
self._seed_installed(deck_dir, {"1_llm_deck.toml": "old"})
mocker.patch.object(deck_manifest, "get_package_version", return_value="1.0.0")
- write_manifest(deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=deck_dir)
# Simulate a kit upgrade — the file content has moved on but the user has not edited theirs.
(kit_dir / "1_llm_deck.toml").write_text("new", encoding="utf-8")
@@ -170,7 +170,7 @@ class TestDeckManifest:
self._seed_kit(mocker, kit_dir, {"1_llm_deck.toml": "kit-version"})
self._seed_installed(deck_dir, {"1_llm_deck.toml": "kit-version"})
mocker.patch.object(deck_manifest, "get_package_version", return_value="1.0.0")
- write_manifest(deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=deck_dir)
# User edits their installed file, kit unchanged.
(deck_dir / "1_llm_deck.toml").write_text("user-edited", encoding="utf-8")
@@ -185,7 +185,9 @@ class TestDeckManifest:
self._seed_installed(deck_dir, {"1_llm_deck.toml": "a"})
mocker.patch.object(deck_manifest, "get_package_version", return_value="1.0.0")
# Manifest captures only the file that existed at install time.
- write_manifest(deck_dir, DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": compute_file_sha256(deck_dir / "1_llm_deck.toml")}))
+ write_manifest(
+ DeckManifest(kit_version="1.0.0", files={"1_llm_deck.toml": compute_file_sha256(deck_dir / "1_llm_deck.toml")}), deck_dir=deck_dir
+ )
report = compute_deck_sync_report(deck_dir)
assert report.files["5_new_deck.toml"] == DeckFileStatus.KIT_ADDED
@@ -198,7 +200,6 @@ class TestDeckManifest:
self._seed_installed(deck_dir, {"1_llm_deck.toml": "a", "9_retired_deck.toml": "old"})
mocker.patch.object(deck_manifest, "get_package_version", return_value="1.1.0")
write_manifest(
- deck_dir,
DeckManifest(
kit_version="1.0.0",
files={
@@ -206,6 +207,7 @@ class TestDeckManifest:
"9_retired_deck.toml": compute_file_sha256(deck_dir / "9_retired_deck.toml"),
},
),
+ deck_dir=deck_dir,
)
report = compute_deck_sync_report(deck_dir)
@@ -218,7 +220,7 @@ class TestDeckManifest:
self._seed_kit(mocker, kit_dir, {"1_llm_deck.toml": "kit"})
self._seed_installed(deck_dir, {"1_llm_deck.toml": "kit", "cookbook.toml": "user-content"})
mocker.patch.object(deck_manifest, "get_package_version", return_value="1.0.0")
- write_manifest(deck_dir, compute_kit_manifest())
+ write_manifest(compute_kit_manifest(), deck_dir=deck_dir)
report = compute_deck_sync_report(deck_dir)
assert "cookbook.toml" not in report.files
@@ -274,7 +276,7 @@ class TestDeckManifest:
) -> None:
deck_dir = tmp_path / "deck"
deck_dir.mkdir()
- write_manifest(deck_dir, DeckManifest(kit_version=manifest_version, files={}))
+ write_manifest(DeckManifest(kit_version=manifest_version, files={}), deck_dir=deck_dir)
mocker.patch.object(deck_manifest, "get_package_version", return_value=current_version)
assert is_deck_stale_fast(deck_dir) is expected_stale
diff --git a/tests/unit/pipelex/cogt/test_worker_error_enrichment.py b/tests/unit/pipelex/cogt/test_worker_error_enrichment.py
index 7db702da5..89cace875 100644
--- a/tests/unit/pipelex/cogt/test_worker_error_enrichment.py
+++ b/tests/unit/pipelex/cogt/test_worker_error_enrichment.py
@@ -72,7 +72,7 @@ class _StubLLMWorker(LLMWorkerAbstract):
raise self._error
@override
- async def _gen_object(self, llm_job: Any, schema: Any) -> Any:
+ async def _gen_object(self, llm_job: Any, *, schema: Any) -> Any:
raise self._error
@@ -88,7 +88,7 @@ class _StubImgGenWorker(ImgGenWorkerAbstract):
raise self._error
@override
- async def _gen_image_list(self, img_gen_job: Any, nb_images: int) -> Any:
+ async def _gen_image_list(self, img_gen_job: Any, *, nb_images: int) -> Any:
raise self._error
@@ -116,7 +116,7 @@ class _StubSearchWorker(SearchWorkerAbstract):
raise self._error
@override
- async def _search_structured(self, search_job: Any, schema: Any) -> Any:
+ async def _search_structured(self, search_job: Any, *, schema: Any) -> Any:
raise self._error
diff --git a/tests/unit/pipelex/cogt/usage/test_cost_registry.py b/tests/unit/pipelex/cogt/usage/test_cost_registry.py
index 91c4aa53c..1a981a37a 100644
--- a/tests/unit/pipelex/cogt/usage/test_cost_registry.py
+++ b/tests/unit/pipelex/cogt/usage/test_cost_registry.py
@@ -73,7 +73,7 @@ class TestCostRegistry:
# Save to CSV
csv_file = tmp_path / "test_report.csv"
- CostRegistry.save_to_csv(records, csv_file)
+ CostRegistry.save_to_csv(records, file_path=csv_file)
# Verify file exists
assert csv_file.exists()
@@ -99,7 +99,7 @@ class TestCostRegistry:
def test_save_to_csv_empty_records(self, tmp_path: Path):
"""Test that save_to_csv handles empty records gracefully."""
csv_file = tmp_path / "empty_report.csv"
- CostRegistry.save_to_csv([], csv_file)
+ CostRegistry.save_to_csv([], file_path=csv_file)
# File should not be created for empty records
assert not csv_file.exists()
@@ -135,7 +135,7 @@ class TestCostRegistry:
# Save to CSV - should handle varying fields without errors
csv_file = tmp_path / "varying_fields_report.csv"
- CostRegistry.save_to_csv(records, csv_file)
+ CostRegistry.save_to_csv(records, file_path=csv_file)
# Verify file exists
assert csv_file.exists()
diff --git a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py
index c05e47a66..5a5347cbf 100644
--- a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py
+++ b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator.py
@@ -21,7 +21,9 @@ class TestStructureGenerator:
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("TestModel", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="TestModel", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -77,7 +79,9 @@ class TestModel(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("ComplexModel", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="ComplexModel", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -119,7 +123,9 @@ class ComplexModel(StructuredContent):
"size": ConceptStructureBlueprint(description="Size of the product", choices=["XS", "S", "M", "L", "XL"], required=False),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("Product", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="Product", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -173,7 +179,7 @@ class Product(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("Order", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(class_name="Order", structure_blueprint=structure_blueprint)
expected_code = '''\
"""
@@ -209,7 +215,9 @@ class Order(StructuredContent):
"""Test generation of structure with no fields."""
structure_blueprint: dict[str, ConceptStructureBlueprint] = {}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("EmptyModel", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="EmptyModel", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -245,7 +253,9 @@ class EmptyModel(StructuredContent):
"page_count": ConceptStructureBlueprint(description="Number of pages", type=ConceptStructureBlueprintFieldType.INTEGER, required=False),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("DocumentInfo", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="DocumentInfo", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -282,7 +292,9 @@ class DocumentInfo(StructuredContent):
"value": ConceptStructureBlueprint(description="Test value", type=ConceptStructureBlueprintFieldType.TEXT, required=True),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("ConvenienceTest", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="ConvenienceTest", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -334,7 +346,9 @@ class ConvenienceTest(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("TypeMappingTest", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="TypeMappingTest", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -376,7 +390,9 @@ class TypeMappingTest(StructuredContent):
"optional_field": ConceptStructureBlueprint(description="Optional field", type=ConceptStructureBlueprintFieldType.TEXT, required=False),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("RequiredFieldsModel", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="RequiredFieldsModel", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -430,7 +446,9 @@ class RequiredFieldsModel(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("PersonWithDefaults", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="PersonWithDefaults", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -485,7 +503,9 @@ class PersonWithDefaults(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("ListTypesModel", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="ListTypesModel", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -543,7 +563,9 @@ class ListTypesModel(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("DictTypesModel", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="DictTypesModel", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -607,7 +629,9 @@ class DictTypesModel(StructuredContent):
),
}
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("ComplexItem", structure_blueprint)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="ComplexItem", structure_blueprint=structure_blueprint
+ )
expected_code = '''\
"""
@@ -657,7 +681,9 @@ class ComplexItem(StructuredContent):
normalized_structure = normalize_structure_blueprint(mixed_structure_blueprint)
- result, generated_class = StructureGenerator().generate_from_structure_blueprint("PersonInfo", normalized_structure)
+ result, generated_class = StructureGenerator().generate_from_structure_blueprint(
+ class_name="PersonInfo", structure_blueprint=normalized_structure
+ )
expected_code = '''\
"""
@@ -703,7 +729,7 @@ class PersonInfo(StructuredContent):
}
generator = StructureGenerator()
- python_code, the_class = generator.generate_from_structure_blueprint("ValidTestModel", structure_blueprint)
+ python_code, the_class = generator.generate_from_structure_blueprint(class_name="ValidTestModel", structure_blueprint=structure_blueprint)
expected_code = '''\
"""
@@ -777,8 +803,8 @@ class WrongClassName(StructuredContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- "Question",
- structure_blueprint,
+ class_name="Question",
+ structure_blueprint=structure_blueprint,
base_class_name="TextContent",
)
@@ -839,8 +865,8 @@ class Question(TextContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- "TableScreenshot",
- structure_blueprint,
+ class_name="TableScreenshot",
+ structure_blueprint=structure_blueprint,
base_class_name="ImageContent",
)
@@ -893,8 +919,8 @@ class TableScreenshot(ImageContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- "Temperature",
- structure_blueprint,
+ class_name="Temperature",
+ structure_blueprint=structure_blueprint,
base_class_name="NumberContent",
)
@@ -946,8 +972,8 @@ class Temperature(NumberContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- "ConfigData",
- structure_blueprint,
+ class_name="ConfigData",
+ structure_blueprint=structure_blueprint,
base_class_name="JSONContent",
)
@@ -993,8 +1019,8 @@ class ConfigData(JSONContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- "EnhancedText",
- structure_blueprint,
+ class_name="EnhancedText",
+ structure_blueprint=structure_blueprint,
base_class_name="TextContent",
)
@@ -1049,8 +1075,8 @@ class EnhancedText(TextContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- "Invoice",
- structure_blueprint,
+ class_name="Invoice",
+ structure_blueprint=structure_blueprint,
base_class_name="DocumentContent",
)
@@ -1112,8 +1138,8 @@ class Invoice(DocumentContent):
generator = StructureGenerator()
generated_code, generated_class = generator.generate_from_structure_blueprint(
- class_name,
- structure_blueprint,
+ class_name=class_name,
+ structure_blueprint=structure_blueprint,
base_class_name=base_class_name,
)
diff --git a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_concept_refs.py b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_concept_refs.py
index 48fe0ff20..738f9125b 100644
--- a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_concept_refs.py
+++ b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_concept_refs.py
@@ -51,7 +51,7 @@ class TestStructureGeneratorConceptRefs:
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Invoice", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Invoice", structure_blueprint=structure_blueprint)
expected_code = (
AUTOGEN_HEADER
@@ -86,7 +86,7 @@ class Invoice(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Invoice", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Invoice", structure_blueprint=structure_blueprint)
expected_code = (
AUTOGEN_HEADER
@@ -120,7 +120,9 @@ class Invoice(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("CategoryNode", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(
+ class_name="CategoryNode", structure_blueprint=structure_blueprint
+ )
expected_code = (
AUTOGEN_HEADER
@@ -150,7 +152,7 @@ class CategoryNode(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Parent", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Parent", structure_blueprint=structure_blueprint)
expected_code = (
AUTOGEN_HEADER
@@ -185,7 +187,7 @@ class Parent(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Order", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Order", structure_blueprint=structure_blueprint)
expected_code = (
AUTOGEN_HEADER
@@ -214,7 +216,7 @@ class Order(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Container", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Container", structure_blueprint=structure_blueprint)
expected_code = (
AUTOGEN_HEADER
@@ -272,7 +274,9 @@ class Container(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("ComplexEntity", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(
+ class_name="ComplexEntity", structure_blueprint=structure_blueprint
+ )
expected_code = (
AUTOGEN_HEADER
@@ -305,7 +309,9 @@ class ComplexEntity(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("ReportWrapper", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(
+ class_name="ReportWrapper", structure_blueprint=structure_blueprint
+ )
# Native concepts should generate imports and use the Content class name
assert "from pipelex.core.stuffs.html_content import HtmlContent" in generated_code
@@ -324,7 +330,9 @@ class ComplexEntity(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("TextWrapper", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(
+ class_name="TextWrapper", structure_blueprint=structure_blueprint
+ )
# Native concepts should generate imports and use the Content class name
assert "from pipelex.core.stuffs.text_content import TextContent" in generated_code
@@ -344,7 +352,9 @@ class ComplexEntity(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("ImageGallery", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(
+ class_name="ImageGallery", structure_blueprint=structure_blueprint
+ )
# Native concepts in lists should also generate imports
assert "from pipelex.core.stuffs.image_content import ImageContent" in generated_code
@@ -375,7 +385,7 @@ class ComplexEntity(StructuredContent):
}
generator = StructureGenerator(concept_ref_to_class_info=concept_ref_to_class_info)
- class_code = generator._generate_class_source_code_from_blueprint("SkillMatchResult", structure_blueprint) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ class_code = generator._generate_class_source_code_from_blueprint("SkillMatchResult", structure_blueprint=structure_blueprint) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
expected_class_code = '''\
class SkillMatchResult(StructuredContent):
@@ -420,7 +430,7 @@ class SkillMatchResult(StructuredContent):
}
generator = StructureGenerator(concept_ref_to_class_info=concept_ref_to_class_info)
- class_code = generator._generate_class_source_code_from_blueprint("TechAnalysis", structure_blueprint) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ class_code = generator._generate_class_source_code_from_blueprint("TechAnalysis", structure_blueprint=structure_blueprint) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
expected_class_code = '''\
class TechAnalysis(StructuredContent):
@@ -459,7 +469,7 @@ class TechAnalysis(StructuredContent):
}
generator = StructureGenerator(concept_ref_to_class_info=concept_ref_to_class_info)
- generated_code, generated_class = generator.generate_from_structure_blueprint("Container", structure_blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Container", structure_blueprint=structure_blueprint)
expected_code = (
AUTOGEN_HEADER
@@ -504,7 +514,7 @@ class Container(StructuredContent):
}
generator = StructureGenerator(concept_ref_to_class_info=concept_ref_to_class_info)
- class_code = generator._generate_class_source_code_from_blueprint("Order", structure_blueprint) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
+ class_code = generator._generate_class_source_code_from_blueprint("Order", structure_blueprint=structure_blueprint) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]
expected_class_code = '''\
class Order(StructuredContent):
diff --git a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_escaping.py b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_escaping.py
index a20675b19..bad97aa3a 100644
--- a/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_escaping.py
+++ b/tests/unit/pipelex/core/concepts/structure_generation/test_structure_generator_escaping.py
@@ -30,7 +30,7 @@ class TestStructureGeneratorEscaping:
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Animal", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Animal", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -75,7 +75,7 @@ class Animal(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("TestClass", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="TestClass", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -120,7 +120,7 @@ class TestClass(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Message", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Message", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -165,7 +165,7 @@ class Message(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("FilePath", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="FilePath", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -210,7 +210,7 @@ class FilePath(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("MultiLine", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="MultiLine", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -255,7 +255,7 @@ class MultiLine(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("Columns", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="Columns", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -301,7 +301,7 @@ and more!"""
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("ComplexType", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="ComplexType", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -347,7 +347,7 @@ class ComplexType(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("WithDefault", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="WithDefault", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -395,7 +395,7 @@ class WithDefault(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("DefaultPath", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="DefaultPath", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -440,7 +440,7 @@ class DefaultPath(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("EmptyDesc", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="EmptyDesc", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -491,7 +491,7 @@ class EmptyDesc(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("LongDesc", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="LongDesc", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -540,7 +540,7 @@ class LongDesc(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("UnicodeTest", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="UnicodeTest", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -585,7 +585,7 @@ class UnicodeTest(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("CRLF", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="CRLF", structure_blueprint=blueprint)
expected_code = '''\
"""
@@ -644,7 +644,7 @@ class CRLF(StructuredContent):
}
generator = StructureGenerator()
- generated_code, generated_class = generator.generate_from_structure_blueprint("AnimalRecord", blueprint)
+ generated_code, generated_class = generator.generate_from_structure_blueprint(class_name="AnimalRecord", structure_blueprint=blueprint)
expected_code = '''\
"""
diff --git a/tests/unit/pipelex/core/concepts/test_concept.py b/tests/unit/pipelex/core/concepts/test_concept.py
index 07a6533b5..7cf2e01a6 100644
--- a/tests/unit/pipelex/core/concepts/test_concept.py
+++ b/tests/unit/pipelex/core/concepts/test_concept.py
@@ -307,21 +307,21 @@ class TestConcept:
blueprint_or_string_description=ConceptBlueprint(description="Lorem Ipsum"),
)
- assert Concept.are_concept_compatible(concept_7, concept_6, strict=True) is False
- assert Concept.are_concept_compatible(concept_7, concept_6, strict=False) is False
+ assert Concept.are_concept_compatible(concept_1=concept_7, concept_2=concept_6, strict=True) is False
+ assert Concept.are_concept_compatible(concept_1=concept_7, concept_2=concept_6, strict=False) is False
# Test same code and domain
- assert Concept.are_concept_compatible(concept1, concept2) is True
+ assert Concept.are_concept_compatible(concept_1=concept1, concept_2=concept2) is True
# Test different code and domain
- assert Concept.are_concept_compatible(concept1, concept3) is True
+ assert Concept.are_concept_compatible(concept_1=concept1, concept_2=concept3) is True
# Test same structure class name
- assert Concept.are_concept_compatible(concept1, concept4) is False
+ assert Concept.are_concept_compatible(concept_1=concept1, concept_2=concept4) is False
# Test same refines
- assert Concept.are_concept_compatible(concept_5, concept_6, strict=False) is True
- assert Concept.are_concept_compatible(concept_5, concept_6, strict=True) is False
+ assert Concept.are_concept_compatible(concept_1=concept_5, concept_2=concept_6, strict=False) is True
+ assert Concept.are_concept_compatible(concept_1=concept_5, concept_2=concept_6, strict=True) is False
def test_concept_refining_text_is_strictly_compatible(self):
"""Test that a concept created with .make() that refines native.Text is strictly compatible with Text."""
@@ -338,8 +338,8 @@ class TestConcept:
text_concept = ConceptFactory.make_native_concept(native_concept_code=NativeConceptCode.TEXT)
# A concept that refines Text should be strictly compatible with Text
- assert Concept.are_concept_compatible(concept_not_native_text, text_concept, strict=True) is True
- assert Concept.are_concept_compatible(concept_not_native_text, text_concept, strict=False) is True
+ assert Concept.are_concept_compatible(concept_1=concept_not_native_text, concept_2=text_concept, strict=True) is True
+ assert Concept.are_concept_compatible(concept_1=concept_not_native_text, concept_2=text_concept, strict=False) is True
def test_concept_with_same_structure_as_text_content(self):
"""Test: create a concept with a structure EXACTLY like TextContent (text: str) and compare with native Text."""
@@ -366,8 +366,8 @@ class TestConcept:
assert custom_text_like_concept.structure_class_name != native_text_concept.structure_class_name
# Concepts with the same JSON structure should be compatible
- assert Concept.are_concept_compatible(custom_text_like_concept, native_text_concept, strict=True) is True
- assert Concept.are_concept_compatible(custom_text_like_concept, native_text_concept, strict=False) is True
+ assert Concept.are_concept_compatible(concept_1=custom_text_like_concept, concept_2=native_text_concept, strict=True) is True
+ assert Concept.are_concept_compatible(concept_1=custom_text_like_concept, concept_2=native_text_concept, strict=False) is True
def test_nested_image_content_strict_false_nonstrict_true(self):
"""Test: strict=True returns False, strict=False returns True for nested compatible field."""
@@ -396,18 +396,18 @@ class TestConcept:
# --- Test with NestedImageInfo (custom class with same structure as ImageContent) ---
# strict=True should be False: DocumentWithNestedImage is NOT structurally equivalent to NestedImageInfo
- assert Concept.are_concept_compatible(concept_with_nested_image, concept_image_like, strict=True) is False
+ assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=concept_image_like, strict=True) is False
# strict=False should be True: DocumentWithNestedImage has a field (metadata) that is NestedImageInfo
- assert Concept.are_concept_compatible(concept_with_nested_image, concept_image_like, strict=False) is True
+ assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=concept_image_like, strict=False) is True
# --- Test NestedImageInfo vs native Image (ImageContent) ---
# NestedImageInfo has the same structure as ImageContent, so should be strictly compatible
- assert Concept.are_concept_compatible(concept_image_like, native_image_concept, strict=True) is True
- assert Concept.are_concept_compatible(concept_image_like, native_image_concept, strict=False) is True
+ assert Concept.are_concept_compatible(concept_1=concept_image_like, concept_2=native_image_concept, strict=True) is True
+ assert Concept.are_concept_compatible(concept_1=concept_image_like, concept_2=native_image_concept, strict=False) is True
# --- Test DocumentWithNestedImage vs native Image (ImageContent) ---
# strict=True should be False: DocumentWithNestedImage is NOT structurally equivalent to ImageContent
- assert Concept.are_concept_compatible(concept_with_nested_image, native_image_concept, strict=True) is False
+ assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=native_image_concept, strict=True) is False
# strict=False should be True: DocumentWithNestedImage has a nested field (metadata: NestedImageInfo)
# that is STRUCTURALLY EQUIVALENT to ImageContent
- assert Concept.are_concept_compatible(concept_with_nested_image, native_image_concept, strict=False) is True
+ assert Concept.are_concept_compatible(concept_1=concept_with_nested_image, concept_2=native_image_concept, strict=False) is True
diff --git a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py
index 7eeec4556..9da17d5b4 100644
--- a/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py
+++ b/tests/unit/pipelex/core/concepts/test_concept_representation_generator.py
@@ -115,38 +115,38 @@ class TestGenerateFieldValueBasicTypes:
def test_string_field(self) -> None:
"""String field generates 'fieldname_value'."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(str, "my_field")
+ result = generator.generate_field_value(str, field_name="my_field")
assert result == "my_field_value"
def test_int_field(self) -> None:
"""Int field generates 0."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(int, "count")
+ result = generator.generate_field_value(int, field_name="count")
assert result == 0
def test_float_field(self) -> None:
"""Float field generates 0.0."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(float, "rate")
+ result = generator.generate_field_value(float, field_name="rate")
assert result == 0.0
def test_bool_field(self) -> None:
"""Bool field generates False."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(bool, "active")
+ result = generator.generate_field_value(bool, field_name="active")
assert result is False
def test_int_or_float_union_field(self) -> None:
"""Int | float union field generates a numeric value (1), not a string placeholder."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(int | float, "number")
+ result = generator.generate_field_value(int | float, field_name="number")
assert isinstance(result, (int, float)), f"Expected int or float, got {type(result)}: {result}"
assert result == 1
def test_float_or_int_union_field(self) -> None:
"""Float | int union field generates a numeric value (1), not a string placeholder."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(float | int, "amount")
+ result = generator.generate_field_value(float | int, field_name="amount")
assert isinstance(result, (int, float)), f"Expected int or float, got {type(result)}: {result}"
assert result == 1
@@ -162,54 +162,54 @@ class TestGenerateFieldValueComplexTypes:
def test_enum_field(self) -> None:
"""Enum field generates first enum value."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(StatusEnum, "status")
+ result = generator.generate_field_value(StatusEnum, field_name="status")
assert result == "pending"
def test_list_of_strings(self) -> None:
"""List[str] generates list with one placeholder."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(list[str], "tags")
+ result = generator.generate_field_value(list[str], field_name="tags")
assert result == ["tags_item_value"]
def test_list_of_nested_content_json(self) -> None:
"""List[StuffContent] generates list with nested dict (JSON)."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(list[NestedChild], "children")
+ result = generator.generate_field_value(list[NestedChild], field_name="children")
expected = [{"value": "value_value"}]
assert result == expected
def test_list_of_nested_content_python(self) -> None:
"""List[StuffContent] generates list with instantiation (Python)."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- result = generator.generate_field_value(list[NestedChild], "children")
+ result = generator.generate_field_value(list[NestedChild], field_name="children")
expected = ['NestedChild(value="value_value")']
assert result == expected
def test_dict_field(self) -> None:
"""Dict field generates placeholder dict."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(dict[str, str], "metadata")
+ result = generator.generate_field_value(dict[str, str], field_name="metadata")
expected = {"metadata_key": "metadata_value"}
assert result == expected
def test_nested_content_json(self) -> None:
"""Nested StuffContent generates dict (JSON)."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(NestedChild, "child")
+ result = generator.generate_field_value(NestedChild, field_name="child")
expected = {"value": "value_value"}
assert result == expected
def test_nested_content_python(self) -> None:
"""Nested StuffContent generates instantiation (Python)."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- result = generator.generate_field_value(NestedChild, "child")
+ result = generator.generate_field_value(NestedChild, field_name="child")
expected = 'NestedChild(value="value_value")'
assert result == expected
def test_optional_field_unwrapped(self) -> None:
"""Optional[str] is unwrapped and handled as str."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(str | None, "name")
+ result = generator.generate_field_value(str | None, field_name="name")
assert result == "name_value"
@@ -317,7 +317,7 @@ class TestGenerateRepresentation:
def test_wraps_with_concept_json(self) -> None:
"""Result is wrapped with concept (JSON)."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.SimpleContent", SimpleContent)
+ result = generator.generate_representation("test.SimpleContent", structure_class=SimpleContent)
expected = {
"concept": "test.SimpleContent",
"content": {
@@ -332,7 +332,7 @@ class TestGenerateRepresentation:
def test_wraps_with_concept_python(self) -> None:
"""Result is wrapped with concept (Python)."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.PYTHON)
- result = generator.generate_representation("test.SimpleContent", SimpleContent)
+ result = generator.generate_representation("test.SimpleContent", structure_class=SimpleContent)
expected = {
"concept": "test.SimpleContent",
"content": 'SimpleContent(name="name_value", count=0, rate=0.0, active=False)',
@@ -342,7 +342,7 @@ class TestGenerateRepresentation:
def test_nested_structure_wrapped(self) -> None:
"""Nested structure is wrapped correctly."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_representation("test.Nested", ContentWithNestedClass)
+ result = generator.generate_representation("test.Nested", structure_class=ContentWithNestedClass)
expected = {
"concept": "test.Nested",
"content": {"child": {"value": "value_value"}},
@@ -361,21 +361,21 @@ class TestImportsTracking:
def test_tracks_main_class(self) -> None:
"""Tracks the main class."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- generator.generate_representation("test.Simple", SimpleContent)
+ generator.generate_representation("test.Simple", structure_class=SimpleContent)
assert "SimpleContent" in generator.imports_needed
def test_tracks_nested_classes(self) -> None:
"""Tracks nested classes."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- generator.generate_representation("test.Nested", ContentWithNestedClass)
+ generator.generate_representation("test.Nested", structure_class=ContentWithNestedClass)
assert "ContentWithNestedClass" in generator.imports_needed
assert "NestedChild" in generator.imports_needed
def test_clears_on_new_generation(self) -> None:
"""Clears imports on new generation call."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- generator.generate_representation("test.Nested", ContentWithNestedClass)
- generator.generate_representation("test.Simple", SimpleContent)
+ generator.generate_representation("test.Nested", structure_class=ContentWithNestedClass)
+ generator.generate_representation("test.Simple", structure_class=SimpleContent)
assert "NestedChild" not in generator.imports_needed
assert "SimpleContent" in generator.imports_needed
@@ -390,7 +390,7 @@ class TestConvenienceFunctions:
def test_generate_json_representation(self) -> None:
"""generate_json_representation returns correct result."""
- result = generate_json_representation("test.Simple", SimpleContent)
+ result = generate_json_representation("test.Simple", structure_class=SimpleContent)
expected = {
"concept": "test.Simple",
"content": {
@@ -404,7 +404,7 @@ class TestConvenienceFunctions:
def test_generate_python_representation(self) -> None:
"""generate_python_representation returns correct result and imports."""
- result, imports = generate_python_representation("test.Simple", SimpleContent)
+ result, imports = generate_python_representation("test.Simple", structure_class=SimpleContent)
expected = {
"concept": "test.Simple",
"content": 'SimpleContent(name="name_value", count=0, rate=0.0, active=False)',
diff --git a/tests/unit/pipelex/core/concepts/test_concept_representation_generator_literal.py b/tests/unit/pipelex/core/concepts/test_concept_representation_generator_literal.py
index 32182e857..aba3ed2e1 100644
--- a/tests/unit/pipelex/core/concepts/test_concept_representation_generator_literal.py
+++ b/tests/unit/pipelex/core/concepts/test_concept_representation_generator_literal.py
@@ -59,7 +59,7 @@ class TestGenerateFieldValueLiteralTypes:
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
result = generator.generate_field_value(
Literal["Casual", "Professional", "Humorous", "Academic"],
- "tone",
+ field_name="tone",
)
assert result in TONE_CHOICES, f"Expected one of {TONE_CHOICES}, got {result!r}"
@@ -68,7 +68,7 @@ class TestGenerateFieldValueLiteralTypes:
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
result = generator.generate_field_value(
Literal["Short", "Medium", "Long"],
- "length",
+ field_name="length",
)
assert result in LENGTH_CHOICES
assert "Literal" not in str(result), f"Should not contain 'Literal' placeholder, got {result!r}"
@@ -79,7 +79,7 @@ class TestGenerateFieldValueLiteralTypes:
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
result = generator.generate_field_value(
Literal["electronics", "clothing", "food"] | None,
- "category",
+ field_name="category",
)
assert result in {"electronics", "clothing", "food"}, f"Expected a valid choice, got {result!r}"
@@ -98,7 +98,7 @@ class TestGenerateFieldValueLiteralTypes:
) -> None:
"""Literal fields with different sets of choices all generate valid values."""
generator = ConceptRepresentationGenerator(ConceptRepresentationFormat.JSON)
- result = generator.generate_field_value(literal_type, "field")
+ result = generator.generate_field_value(literal_type, field_name="field")
assert result in valid_choices, f"[{topic}] Expected one of {valid_choices}, got {result!r}"
def test_class_with_literal_field_json(self) -> None:
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
index 35ab25ce3..4d01c8e3b 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
+++ b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_condition.py
@@ -46,7 +46,7 @@ class TestCollectPossibleOutputsCondition:
}
get_pipe_mock = mocker.patch(GET_REQUIRED_PIPE_TARGET, return_value=mapped_pipe)
- result = _collect_possible_outputs(condition_pipe, ConceptRepresentationFormat.JSON)
+ result = _collect_possible_outputs(condition_pipe, output_format=ConceptRepresentationFormat.JSON)
assert result == [{"concept_ref": "test.Summary", "content": {"text": "summary text"}}]
get_pipe_mock.assert_called_once_with(pipe_code="make_summary")
@@ -66,7 +66,7 @@ class TestCollectPossibleOutputsCondition:
mocker.patch(GET_REQUIRED_PIPE_TARGET, side_effect=resolve_pipe)
- result = _collect_possible_outputs(condition_pipe, ConceptRepresentationFormat.JSON)
+ result = _collect_possible_outputs(condition_pipe, output_format=ConceptRepresentationFormat.JSON)
assert [entry["content"]["from"] for entry in result] == ["alpha_branch", "mid_branch", "zeta_branch"]
@@ -78,7 +78,7 @@ class TestCollectPossibleOutputsCondition:
mapped_pipe.output.render_stuff_spec.return_value = rendered_dict
mocker.patch(GET_REQUIRED_PIPE_TARGET, return_value=mapped_pipe)
- result = _collect_possible_outputs(condition_pipe, ConceptRepresentationFormat.SCHEMA)
+ result = _collect_possible_outputs(condition_pipe, output_format=ConceptRepresentationFormat.SCHEMA)
assert result == [{"concept_ref": "test.Schema", "content": rendered_dict}]
diff --git a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
index 5ecfc1317..9c077670b 100644
--- a/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
+++ b/tests/unit/pipelex/core/pipes/output/test_output_renderer_collect_sequence.py
@@ -63,7 +63,7 @@ class TestCollectPossibleOutputsSequence:
}
get_pipe_mock = mocker.patch(GET_REQUIRED_PIPE_TARGET, return_value=final_pipe)
- result = _collect_possible_outputs(sequence_pipe, ConceptRepresentationFormat.JSON)
+ result = _collect_possible_outputs(sequence_pipe, output_format=ConceptRepresentationFormat.JSON)
assert result == [{"concept_ref": "test.Final", "content": {"text": "final output"}}]
get_pipe_mock.assert_called_once_with(pipe_code="final_step")
@@ -105,7 +105,7 @@ class TestCollectPossibleOutputsSequence:
get_pipe_mock = mocker.patch(GET_REQUIRED_PIPE_TARGET, side_effect=fake_get_required_pipe)
- result = _collect_possible_outputs(outer_pipe, ConceptRepresentationFormat.JSON)
+ result = _collect_possible_outputs(outer_pipe, output_format=ConceptRepresentationFormat.JSON)
assert result == [{"concept_ref": "test.Leaf", "content": {"text": "leaf output"}}]
assert get_pipe_mock.call_count == 2
diff --git a/tests/unit/pipelex/core/pipes/test_concept_multiplicity_formatting.py b/tests/unit/pipelex/core/pipes/test_concept_multiplicity_formatting.py
index 818dbb3f1..4f79230c2 100644
--- a/tests/unit/pipelex/core/pipes/test_concept_multiplicity_formatting.py
+++ b/tests/unit/pipelex/core/pipes/test_concept_multiplicity_formatting.py
@@ -40,4 +40,4 @@ class TestFormatConceptWithMultiplicity:
)
def test_format_concept_with_multiplicity(self, concept_code: str, multiplicity: int | bool | None, expected: str):
"""Test formatting concept codes with all multiplicity variations."""
- assert format_concept_with_multiplicity(concept_code, multiplicity) == expected
+ assert format_concept_with_multiplicity(concept_code, multiplicity=multiplicity) == expected
diff --git a/tests/unit/pipelex/core/pipes/test_is_multiplicity_compatible.py b/tests/unit/pipelex/core/pipes/test_is_multiplicity_compatible.py
index 7713574a8..13e5762fa 100644
--- a/tests/unit/pipelex/core/pipes/test_is_multiplicity_compatible.py
+++ b/tests/unit/pipelex/core/pipes/test_is_multiplicity_compatible.py
@@ -36,7 +36,7 @@ class TestIsMultiplicityCompatible:
expected: bool,
):
"""Test various multiplicity compatibility scenarios."""
- result = is_multiplicity_compatible(source_multiplicity, target_multiplicity)
+ result = is_multiplicity_compatible(source_multiplicity=source_multiplicity, target_multiplicity=target_multiplicity)
assert result == expected
def test_false_is_not_compatible_with_variable_list(self):
@@ -46,11 +46,11 @@ class TestIsMultiplicityCompatible:
because bool is a subclass of int in Python.
"""
# False should be treated as "force single output", not as a valid multiplicity
- assert is_multiplicity_compatible(False, True) is False
+ assert is_multiplicity_compatible(source_multiplicity=False, target_multiplicity=True) is False
def test_false_is_compatible_with_none(self):
"""Test that False matches None semantically (both mean single item)."""
# Note: The type system allows False as VariableMultiplicity, and semantically
# False should mean "force single", which is compatible with None (single item)
# This test documents the current behavior - False == None as integers
- assert is_multiplicity_compatible(False, None) is False
+ assert is_multiplicity_compatible(source_multiplicity=False, target_multiplicity=None) is False
diff --git a/tests/unit/pipelex/core/pipes/test_make_variable_multiplicity.py b/tests/unit/pipelex/core/pipes/test_make_variable_multiplicity.py
index a1dc65b65..2b5005748 100644
--- a/tests/unit/pipelex/core/pipes/test_make_variable_multiplicity.py
+++ b/tests/unit/pipelex/core/pipes/test_make_variable_multiplicity.py
@@ -92,8 +92,8 @@ class TestMakeVariableMultiplicity:
result = make_variable_multiplicity(nb_items=3, multiple_items=None)
assert result == 3
- # Test with positional arguments
- result = make_variable_multiplicity(5, False)
+ # Test with an explicit item count
+ result = make_variable_multiplicity(nb_items=5, multiple_items=False)
assert result == 5
# Test with mixed arguments
diff --git a/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py b/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
index 510546894..e51fd1daa 100644
--- a/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
+++ b/tests/unit/pipelex/core/stuffs/test_structured_content_render_with_images.py
@@ -67,7 +67,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, TextFormat.PLAIN)
+ result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_PLAIN_LIST
assert len(registry.images) == 3
@@ -86,7 +86,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, TextFormat.PLAIN)
+ result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_DICT
assert len(registry.images) == 2
@@ -107,7 +107,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, TextFormat.PLAIN)
+ result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_NESTED_LIST
assert len(registry.images) == 3
@@ -125,7 +125,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, TextFormat.PLAIN)
+ result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_IMAGE_RENDERABLE
assert len(registry.images) == 2
@@ -144,7 +144,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = page.render_with_images(registry, TextFormat.PLAIN)
+ result = page.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_PAGE_CONTENT_ALL
assert len(registry.images) == 3
@@ -160,7 +160,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = content.render_with_images(registry, TextFormat.PLAIN)
+ result = content.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_EMPTY_LIST
assert len(registry.images) == 0
@@ -176,7 +176,7 @@ class TestStructuredContentRenderWithImages:
)
registry = ImageRegistry()
- result = page.render_with_images(registry, TextFormat.PLAIN)
+ result = page.render_with_images(registry, text_format=TextFormat.PLAIN)
assert result == TestData.EXPECTED_NONE_PAGE_VIEW
assert len(registry.images) == 1
@@ -198,4 +198,4 @@ class TestStuffArtefactWithImagesFailFast:
registry = ImageRegistry()
with pytest.raises(TypeError, match="does not implement ImageRenderable"):
- artefact.render_with_images(registry, TextFormat.PLAIN)
+ artefact.render_with_images(registry, text_format=TextFormat.PLAIN)
diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
index e05a5e0bd..2172f8195 100644
--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py
+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
@@ -18,7 +18,6 @@ from pipelex.cogt.exceptions import (
)
from pipelex.core.interpreter.exceptions import PipelexInterpreterError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipeline.exceptions import PipeExecutionError, PipelineExecutionError, ValidateBundleError
from pipelex.system.exceptions import EnvVarNotFoundError
from pipelex.system.pipelex_service.exceptions import (
@@ -48,7 +47,6 @@ class TestClassLevelMetadata:
("pipe_execution", PipeExecutionError("boom"), ErrorDomain.RUNTIME),
("validate_bundle", ValidateBundleError("boom"), ErrorDomain.INPUT),
("interpreter", PipelexInterpreterError("boom"), ErrorDomain.INPUT),
- ("signatures_not_allowed", SignaturesNotAllowedError(offending_pipe_refs=set(), signature_refs=set(), dep_paths={}), ErrorDomain.INPUT),
("setup", PipelexSetupError("boom"), ErrorDomain.CONFIG),
("config", PipelexConfigError("boom"), ErrorDomain.CONFIG),
("service_base", PipelexServiceError("boom"), ErrorDomain.CONFIG),
@@ -104,7 +102,6 @@ class TestClassLevelMetadata:
("interpreter", PipelexInterpreterError("boom"), True),
("validate_bundle", ValidateBundleError("boom"), True),
("csv", CsvError("boom"), True),
- ("signatures_not_allowed", SignaturesNotAllowedError(offending_pipe_refs=set(), signature_refs=set(), dep_paths={}), True),
("config", PipelexConfigError("boom"), False),
("pipe_execution", PipeExecutionError("boom"), False),
("cogt", CogtError("boom"), False),
diff --git a/tests/unit/pipelex/graph/test_combo_mermaid.py b/tests/unit/pipelex/graph/test_combo_mermaid.py
index 599b4d693..a15f72714 100644
--- a/tests/unit/pipelex/graph/test_combo_mermaid.py
+++ b/tests/unit/pipelex/graph/test_combo_mermaid.py
@@ -56,7 +56,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert "No data flow information available" in result.mermaid_code
def test_controller_renders_as_subgraph(self) -> None:
@@ -88,7 +88,7 @@ class TestMermaidflow:
edges=[contains_edge],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have subgraph for controller
assert "subgraph" in result.mermaid_code
@@ -126,7 +126,7 @@ class TestMermaidflow:
edges=[contains_edge],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Stuff node should be rendered
assert "my_output" in result.mermaid_code
@@ -146,7 +146,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[consumer_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Pipeline input stuff should appear
assert "pipeline_input" in result.mermaid_code
@@ -177,7 +177,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[producer_node, consumer_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Verify producer -> stuff -> consumer edges exist
lines = result.mermaid_code.split("\n")
@@ -219,7 +219,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[producer_node, consumer1_node, consumer2_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# All pipe nodes and stuff should appear
assert "producer" in result.mermaid_code
@@ -246,7 +246,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[failed_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert ":::failed" in result.mermaid_code
def test_style_definitions_included(self) -> None:
@@ -263,7 +263,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert "classDef failed" in result.mermaid_code
assert "classDef controller" in result.mermaid_code
assert "classDef stuff" in result.mermaid_code
@@ -284,11 +284,11 @@ class TestMermaidflow:
graph_config = make_graph_config()
# Without show_stuff_codes
- result_without = MermaidflowFactory.make_from_graphspec(graph, graph_config, show_stuff_codes=False)
+ result_without = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config, show_stuff_codes=False)
assert "xyzab" not in result_without.mermaid_code # First 5 chars
# With show_stuff_codes
- result_with = MermaidflowFactory.make_from_graphspec(graph, graph_config, show_stuff_codes=True)
+ result_with = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config, show_stuff_codes=True)
assert "xyzab" in result_with.mermaid_code # First 5 chars should be shown
def test_deterministic_output(self) -> None:
@@ -336,8 +336,8 @@ class TestMermaidflow:
edges=[contains_edge_1, contains_edge_2],
)
graph_config = make_graph_config()
- result1 = MermaidflowFactory.make_from_graphspec(graph, graph_config)
- result2 = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result1 = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
+ result2 = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert result1.mermaid_code == result2.mermaid_code
def test_subgraph_depth_coloring(self) -> None:
@@ -381,7 +381,7 @@ class TestMermaidflow:
edges=[outer_contains, inner_contains],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have multiple subgraphs with different colors
assert "subgraph" in result.mermaid_code
diff --git a/tests/unit/pipelex/graph/test_combo_mermaid_with_data.py b/tests/unit/pipelex/graph/test_combo_mermaid_with_data.py
index 3d4d325c7..f26fbbfb6 100644
--- a/tests/unit/pipelex/graph/test_combo_mermaid_with_data.py
+++ b/tests/unit/pipelex/graph/test_combo_mermaid_with_data.py
@@ -62,7 +62,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert isinstance(result, Mermaidflow)
assert isinstance(result.mermaid_code, str)
@@ -82,7 +82,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data with the data content
assert result.stuff_data is not None
@@ -105,7 +105,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Keys should start with s_ prefix
assert result.stuff_data is not None
@@ -126,7 +126,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[consumer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data for the input
assert result.stuff_data is not None
@@ -158,7 +158,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node, consumer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should only have one entry for this digest
assert result.stuff_data is not None
@@ -179,8 +179,8 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
- result_with_data = MermaidflowFactory.make_from_graphspec(graph, make_graph_config(include_stuff_json=True))
- result_without_data = MermaidflowFactory.make_from_graphspec(graph, make_graph_config(include_stuff_json=False))
+ result_with_data = MermaidflowFactory.make_from_graphspec(graph, graph_config=make_graph_config(include_stuff_json=True))
+ result_without_data = MermaidflowFactory.make_from_graphspec(graph, graph_config=make_graph_config(include_stuff_json=False))
assert result_with_data.mermaid_code == result_without_data.mermaid_code
@@ -198,7 +198,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=False)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data should be None when not configured
assert result.stuff_data is None
@@ -217,7 +217,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data should be empty since data=None
assert result.stuff_data is not None
@@ -238,7 +238,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Dict data should be preserved
assert result.stuff_data is not None
@@ -261,7 +261,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_text=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data_text with the pre-rendered text
assert result.stuff_data_text is not None
@@ -284,7 +284,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_html=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data_html with the pre-rendered HTML
assert result.stuff_data_html is not None
@@ -306,7 +306,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_text=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data_text should be empty since data_text=None
assert result.stuff_data_text is not None
@@ -326,7 +326,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_html=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data_html should be empty since data_html=None
assert result.stuff_data_html is not None
diff --git a/tests/unit/pipelex/graph/test_dashed_edge_rendering.py b/tests/unit/pipelex/graph/test_dashed_edge_rendering.py
index eccf4f7a8..12eb59920 100644
--- a/tests/unit/pipelex/graph/test_dashed_edge_rendering.py
+++ b/tests/unit/pipelex/graph/test_dashed_edge_rendering.py
@@ -158,7 +158,7 @@ class TestDashedEdgeRendering:
"""Verify that each dashed-edge kind produces at least one dashed arrow."""
graph = self._build_controller_graph_with_dashed_edge(edge_kind=edge_kind)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
dashed_lines = self._extract_dashed_edges(result.mermaid_code)
assert len(dashed_lines) >= 1, f"Expected at least one dashed edge for {topic}, got none"
@@ -175,7 +175,7 @@ class TestDashedEdgeRendering:
"""Verify that labeled dashed edges include the label in the mermaid syntax."""
graph = self._build_controller_graph_with_dashed_edge(edge_kind=edge_kind, edge_label="my_label")
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
dashed_lines = self._extract_dashed_edges(result.mermaid_code)
labeled = [line for line in dashed_lines if "my_label" in line]
@@ -193,7 +193,7 @@ class TestDashedEdgeRendering:
"""Verify that unlabeled dashed edges use plain dashed arrow syntax."""
graph = self._build_controller_graph_with_dashed_edge(edge_kind=edge_kind)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
dashed_lines = self._extract_dashed_edges(result.mermaid_code)
# Unlabeled edges use `-.->` without a label string
@@ -209,7 +209,7 @@ class TestDashedEdgeRendering:
for edge_kind in (EdgeKind.BATCH_ITEM, EdgeKind.BATCH_AGGREGATE, EdgeKind.PARALLEL_COMBINE):
graph = self._build_controller_graph_with_dashed_edge(edge_kind=edge_kind, edge_label="test_label")
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
dashed_lines = self._extract_dashed_edges(result.mermaid_code)
# Extract just the arrow operator from each line (e.g., `-."test_label".->` or `-.->`)
@@ -270,7 +270,7 @@ class TestDashedEdgeRendering:
edges=[contains, aggregate_edge],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# The aggregated_output stuff should be rendered (resolved on the fly)
assert "aggregated_output" in result.mermaid_code
diff --git a/tests/unit/pipelex/graph/test_graph_output_generation.py b/tests/unit/pipelex/graph/test_graph_output_generation.py
index 8c77b1ca3..cbd1683c9 100644
--- a/tests/unit/pipelex/graph/test_graph_output_generation.py
+++ b/tests/unit/pipelex/graph/test_graph_output_generation.py
@@ -109,7 +109,7 @@ class TestGraphOutputGeneration:
graph_spec = _make_sequence_graphspec()
config = _enable_all_outputs(make_graph_config())
- outputs = await generate_graph_outputs(graph_spec, config, pipe_code="my_sequence")
+ outputs = await generate_graph_outputs(graph_spec, graph_config=config, pipe_code="my_sequence")
assert outputs.graphspec_json is not None
assert "output_test_graph" in outputs.graphspec_json
@@ -129,9 +129,9 @@ class TestGraphOutputGeneration:
graph_spec = _make_sequence_graphspec()
config = _enable_all_outputs(make_graph_config())
- outputs = await generate_graph_outputs(graph_spec, config, pipe_code="my_sequence")
+ outputs = await generate_graph_outputs(graph_spec, graph_config=config, pipe_code="my_sequence")
output_dir = tmp_path / "graph_output"
- saved_files = save_graph_outputs_to_dir(outputs, output_dir)
+ saved_files = save_graph_outputs_to_dir(outputs, output_dir=output_dir)
assert output_dir.is_dir()
assert "graphspec_json" in saved_files
@@ -163,7 +163,7 @@ class TestGraphOutputGeneration:
},
)
- outputs = await generate_graph_outputs(graph_spec, config, pipe_code="my_sequence")
+ outputs = await generate_graph_outputs(graph_spec, graph_config=config, pipe_code="my_sequence")
assert outputs.graphspec_json is not None
assert outputs.mermaidflow_mmd is None
@@ -185,7 +185,7 @@ class TestGraphOutputGeneration:
},
)
- outputs = await generate_graph_outputs(graph_spec, config, pipe_code="my_sequence")
+ outputs = await generate_graph_outputs(graph_spec, graph_config=config, pipe_code="my_sequence")
assert outputs.mermaidflow_mmd is not None
assert "step_one" in outputs.mermaidflow_mmd
diff --git a/tests/unit/pipelex/graph/test_graphspec_roundtrip.py b/tests/unit/pipelex/graph/test_graphspec_roundtrip.py
index 7f8ff01b4..8ce85d971 100644
--- a/tests/unit/pipelex/graph/test_graphspec_roundtrip.py
+++ b/tests/unit/pipelex/graph/test_graphspec_roundtrip.py
@@ -218,7 +218,7 @@ class TestGraphSpecRoundtrip:
)
file_path = tmp_path / "test_graph.json"
- save_text_to_path(graph.to_json(), file_path)
+ save_text_to_path(graph.to_json(), path=file_path)
json_str = load_text_from_path(file_path)
restored = GraphSpec.model_validate_json(json_str)
diff --git a/tests/unit/pipelex/graph/test_mermaidflow.py b/tests/unit/pipelex/graph/test_mermaidflow.py
index c875dcf39..274f8f623 100644
--- a/tests/unit/pipelex/graph/test_mermaidflow.py
+++ b/tests/unit/pipelex/graph/test_mermaidflow.py
@@ -56,7 +56,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert "No data flow information available" in result.mermaid_code
def test_controller_renders_as_subgraph(self) -> None:
@@ -88,7 +88,7 @@ class TestMermaidflow:
edges=[contains_edge],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have subgraph for controller
assert "subgraph" in result.mermaid_code
@@ -126,7 +126,7 @@ class TestMermaidflow:
edges=[contains_edge],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Stuff node should be rendered
assert "my_output" in result.mermaid_code
@@ -146,7 +146,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[consumer_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Pipeline input stuff should appear
assert "pipeline_input" in result.mermaid_code
@@ -177,7 +177,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[producer_node, consumer_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Verify producer -> stuff -> consumer edges exist
lines = result.mermaid_code.split("\n")
@@ -219,7 +219,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[producer_node, consumer1_node, consumer2_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# All pipe nodes and stuff should appear
assert "producer" in result.mermaid_code
@@ -246,7 +246,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[failed_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert ":::failed" in result.mermaid_code
def test_style_definitions_included(self) -> None:
@@ -263,7 +263,7 @@ class TestMermaidflow:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert "classDef failed" in result.mermaid_code
assert "classDef controller" in result.mermaid_code
assert "classDef stuff" in result.mermaid_code
@@ -284,11 +284,11 @@ class TestMermaidflow:
graph_config = make_graph_config()
# Without show_stuff_codes
- result_without = MermaidflowFactory.make_from_graphspec(graph, graph_config, show_stuff_codes=False)
+ result_without = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config, show_stuff_codes=False)
assert "xyzab" not in result_without.mermaid_code # First 5 chars
# With show_stuff_codes
- result_with = MermaidflowFactory.make_from_graphspec(graph, graph_config, show_stuff_codes=True)
+ result_with = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config, show_stuff_codes=True)
assert "xyzab" in result_with.mermaid_code # First 5 chars should be shown
def test_deterministic_output(self) -> None:
@@ -336,8 +336,8 @@ class TestMermaidflow:
edges=[contains_edge_1, contains_edge_2],
)
graph_config = make_graph_config()
- result1 = MermaidflowFactory.make_from_graphspec(graph, graph_config)
- result2 = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result1 = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
+ result2 = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert result1.mermaid_code == result2.mermaid_code
def test_subgraph_depth_coloring(self) -> None:
@@ -381,7 +381,7 @@ class TestMermaidflow:
edges=[outer_contains, inner_contains],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have multiple subgraphs with different colors
assert "subgraph" in result.mermaid_code
@@ -452,7 +452,7 @@ class TestMermaidflow:
edges=[contains_a, contains_b, combine_a, combine_b],
)
graph_config = make_graph_config()
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# The combined output stuff should appear inside the controller's subgraph
# (between subgraph ... and end)
diff --git a/tests/unit/pipelex/graph/test_mermaidflow_with_data.py b/tests/unit/pipelex/graph/test_mermaidflow_with_data.py
index 3d4d325c7..f26fbbfb6 100644
--- a/tests/unit/pipelex/graph/test_mermaidflow_with_data.py
+++ b/tests/unit/pipelex/graph/test_mermaidflow_with_data.py
@@ -62,7 +62,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
assert isinstance(result, Mermaidflow)
assert isinstance(result.mermaid_code, str)
@@ -82,7 +82,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data with the data content
assert result.stuff_data is not None
@@ -105,7 +105,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Keys should start with s_ prefix
assert result.stuff_data is not None
@@ -126,7 +126,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[consumer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data for the input
assert result.stuff_data is not None
@@ -158,7 +158,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node, consumer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should only have one entry for this digest
assert result.stuff_data is not None
@@ -179,8 +179,8 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
- result_with_data = MermaidflowFactory.make_from_graphspec(graph, make_graph_config(include_stuff_json=True))
- result_without_data = MermaidflowFactory.make_from_graphspec(graph, make_graph_config(include_stuff_json=False))
+ result_with_data = MermaidflowFactory.make_from_graphspec(graph, graph_config=make_graph_config(include_stuff_json=True))
+ result_without_data = MermaidflowFactory.make_from_graphspec(graph, graph_config=make_graph_config(include_stuff_json=False))
assert result_with_data.mermaid_code == result_without_data.mermaid_code
@@ -198,7 +198,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=False)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data should be None when not configured
assert result.stuff_data is None
@@ -217,7 +217,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data should be empty since data=None
assert result.stuff_data is not None
@@ -238,7 +238,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_json=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Dict data should be preserved
assert result.stuff_data is not None
@@ -261,7 +261,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_text=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data_text with the pre-rendered text
assert result.stuff_data_text is not None
@@ -284,7 +284,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_html=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# Should have stuff_data_html with the pre-rendered HTML
assert result.stuff_data_html is not None
@@ -306,7 +306,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_text=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data_text should be empty since data_text=None
assert result.stuff_data_text is not None
@@ -326,7 +326,7 @@ class TestMermaidflowWithData:
}
graph = self._make_graph(nodes=[producer_node])
graph_config = make_graph_config(include_stuff_html=True)
- result = MermaidflowFactory.make_from_graphspec(graph, graph_config)
+ result = MermaidflowFactory.make_from_graphspec(graph, graph_config=graph_config)
# stuff_data_html should be empty since data_html=None
assert result.stuff_data_html is not None
diff --git a/tests/unit/pipelex/graph/test_reactflow_html.py b/tests/unit/pipelex/graph/test_reactflow_html.py
index ac7708f80..c19dcf849 100644
--- a/tests/unit/pipelex/graph/test_reactflow_html.py
+++ b/tests/unit/pipelex/graph/test_reactflow_html.py
@@ -26,7 +26,7 @@ class TestReactFlowHtml:
def test_generates_html_with_embedded_graphspec(self) -> None:
"""Test that HTML contains embedded GraphSpec as JSON."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert "<!DOCTYPE html>" in html
assert '<script type="application/json" id="pipelex-graphspec">' in html
@@ -34,13 +34,13 @@ class TestReactFlowHtml:
def test_embeds_config_json(self) -> None:
"""Test that viewer config is embedded as JSON."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert '<script type="application/json" id="pipelex-config">' in html
def test_custom_title_in_html(self) -> None:
"""Test that custom title appears in HTML."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config(), title="My Custom Graph")
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config(), title="My Custom Graph")
assert "<title>My Custom Graph</title>" in html
@@ -60,7 +60,7 @@ class TestReactFlowHtml:
edges=[],
)
- html = generate_reactflow_html(graph, self._rf_config())
+ html = generate_reactflow_html(graph, config=self._rf_config())
assert '"id": "node_1"' in html
assert '"node_id"' not in html
@@ -68,7 +68,7 @@ class TestReactFlowHtml:
def test_html_is_valid_structure(self) -> None:
"""Test that generated HTML has valid structure."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert html.startswith("<!DOCTYPE html>")
assert "<html" in html
@@ -77,21 +77,21 @@ class TestReactFlowHtml:
def test_html_loads_mthds_ui_js_from_cdn_with_sri(self) -> None:
"""The HTML must reference the pinned mthds-ui JS bundle on jsDelivr with SRI."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
expected = f'<script src="{MTHDS_UI_JS.url}" integrity="{MTHDS_UI_JS.integrity}" crossorigin="{MTHDS_UI_JS.crossorigin}"></script>'
assert expected in html
def test_html_loads_mthds_ui_css_from_cdn_with_sri(self) -> None:
"""The HTML must reference the pinned mthds-ui CSS on jsDelivr with SRI."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
expected = f'<link rel="stylesheet" href="{MTHDS_UI_CSS.url}" integrity="{MTHDS_UI_CSS.integrity}" crossorigin="{MTHDS_UI_CSS.crossorigin}">'
assert expected in html
def test_html_loads_elkjs_from_jsdelivr_with_sri(self) -> None:
"""Elkjs must come from jsDelivr (not unpkg) and carry an SRI hash."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
expected = f'<script src="{ELKJS.url}" integrity="{ELKJS.integrity}" crossorigin="{ELKJS.crossorigin}"></script>'
assert expected in html
@@ -99,7 +99,7 @@ class TestReactFlowHtml:
def test_html_does_not_inline_bundle_contents(self) -> None:
"""Bundle bytes must not be inlined — externalized via <link>/<script src>."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
# Tokens that only exist inside the IIFE bundle / CSS bundle.
assert '"use strict"' not in html
@@ -108,26 +108,26 @@ class TestReactFlowHtml:
def test_json_data_scripts_have_no_nonce(self) -> None:
"""Verify application/json script tags do NOT have a nonce attribute."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert '<script type="application/json" id="pipelex-graphspec">' in html
assert '<script type="application/json" id="pipelex-config">' in html
def test_no_csp_meta_tag(self) -> None:
"""Verify no CSP meta tag is present."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert "Content-Security-Policy" not in html
def test_script_tag_count(self) -> None:
"""Verify exactly 4 closing script tags (graphspec, config, elkjs CDN, IIFE)."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert html.count("</script>") == 4
def test_no_legacy_toolbar(self) -> None:
"""Verify the old hand-rendered toolbar is gone; mthds-ui v0.6+ owns chrome."""
- html = generate_reactflow_html(self._empty_graphspec(), self._rf_config())
+ html = generate_reactflow_html(self._empty_graphspec(), config=self._rf_config())
assert '<div class="toolbar">' not in html
assert 'id="direction-toggle"' not in html
diff --git a/tests/unit/pipelex/graph/test_smoke_html_render.py b/tests/unit/pipelex/graph/test_smoke_html_render.py
index 1795cc238..e1e3cffba 100644
--- a/tests/unit/pipelex/graph/test_smoke_html_render.py
+++ b/tests/unit/pipelex/graph/test_smoke_html_render.py
@@ -19,7 +19,7 @@ class TestSmokeHtmlRender:
)
config = get_config().pipelex.pipeline_execution_config.graph_config.reactflow_config
- html = generate_reactflow_html(graph, config)
+ html = generate_reactflow_html(graph, config=config)
assert "cdn.jsdelivr.net/npm/@pipelex/mthds-ui" in html
assert "cdn.jsdelivr.net/npm/elkjs" in html
diff --git a/tests/unit/pipelex/language/test_mthds_factory.py b/tests/unit/pipelex/language/test_mthds_factory.py
index 7988c13f2..8fb1550b6 100644
--- a/tests/unit/pipelex/language/test_mthds_factory.py
+++ b/tests/unit/pipelex/language/test_mthds_factory.py
@@ -129,7 +129,7 @@ class TestMthdsFactoryUnit:
input_dict = {"key2": "value2", "key1": "value1", "key3": "value3"}
field_ordering = ["key1", "key3"]
- result = MthdsFactory.convert_dicts_to_inline_tables(input_dict, field_ordering)
+ result = MthdsFactory.convert_dicts_to_inline_tables(input_dict, field_ordering=field_ordering)
assert isinstance(result, tomlkit.items.InlineTable) # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
# All input keys must be present in the result
@@ -181,7 +181,7 @@ class TestMthdsFactoryUnit:
"""Test that all input fields are preserved in the output regardless of field_ordering."""
_mock_config = mocker.patch.object(MthdsFactory, "_mthds_config", return_value=mock_mthds_config)
- result = MthdsFactory.convert_dicts_to_inline_tables(input_dict, field_ordering or None)
+ result = MthdsFactory.convert_dicts_to_inline_tables(input_dict, field_ordering=field_ordering or None)
assert isinstance(result, tomlkit.items.InlineTable) # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
result_keys = set(result.keys())
@@ -250,7 +250,7 @@ class TestMthdsFactoryUnit:
mapping = {"field3": "value3", "field1": "value1", "field2": "value2"}
field_ordering = ["field1", "field2"]
- result = MthdsFactory.convert_mapping_to_table(mapping, field_ordering)
+ result = MthdsFactory.convert_mapping_to_table(mapping, field_ordering=field_ordering)
assert isinstance(result, tomlkit.items.Table) # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType]
# Check ordering (note: tomlkit preserves insertion order)
diff --git a/tests/unit/pipelex/pipe_run/test_pipe_run_params.py b/tests/unit/pipelex/pipe_run/test_pipe_run_params.py
index f3839a84e..762824f9e 100644
--- a/tests/unit/pipelex/pipe_run/test_pipe_run_params.py
+++ b/tests/unit/pipelex/pipe_run/test_pipe_run_params.py
@@ -23,7 +23,7 @@ class TestOutputMultiplicityToApply:
description: str,
):
"""Test output_multiplicity_to_apply with all parameter combinations."""
- result = output_multiplicity_to_apply(base, override)
+ result = output_multiplicity_to_apply(base_multiplicity=base, override_multiplicity=override)
assert result.resolved_multiplicity == expected_result.resolved_multiplicity, f"Failed resolved_multiplicity for case: {description}"
assert result.is_multiple_outputs_enabled == expected_result.is_multiple_outputs_enabled, (
f"Failed enable_multiple_outputs for case: {description}"
@@ -33,7 +33,7 @@ class TestOutputMultiplicityToApply:
def test_override_none_uses_base(self):
"""Test that when override is None, base value is used as-is."""
# Base None -> single output
- result = output_multiplicity_to_apply(None, None)
+ result = output_multiplicity_to_apply(base_multiplicity=None, override_multiplicity=None)
assert result.resolved_multiplicity is None
assert result.is_multiple_outputs_enabled is False
assert result.specific_output_count is None
diff --git a/tests/unit/pipelex/pipeline/test_bundle_validator.py b/tests/unit/pipelex/pipeline/test_bundle_validator.py
index f0969a5c4..907899cc3 100644
--- a/tests/unit/pipelex/pipeline/test_bundle_validator.py
+++ b/tests/unit/pipelex/pipeline/test_bundle_validator.py
@@ -1,10 +1,10 @@
"""Unit tests for the BundleValidator classify engine (Phase 2).
These pin the tolerant per-pipe classification, the D3 union catch + recursive SKIPPED
-cause-walk, the D7 wiring-before-signature precedence, the single collect-all aggregate
-(no per-pipe early abort), and the per-sweep telemetry. The seams (``prepare_pipe_job``)
-and the run primitive (``PipeRun``) are mocked here; the real composition is exercised by
-the integration suite.
+cause-walk, the strict-mode signature exclusion (signatures are never an error — D-B), the
+single collect-all aggregate (no per-pipe early abort), and the per-sweep telemetry. The seams
+(``prepare_pipe_job``) and the run primitive (``PipeRun``) are mocked here; the real composition
+is exercised by the integration suite.
"""
import pytest
@@ -16,7 +16,6 @@ from pipelex.base_exceptions import PipelexError
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_run.exceptions import DryRunError, PipeRunError
from pipelex.pipe_run.pipe_run_mode import PipeRunMode
-from pipelex.pipe_signature.exceptions import SignaturesNotAllowedError
from pipelex.pipeline.bundle_validator import BundleValidator, DryRunStatus
from pipelex.system.telemetry.events import EventName, EventProperty
@@ -171,53 +170,41 @@ class TestBundleValidator:
assert "dom.b_pipe" in message
@pytest.mark.asyncio
- async def test_strict_signature_pre_pass_raises_before_sweep(self, mocker: MockerFixture) -> None:
- # In strict mode a reached signature raises the aggregated SignaturesNotAllowedError before any
- # pipe is dry-run — so the seam (prepare_pipe_job) is never invoked.
+ async def test_strict_mode_excludes_signature_pipes_from_sweep(self, mocker: MockerFixture) -> None:
+ # Signatures are never an error (D-B): in strict mode a signature pipe is excluded from the sweep
+ # entirely — not mock-run (the seam is never invoked) and absent from the returned status map (so
+ # absent from validated_pipes). The unsatisfied set is reported library-wide via pending_signatures.
validator, _telemetry, prepare_mock, _pipe_run = self._patch_env(mocker)
signature_pipe = self._make_pipe(mocker, code="sig_pipe", pipe_ref="dom.sig_pipe", is_signature=True)
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await validator.validate_pipes([signature_pipe], library_id="lib-1", allow_signatures=False)
- assert "dom.sig_pipe" in exc_info.value.signature_refs
+ results = await validator.validate_pipes([signature_pipe], library_id="lib-1", allow_signatures=False)
+
+ assert results == {}
prepare_mock.assert_not_called()
@pytest.mark.asyncio
- async def test_validate_with_libraries_error_precedes_signature_pre_pass(self, mocker: MockerFixture) -> None:
- # D7 precedence: the static wiring pass runs (and can raise) BEFORE the signature pre-pass, so a
- # wiring failure surfaces ahead of a signature error even when both are present.
+ async def test_lenient_mode_sweeps_signature_pipes(self, mocker: MockerFixture) -> None:
+ # allow_signatures is sweep mechanics (D-B): in lenient mode a signature pipe IS swept (it dry-runs
+ # trivially by minting a mock) and therefore appears in the returned status map / validated_pipes.
+ validator, _telemetry, prepare_mock, _pipe_run = self._patch_env(mocker)
+ signature_pipe = self._make_pipe(mocker, code="sig_pipe", pipe_ref="dom.sig_pipe", is_signature=True)
+
+ results = await validator.validate_pipes([signature_pipe], library_id="lib-1", allow_signatures=True)
+
+ assert results["dom.sig_pipe"].status.is_success
+ prepare_mock.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_wiring_error_propagates(self, mocker: MockerFixture) -> None:
+ # The static wiring pass runs first and can raise (real validate_with_libraries raises
+ # PipeValidationError) — a wiring failure aborts the sweep rather than being swallowed.
validator, _telemetry, _prepare, _pipe_run = self._patch_env(mocker)
- spy_collect = mocker.patch("pipelex.pipeline.bundle_validator.collect_signature_refs")
wiring_pipe = self._make_pipe(mocker, code="wiring_pipe", pipe_ref="dom.wiring_pipe")
# Stand-in for a wiring error (real validate_with_libraries raises PipeValidationError).
wiring_pipe.validate_with_libraries.side_effect = RuntimeError("wiring failed")
- signature_pipe = self._make_pipe(mocker, code="sig_pipe", pipe_ref="dom.sig_pipe", is_signature=True)
with pytest.raises(RuntimeError, match="wiring failed"):
- await validator.validate_pipes([wiring_pipe, signature_pipe], library_id="lib-1", allow_signatures=False)
- # The signature pre-pass was never reached — the wiring pass pre-empted it.
- spy_collect.assert_not_called()
-
- @pytest.mark.asyncio
- async def test_signature_behind_cross_package_wiring_gap_still_raises(self, mocker: MockerFixture) -> None:
- # A pipe dropped to SKIPPED in step 1 for an unresolved cross-package dependency must STILL be
- # signature-checked: the strict pre-pass runs over the FULL pipe list, not just the wiring
- # survivors. Otherwise an unimplemented PipeSignature hidden behind a wiring gap would silently
- # pass strict validation (the old dry_run_pipes ran the pre-pass over all pipes first).
- validator, _telemetry, prepare_mock, _pipe_run = self._patch_env(mocker)
- # Step 1 drops this pipe to SKIPPED — its wiring references an unloaded cross-package sub-pipe...
- pipe = self._make_pipe(mocker, code="hybrid_pipe", pipe_ref="dom.hybrid_pipe")
- pipe.validate_with_libraries.side_effect = PipeNotFoundError("hybrid->other.missing not found")
- # ...but it also reaches an unimplemented signature through a RESOLVED branch (real
- # collect_signature_refs tolerates the unresolved branch via get_optional_pipe and still finds it).
- mocker.patch("pipelex.pipeline.bundle_validator.collect_signature_refs", return_value={"dom.unimplemented_sig"})
- mocker.patch("pipelex.pipeline.bundle_validator.collect_signature_paths", return_value={})
-
- with pytest.raises(SignaturesNotAllowedError) as exc_info:
- await validator.validate_pipes([pipe], library_id="lib-1", allow_signatures=False)
- assert "dom.unimplemented_sig" in exc_info.value.signature_refs
- # The signature is caught at the pre-pass, before any dry-run of the (SKIPPED) pipe.
- prepare_mock.assert_not_called()
+ await validator.validate_pipes([wiring_pipe], library_id="lib-1", allow_signatures=False)
@pytest.mark.asyncio
async def test_one_pipe_dry_run_event_emitted_for_the_sweep(self, mocker: MockerFixture) -> None:
diff --git a/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py b/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py
index 20dbb3c4d..558ee0a50 100644
--- a/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py
+++ b/tests/unit/pipelex/pipeline/test_runner_execute_error_paths.py
@@ -42,7 +42,7 @@ class _RaisingPipeRun(PipeRunProtocol):
self._exc = exc
@override
- async def run(self, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
+ async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:
raise self._exc
diff --git a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
index 7aca19c1c..349f82d79 100644
--- a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
+++ b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
@@ -41,27 +41,28 @@ class _ValidateEnv(NamedTuple):
class TestRunnerValidatePlumbing:
def _patch_env(self, mocker: MockerFixture, *, library_ids: list[str | None]) -> _ValidateEnv:
"""Patch ``validate_bundle``, the library hub getters, and the report-artifact builders
- at the runner namespace so ``validate``'s body runs without a real loaded library.
+ at the ``validate_in_process`` namespace (the shared orchestrator the protocol ``validate``
+ wrapper delegates to) so the body runs without a real loaded library.
``library_ids`` feeds ``get_current_library_id_or_none`` as a side_effect pair: first
call = the caller's prev library, second call = the validation library left current by
``validate_bundle``.
"""
validate_bundle_mock = mocker.patch(
- "pipelex.pipeline.runner.validate_bundle",
+ "pipelex.pipeline.validate_in_process.validate_bundle",
new=mocker.AsyncMock(return_value=mocker.MagicMock(name="validate_bundle_result")),
)
- mocker.patch("pipelex.pipeline.runner.get_current_library_id_or_none", side_effect=library_ids)
- set_current_library_mock = mocker.patch("pipelex.pipeline.runner.set_current_library")
- clear_current_library_mock = mocker.patch("pipelex.pipeline.runner.clear_current_library")
- library_manager = mocker.patch("pipelex.pipeline.runner.get_library_manager").return_value
+ mocker.patch("pipelex.pipeline.validate_in_process.get_current_library_id_or_none", side_effect=library_ids)
+ set_current_library_mock = mocker.patch("pipelex.pipeline.validate_in_process.set_current_library")
+ clear_current_library_mock = mocker.patch("pipelex.pipeline.validate_in_process.clear_current_library")
+ library_manager = mocker.patch("pipelex.pipeline.validate_in_process.get_library_manager").return_value
# These artifact builders run inside the library window; mock them so the body completes
# without a real loaded library. Their output shaping is pinned in test_validation_report.py
# and the integration test_protocol_validate.py — this module asserts only the plumbing.
- mocker.patch("pipelex.pipeline.runner.build_pipe_io_contracts", return_value={})
- mocker.patch("pipelex.pipeline.runner.select_primary_blueprint")
- mocker.patch("pipelex.pipeline.runner.best_effort_graph_spec", new=mocker.AsyncMock(return_value=None))
- mocker.patch("pipelex.pipeline.runner.build_validation_report")
+ mocker.patch("pipelex.pipeline.validate_in_process.build_pipe_io_contracts", return_value={})
+ mocker.patch("pipelex.pipeline.validate_in_process.select_primary_blueprint")
+ mocker.patch("pipelex.pipeline.validate_in_process.best_effort_graph_spec", new=mocker.AsyncMock(return_value=None))
+ mocker.patch("pipelex.pipeline.validate_in_process.build_validation_report")
return _ValidateEnv(
validate_bundle_mock=validate_bundle_mock,
set_current_library_mock=set_current_library_mock,
@@ -78,6 +79,7 @@ class TestRunnerValidatePlumbing:
env.validate_bundle_mock.assert_awaited_once_with(
mthds_contents=["bundle-content"],
+ mthds_sources=None,
library_dirs=[Path("dir_alpha"), Path("nested/dir_beta")],
allow_signatures=True,
)
@@ -91,6 +93,7 @@ class TestRunnerValidatePlumbing:
env.validate_bundle_mock.assert_awaited_once_with(
mthds_contents=["bundle-content"],
+ mthds_sources=None,
library_dirs=None,
allow_signatures=False,
)
diff --git a/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py b/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
new file mode 100644
index 000000000..bf9c3f18b
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_validate_bundle_error_report.py
@@ -0,0 +1,83 @@
+"""Unit tests for ``ValidateBundleError.to_error_report`` — structured errors on the wire.
+
+The override attaches the shared ``build_validation_error_items`` output onto
+``ErrorReport.validation_errors``, so the RFC 7807 problem document the API emits
+on a 422 carries machine-mappable per-error diagnostics (with ``source``) instead
+of only a single ``detail`` string. The cause-chain enrichment from the base
+``to_error_report`` is preserved.
+"""
+
+from pipelex.base_exceptions import DisclosureMode, ErrorDomain, ValidationErrorCategory
+from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData
+from pipelex.core.exceptions import PipesAndConceptValidationErrorData
+from pipelex.core.pipes.exceptions import PipeValidationErrorType
+from pipelex.pipeline.exceptions import ValidateBundleError
+
+
+def _error_with_two_categories() -> ValidateBundleError:
+ return ValidateBundleError(
+ message="bundle 'main.mthds' failed validation",
+ pipelex_bundle_blueprint_validation_errors=[
+ PipelexBundleBlueprintValidationErrorData(
+ error_type=PipeValidationErrorType.INVALID_PIPE_CODE_SYNTAX,
+ source="main.mthds",
+ message="Invalid main pipe syntax 'Not A Pipe'",
+ ),
+ ],
+ pipe_validation_errors=[
+ PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
+ source="helpers.mthds",
+ pipe_code="summarize",
+ message="Missing input variable(s): doc.",
+ field_path="summarize.inputs.doc",
+ variable_names=["doc"],
+ ),
+ ],
+ )
+
+
+class TestValidateBundleErrorReport:
+ def test_to_error_report_populates_validation_errors(self) -> None:
+ """``to_error_report`` attaches one structured item per underlying error."""
+ report = _error_with_two_categories().to_error_report()
+ assert report.validation_errors is not None
+ sources = sorted(item.source or "" for item in report.validation_errors)
+ assert sources == ["helpers.mthds", "main.mthds"]
+
+ def test_report_keeps_caller_facing_input_classification(self) -> None:
+ """The base classification (INPUT domain, caller-facing message) still holds."""
+ report = _error_with_two_categories().to_error_report()
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.caller_facing_message is True
+ assert report.error_type == "ValidateBundleError"
+
+ def test_message_only_error_surfaces_a_residual_item(self) -> None:
+ """No categorized errors → a ``blueprint_validation`` residual still rides the wire (invariant is total).
+
+ ``to_error_report`` passes ``fallback_message=self.message``, so a parse-level failure that
+ carries only a message (TOML syntax, an empty blueprint, a bundle elaborator) projects one
+ residual item rather than a bare ``detail`` with an empty ``validation_errors[]``.
+ """
+ report = ValidateBundleError(message="generic failure").to_error_report()
+ assert report.validation_errors is not None
+ assert [item.category for item in report.validation_errors] == [ValidationErrorCategory.BLUEPRINT_VALIDATION]
+ assert report.validation_errors[0].message == "generic failure"
+
+ def test_problem_document_carries_validation_errors_with_source(self) -> None:
+ """The 422 problem document rides ``validation_errors[]`` as an extension member."""
+ document = _error_with_two_categories().to_error_report().to_problem_document()
+ assert document["status"] == 422
+ items = document["validation_errors"]
+ assert {item["source"] for item in items} == {"main.mthds", "helpers.mthds"}
+ assert {item["category"] for item in items} == {"blueprint_validation", "pipe_validation"}
+
+ def test_strict_problem_document_retains_validation_errors(self) -> None:
+ """STRICT disclosure keeps ``validation_errors`` — they are the caller's own bundle diagnostics.
+
+ ``ValidateBundleError`` is a caller-facing INPUT error, so STRICT also
+ keeps the ``detail`` message; the structured items ride alongside it.
+ """
+ document = _error_with_two_categories().to_error_report().to_problem_document(disclosure_mode=DisclosureMode.STRICT)
+ assert "validation_errors" in document
+ assert len(document["validation_errors"]) == 2
diff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.py
new file mode 100644
index 000000000..2175b49bd
--- /dev/null
+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py
@@ -0,0 +1,298 @@
+"""Unit tests for ``build_validation_error_items`` — the shared structured-error builder.
+
+The single builder feeds both the agent CLI's ``validation_errors`` JSON array
+(via ``extract_validation_errors``) and the API 422's
+``ErrorReport.validation_errors`` (via ``ValidateBundleError.to_error_report``),
+so the two surfaces can never drift. These tests pin the per-category field
+projection — including the ``source`` / ``field_name`` / ``concept_code`` fields
+that the older CLI-only extractor dropped — and the CLI↔API shape parity.
+"""
+
+import json
+
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.cli.agent_cli.commands.agent_output import extract_validation_errors
+from pipelex.core.bundles.exceptions import PipelexBundleBlueprintValidationErrorData
+from pipelex.core.exceptions import PipeFactoryErrorData, PipesAndConceptValidationErrorData
+from pipelex.core.pipes.exceptions import PipeFactoryErrorType, PipeValidationErrorType
+from pipelex.pipeline.exceptions import ValidateBundleError
+from pipelex.pipeline.validation_errors import build_validation_error_items
+
+
+def _build_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:
+ """Call the builder with the error's categorized lists only — for the category-projection tests.
+
+ The pipe-validation arm uses ``pipe_validation_error_data`` (pipe validation **plus**
+ pipe/concept instantiation errors) — the same combined accessor both real call sites
+ (``ValidateBundleError.to_error_report`` and the CLI ``extract_validation_errors``) pass.
+ The residual channels (``dry_run_error_message`` / ``fallback_message``) are intentionally
+ omitted here so these tests pin the categorized projection in isolation; the residual behavior
+ has its own dedicated tests below.
+ """
+ return build_validation_error_items(
+ blueprint_errors=exc.pipelex_bundle_blueprint_validation_errors,
+ factory_errors=exc.pipe_factory_errors,
+ pipe_validation_errors=exc.pipe_validation_error_data,
+ )
+
+
+def _all_category_error() -> ValidateBundleError:
+ return ValidateBundleError(
+ message="validation failed",
+ pipelex_bundle_blueprint_validation_errors=[
+ PipelexBundleBlueprintValidationErrorData(
+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
+ domain_code="testapp",
+ source="sibling.mthds",
+ pipe_code="pipe_a",
+ concept_code="Customer",
+ message="missing var x",
+ variable_names=["x"],
+ ),
+ ],
+ pipe_factory_errors=[
+ PipeFactoryErrorData(
+ error_type=PipeFactoryErrorType.UNKNOWN_CONCEPT,
+ domain_code="testapp",
+ pipe_code="pipe_b",
+ missing_concept_code="Foo",
+ declared_concepts=["Bar", "Baz"],
+ message="concept Foo not found",
+ ),
+ ],
+ pipe_validation_errors=[
+ PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.EXTRANEOUS_INPUT_VARIABLE,
+ domain_code="testapp",
+ source="main.mthds",
+ pipe_code="pipe_c",
+ concept_code="Order",
+ field_name="inputs",
+ message="extra var y",
+ field_path="pipe_c.inputs.y",
+ variable_names=["y"],
+ ),
+ ],
+ )
+
+
+class TestBuildValidationErrorItems:
+ def test_covers_all_three_categories_in_order(self) -> None:
+ """The builder emits one item per underlying error, blueprint → factory → pipe-validation."""
+ items = _build_items(_all_category_error())
+ assert [item.category for item in items] == [
+ ValidationErrorCategory.BLUEPRINT_VALIDATION,
+ ValidationErrorCategory.PIPE_FACTORY,
+ ValidationErrorCategory.PIPE_VALIDATION,
+ ]
+
+ def test_blueprint_item_carries_source_and_identity(self) -> None:
+ """Blueprint errors now surface ``source`` and ``concept_code`` (dropped by the old extractor)."""
+ blueprint_item = _build_items(_all_category_error())[0]
+ assert blueprint_item.source == "sibling.mthds"
+ assert blueprint_item.concept_code == "Customer"
+ assert blueprint_item.pipe_code == "pipe_a"
+ assert blueprint_item.domain_code == "testapp"
+ assert blueprint_item.error_type == PipeValidationErrorType.MISSING_INPUT_VARIABLE
+ assert blueprint_item.variable_names == ["x"]
+ # Factory-only fields stay unset for a blueprint error.
+ assert blueprint_item.missing_concept_code is None
+ assert blueprint_item.declared_concepts is None
+
+ def test_factory_item_keeps_missing_concept_and_declared_concepts(self) -> None:
+ """The factory-only fields the old extractor emitted are preserved by the shared builder."""
+ factory_item = _build_items(_all_category_error())[1]
+ assert factory_item.category == ValidationErrorCategory.PIPE_FACTORY
+ assert factory_item.missing_concept_code == "Foo"
+ assert factory_item.declared_concepts == ["Bar", "Baz"]
+ # Factory errors have no source / field_path.
+ assert factory_item.source is None
+ assert factory_item.field_path is None
+
+ def test_pipe_validation_item_carries_source_field_name_and_field_path(self) -> None:
+ """Pipe/concept-validation errors surface ``source`` and ``field_name`` alongside ``field_path``."""
+ pipe_item = _build_items(_all_category_error())[2]
+ assert pipe_item.source == "main.mthds"
+ assert pipe_item.field_name == "inputs"
+ assert pipe_item.field_path == "pipe_c.inputs.y"
+ assert pipe_item.concept_code == "Order"
+ assert pipe_item.variable_names == ["y"]
+
+ def test_empty_error_yields_no_items(self) -> None:
+ """A ValidateBundleError with no categorized lists builds an empty list."""
+ assert _build_items(ValidateBundleError(message="no details")) == []
+
+ def test_dry_run_residual_becomes_single_dry_run_item(self) -> None:
+ """A residual dry-run failure (no categorized data) yields one ``dry_run`` item — the structured-info invariant.
+
+ This is the case that previously produced a bare-message error with an empty
+ ``validation_errors[]``; it now carries the message as a ``dry_run``-category item.
+ It is graph-level, so it has no ``source``.
+ """
+ items = build_validation_error_items(
+ blueprint_errors=[],
+ factory_errors=[],
+ pipe_validation_errors=[],
+ dry_run_error_message="Dry run failed: residual error",
+ )
+ assert [item.category for item in items] == [ValidationErrorCategory.DRY_RUN]
+ assert items[0].message == "Dry run failed: residual error"
+ assert items[0].error_type == "DryRunError"
+ assert items[0].source is None
+
+ def test_dry_run_residual_suppressed_when_categorized_data_present(self) -> None:
+ """When a categorized error carries data, the dry-run residual is NOT added — the categorized items win."""
+ items = build_validation_error_items(
+ blueprint_errors=[],
+ factory_errors=[
+ PipeFactoryErrorData(
+ error_type=PipeFactoryErrorType.UNKNOWN_CONCEPT,
+ pipe_code="pipe_x",
+ missing_concept_code="Foo",
+ message="concept Foo not found",
+ ),
+ ],
+ pipe_validation_errors=[],
+ dry_run_error_message="should be ignored",
+ )
+ assert [item.category for item in items] == [ValidationErrorCategory.PIPE_FACTORY]
+
+ def test_to_error_report_projects_dry_run_residual(self) -> None:
+ """A ``ValidateBundleError`` carrying only ``dry_run_error_message`` surfaces one ``dry_run`` item on the report."""
+ report = ValidateBundleError(message="Dry run failed", dry_run_error_message="Dry run failed: residual error").to_error_report()
+ assert report.validation_errors is not None
+ assert [item.category for item in report.validation_errors] == [ValidationErrorCategory.DRY_RUN]
+
+ def test_fallback_message_residual_becomes_single_blueprint_item(self) -> None:
+ """A parse-level failure (only a message, no categorized data) yields one ``blueprint_validation`` item.
+
+ This is the most common failure — a malformed ``.mthds`` file (TOML syntax, an empty
+ blueprint, a bundle elaborator). The bundle could not be turned into a blueprint at all, so
+ ``blueprint_validation`` is the right bucket. It is parse-level, so it has no ``source``, and
+ ``error_type`` stays ``None`` (the message is authoritative).
+ """
+ items = build_validation_error_items(
+ blueprint_errors=[],
+ factory_errors=[],
+ pipe_validation_errors=[],
+ fallback_message="TOML syntax error at line 3, column 1: unclosed table header",
+ )
+ assert [item.category for item in items] == [ValidationErrorCategory.BLUEPRINT_VALIDATION]
+ assert items[0].message == "TOML syntax error at line 3, column 1: unclosed table header"
+ assert items[0].error_type is None
+ assert items[0].source is None
+
+ def test_dry_run_residual_wins_over_fallback_message(self) -> None:
+ """When both residual channels are available, the more-specific ``dry_run`` item wins (ordering)."""
+ items = build_validation_error_items(
+ blueprint_errors=[],
+ factory_errors=[],
+ pipe_validation_errors=[],
+ dry_run_error_message="Dry run failed: residual error",
+ fallback_message="should not be used",
+ )
+ assert [item.category for item in items] == [ValidationErrorCategory.DRY_RUN]
+
+ def test_fallback_message_suppressed_when_categorized_data_present(self) -> None:
+ """A categorized error wins over the fallback residual — the residual is a last resort only."""
+ items = build_validation_error_items(
+ blueprint_errors=[],
+ factory_errors=[
+ PipeFactoryErrorData(
+ error_type=PipeFactoryErrorType.UNKNOWN_CONCEPT,
+ pipe_code="pipe_x",
+ missing_concept_code="Foo",
+ message="concept Foo not found",
+ ),
+ ],
+ pipe_validation_errors=[],
+ fallback_message="should not be used",
+ )
+ assert [item.category for item in items] == [ValidationErrorCategory.PIPE_FACTORY]
+
+ def test_to_error_report_is_total_for_message_only_error(self) -> None:
+ """A bare-message ``ValidateBundleError`` still surfaces a non-empty ``validation_errors`` — the invariant is total.
+
+ ``to_error_report`` passes ``fallback_message=self.message``, so even an error with no
+ categorized data and no dry-run channel projects one ``blueprint_validation`` residual.
+ An invalid verdict is therefore NEVER a bare ``detail`` with an empty ``validation_errors[]``.
+ """
+ report = ValidateBundleError(message="Could not make 'PipelexBundleBlueprint': no blueprint found").to_error_report()
+ assert report.validation_errors is not None
+ assert report.validation_errors # non-empty: the totality guarantee
+ assert [item.category for item in report.validation_errors] == [ValidationErrorCategory.BLUEPRINT_VALIDATION]
+ assert report.validation_errors[0].message == "Could not make 'PipelexBundleBlueprint': no blueprint found"
+
+ def test_cli_extractor_is_total_for_message_only_error(self) -> None:
+ """The CLI ``extract_validation_errors`` is also total — a bare-message error yields one item, never an empty array."""
+ cli_dicts = extract_validation_errors(ValidateBundleError(message="empty blueprint"))
+ assert cli_dicts == [{"category": "blueprint_validation", "message": "empty blueprint"}]
+
+ def test_empty_collections_collapse_to_none(self) -> None:
+ """An empty ``declared_concepts`` / ``variable_names`` becomes ``None`` so it drops from the wire."""
+ exc = ValidateBundleError(
+ message="validation failed",
+ pipe_factory_errors=[
+ PipeFactoryErrorData(
+ error_type=PipeFactoryErrorType.UNKNOWN_FACTORY_ERROR,
+ pipe_code="pipe_x",
+ declared_concepts=[],
+ message="boom",
+ ),
+ ],
+ )
+ factory_item = _build_items(exc)[0]
+ assert factory_item.declared_concepts is None
+
+ def test_cli_extractor_matches_builder_dumped_shape(self) -> None:
+ """The CLI ``extract_validation_errors`` dicts equal the dumped builder items — single shape, two surfaces.
+
+ Pins that the agent CLI and the API 422 emit the identical structured
+ items: the CLI adapter is exactly ``model_dump(exclude_none=True)`` over
+ the same builder the API report uses.
+ """
+ exc = _all_category_error()
+ cli_dicts = extract_validation_errors(exc)
+ builder_dicts = [item.model_dump(mode="json", exclude_none=True) for item in _build_items(exc)]
+ assert cli_dicts == builder_dicts
+
+ def test_cli_extractor_equals_api_report_validation_errors(self) -> None:
+ """The CLI array and the API 422 ``validation_errors`` are identical on the wire.
+
+ The API report path dumps in python mode (``to_dict`` → ``model_dump(exclude_none=True)``),
+ so ``category`` rides as a live ``ValidationErrorCategory`` enum, while the CLI dumps
+ ``mode="json"`` strings. A plain ``==`` would pass merely because ``StrEnum`` subclasses
+ ``str``; to prove *wire-byte* parity (and catch a future python/json-divergent field that
+ is not a StrEnum), we also compare the encoded JSON, not just the in-memory dicts.
+ """
+ exc = _all_category_error()
+ cli_dicts = extract_validation_errors(exc)
+ problem_document = exc.to_error_report().to_problem_document()
+ assert problem_document["validation_errors"] == cli_dicts
+ assert json.dumps(problem_document["validation_errors"], sort_keys=True) == json.dumps(cli_dicts, sort_keys=True)
+
+ def test_instantiation_errors_are_projected_as_pipe_validation(self) -> None:
+ """Pipe/concept *instantiation* errors reach the wire too (not silently dropped).
+
+ ``ValidateBundleError`` aggregates them in a separate list; both real call sites route
+ through ``pipe_validation_error_data`` so they project as ``PIPE_VALIDATION`` items.
+ """
+ exc = ValidateBundleError(
+ message="validation failed",
+ pipe_concept_instantiation_errors=[
+ PipesAndConceptValidationErrorData(
+ error_type=PipeValidationErrorType.MISSING_INPUT_VARIABLE,
+ source="instantiated.mthds",
+ pipe_code="pipe_inst",
+ message="instantiation failed",
+ field_path="pipe_inst.inputs.z",
+ ),
+ ],
+ )
+ items = _build_items(exc)
+ assert [item.category for item in items] == [ValidationErrorCategory.PIPE_VALIDATION]
+ assert items[0].source == "instantiated.mthds"
+ # And the API report surfaces it (would be None/empty if the list were dropped).
+ report = exc.to_error_report()
+ assert report.validation_errors is not None
+ assert report.validation_errors[0].pipe_code == "pipe_inst"
diff --git a/tests/unit/pipelex/pipeline/test_validation_report.py b/tests/unit/pipelex/pipeline/test_validation_report.py
index bdabb355a..0eede27cd 100644
--- a/tests/unit/pipelex/pipeline/test_validation_report.py
+++ b/tests/unit/pipelex/pipeline/test_validation_report.py
@@ -59,6 +59,8 @@ class TestBuildValidationReport:
pending_signatures=["beta.still_pending"],
)
+ # is_valid is the always-True discriminant of the valid arm of the HTTP response union.
+ assert report.is_valid is True
# Primary selection: the first blueprint declaring main_pipe wins, not the first in the batch.
assert report.bundle_blueprint is blueprints[1]
assert report.pipe_io_contracts == pipe_io_contracts
diff --git a/tests/unit/pipelex/runtime_bridge/primitives/test_validate_as_known_class.py b/tests/unit/pipelex/runtime_bridge/primitives/test_validate_as_known_class.py
index 2b857f3a0..39cfdddbd 100644
--- a/tests/unit/pipelex/runtime_bridge/primitives/test_validate_as_known_class.py
+++ b/tests/unit/pipelex/runtime_bridge/primitives/test_validate_as_known_class.py
@@ -29,19 +29,19 @@ class TestValidateAsKnownClass:
def test_returns_instance_when_class_identity_matches(self) -> None:
"""When type(raw_item) is item_class, return the instance as-is (no round-trip)."""
instance = TextContent(text="hello")
- result = _validate_as_known_class(TextContent, instance)
+ result = _validate_as_known_class(item_class=TextContent, raw_item=instance)
assert result is instance
def test_validates_dict_input(self) -> None:
"""When raw_item is a dict, validate it through model_validate."""
- result = _validate_as_known_class(TextContent, {"text": "hello"})
+ result = _validate_as_known_class(item_class=TextContent, raw_item={"text": "hello"})
assert isinstance(result, TextContent)
assert result.text == "hello"
def test_cross_exec_round_trip_basic(self) -> None:
"""Cross-exec instance (different class identity, same shape) round-trips correctly."""
original = _OuterContent(meta=_StuffContentAllowExtra())
- result = _validate_as_known_class(_RebuiltOuterContent, original)
+ result = _validate_as_known_class(item_class=_RebuiltOuterContent, raw_item=original)
assert type(result) is _RebuiltOuterContent
def test_cross_exec_preserves_nested_subclass_data(self) -> None:
@@ -55,7 +55,7 @@ class TestValidateAsKnownClass:
implementation regressed back to ``model_dump()``.
"""
instance = _OuterContent(meta=_SpecificMeta(flavor="vanilla"))
- result = _validate_as_known_class(_RebuiltOuterContent, instance)
+ result = _validate_as_known_class(item_class=_RebuiltOuterContent, raw_item=instance)
assert type(result) is _RebuiltOuterContent
extras = result.meta.model_extra or {}
diff --git a/tests/unit/pipelex/system/pipelex_service/test_gateway_config_merger.py b/tests/unit/pipelex/system/pipelex_service/test_gateway_config_merger.py
index 69f622507..ba793fc1f 100644
--- a/tests/unit/pipelex/system/pipelex_service/test_gateway_config_merger.py
+++ b/tests/unit/pipelex/system/pipelex_service/test_gateway_config_merger.py
@@ -23,7 +23,7 @@ class TestGatewayConfigMerger:
}
local_overrides: dict[str, Any] = {}
- result = GatewayConfigMerger.merge(remote_config, local_overrides)
+ result = GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
assert result == remote_config
# Verify it's a copy, not the same object
@@ -47,7 +47,7 @@ class TestGatewayConfigMerger:
with warnings.catch_warnings(record=True) as caught_warnings:
warnings.simplefilter("always")
- result = GatewayConfigMerger.merge(remote_config, local_overrides)
+ result = GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
assert result["gpt-4o"]["sdk"] == "gateway_responses"
assert result["gpt-4o"]["structure_method"] == "instructor/openai_responses_tools"
@@ -71,7 +71,7 @@ class TestGatewayConfigMerger:
},
}
- result = GatewayConfigMerger.merge(remote_config, local_overrides)
+ result = GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
# Original values should be preserved
assert result["gpt-4o"]["model_id"] == "gpt-4o-2024-11-20"
@@ -86,7 +86,7 @@ class TestGatewayConfigMerger:
"unknown-model": {"sdk": "gateway_responses"},
}
- result = GatewayConfigMerger.merge(remote_config, local_overrides)
+ result = GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
# Unknown model should not be added
assert "unknown-model" not in result
@@ -105,7 +105,7 @@ class TestGatewayConfigMerger:
},
}
- result = GatewayConfigMerger.merge(remote_config, local_overrides)
+ result = GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
# Defaults override should be ignored - original values preserved
assert result["defaults"]["sdk"] == "gateway_completions"
@@ -121,7 +121,7 @@ class TestGatewayConfigMerger:
},
}
- result = GatewayConfigMerger.merge(remote_config, {})
+ result = GatewayConfigMerger.merge(remote_config, local_overrides={})
# Modify the result
result["gpt-4o"]["costs"]["input"] = 999
@@ -145,7 +145,7 @@ class TestGatewayConfigMerger:
}
with pytest.raises(GatewayConfigMergeError) as exc_info:
- GatewayConfigMerger.merge(remote_config, local_overrides)
+ GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
assert "gpt-4o" in str(exc_info.value)
assert "must be a dictionary" in str(exc_info.value)
@@ -160,7 +160,7 @@ class TestGatewayConfigMerger:
}
with pytest.raises(GatewayConfigMergeError) as exc_info:
- GatewayConfigMerger.merge(remote_config, local_overrides)
+ GatewayConfigMerger.merge(remote_config, local_overrides=local_overrides)
assert "gpt-4o" in str(exc_info.value)
assert "must be a dictionary" in str(exc_info.value)
diff --git a/tests/unit/pipelex/system/telemetry/test_otel_factory.py b/tests/unit/pipelex/system/telemetry/test_otel_factory.py
index a2a02c027..cfc939f2b 100644
--- a/tests/unit/pipelex/system/telemetry/test_otel_factory.py
+++ b/tests/unit/pipelex/system/telemetry/test_otel_factory.py
@@ -83,7 +83,7 @@ class TestOtelFactory:
def test_make_trace_names_returns_full_and_redacted(self) -> None:
"""Test that make_trace_names returns both full and redacted trace names."""
- trace_name, trace_name_redacted = OtelFactory.make_trace_names("run_123", "my_pipe")
+ trace_name, trace_name_redacted = OtelFactory.make_trace_names("run_123", pipe_code="my_pipe")
# Full trace name should include pipe code
assert trace_name.startswith("my_pipe_")
diff --git a/tests/unit/pipelex/temporal/test_observability_helpers.py b/tests/unit/pipelex/temporal/test_observability_helpers.py
index 3cf5b5edd..bf93c39df 100644
--- a/tests/unit/pipelex/temporal/test_observability_helpers.py
+++ b/tests/unit/pipelex/temporal/test_observability_helpers.py
@@ -296,7 +296,7 @@ class TestObservabilityHelpers:
def test_build_activity_summary_includes_method_pipe_and_extras(self) -> None:
job_metadata = JobMetadata(user_id="u", pipeline_run_id="r", pipe_code="translate_doc")
- summary = build_activity_summary("LLM text", job_metadata, extras={"model": "gpt-4o"})
+ summary = build_activity_summary("LLM text", job_metadata=job_metadata, extras={"model": "gpt-4o"})
assert summary == "LLM text · pipe=translate_doc · model=gpt-4o"
@@ -307,21 +307,21 @@ class TestObservabilityHelpers:
"""
job_metadata = JobMetadata(user_id="u", pipeline_run_id="r", pipe_code="extract_text")
- summary = build_activity_summary("LLM object", job_metadata, extras={"class": "Section"})
+ summary = build_activity_summary("LLM object", job_metadata=job_metadata, extras={"class": "Section"})
assert summary == "LLM object · pipe=extract_text · class=Section"
def test_build_activity_summary_omits_pipe_segment_when_pipe_code_is_unset(self) -> None:
job_metadata = JobMetadata(user_id="u", pipeline_run_id="r")
- summary = build_activity_summary("LLM text", job_metadata, extras={"model": "gpt-4o"})
+ summary = build_activity_summary("LLM text", job_metadata=job_metadata, extras={"model": "gpt-4o"})
assert summary == "LLM text · model=gpt-4o"
def test_build_activity_summary_omits_extras_section_when_none(self) -> None:
job_metadata = JobMetadata(user_id="u", pipeline_run_id="r", pipe_code="my_pipe")
- summary = build_activity_summary("Templated text", job_metadata)
+ summary = build_activity_summary("Templated text", job_metadata=job_metadata)
assert summary == "Templated text · pipe=my_pipe"
@@ -329,7 +329,7 @@ class TestObservabilityHelpers:
job_metadata = JobMetadata(user_id="u", pipeline_run_id="r", pipe_code="p")
long_value = "x" * 500
- summary = build_activity_summary("LLM text", job_metadata, extras={"extra": long_value})
+ summary = build_activity_summary("LLM text", job_metadata=job_metadata, extras={"extra": long_value})
assert len(summary.encode("utf-8")) <= 200
assert summary.endswith("…")
diff --git a/tests/unit/pipelex/temporal/test_resolve_dispatch.py b/tests/unit/pipelex/temporal/test_resolve_dispatch.py
index 3945b3896..4230fcbcc 100644
--- a/tests/unit/pipelex/temporal/test_resolve_dispatch.py
+++ b/tests/unit/pipelex/temporal/test_resolve_dispatch.py
@@ -337,6 +337,6 @@ class TestResolveDispatch:
assert worker_config.resolve_queue("act_jinja2_gen_text") == "default_q"
# resolve_dispatch agrees with resolve_queue on the queue name.
- assert worker_config.resolve_dispatch("act_llm_gen_text", "claude-opus-4-7").task_queue == "anthropic_q"
- assert worker_config.resolve_dispatch("act_llm_gen_text", "gpt-5").task_queue == "inference_q"
+ assert worker_config.resolve_dispatch("act_llm_gen_text", routing_key="claude-opus-4-7").task_queue == "anthropic_q"
+ assert worker_config.resolve_dispatch("act_llm_gen_text", routing_key="gpt-5").task_queue == "inference_q"
assert worker_config.resolve_dispatch("act_jinja2_gen_text").task_queue == "default_q"
diff --git a/tests/unit/pipelex/temporal/test_worker_cli.py b/tests/unit/pipelex/temporal/test_worker_cli.py
index b2bb0afaa..c4624d114 100644
--- a/tests/unit/pipelex/temporal/test_worker_cli.py
+++ b/tests/unit/pipelex/temporal/test_worker_cli.py
@@ -70,14 +70,14 @@ class TestWorkerCli:
boot_mocks["load_toml"].assert_not_called()
boot_mocks["pipelex_make"].assert_called_once_with(temporal_enabled=True)
- assert boot_mocks["run_worker"].call_args.args[0] == "explicit-project"
+ assert boot_mocks["run_worker"].call_args.kwargs["project"] == "explicit-project"
def test_project_resolved_from_pyproject_project_name(self, boot_mocks: dict[str, Any]) -> None:
"""With no argument, the project name comes from [project].name in pyproject.toml."""
worker_cli.configure()
boot_mocks["load_toml"].assert_called_once_with(path="pyproject.toml")
- assert boot_mocks["run_worker"].call_args.args[0] == "my-project"
+ assert boot_mocks["run_worker"].call_args.kwargs["project"] == "my-project"
def test_project_falls_back_to_poetry_name(self, boot_mocks: dict[str, Any]) -> None:
"""When [project].name is absent, [tool.poetry].name is used."""
@@ -85,7 +85,7 @@ class TestWorkerCli:
worker_cli.configure()
- assert boot_mocks["run_worker"].call_args.args[0] == "poetry-project"
+ assert boot_mocks["run_worker"].call_args.kwargs["project"] == "poetry-project"
def test_missing_project_name_raises(self, boot_mocks: dict[str, Any]) -> None:
"""A pyproject.toml without any project name aborts before booting Pipelex."""
@@ -178,7 +178,7 @@ class TestWorkerCli:
assert boot_mocks["config"].temporal is temporal_mock
def test_cli_arg_wiring_reaches_run_worker(self, boot_mocks: dict[str, Any]) -> None:
- """All CLI options travel through Typer parsing into run_worker, positionally correct."""
+ """All CLI options travel through Typer parsing into run_worker, with the correct keyword wiring."""
runner = CliRunner()
result = runner.invoke(
@@ -197,7 +197,14 @@ class TestWorkerCli:
)
assert result.exit_code == 0, result.output
- boot_mocks["run_worker"].assert_called_once_with("cli-project", True, True, "queue_from_cli", "router", "anthropic-tier4")
+ boot_mocks["run_worker"].assert_called_once_with(
+ project="cli-project",
+ is_not_sandboxed=True,
+ is_unit_testing=True,
+ task_queue="queue_from_cli",
+ scope_name="router",
+ profile_name="anthropic-tier4",
+ )
def test_cli_defaults_reach_run_worker(self, boot_mocks: dict[str, Any]) -> None:
"""Invoking with no arguments resolves the project from pyproject and passes default options."""
@@ -206,4 +213,11 @@ class TestWorkerCli:
result = runner.invoke(worker_cli.app, [])
assert result.exit_code == 0, result.output
- boot_mocks["run_worker"].assert_called_once_with("my-project", False, False, None, None, None)
+ boot_mocks["run_worker"].assert_called_once_with(
+ project="my-project",
+ is_not_sandboxed=False,
+ is_unit_testing=False,
+ task_queue=None,
+ scope_name=None,
+ profile_name=None,
+ )
diff --git a/tests/unit/pipelex/test_error_report_disclosure_mode.py b/tests/unit/pipelex/test_error_report_disclosure_mode.py
index 98bc9f896..a1c32b8fc 100644
--- a/tests/unit/pipelex/test_error_report_disclosure_mode.py
+++ b/tests/unit/pipelex/test_error_report_disclosure_mode.py
@@ -29,6 +29,8 @@ from pipelex.base_exceptions import (
ErrorDomain,
ErrorReport,
PipelexUnexpectedError,
+ ValidationErrorCategory,
+ ValidationErrorItem,
)
from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction, UserActionKind
from pipelex.cogt.inference.provider_name import ProviderName
@@ -428,6 +430,43 @@ class TestErrorReportDisclosureMode:
# those are the legitimate divergences. After removing them, the key sets must match.
assert set(caller_facing_payload) - {"message", "user_action"} == set(redacted_payload) - {"message"}
+ @pytest.mark.parametrize(
+ "caller_facing",
+ [
+ pytest.param(True, id="caller-facing-branch"),
+ pytest.param(False, id="redacted-branch"),
+ ],
+ )
+ def test_strict_retains_validation_errors_on_both_branches(self, caller_facing: bool) -> None:
+ """``validation_errors`` survives STRICT on BOTH the caller-facing and redacted branches.
+
+ The structured per-error list describes the caller's own submitted bundle,
+ not server internals — so it is kept on the external surface via
+ ``_STRICT_KEPT_FIELDS`` rather than by the caller-facing branch's bespoke
+ message logic. A real ``ValidateBundleError`` only ever rides the
+ caller-facing branch, but the field must be branch-independent so a future
+ non-caller-facing report carrying it is not silently redacted.
+ """
+ report = ErrorReport(
+ error_type="ValidateBundleError",
+ message="bundle failed validation",
+ title="Validate bundle error",
+ type_uri="https://docs.pipelex.com/latest/errors/validate-bundle-error/",
+ error_domain=ErrorDomain.INPUT,
+ caller_facing_message=caller_facing,
+ validation_errors=[
+ ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ source="main.mthds",
+ pipe_code="summarize",
+ message="Missing input variable(s): doc.",
+ ),
+ ],
+ )
+ payload = report.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert "validation_errors" in payload
+ assert payload["validation_errors"][0]["source"] == "main.mthds"
+
def test_receiver_rehydrates_verbose_payload_for_webhook(self) -> None:
"""An API-side receiver rebuilds the report from a VERBOSE webhook payload.
diff --git a/tests/unit/pipelex/tools/misc/test_dict_utils.py b/tests/unit/pipelex/tools/misc/test_dict_utils.py
index f5cf24e8f..f882a60aa 100644
--- a/tests/unit/pipelex/tools/misc/test_dict_utils.py
+++ b/tests/unit/pipelex/tools/misc/test_dict_utils.py
@@ -11,7 +11,7 @@ class TestDictUtils:
def test_insert_before_basic(self) -> None:
"""Test basic insert_before functionality."""
original = {"a": 1, "c": 3}
- result = insert_before(original, "c", "b", 2)
+ result = insert_before(original, target_key="c", new_key="b", new_value=2)
expected_keys = ["a", "b", "c"]
assert list(result.keys()) == expected_keys
@@ -23,7 +23,7 @@ class TestDictUtils:
def test_insert_before_target_not_found(self) -> None:
"""Test insert_before when target key doesn't exist."""
original = {"a": 1, "b": 2}
- result = insert_before(original, "z", "c", 3)
+ result = insert_before(original, target_key="z", new_key="c", new_value=3)
expected_keys = ["a", "b", "c"]
assert list(result.keys()) == expected_keys
@@ -34,7 +34,7 @@ class TestDictUtils:
original = {"a": 1, "b": 2, "c": 3}
original_copy = original.copy()
- insert_before(original, "b", "x", 999)
+ insert_before(original, target_key="b", new_key="x", new_value=999)
assert original == original_copy
@@ -43,7 +43,7 @@ class TestDictUtils:
original = {"type": "PipeLLM", "description": "Test pipe", "output": NativeConceptCode.TEXT, "system_prompt": "Test prompt"}
# Insert inputs before output
- result = insert_before(original, "output", "inputs", "InputText")
+ result = insert_before(original, target_key="output", new_key="inputs", new_value="InputText")
expected_keys = ["type", "description", "inputs", "output", "system_prompt"]
assert list(result.keys()) == expected_keys
@@ -56,7 +56,7 @@ class TestDictUtils:
def uppercase_transform(s: str) -> str:
return s.upper()
- result = apply_to_strings_recursive(data, uppercase_transform)
+ result = apply_to_strings_recursive(data, transform_func=uppercase_transform)
assert result["name"] == "HELLO ${USER}"
assert result["age"] == 25 # Non-string values unchanged
@@ -69,7 +69,7 @@ class TestDictUtils:
def env_substitute(s: str) -> str:
return s.replace("${SUFFIX}", "_doe").replace("${MODE}", "_theme").replace("${BUILD}", "_final")
- result = apply_to_strings_recursive(data, env_substitute)
+ result = apply_to_strings_recursive(data, transform_func=env_substitute)
assert result["user"]["name"] == "john _doe"
assert result["user"]["settings"]["theme"] == "dark _theme"
@@ -83,7 +83,7 @@ class TestDictUtils:
def substitute_vars(s: str) -> str:
return s.replace("${WORLD}", "earth").replace("${ENV}", "production").replace("${VAR}", "123")
- result = apply_to_strings_recursive(data, substitute_vars)
+ result = apply_to_strings_recursive(data, transform_func=substitute_vars)
assert result["items"] == ["hello earth", 42, "goodbye earth"]
assert result["config"]["values"][0] == 1
@@ -98,7 +98,7 @@ class TestDictUtils:
def dummy_transform(s: str) -> str:
return s.upper()
- result = apply_to_strings_recursive(data, dummy_transform)
+ result = apply_to_strings_recursive(data, transform_func=dummy_transform)
assert result["empty_dict"] == {}
assert result["empty_list"] == []
@@ -113,7 +113,7 @@ class TestDictUtils:
def transform(s: str) -> str:
return s.replace("${USER}", "john").replace("${ENV}", "prod").replace("${VAR}", "test")
- result = apply_to_strings_recursive(original, transform)
+ result = apply_to_strings_recursive(original, transform_func=transform)
# Original should be unchanged
assert original == original_copy
@@ -130,7 +130,7 @@ class TestDictUtils:
def substitute_vars(s: str) -> str:
return s.replace("${USER}", "john").replace("${ENV}", "production")
- result = apply_to_strings_in_list(data, substitute_vars)
+ result = apply_to_strings_in_list(data, transform_func=substitute_vars)
assert result == ["hello john", "world", 42, True, "test production"]
assert result is not data # Should return a new list
@@ -142,7 +142,7 @@ class TestDictUtils:
def transform(s: str) -> str:
return s.replace("${VAR}", "variable").replace("${NESTED}", "nested").replace("${DEEP}", "deep").replace("${END}", "end")
- result = apply_to_strings_in_list(data, transform)
+ result = apply_to_strings_in_list(data, transform_func=transform)
assert result[0] == "outer variable"
assert result[1][0] == 1
@@ -158,7 +158,7 @@ class TestDictUtils:
def transform(s: str) -> str:
return s.replace("${VAR}", "var").replace("${DICT}", "dict").replace("${DEEP}", "deep").replace("${ITEM}", "item")
- result = apply_to_strings_in_list(data, transform)
+ result = apply_to_strings_in_list(data, transform_func=transform)
assert result[0] == "list item var"
assert result[1]["key1"] == "dict value dict"
@@ -174,7 +174,7 @@ class TestDictUtils:
def dummy_transform(s: str) -> str:
return s.upper()
- result = apply_to_strings_in_list(data, dummy_transform)
+ result = apply_to_strings_in_list(data, transform_func=dummy_transform)
assert result == []
assert result is not data # Should return a new list
@@ -186,7 +186,7 @@ class TestDictUtils:
def transform(s: str) -> str:
return s.upper()
- result = apply_to_strings_in_list(data, transform)
+ result = apply_to_strings_in_list(data, transform_func=transform)
assert result[0] == 1
assert result[1] == 2.5
@@ -203,7 +203,7 @@ class TestDictUtils:
def transform(s: str) -> str:
return s.replace("${USER}", "john").replace("${VAR}", "variable").replace("${NESTED}", "nested")
- result = apply_to_strings_in_list(original, transform)
+ result = apply_to_strings_in_list(original, transform_func=transform)
# Original should be unchanged
assert original == original_copy
@@ -236,7 +236,7 @@ class TestDictUtils:
result = result.replace(old, new)
return result
- result = apply_to_strings_in_list(data, transform)
+ result = apply_to_strings_in_list(data, transform_func=transform)
assert result[0] == "root root"
assert result[1]["dict_key"] == "dict value dict"
@@ -252,7 +252,7 @@ class TestDictUtils:
context: dict[str, Any] = {}
extra_params = {"foo.bar": "hello"}
- result = substitute_nested_in_context(context, extra_params)
+ result = substitute_nested_in_context(context, extra_params=extra_params)
assert result is context # Should mutate original
assert context["foo"]["bar"] == "hello"
@@ -262,7 +262,7 @@ class TestDictUtils:
context: dict[str, Any] = {}
extra_params = {"a.b.c.d": "deep_value"}
- substitute_nested_in_context(context, extra_params)
+ substitute_nested_in_context(context, extra_params=extra_params)
assert context["a"]["b"]["c"]["d"] == "deep_value"
@@ -275,7 +275,7 @@ class TestDictUtils:
"other.key": "value4",
}
- substitute_nested_in_context(context, extra_params)
+ substitute_nested_in_context(context, extra_params=extra_params)
assert context["foo"]["bar"]["nested"] == "value3"
assert context["foo"]["baz"] == "value2"
@@ -290,7 +290,7 @@ class TestDictUtils:
"another": 42,
}
- substitute_nested_in_context(context, extra_params)
+ substitute_nested_in_context(context, extra_params=extra_params)
assert context["simple"] == "simple_value"
assert context["nested"]["key"] == "nested_value"
@@ -301,7 +301,7 @@ class TestDictUtils:
context: dict[str, Any] = {"foo": {"existing": "old_value"}}
extra_params = {"foo.bar": "new_value"}
- substitute_nested_in_context(context, extra_params)
+ substitute_nested_in_context(context, extra_params=extra_params)
assert context["foo"]["existing"] == "old_value"
assert context["foo"]["bar"] == "new_value"
@@ -312,7 +312,7 @@ class TestDictUtils:
extra_params = {"foo.bar": "new_value"}
with pytest.raises(NestedKeyConflictError) as exc_info:
- substitute_nested_in_context(context, extra_params)
+ substitute_nested_in_context(context, extra_params=extra_params)
assert "foo.bar" in exc_info.value.message
assert "foo" in exc_info.value.message
@@ -322,7 +322,7 @@ class TestDictUtils:
"""Test function works when extra_params is None."""
context: dict[str, Any] = {"existing": "value"}
- result = substitute_nested_in_context(context, None)
+ result = substitute_nested_in_context(context, extra_params=None)
assert result is context
assert context == {"existing": "value"}
@@ -332,7 +332,7 @@ class TestDictUtils:
context: dict[str, Any] = {"existing": "value"}
extra_params: dict[str, Any] = {}
- result = substitute_nested_in_context(context, extra_params)
+ result = substitute_nested_in_context(context, extra_params=extra_params)
assert result is context
assert context == {"existing": "value"}
@@ -343,7 +343,7 @@ class TestDictUtils:
original_id = id(context)
extra_params = {"foo.bar": "hello"}
- result = substitute_nested_in_context(context, extra_params)
+ result = substitute_nested_in_context(context, extra_params=extra_params)
assert id(result) == original_id
assert result is context
diff --git a/tests/unit/pipelex/tools/misc/test_diff.py b/tests/unit/pipelex/tools/misc/test_diff.py
index 61223ad23..4c1061ad4 100644
--- a/tests/unit/pipelex/tools/misc/test_diff.py
+++ b/tests/unit/pipelex/tools/misc/test_diff.py
@@ -22,7 +22,7 @@ class TestDiff:
(dir1 / "file1.txt").write_text("content")
(dir2 / "file1.txt").write_text("content")
- assert has_diff_dirs(dir1, dir2) is False
+ assert has_diff_dirs(dir1=dir1, dir2=dir2) is False
def test_has_diff_dirs_file_only_in_left(self):
"""Test that file only in left directory returns True."""
@@ -36,7 +36,7 @@ class TestDiff:
(dir1 / "common.txt").write_text("content")
(dir2 / "common.txt").write_text("content")
- assert has_diff_dirs(dir1, dir2) is True
+ assert has_diff_dirs(dir1=dir1, dir2=dir2) is True
def test_has_diff_dirs_file_only_in_right(self):
"""Test that file only in right directory returns True."""
@@ -50,7 +50,7 @@ class TestDiff:
(dir1 / "common.txt").write_text("content")
(dir2 / "common.txt").write_text("content")
- assert has_diff_dirs(dir1, dir2) is True
+ assert has_diff_dirs(dir1=dir1, dir2=dir2) is True
def test_has_diff_dirs_different_content(self):
"""Test that files with different content return True."""
@@ -63,7 +63,7 @@ class TestDiff:
(dir1 / "file.txt").write_text("content1")
(dir2 / "file.txt").write_text("content2")
- assert has_diff_dirs(dir1, dir2) is True
+ assert has_diff_dirs(dir1=dir1, dir2=dir2) is True
def test_has_diff_dirs_recursive(self):
"""Test that subdirectory differences are detected."""
@@ -83,7 +83,7 @@ class TestDiff:
(dir1 / "subdir" / "different.txt").write_text("content1")
(dir2 / "subdir" / "different.txt").write_text("content2")
- assert has_diff_dirs(dir1, dir2) is True
+ assert has_diff_dirs(dir1=dir1, dir2=dir2) is True
def test_has_diff_dirs_empty_directories(self):
"""Test that two empty directories return False."""
@@ -93,7 +93,7 @@ class TestDiff:
dir1.mkdir()
dir2.mkdir()
- assert has_diff_dirs(dir1, dir2) is False
+ assert has_diff_dirs(dir1=dir1, dir2=dir2) is False
def test_diff_files_basic(self):
"""Test basic file diff functionality."""
@@ -135,7 +135,7 @@ class TestDiff:
(dir1 / "file.txt").write_text("content")
(dir2 / "file.txt").write_text("content")
- result = make_diff_dirs_pretty(dir1, dir2)
+ result = make_diff_dirs_pretty(dir1=dir1, dir2=dir2)
assert isinstance(result, Text)
assert "No differences found" in str(result)
@@ -153,7 +153,7 @@ class TestDiff:
(dir1 / "different.txt").write_text("content1")
(dir2 / "different.txt").write_text("content2")
- result = make_diff_dirs_pretty(dir1, dir2)
+ result = make_diff_dirs_pretty(dir1=dir1, dir2=dir2)
assert isinstance(result, Group)
@@ -169,7 +169,7 @@ class TestDiff:
(dir1 / "binary.bin").write_bytes(b"\x00\x01\x02\x03")
(dir2 / "binary.bin").write_bytes(b"\x04\x05\x06\x07")
- result = make_diff_dirs_pretty(dir1, dir2)
+ result = make_diff_dirs_pretty(dir1=dir1, dir2=dir2)
# Should return Group with binary file note
assert isinstance(result, Group)
@@ -188,7 +188,7 @@ class TestDiff:
(dir1 / "subdir" / "file.txt").write_text("content1")
(dir2 / "subdir" / "file.txt").write_text("content2")
- result = make_diff_dirs_pretty(dir1, dir2)
+ result = make_diff_dirs_pretty(dir1=dir1, dir2=dir2)
assert isinstance(result, Group)
@@ -204,7 +204,7 @@ class TestDiff:
(dir2 / "file.txt").write_text("content2")
# Pass as strings
- result = make_diff_dirs_pretty(str(dir1), str(dir2))
+ result = make_diff_dirs_pretty(dir1=str(dir1), dir2=str(dir2))
assert isinstance(result, Group)
@@ -257,7 +257,7 @@ class TestDiff:
(dir2 / "file.txt").write_text("content")
# Pass as strings
- result = has_diff_dirs(str(dir1), str(dir2))
+ result = has_diff_dirs(dir1=str(dir1), dir2=str(dir2))
assert result is False
@@ -290,7 +290,7 @@ class TestDiff:
# Create file in dir2 (newer)
(dir2 / "file.txt").write_text("content2")
- result = make_diff_dirs_pretty(dir1, dir2)
+ result = make_diff_dirs_pretty(dir1=dir1, dir2=dir2)
# Result should be a Group containing the diff
assert isinstance(result, Group)
diff --git a/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py b/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py
index 29215ff02..90902cabc 100644
--- a/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py
+++ b/tests/unit/pipelex/tools/misc/test_find_files_in_dir.py
@@ -19,7 +19,7 @@ class TestFindFilesInDir:
(sub_dir / "file4.py").touch()
# Find Python files non-recursively
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=False)
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=False)
assert len(files) == 2
file_names = [f.name for f in files]
@@ -41,7 +41,7 @@ class TestFindFilesInDir:
(sub_dir / "file4.py").touch()
# Find Python files recursively
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True)
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True)
expected_files_length = 3
assert len(files) == expected_files_length
@@ -53,7 +53,7 @@ class TestFindFilesInDir:
def test_find_files_empty_directory(self):
"""Test finding files in empty directory."""
with tempfile.TemporaryDirectory() as temp_dir:
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=False)
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=False)
assert len(files) == 0
def test_find_files_no_matches(self):
@@ -62,7 +62,7 @@ class TestFindFilesInDir:
(Path(temp_dir) / "file1.txt").touch()
(Path(temp_dir) / "file2.md").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=False)
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=False)
assert len(files) == 0
def test_find_files_with_excluded_dirs_single(self):
@@ -86,7 +86,7 @@ class TestFindFilesInDir:
normal_dir.mkdir()
(normal_dir / "normal.py").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"])
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=[".venv"])
assert len(files) == 2
file_names = [f.name for f in files]
@@ -118,7 +118,7 @@ class TestFindFilesInDir:
src_dir = Path(temp_dir) / "src"
(src_dir / "normal.py").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv", "node_modules", "__pycache__"])
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=[".venv", "node_modules", "__pycache__"])
assert len(files) == 2
file_names = [f.name for f in files]
@@ -157,7 +157,7 @@ class TestFindFilesInDir:
files = find_files_in_dir(
Path(temp_dir),
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv"],
force_include_dirs=[str(force_include_dir)],
@@ -202,7 +202,7 @@ class TestFindFilesInDir:
files = find_files_in_dir(
Path(temp_dir),
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv"],
force_include_dirs=["pipelex"],
@@ -248,7 +248,7 @@ class TestFindFilesInDir:
files = find_files_in_dir(
Path(temp_dir),
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv", "node_modules"],
force_include_dirs=[str(pipelex_dir), "special"],
@@ -292,7 +292,7 @@ class TestFindFilesInDir:
files = find_files_in_dir(
Path(temp_dir),
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv"],
force_include_dirs=[str(pkg1), str(pkg2)],
@@ -323,7 +323,7 @@ class TestFindFilesInDir:
files = find_files_in_dir(
Path(temp_dir),
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv"],
force_include_dirs=[str(deep_path)],
@@ -346,7 +346,7 @@ class TestFindFilesInDir:
venv_dir.mkdir()
(venv_dir / "venv_file.py").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=None)
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=None)
# Should find all files when no exclusions
assert len(files) == 2
@@ -364,7 +364,7 @@ class TestFindFilesInDir:
venv_dir.mkdir()
(venv_dir / "venv_file.py").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=None)
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=None)
# Should exclude all venv files when no includes
assert len(files) == 1
@@ -386,7 +386,7 @@ class TestFindFilesInDir:
# Include directory is in src, not in excluded dir
files = find_files_in_dir(
Path(temp_dir),
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv"],
force_include_dirs=[str(src_dir)],
@@ -410,12 +410,12 @@ class TestFindFilesInDir:
(venv_dir / "venv_data.json").touch()
# Find only .py files
- py_files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"])
+ py_files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=[".venv"])
assert len(py_files) == 1
assert py_files[0].name == "script.py"
# Find only .json files
- json_files = find_files_in_dir(Path(temp_dir), "*.json", is_recursive=True, excluded_dirs=[".venv"])
+ json_files = find_files_in_dir(Path(temp_dir), pattern="*.json", is_recursive=True, excluded_dirs=[".venv"])
assert len(json_files) == 1
assert json_files[0].name == "data.json"
@@ -428,7 +428,7 @@ class TestFindFilesInDir:
venv_dir.mkdir()
(venv_dir / "venv_file.py").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[])
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=[])
# Empty list should behave like None - no exclusions
assert len(files) == 2
@@ -442,7 +442,7 @@ class TestFindFilesInDir:
venv_dir.mkdir()
(venv_dir / "venv_file.py").touch()
- files = find_files_in_dir(Path(temp_dir), "*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=[])
+ files = find_files_in_dir(Path(temp_dir), pattern="*.py", is_recursive=True, excluded_dirs=[".venv"], force_include_dirs=[])
# Empty include list should exclude all venv files
assert len(files) == 1
@@ -467,7 +467,7 @@ class TestFindFilesInDir:
# Exclude structures using its absolute path
result = find_files_in_dir(
temp_path,
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[str(structures_dir.resolve())],
)
@@ -494,7 +494,7 @@ class TestFindFilesInDir:
# Test with trailing slash
result_with_slash = find_files_in_dir(
temp_path,
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[str(structures_dir.resolve()) + "/"],
)
@@ -502,7 +502,7 @@ class TestFindFilesInDir:
# Test without trailing slash
result_without_slash = find_files_in_dir(
temp_path,
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[str(structures_dir.resolve())],
)
@@ -537,7 +537,7 @@ class TestFindFilesInDir:
result = find_files_in_dir(
temp_path,
- "*.py",
+ pattern="*.py",
is_recursive=True,
excluded_dirs=[".venv", str(structures_dir.resolve())],
)
diff --git a/tests/unit/pipelex/tools/misc/test_hash_sha256.py b/tests/unit/pipelex/tools/misc/test_hash_sha256.py
index 257aceb38..0c43a2666 100644
--- a/tests/unit/pipelex/tools/misc/test_hash_sha256.py
+++ b/tests/unit/pipelex/tools/misc/test_hash_sha256.py
@@ -23,7 +23,7 @@ class TestHashSha256:
)
def test_hash_sha256(self, input_string: str, length: int | None, expected: str) -> None:
"""Test SHA256 hashing with various inputs and truncation lengths."""
- assert hash_sha256(input_string, length) == expected
+ assert hash_sha256(input_string, length=length) == expected
def test_hash_sha256_deterministic(self) -> None:
"""Test that the same input always produces the same output."""
diff --git a/tests/unit/pipelex/tools/misc/test_mirror_dir.py b/tests/unit/pipelex/tools/misc/test_mirror_dir.py
index 5d49a84d1..c13528b6e 100644
--- a/tests/unit/pipelex/tools/misc/test_mirror_dir.py
+++ b/tests/unit/pipelex/tools/misc/test_mirror_dir.py
@@ -21,7 +21,7 @@ class TestMirrorDir:
_write(source / "config.toml", "value = 1")
target.mkdir()
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.copied_files == ["config.toml"]
assert result.deleted_files == []
@@ -35,7 +35,7 @@ class TestMirrorDir:
_write(source / "config.toml", "value = 2")
_write(target / "config.toml", "value = 1")
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.copied_files == ["config.toml"]
assert (target / "config.toml").read_text(encoding="utf-8") == "value = 2"
@@ -48,7 +48,7 @@ class TestMirrorDir:
_write(source / "config.toml", "value = 1")
_write(target / "config.toml", "value = 1")
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.has_changes is False
assert result.copied_files == []
@@ -61,7 +61,7 @@ class TestMirrorDir:
source.mkdir()
_write(target / "stale.toml", "obsolete")
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.deleted_files == ["stale.toml"]
assert not (target / "stale.toml").exists()
@@ -74,7 +74,7 @@ class TestMirrorDir:
source.mkdir()
_write(target / "stale_dir" / "nested" / "file.toml", "obsolete")
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.deleted_dirs == ["stale_dir"]
assert result.deleted_files == []
@@ -89,7 +89,7 @@ class TestMirrorDir:
_write(source / "inference" / "deck" / "llm.toml", "llm")
target.mkdir()
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.copied_files == ["inference/backends/openai.toml", "inference/deck/llm.toml"]
assert (target / "inference" / "backends" / "openai.toml").read_text(encoding="utf-8") == "openai"
@@ -103,7 +103,7 @@ class TestMirrorDir:
(source / "empty_dir").mkdir(parents=True)
target.mkdir()
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.created_dirs == ["empty_dir"]
assert result.has_changes is True
@@ -117,7 +117,7 @@ class TestMirrorDir:
(source / "empty_dir").mkdir(parents=True)
target.mkdir()
- result = mirror_dir(source, target, dry_run=True)
+ result = mirror_dir(source_dir=source, target_dir=target, dry_run=True)
assert result.created_dirs == ["empty_dir"]
assert result.has_changes is True
@@ -131,7 +131,7 @@ class TestMirrorDir:
source.mkdir()
_write(target / "telemetry.project.toml", "kit-only template")
- result = mirror_dir(source, target, exclude_files=frozenset({"telemetry.project.toml"}))
+ result = mirror_dir(source_dir=source, target_dir=target, exclude_files=frozenset({"telemetry.project.toml"}))
assert result.deleted_files == []
assert (target / "telemetry.project.toml").exists()
@@ -144,7 +144,7 @@ class TestMirrorDir:
_write(source / "telemetry.toml", "dogfood override")
target.mkdir()
- result = mirror_dir(source, target, exclude_files=frozenset({"telemetry.toml"}))
+ result = mirror_dir(source_dir=source, target_dir=target, exclude_files=frozenset({"telemetry.toml"}))
assert result.copied_files == []
assert not (target / "telemetry.toml").exists()
@@ -157,7 +157,7 @@ class TestMirrorDir:
source.mkdir()
_write(target / "storage" / "cached.bin", "runtime data")
- result = mirror_dir(source, target, exclude_dirs=frozenset({"storage"}))
+ result = mirror_dir(source_dir=source, target_dir=target, exclude_dirs=frozenset({"storage"}))
assert result.deleted_dirs == []
assert (target / "storage" / "cached.bin").exists()
@@ -170,7 +170,7 @@ class TestMirrorDir:
_write(source / "inference" / "backends.toml", "backends")
_write(target / "inference" / "traces" / "run.log", "trace")
- result = mirror_dir(source, target, exclude_dirs=frozenset({"traces"}))
+ result = mirror_dir(source_dir=source, target_dir=target, exclude_dirs=frozenset({"traces"}))
assert result.deleted_dirs == []
assert (target / "inference" / "traces" / "run.log").exists()
@@ -183,7 +183,7 @@ class TestMirrorDir:
_write(source / "new.toml", "fresh")
_write(target / "stale.toml", "obsolete")
- result = mirror_dir(source, target, dry_run=True)
+ result = mirror_dir(source_dir=source, target_dir=target, dry_run=True)
assert result.dry_run is True
assert result.copied_files == ["new.toml"]
@@ -198,7 +198,7 @@ class TestMirrorDir:
target = Path(temp_dir) / "target"
_write(source / "config.toml", "value = 1")
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.copied_files == ["config.toml"]
assert (target / "config.toml").read_text(encoding="utf-8") == "value = 1"
@@ -211,7 +211,7 @@ class TestMirrorDir:
_write(source / "item", "now a file")
_write(target / "item" / "nested.toml", "was a directory")
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.deleted_dirs == ["item"]
assert result.copied_files == ["item"]
@@ -234,13 +234,13 @@ class TestMirrorDir:
_write(target / "storage" / "cached.bin", "runtime data")
_write(target / "stale.toml", "obsolete")
- first = mirror_dir(source, target, exclude_files=exclude_files, exclude_dirs=exclude_dirs)
+ first = mirror_dir(source_dir=source, target_dir=target, exclude_files=exclude_files, exclude_dirs=exclude_dirs)
assert first.has_changes is True
- second = mirror_dir(source, target, exclude_files=exclude_files, exclude_dirs=exclude_dirs)
+ second = mirror_dir(source_dir=source, target_dir=target, exclude_files=exclude_files, exclude_dirs=exclude_dirs)
assert second.has_changes is False
- assert has_diff_dirs(source, target, exclude_files=exclude_files, exclude_dirs=exclude_dirs) is False
+ assert has_diff_dirs(dir1=source, dir2=target, exclude_files=exclude_files, exclude_dirs=exclude_dirs) is False
assert (target / "telemetry.toml").read_text(encoding="utf-8") == "target-side excluded"
assert (target / "storage" / "cached.bin").exists()
assert not (target / "stale.toml").exists()
@@ -253,7 +253,7 @@ class TestMirrorDir:
_write(target / "keep.toml", "precious")
with pytest.raises(FileNotFoundError):
- mirror_dir(source, target)
+ mirror_dir(source_dir=source, target_dir=target)
assert (target / "keep.toml").read_text(encoding="utf-8") == "precious"
@@ -266,7 +266,7 @@ class TestMirrorDir:
_write(target / "keep.toml", "precious")
with pytest.raises(NotADirectoryError):
- mirror_dir(source, target)
+ mirror_dir(source_dir=source, target_dir=target)
assert (target / "keep.toml").read_text(encoding="utf-8") == "precious"
@@ -281,7 +281,7 @@ class TestMirrorDir:
target.mkdir()
(target / "config.toml").symlink_to(external)
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.copied_files == ["config.toml"]
assert not (target / "config.toml").is_symlink()
@@ -300,7 +300,7 @@ class TestMirrorDir:
target.mkdir()
(target / "config.toml").symlink_to(external)
- result = mirror_dir(source, target, dry_run=True)
+ result = mirror_dir(source_dir=source, target_dir=target, dry_run=True)
assert result.copied_files == ["config.toml"]
assert (target / "config.toml").is_symlink()
@@ -319,7 +319,7 @@ class TestMirrorDir:
# Make the symlink broken by removing the target it points to.
external.unlink()
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.deleted_files == ["stale_link.toml"]
# The broken symlink itself must actually be gone from the target tree.
@@ -337,7 +337,7 @@ class TestMirrorDir:
target.mkdir()
(target / "linked_dir").symlink_to(real_dir, target_is_directory=True)
- result = mirror_dir(source, target)
+ result = mirror_dir(source_dir=source, target_dir=target)
assert result.deleted_dirs == ["linked_dir"]
assert not (target / "linked_dir").exists()
diff --git a/tests/unit/pipelex/tools/misc/test_semver.py b/tests/unit/pipelex/tools/misc/test_semver.py
index f41901788..f8af91a49 100644
--- a/tests/unit/pipelex/tools/misc/test_semver.py
+++ b/tests/unit/pipelex/tools/misc/test_semver.py
@@ -81,7 +81,7 @@ class TestSemver:
"""Caret constraints allow compatible updates within the same major (or minor for 0.x)."""
constraint = parse_constraint(constraint_str)
version = parse_version(version_str)
- assert version_satisfies(version, constraint) == expected
+ assert version_satisfies(version, constraint=constraint) == expected
@pytest.mark.parametrize(
("constraint_str", "version_str", "expected"),
@@ -96,7 +96,7 @@ class TestSemver:
"""Tilde constraints allow patch-level updates only."""
constraint = parse_constraint(constraint_str)
version = parse_version(version_str)
- assert version_satisfies(version, constraint) == expected
+ assert version_satisfies(version, constraint=constraint) == expected
@pytest.mark.parametrize(
("constraint_str", "version_str", "expected"),
@@ -119,7 +119,7 @@ class TestSemver:
"""Comparison operators (>=, >, <=, <, ==, !=) work correctly."""
constraint = parse_constraint(constraint_str)
version = parse_version(version_str)
- assert version_satisfies(version, constraint) == expected
+ assert version_satisfies(version, constraint=constraint) == expected
@pytest.mark.parametrize(
("constraint_str", "version_str", "expected"),
@@ -135,7 +135,7 @@ class TestSemver:
"""Wildcard constraints match any version (or within a major range)."""
constraint = parse_constraint(constraint_str)
version = parse_version(version_str)
- assert version_satisfies(version, constraint) == expected
+ assert version_satisfies(version, constraint=constraint) == expected
@pytest.mark.parametrize(
("constraint_str", "version_str", "expected"),
@@ -149,13 +149,13 @@ class TestSemver:
"""Compound constraints (AND of multiple sub-constraints) work correctly."""
constraint = parse_constraint(constraint_str)
version = parse_version(version_str)
- assert version_satisfies(version, constraint) == expected
+ assert version_satisfies(version, constraint=constraint) == expected
def test_version_satisfies_exact_no_operator(self) -> None:
"""A bare version string (no operator) means exact match."""
constraint = parse_constraint("1.0.0")
- assert version_satisfies(parse_version("1.0.0"), constraint) is True
- assert version_satisfies(parse_version("1.0.1"), constraint) is False
+ assert version_satisfies(parse_version("1.0.0"), constraint=constraint) is True
+ assert version_satisfies(parse_version("1.0.1"), constraint=constraint) is False
@pytest.mark.parametrize(
("tag", "expected_major", "expected_minor", "expected_patch"),
@@ -187,39 +187,39 @@ class TestSemver:
"""MVS returns the lowest version satisfying the constraint."""
versions = [Version("1.0.0"), Version("1.1.0"), Version("1.2.0"), Version("2.0.0")]
constraint = SimpleSpec("^1.0.0")
- result = select_minimum_version(versions, constraint)
+ result = select_minimum_version(versions, constraint=constraint)
assert result == Version("1.0.0")
def test_select_minimum_version_skips_non_matching(self) -> None:
"""MVS skips versions that don't satisfy the constraint."""
versions = [Version("0.9.0"), Version("1.0.0"), Version("1.5.0")]
constraint = SimpleSpec(">=1.0.0")
- result = select_minimum_version(versions, constraint)
+ result = select_minimum_version(versions, constraint=constraint)
assert result == Version("1.0.0")
def test_select_minimum_version_no_match(self) -> None:
"""MVS returns None when no version matches."""
versions = [Version("1.0.0")]
constraint = SimpleSpec("^2.0.0")
- result = select_minimum_version(versions, constraint)
+ result = select_minimum_version(versions, constraint=constraint)
assert result is None
def test_select_minimum_version_empty_list(self) -> None:
"""MVS returns None for an empty version list."""
constraint = SimpleSpec("^1.0.0")
- result = select_minimum_version([], constraint)
+ result = select_minimum_version([], constraint=constraint)
assert result is None
def test_select_minimum_version_multiple_constraints(self) -> None:
"""Multi-constraint MVS returns the lowest version satisfying all constraints."""
versions = [Version("1.0.0"), Version("1.2.0"), Version("2.0.0")]
constraints = [SimpleSpec(">=1.0.0"), SimpleSpec(">=1.2.0")]
- result = select_minimum_version_for_multiple_constraints(versions, constraints)
+ result = select_minimum_version_for_multiple_constraints(versions, constraints=constraints)
assert result == Version("1.2.0")
def test_select_minimum_version_multiple_constraints_unsatisfiable(self) -> None:
"""Multi-constraint MVS returns None when constraints are unsatisfiable together."""
versions = [Version("1.0.0"), Version("2.0.0")]
constraints = [SimpleSpec(">=1.5.0"), SimpleSpec("<2.0.0")]
- result = select_minimum_version_for_multiple_constraints(versions, constraints)
+ result = select_minimum_version_for_multiple_constraints(versions, constraints=constraints)
assert result is None
diff --git a/tests/unit/pipelex/tools/misc/test_string_utils.py b/tests/unit/pipelex/tools/misc/test_string_utils.py
index ccbba17ff..6eaab25a3 100644
--- a/tests/unit/pipelex/tools/misc/test_string_utils.py
+++ b/tests/unit/pipelex/tools/misc/test_string_utils.py
@@ -368,31 +368,31 @@ class TestMatchesWildcardPattern:
],
)
def test_matches_wildcard_pattern(self, text: str, pattern: str, expected: bool) -> None:
- assert matches_wildcard_pattern(text, pattern) is expected
+ assert matches_wildcard_pattern(text, pattern=pattern) is expected
def test_matches_wildcard_pattern_model_routing_examples(self) -> None:
"""Test with real-world model routing examples."""
# Claude models
- assert matches_wildcard_pattern("claude-3-sonnet", "claude-*") is True
- assert matches_wildcard_pattern("claude-3-haiku", "claude-*") is True
- assert matches_wildcard_pattern("claude-3.5-sonnet", "claude-*") is True
+ assert matches_wildcard_pattern("claude-3-sonnet", pattern="claude-*") is True
+ assert matches_wildcard_pattern("claude-3-haiku", pattern="claude-*") is True
+ assert matches_wildcard_pattern("claude-3.5-sonnet", pattern="claude-*") is True
# GPT models
- assert matches_wildcard_pattern("gpt-4o-mini", "gpt-*") is True
- assert matches_wildcard_pattern("gpt-4", "gpt-*") is True
- assert matches_wildcard_pattern("gpt-3.5-turbo", "gpt-*") is True
+ assert matches_wildcard_pattern("gpt-4o-mini", pattern="gpt-*") is True
+ assert matches_wildcard_pattern("gpt-4", pattern="gpt-*") is True
+ assert matches_wildcard_pattern("gpt-3.5-turbo", pattern="gpt-*") is True
# Mistral models
- assert matches_wildcard_pattern("mistral-large", "*large") is True
- assert matches_wildcard_pattern("mistral-medium", "*medium") is True
- assert matches_wildcard_pattern("mistral-small", "*small") is True
+ assert matches_wildcard_pattern("mistral-large", pattern="*large") is True
+ assert matches_wildcard_pattern("mistral-medium", pattern="*medium") is True
+ assert matches_wildcard_pattern("mistral-small", pattern="*small") is True
# Contains patterns
- assert matches_wildcard_pattern("claude-3-sonnet", "*sonnet*") is True
- assert matches_wildcard_pattern("gpt-4o-mini", "*4o*") is True
- assert matches_wildcard_pattern("mistral-large-instruct", "*large*") is True
+ assert matches_wildcard_pattern("claude-3-sonnet", pattern="*sonnet*") is True
+ assert matches_wildcard_pattern("gpt-4o-mini", pattern="*4o*") is True
+ assert matches_wildcard_pattern("mistral-large-instruct", pattern="*large*") is True
# Negative cases
- assert matches_wildcard_pattern("gemini-pro", "claude-*") is False
- assert matches_wildcard_pattern("llama-2", "*gpt*") is False
- assert matches_wildcard_pattern("anthropic-claude", "*sonnet") is False
+ assert matches_wildcard_pattern("gemini-pro", pattern="claude-*") is False
+ assert matches_wildcard_pattern("llama-2", pattern="*gpt*") is False
+ assert matches_wildcard_pattern("anthropic-claude", pattern="*sonnet") is False
diff --git a/tests/unit/pipelex/tools/misc/test_toml_sync_nested_access.py b/tests/unit/pipelex/tools/misc/test_toml_sync_nested_access.py
index aab89c1f6..4282c1ad8 100644
--- a/tests/unit/pipelex/tools/misc/test_toml_sync_nested_access.py
+++ b/tests/unit/pipelex/tools/misc/test_toml_sync_nested_access.py
@@ -36,7 +36,7 @@ class TestTomlSyncNestedAccess:
def test_get_nested_value_found(self, doc_kind: str, key_path: str, expected_value: Any) -> None:
"""Existing top-level, 2-deep and 3-deep dotted paths are found with the right value."""
doc = make_doc(doc_kind)
- found, value = get_nested_value(doc, key_path)
+ found, value = get_nested_value(doc, key_path=key_path)
assert found is True
assert value == expected_value
@@ -54,7 +54,7 @@ class TestTomlSyncNestedAccess:
def test_get_nested_value_not_found(self, doc_kind: str, key_path: str) -> None:
"""Missing leaves, missing intermediate tables and traversal through scalars all yield (False, None)."""
doc = make_doc(doc_kind)
- found, value = get_nested_value(doc, key_path)
+ found, value = get_nested_value(doc, key_path=key_path)
assert found is False
assert value is None
diff --git a/tests/unit/pipelex/tools/misc/test_toml_sync_set_value.py b/tests/unit/pipelex/tools/misc/test_toml_sync_set_value.py
index e3ed165b7..024ea0bc9 100644
--- a/tests/unit/pipelex/tools/misc/test_toml_sync_set_value.py
+++ b/tests/unit/pipelex/tools/misc/test_toml_sync_set_value.py
@@ -34,7 +34,7 @@ class TestTomlSyncSetValue:
def test_set_existing_key(self, key_path: str, new_value: str | int) -> None:
"""Setting an existing top-level or nested key returns True and changes the value in the doc."""
doc = tomlkit.parse(NESTED_TOML_CONTENT)
- result = set_nested_value(doc, key_path, new_value)
+ result = set_nested_value(doc, key_path=key_path, value=new_value)
assert result is True
current: Any = doc
for key in key_path.split("."):
@@ -55,20 +55,20 @@ class TestTomlSyncSetValue:
def test_missing_key_returns_false_and_doc_untouched(self, key_path: str) -> None:
"""Missing final key, missing intermediate table or traversal through a scalar returns False and never creates the key."""
doc = tomlkit.parse(NESTED_TOML_CONTENT)
- result = set_nested_value(doc, key_path, "intruder")
+ result = set_nested_value(doc, key_path=key_path, value="intruder")
assert result is False
assert dump_doc(doc) == NESTED_TOML_CONTENT
def test_set_value_preserves_inline_comment(self) -> None:
"""Replacing a value keeps the existing inline comment via trivia restoration."""
doc = tomlkit.parse("timeout = 30 # seconds\n")
- result = set_nested_value(doc, "timeout", 60)
+ result = set_nested_value(doc, key_path="timeout", value=60)
assert result is True
assert dump_doc(doc) == "timeout = 60 # seconds\n"
def test_set_value_preserves_inline_comment_on_nested_key(self) -> None:
"""Trivia restoration also applies to keys inside a [section] table."""
doc = tomlkit.parse('[section]\nname = "old" # keep me\n')
- result = set_nested_value(doc, "section.name", "new")
+ result = set_nested_value(doc, key_path="section.name", value="new")
assert result is True
assert dump_doc(doc) == '[section]\nname = "new" # keep me\n'
diff --git a/tests/unit/pipelex/tools/misc/test_toml_sync_values.py b/tests/unit/pipelex/tools/misc/test_toml_sync_values.py
index ebe5e9ebc..c7e91f7fd 100644
--- a/tests/unit/pipelex/tools/misc/test_toml_sync_values.py
+++ b/tests/unit/pipelex/tools/misc/test_toml_sync_values.py
@@ -55,7 +55,7 @@ class TestSyncTomlValues:
"""Differing values are updated in place while header comments, inline comments and blank lines all survive."""
source_path, target_path = write_pair(tmp_path, SOURCE_CONTENT, TARGET_CONTENT)
- result = sync_toml_values(source_path, target_path)
+ result = sync_toml_values(source_path=source_path, target_path=target_path)
assert target_path.read_text() == SYNCED_TARGET_CONTENT
assert result.updated_keys == ["title", "section.sub.deep"]
@@ -75,7 +75,7 @@ class TestSyncTomlValues:
'shared = "from-target"\n',
)
- result = sync_toml_values(source_path, target_path)
+ result = sync_toml_values(source_path=source_path, target_path=target_path)
target_text = target_path.read_text()
assert "source_only" not in target_text
@@ -90,7 +90,7 @@ class TestSyncTomlValues:
'shared = "same"\ntarget_only = "precious" # do not lose\n',
)
- result = sync_toml_values(source_path, target_path)
+ result = sync_toml_values(source_path=source_path, target_path=target_path)
assert target_path.read_text() == 'shared = "same"\ntarget_only = "precious" # do not lose\n'
assert result.updated_keys == []
@@ -102,7 +102,7 @@ class TestSyncTomlValues:
source_path, target_path = write_pair(tmp_path, SOURCE_CONTENT, TARGET_CONTENT)
bytes_before = target_path.read_bytes()
- result = sync_toml_values(source_path, target_path, dry_run=True)
+ result = sync_toml_values(source_path=source_path, target_path=target_path, dry_run=True)
assert target_path.read_bytes() == bytes_before
assert result.updated_keys == ["title", "section.sub.deep"]
@@ -117,7 +117,7 @@ class TestSyncTomlValues:
source_path, target_path = write_pair(tmp_path, 'answer = 42\n\n[section]\nkey = "tight"\n', quirky_target)
bytes_before = target_path.read_bytes()
- result = sync_toml_values(source_path, target_path)
+ result = sync_toml_values(source_path=source_path, target_path=target_path)
assert target_path.read_bytes() == bytes_before
assert result.updated_keys == []
@@ -127,10 +127,10 @@ class TestSyncTomlValues:
"""A second sync after a first one that applied changes finds nothing to update and leaves the bytes identical."""
source_path, target_path = write_pair(tmp_path, SOURCE_CONTENT, TARGET_CONTENT)
- first_result = sync_toml_values(source_path, target_path)
+ first_result = sync_toml_values(source_path=source_path, target_path=target_path)
bytes_after_first = target_path.read_bytes()
- second_result = sync_toml_values(source_path, target_path)
+ second_result = sync_toml_values(source_path=source_path, target_path=target_path)
assert first_result.updated_keys == ["title", "section.sub.deep"]
assert second_result.updated_keys == []
@@ -146,7 +146,7 @@ class TestSyncTomlValues:
"count = 30 # inline note\n\n[outer.inner]\nflag = false\n",
)
- result = sync_toml_values(source_path, target_path)
+ result = sync_toml_values(source_path=source_path, target_path=target_path)
assert target_path.read_text() == 'count = "thirty" # inline note\n\n[outer.inner]\nflag = true\n'
assert result.updated_keys == ["count", "outer.inner.flag"]
@@ -163,7 +163,7 @@ class TestSyncTomlValues:
'[[servers]]\nname = "beta"\nport = 8000\n\n[[servers]]\nname = "gamma"\nport = 8001\n',
)
- result = sync_toml_values(source_path, target_path)
+ result = sync_toml_values(source_path=source_path, target_path=target_path)
assert target_path.read_text() == '[[servers]]\nname = "alpha"\nport = 9000\n'
assert result.updated_keys == ["servers"]
@@ -181,4 +181,4 @@ class TestSyncTomlValues:
source_path, target_path = existing_path, absent_path
with pytest.raises(FileNotFoundError):
- sync_toml_values(source_path, target_path)
+ sync_toml_values(source_path=source_path, target_path=target_path)
diff --git a/tests/unit/pipelex/tools/network/test_ssrf_guard.py b/tests/unit/pipelex/tools/network/test_ssrf_guard.py
index b00479eab..8fdf799f0 100644
--- a/tests/unit/pipelex/tools/network/test_ssrf_guard.py
+++ b/tests/unit/pipelex/tools/network/test_ssrf_guard.py
@@ -24,7 +24,7 @@ class TestSsrfGuard:
return _addrinfo("93.184.216.34", 443)
mocker.patch("socket.getaddrinfo", side_effect=fake)
- assert await resolve_to_allowed_ips("example.com", 443) == ["93.184.216.34"]
+ assert await resolve_to_allowed_ips("example.com", port=443) == ["93.184.216.34"]
async def test_resolve_returns_all_public_ips_in_order(self, mocker: MockerFixture) -> None:
# Every vetted IP is returned (not just the first) so the caller can fall back.
@@ -32,7 +32,7 @@ class TestSsrfGuard:
return _addrinfo("93.184.216.34", 443) + _addrinfo("8.8.8.8", 443)
mocker.patch("socket.getaddrinfo", side_effect=fake)
- assert await resolve_to_allowed_ips("example.com", 443) == ["93.184.216.34", "8.8.8.8"]
+ assert await resolve_to_allowed_ips("example.com", port=443) == ["93.184.216.34", "8.8.8.8"]
async def test_resolve_blocks_private_resolution(self, mocker: MockerFixture) -> None:
def fake(*_args: object, **_kwargs: object) -> list[tuple[int, int, int, str, tuple[str, int]]]:
@@ -40,12 +40,12 @@ class TestSsrfGuard:
mocker.patch("socket.getaddrinfo", side_effect=fake)
with pytest.raises(SsrfBlockedError):
- await resolve_to_allowed_ips("attacker.example", 80)
+ await resolve_to_allowed_ips("attacker.example", port=80)
async def test_resolve_blocks_literal_private_host(self) -> None:
# A literal private IP never needs resolution — blocked by the cheap rule.
with pytest.raises(SsrfBlockedError):
- await resolve_to_allowed_ips("10.0.0.5", 80)
+ await resolve_to_allowed_ips("10.0.0.5", port=80)
async def test_resolve_blocks_mixed_public_and_private(self, mocker: MockerFixture) -> None:
# A host resolving to both a public and a private IP is itself a rebinding
@@ -55,13 +55,13 @@ class TestSsrfGuard:
mocker.patch("socket.getaddrinfo", side_effect=fake)
with pytest.raises(SsrfBlockedError):
- await resolve_to_allowed_ips("rebind.example", 80)
+ await resolve_to_allowed_ips("rebind.example", port=80)
async def test_resolution_failure_maps_to_connect_error(self, mocker: MockerFixture) -> None:
# A genuine DNS failure is not a security event — surface httpx's usual connect error.
mocker.patch("socket.getaddrinfo", side_effect=socket.gaierror("name or service not known"))
with pytest.raises(httpcore.ConnectError):
- await resolve_to_allowed_ips("nonexistent.invalid", 80)
+ await resolve_to_allowed_ips("nonexistent.invalid", port=80)
async def test_resolution_timeout_maps_to_connect_timeout(self, mocker: MockerFixture) -> None:
# DNS resolution is bounded by the connect timeout; a slow resolver surfaces as
@@ -72,7 +72,7 @@ class TestSsrfGuard:
mocker.patch("socket.getaddrinfo", side_effect=slow)
with pytest.raises(httpcore.ConnectTimeout):
- await resolve_to_allowed_ips("slow.example", 80, timeout=0.01)
+ await resolve_to_allowed_ips("slow.example", port=80, timeout=0.01)
async def test_connect_falls_back_across_vetted_ips(self, mocker: MockerFixture) -> None:
# First vetted IP is unreachable; the guard must fall back to the next vetted IP.
diff --git a/tests/unit/pipelex/tools/secrets/test_secrets_utils.py b/tests/unit/pipelex/tools/secrets/test_secrets_utils.py
index cf6f2818e..687bdc1a4 100644
--- a/tests/unit/pipelex/tools/secrets/test_secrets_utils.py
+++ b/tests/unit/pipelex/tools/secrets/test_secrets_utils.py
@@ -19,21 +19,21 @@ class TestSubstituteVars:
def test_simple_secret_substitution(self, mock_secrets_provider: Any) -> None:
mock_secrets_provider.get_secret.return_value = "secret_value"
- result = substitute_vars("Hello ${API_KEY}", mock_secrets_provider)
+ result = substitute_vars("Hello ${API_KEY}", secrets_provider=mock_secrets_provider)
assert result == "Hello secret_value"
mock_secrets_provider.get_secret.assert_called_once_with(secret_id="API_KEY")
def test_explicit_env_substitution(self, mocker: MockerFixture, mock_secrets_provider: Any) -> None:
mocker.patch.dict(os.environ, {"TEST_VAR": "env_value"})
- result = substitute_vars("Value: ${env:TEST_VAR}", mock_secrets_provider)
+ result = substitute_vars("Value: ${env:TEST_VAR}", secrets_provider=mock_secrets_provider)
assert result == "Value: env_value"
def test_explicit_secret_substitution(self, mock_secrets_provider: Any) -> None:
mock_secrets_provider.get_secret.return_value = "secret_value"
- result = substitute_vars("Value: ${secret:API_KEY}", mock_secrets_provider)
+ result = substitute_vars("Value: ${secret:API_KEY}", secrets_provider=mock_secrets_provider)
assert result == "Value: secret_value"
mock_secrets_provider.get_secret.assert_called_once_with(secret_id="API_KEY")
@@ -41,7 +41,7 @@ class TestSubstituteVars:
def test_fallback_env_to_secret(self, mock_secrets_provider: Any) -> None:
mock_secrets_provider.get_secret.return_value = "secret_fallback"
- result = substitute_vars("Value: ${env:MISSING_VAR|secret:FALLBACK_KEY}", mock_secrets_provider)
+ result = substitute_vars("Value: ${env:MISSING_VAR|secret:FALLBACK_KEY}", secrets_provider=mock_secrets_provider)
assert result == "Value: secret_fallback"
mock_secrets_provider.get_secret.assert_called_once_with(secret_id="FALLBACK_KEY")
@@ -49,7 +49,7 @@ class TestSubstituteVars:
def test_env_takes_precedence_in_fallback(self, mocker: MockerFixture, mock_secrets_provider: Any) -> None:
mocker.patch.dict(os.environ, {"EXISTING_VAR": "env_value"})
- result = substitute_vars("Value: ${env:EXISTING_VAR|secret:FALLBACK_KEY}", mock_secrets_provider)
+ result = substitute_vars("Value: ${env:EXISTING_VAR|secret:FALLBACK_KEY}", secrets_provider=mock_secrets_provider)
assert result == "Value: env_value"
# Secret should not be called since env var was found
@@ -60,7 +60,7 @@ class TestSubstituteVars:
mock_secrets_provider.get_secret.side_effect = SecretNotFoundError("Secret not found")
mocker.patch.dict(os.environ, {"FALLBACK_ENV": "env_fallback"})
- result = substitute_vars("Value: ${secret:MISSING_SECRET|env:FALLBACK_ENV}", mock_secrets_provider)
+ result = substitute_vars("Value: ${secret:MISSING_SECRET|env:FALLBACK_ENV}", secrets_provider=mock_secrets_provider)
assert result == "Value: env_fallback"
mock_secrets_provider.get_secret.assert_called_once_with(secret_id="MISSING_SECRET")
@@ -70,7 +70,7 @@ class TestSubstituteVars:
mock_secrets_provider.get_secret.return_value = "secret_value"
mocker.patch.dict(os.environ, {"EXISTING_VAR": "env_value"})
- result = substitute_vars("Value: ${secret:EXISTING_SECRET|env:EXISTING_VAR}", mock_secrets_provider)
+ result = substitute_vars("Value: ${secret:EXISTING_SECRET|env:EXISTING_VAR}", secrets_provider=mock_secrets_provider)
assert result == "Value: secret_value"
mock_secrets_provider.get_secret.assert_called_once_with(secret_id="EXISTING_SECRET")
@@ -81,54 +81,54 @@ class TestSubstituteVars:
mocker.patch.dict(os.environ, {"ENV_VAR": "env_value"})
content = "API: ${API_KEY}, DB: ${env:ENV_VAR}, Token: ${secret:TOKEN}"
- result = substitute_vars(content, mock_secrets_provider)
+ result = substitute_vars(content, secrets_provider=mock_secrets_provider)
assert result == "API: secret_API_KEY, DB: env_value, Token: secret_TOKEN"
def test_no_placeholders(self, mock_secrets_provider: Any) -> None:
"""Test content with no placeholders remains unchanged."""
content = "This is just plain text with no variables"
- result = substitute_vars(content, mock_secrets_provider)
+ result = substitute_vars(content, secrets_provider=mock_secrets_provider)
assert result == content
def test_missing_env_var_raises_error(self, mock_secrets_provider: Any) -> None:
"""Test that missing required env var raises VarNotFoundError."""
with pytest.raises(VarNotFoundError, match="Environment variable 'MISSING_VAR' is required but not set"):
- substitute_vars("Value: ${env:MISSING_VAR}", mock_secrets_provider)
+ substitute_vars("Value: ${env:MISSING_VAR}", secrets_provider=mock_secrets_provider)
def test_missing_secret_raises_error(self, mock_secrets_provider: Any) -> None:
"""Test that missing required secret raises error."""
mock_secrets_provider.get_secret.side_effect = SecretNotFoundError("Secret not found")
with pytest.raises(VarNotFoundError, match="Could not get variable 'MISSING_SECRET': Secret not found"):
- substitute_vars("Value: ${secret:MISSING_SECRET}", mock_secrets_provider)
+ substitute_vars("Value: ${secret:MISSING_SECRET}", secrets_provider=mock_secrets_provider)
def test_missing_default_secret_raises_error(self, mock_secrets_provider: Any) -> None:
"""Test that missing default secret (no prefix) raises error."""
mock_secrets_provider.get_secret.side_effect = SecretNotFoundError("Secret not found")
with pytest.raises(VarNotFoundError, match="Could not get variable 'MISSING_SECRET': Secret not found"):
- substitute_vars("Value: ${MISSING_SECRET}", mock_secrets_provider)
+ substitute_vars("Value: ${MISSING_SECRET}", secrets_provider=mock_secrets_provider)
def test_fallback_both_missing_raises_error(self, mock_secrets_provider: Any) -> None:
mock_secrets_provider.get_secret.side_effect = SecretNotFoundError("Secret not found")
with pytest.raises(VarFallbackPatternError, match="Could not get variable from fallback pattern: env:MISSING_ENV\\|secret:MISSING_SECRET"):
- substitute_vars("Value: ${env:MISSING_ENV|secret:MISSING_SECRET}", mock_secrets_provider)
+ substitute_vars("Value: ${env:MISSING_ENV|secret:MISSING_SECRET}", secrets_provider=mock_secrets_provider)
def test_reverse_fallback_both_missing_raises_error(self, mock_secrets_provider: Any) -> None:
"""Test that when both secret and env are missing in reverse order, error is raised."""
mock_secrets_provider.get_secret.side_effect = SecretNotFoundError("Secret not found")
with pytest.raises(VarFallbackPatternError, match="Could not get variable from fallback pattern: secret:MISSING_SECRET\\|env:MISSING_ENV"):
- substitute_vars("Value: ${secret:MISSING_SECRET|env:MISSING_ENV}", mock_secrets_provider)
+ substitute_vars("Value: ${secret:MISSING_SECRET|env:MISSING_ENV}", secrets_provider=mock_secrets_provider)
def test_complex_variable_names(self, mocker: MockerFixture, mock_secrets_provider: Any) -> None:
"""Test complex variable names with underscores, numbers, etc."""
mock_secrets_provider.get_secret.return_value = "complex_secret"
mocker.patch.dict(os.environ, {"API_KEY_V2": "complex_env"})
- result = substitute_vars("${env:API_KEY_V2} and ${DB_PASSWORD_123}", mock_secrets_provider)
+ result = substitute_vars("${env:API_KEY_V2} and ${DB_PASSWORD_123}", secrets_provider=mock_secrets_provider)
assert result == "complex_env and complex_secret"
@@ -137,7 +137,7 @@ class TestSubstituteVars:
mock_secrets_provider.get_secret.return_value = "secret_value"
# Note: whitespace should be preserved as part of the variable name
- result = substitute_vars("Value: ${ API_KEY }", mock_secrets_provider)
+ result = substitute_vars("Value: ${ API_KEY }", secrets_provider=mock_secrets_provider)
assert result == "Value: secret_value"
mock_secrets_provider.get_secret.assert_called_once_with(secret_id=" API_KEY ")
@@ -149,7 +149,7 @@ class TestSubstituteVars:
mock_secrets_provider.get_secret.return_value = "secret_nested"
content = "This ${has ${nested} braces} should not match"
- result = substitute_vars(content, mock_secrets_provider)
+ result = substitute_vars(content, secrets_provider=mock_secrets_provider)
# The ${nested} part should be substituted, but ${has ... should not be matched
# because it contains a $ character which breaks the pattern
@@ -164,7 +164,7 @@ class TestSubstituteVars:
content = """Line 1: ${API_KEY}
Line 2: Some text
Line 3: ${env:HOME}"""
- result = substitute_vars(content, mock_secrets_provider)
+ result = substitute_vars(content, secrets_provider=mock_secrets_provider)
expected = """Line 1: secret_value
Line 2: Some text
@@ -175,18 +175,18 @@ Line 3: /home/user"""
"""Test that the pattern doesn't match variables that span multiple lines."""
content = """This ${VAR
NAME} should not match"""
- result = substitute_vars(content, mock_secrets_provider)
+ result = substitute_vars(content, secrets_provider=mock_secrets_provider)
# Should remain unchanged
assert result == content
def test_pattern_does_not_match_with_quotes(self, mock_secrets_provider: Any) -> None:
"""Test that the pattern doesn't match variables containing quotes."""
content = "This ${VAR\"NAME} and ${VAR'NAME} should not match"
- result = substitute_vars(content, mock_secrets_provider)
+ result = substitute_vars(content, secrets_provider=mock_secrets_provider)
# Should remain unchanged
assert result == content
def test_unknown_prefix_raises_error(self, mock_secrets_provider: Any) -> None:
"""Test that unknown prefix raises UnknownVarPrefixError."""
with pytest.raises(UnknownVarPrefixError, match="Unknown variable prefix: 'foo'"):
- substitute_vars("Value: ${foo:BAR}", mock_secrets_provider)
+ substitute_vars("Value: ${foo:BAR}", secrets_provider=mock_secrets_provider)
diff --git a/tests/unit/pipelex/tools/tabular/test_csv_codec.py b/tests/unit/pipelex/tools/tabular/test_csv_codec.py
index f80376292..25d5f02e6 100644
--- a/tests/unit/pipelex/tools/tabular/test_csv_codec.py
+++ b/tests/unit/pipelex/tools/tabular/test_csv_codec.py
@@ -214,7 +214,7 @@ class TestCsvCodec:
# The headline use case: a BOM-prefixed file (from Excel) binds to a concept without a column error.
path = tmp_path / "bom_required.csv"
path.write_bytes(b"\xef\xbb\xbftext\nhello\n")
- item = list_content_from_csv(path, RequiredTextRow).items[0]
+ item = list_content_from_csv(path, row_model=RequiredTextRow).items[0]
assert item.text == "hello"
def test_read_empty_file_raises(self, tmp_path: Path) -> None:
@@ -228,14 +228,14 @@ class TestCsvCodec:
def test_read_header_only_into_empty_list_content(self, tmp_path: Path) -> None:
# A valid header with zero data rows reads as an empty ListContent (the read-side empty path).
path = write_csv_file(tmp_path, "name,age,height,active,born\n")
- result = list_content_from_csv(path, FlatRow)
+ result = list_content_from_csv(path, row_model=FlatRow)
assert result.items == []
def test_short_row_pads_missing_trailing_cell_to_none(self, tmp_path: Path) -> None:
# A data row with FEWER cells than the header pads the missing trailing column → None on an
# optional field (exercises _row_to_dict's padding branch, not just an explicit empty cell).
path = write_csv_file(tmp_path, "name,age,height,active,born,nickname\nAda,36,1.7,true,1815-12-10\n")
- item = list_content_from_csv(path, FlatRow).items[0]
+ item = list_content_from_csv(path, row_model=FlatRow).items[0]
assert item.nickname is None
assert item.name == "Ada"
@@ -277,12 +277,12 @@ class TestCsvCodec:
def test_write_rows_then_read_rows_round_trips(self, tmp_path: Path) -> None:
path = tmp_path / "out.csv"
rows = [{"name": "Ada", "age": "36"}, {"name": "Grace", "age": "85"}]
- write_rows(path, headers=["name", "age"], rows=rows)
+ write_rows(path=path, headers=["name", "age"], rows=rows)
assert read_rows(path) == rows
def test_write_rows_empty_writes_header_only(self, tmp_path: Path) -> None:
path = tmp_path / "empty.csv"
- write_rows(path, headers=["name", "age"], rows=[])
+ write_rows(path=path, headers=["name", "age"], rows=[])
text = path.read_text(encoding="utf-8")
assert text.splitlines() == ["name,age"]
@@ -327,7 +327,7 @@ class TestCsvCodec:
tmp_path,
"name,age,height,active,born,nickname\nAda,36,1.7,true,1815-12-10,Countess\n",
)
- list_content = list_content_from_csv(path, FlatRow)
+ list_content = list_content_from_csv(path, row_model=FlatRow)
assert isinstance(list_content, ListContent)
assert len(list_content.items) == 1
item = list_content.items[0]
@@ -344,14 +344,14 @@ class TestCsvCodec:
tmp_path,
"name,age,height,active,born,nickname\nVint,82,1.8,true,1943-06-23,\n",
)
- item = list_content_from_csv(path, FlatRow).items[0]
+ item = list_content_from_csv(path, row_model=FlatRow).items[0]
assert item.nickname is None
def test_empty_cell_on_required_field_raises(self, tmp_path: Path) -> None:
# A genuine quoted-empty cell (not a blank line) -> None -> required int fails coercion.
path = write_value_csv(tmp_path, "", name="req.csv")
with pytest.raises(CsvCoercionError):
- list_content_from_csv(path, IntRow)
+ list_content_from_csv(path, row_model=IntRow)
@pytest.mark.parametrize(
("row_model", "cell", "expected"),
@@ -371,7 +371,7 @@ class TestCsvCodec:
)
def test_coercion_accept_table(self, tmp_path: Path, row_model: type[StructuredContent], cell: str, expected: object) -> None:
path = write_value_csv(tmp_path, cell)
- item = list_content_from_csv(path, row_model).items[0]
+ item = list_content_from_csv(path, row_model=row_model).items[0]
assert item.model_dump()["value"] == expected
@pytest.mark.parametrize(
@@ -385,12 +385,12 @@ class TestCsvCodec:
def test_coercion_reject_table(self, tmp_path: Path, row_model: type[StructuredContent], cell: str) -> None:
path = write_value_csv(tmp_path, cell)
with pytest.raises(CsvCoercionError):
- list_content_from_csv(path, row_model)
+ list_content_from_csv(path, row_model=row_model)
def test_coercion_failure_names_row_and_field(self, tmp_path: Path) -> None:
path = write_csv_file(tmp_path, "value\n42\noops\n")
with pytest.raises(CsvCoercionError) as exc_info:
- list_content_from_csv(path, IntRow)
+ list_content_from_csv(path, row_model=IntRow)
message = str(exc_info.value)
assert "value" in message
assert "row 3" in message # 'oops' is on physical CSV line 3 (header=1, '42'=2, 'oops'=3)
@@ -400,7 +400,7 @@ class TestCsvCodec:
# the raw offending cell content — only row/field identifiers and the expected-type reason.
path = write_csv_file(tmp_path, "value\nSUPERSECRET_TOKEN_xyz\n")
with pytest.raises(CsvCoercionError) as exc_info:
- list_content_from_csv(path, IntRow)
+ list_content_from_csv(path, row_model=IntRow)
message = str(exc_info.value)
assert "SUPERSECRET_TOKEN_xyz" not in message
assert "value" in message # the field is still named so the author can locate it
@@ -408,16 +408,16 @@ class TestCsvCodec:
def test_string_literal_and_str_enum_round_trip_on_read(self, tmp_path: Path) -> None:
# The read-side coercion of accepted string Literal / StrEnum cells (flat_field_names accepts
# them; this confirms the cell actually coerces to the member through list_content_from_csv).
- literal_item = list_content_from_csv(write_csv_file(tmp_path, "name,rating\nAda,high\n", name="lit.csv"), LiteralRow).items[0]
+ literal_item = list_content_from_csv(write_csv_file(tmp_path, "name,rating\nAda,high\n", name="lit.csv"), row_model=LiteralRow).items[0]
assert literal_item.rating == "high"
- enum_item = list_content_from_csv(write_csv_file(tmp_path, "name,grade\nAda,pass\n", name="enum.csv"), StrEnumRow).items[0]
+ enum_item = list_content_from_csv(write_csv_file(tmp_path, "name,grade\nAda,pass\n", name="enum.csv"), row_model=StrEnumRow).items[0]
assert enum_item.grade == Grade.PASS
@pytest.mark.parametrize(("row_model", "bad_cell"), [(LiteralRow, "name,rating\nAda,medium\n"), (StrEnumRow, "name,grade\nAda,unknown\n")])
def test_out_of_choice_value_raises_coercion(self, tmp_path: Path, row_model: type[StructuredContent], bad_cell: str) -> None:
# An out-of-choice value for a Literal/StrEnum column fails coercion with a typed error.
with pytest.raises(CsvCoercionError):
- list_content_from_csv(write_csv_file(tmp_path, bad_cell), row_model)
+ list_content_from_csv(write_csv_file(tmp_path, bad_cell), row_model=row_model)
# ----------------------------------------------------------------------------------
# Strict columns
@@ -426,18 +426,18 @@ class TestCsvCodec:
def test_extra_column_raises(self, tmp_path: Path) -> None:
path = write_csv_file(tmp_path, "value,surprise\n42,boom\n")
with pytest.raises(CsvColumnError):
- list_content_from_csv(path, IntRow)
+ list_content_from_csv(path, row_model=IntRow)
def test_missing_required_column_raises(self, tmp_path: Path) -> None:
# 'nickname' is optional so its absence is fine; drop a REQUIRED column ('name') instead.
path = write_csv_file(tmp_path, "age,height,active,born,nickname\n36,1.7,true,1815-12-10,x\n", name="missing_req.csv")
with pytest.raises(CsvColumnError):
- list_content_from_csv(path, FlatRow)
+ list_content_from_csv(path, row_model=FlatRow)
def test_missing_optional_column_sets_field_none(self, tmp_path: Path) -> None:
# 'nickname' (optional) column omitted entirely → None for every row (CT2 lenient).
path = write_csv_file(tmp_path, "name,age,height,active,born\nAda,36,1.7,true,1815-12-10\n")
- item = list_content_from_csv(path, FlatRow).items[0]
+ item = list_content_from_csv(path, row_model=FlatRow).items[0]
assert item.nickname is None
assert item.name == "Ada"
@@ -445,14 +445,14 @@ class TestCsvCodec:
# CT2: an omitted NULLABLE column is None for every row even when the field has a NON-None
# default ('anon') — the CSV is the source of truth, not the row model's construction default.
path = write_csv_file(tmp_path, "name\nAda\n")
- item = list_content_from_csv(path, OptDefaultRow).items[0]
+ item = list_content_from_csv(path, row_model=OptDefaultRow).items[0]
assert item.nickname is None
def test_missing_non_nullable_defaulted_column_keeps_default(self, tmp_path: Path) -> None:
# A non-required but NON-nullable field (count: int = 0) keeps its own default when its column
# is omitted — forcing None there would fail validation rather than honor the absence.
path = write_csv_file(tmp_path, "name\nAda\n")
- item = list_content_from_csv(path, IntDefaultRow).items[0]
+ item = list_content_from_csv(path, row_model=IntDefaultRow).items[0]
assert item.count == 0
# ----------------------------------------------------------------------------------
@@ -493,7 +493,7 @@ class TestCsvCodec:
]
)
csv_from_list_content(original, row_model=FlatRow, path=path)
- reloaded = list_content_from_csv(path, FlatRow)
+ reloaded = list_content_from_csv(path, row_model=FlatRow)
assert reloaded.items == original.items
# ----------------------------------------------------------------------------------
@@ -504,14 +504,14 @@ class TestCsvCodec:
path = tmp_path / "opt.csv"
list_content: ListContent[OptionalTextRow] = ListContent(items=[OptionalTextRow(text=None), OptionalTextRow(text="")])
csv_from_list_content(list_content, row_model=OptionalTextRow, path=path)
- reloaded = list_content_from_csv(path, OptionalTextRow)
+ reloaded = list_content_from_csv(path, row_model=OptionalTextRow)
# Empty-string text is indistinguishable from None → both read back as None (documented).
assert [item.text for item in reloaded.items] == [None, None]
def test_required_text_empty_cell_rejected(self, tmp_path: Path) -> None:
path = write_value_csv(tmp_path, "", name="reqtext.csv", header="text")
with pytest.raises(CsvCoercionError):
- list_content_from_csv(path, RequiredTextRow)
+ list_content_from_csv(path, row_model=RequiredTextRow)
# ----------------------------------------------------------------------------------
# Phase-2 review findings (#2 blank lines, #3 over-wide rows, #4 delimiter/encoding,
@@ -521,7 +521,7 @@ class TestCsvCodec:
def test_blank_line_in_body_is_skipped(self, tmp_path: Path) -> None:
# A blank physical line (csv yields []) is skipped, not turned into a phantom all-None row.
path = write_csv_file(tmp_path, "a,b\nx,y\n\nz,w\n")
- items = list_content_from_csv(path, OptPairRow).items
+ items = list_content_from_csv(path, row_model=OptPairRow).items
assert [(item.a, item.b) for item in items] == [("x", "y"), ("z", "w")]
def test_row_wider_than_header_raises(self, tmp_path: Path) -> None:
@@ -538,7 +538,7 @@ class TestCsvCodec:
with pytest.raises(CsvError):
read_rows(read_path, delimiter=bad_delimiter)
with pytest.raises(CsvError):
- write_rows(tmp_path / "out.csv", headers=["a"], rows=[], delimiter=bad_delimiter)
+ write_rows(path=tmp_path / "out.csv", headers=["a"], rows=[], delimiter=bad_delimiter)
def test_unknown_encoding_raises(self, tmp_path: Path) -> None:
path = write_csv_file(tmp_path, "a\n1\n")
@@ -549,7 +549,7 @@ class TestCsvCodec:
# A cell that the target encoding can't represent must surface a typed CsvError on write,
# not let a raw UnicodeEncodeError escape the codec boundary.
with pytest.raises(CsvError):
- write_rows(tmp_path / "out.csv", headers=["name"], rows=[{"name": "café"}], encoding="ascii")
+ write_rows(path=tmp_path / "out.csv", headers=["name"], rows=[{"name": "café"}], encoding="ascii")
def test_write_rejects_item_not_matching_row_model(self, tmp_path: Path) -> None:
# An item whose class isn't the declared row_model would write silent empty cells → reject loudly.
@@ -562,7 +562,7 @@ class TestCsvCodec:
# row and concept (not the unhelpful "field(s) ?").
path = write_csv_file(tmp_path, "a,b\n5,1\n")
with pytest.raises(CsvCoercionError) as exc_info:
- list_content_from_csv(path, OrderedPairRow)
+ list_content_from_csv(path, row_model=OrderedPairRow)
message = str(exc_info.value)
assert "field(s) ?" not in message
# The offending row is the first data row, which is physical CSV line 2 (the header is line 1).
@@ -575,14 +575,14 @@ class TestCsvCodec:
# =2-3), so the error must say "row 4", not "row 3".
path = write_csv_file(tmp_path, 'label,number\n"multi\nline",1\nbad,oops\n')
with pytest.raises(CsvCoercionError) as exc_info:
- list_content_from_csv(path, LabeledIntRow)
+ list_content_from_csv(path, row_model=LabeledIntRow)
assert "row 4" in str(exc_info.value)
def test_coercion_error_row_number_counts_skipped_blank_lines(self, tmp_path: Path) -> None:
# The reported row number is the physical CSV line, even when a blank line was skipped.
path = write_csv_file(tmp_path, "value\n42\n\noops\n")
with pytest.raises(CsvCoercionError) as exc_info:
- list_content_from_csv(path, IntRow)
+ list_content_from_csv(path, row_model=IntRow)
# 'oops' is on physical CSV line 4 (line 1 header, line 2 '42', line 3 blank, line 4 'oops').
assert "row 4" in str(exc_info.value)
diff --git a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
index 92d16d02f..c4fee3b51 100644
--- a/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
+++ b/tests/unit/pipelex/tools/test_jinja2_tag_filter.py
@@ -40,20 +40,20 @@ class TestTagFilterValidation:
context = self._make_context(mocker)
with pytest.raises(Jinja2ContextError, match="undefined"):
- await tag(context, Undefined())
+ await tag(context, value=Undefined())
async def test_tag_raises_on_undefined_with_tag_name(self, mocker: MockerFixture) -> None:
"""Test tag raises error for undefined value with tag name in message."""
context = self._make_context(mocker)
with pytest.raises(Jinja2ContextError, match="tag_name 'my_tag'"):
- await tag(context, Undefined(), tag_name="my_tag")
+ await tag(context, value=Undefined(), tag_name="my_tag")
async def test_tag_with_string_converts_to_string(self, mocker: MockerFixture) -> None:
"""Test tag filter converts plain string input."""
context = self._make_context(mocker)
- result = await tag(context, "hello world")
+ result = await tag(context, value="hello world")
assert "hello world" in result
assert "```" in result # Default style is TICKS
@@ -62,7 +62,7 @@ class TestTagFilterValidation:
"""Test tag filter converts number input to string."""
context = self._make_context(mocker)
- result = await tag(context, 42)
+ result = await tag(context, value=42)
assert "42" in result
@@ -70,7 +70,7 @@ class TestTagFilterValidation:
"""Test tag filter uses provided custom tag name."""
context = self._make_context(mocker, tag_style=TagStyle.XML)
- result = await tag(context, "content", tag_name="custom")
+ result = await tag(context, value="content", tag_name="custom")
assert "<custom>" in result
assert "</custom>" in result
@@ -85,7 +85,7 @@ class TestTagFilterValidation:
mock_renderable.render_for_tag_async = mocker.AsyncMock(return_value="rendered content")
mock_renderable.default_tag_name = "my_stuff"
- result = await tag(context, mock_renderable)
+ result = await tag(context, value=mock_renderable)
mock_renderable.render_for_tag_async.assert_called_once()
assert "rendered content" in result
@@ -99,7 +99,7 @@ class TestTagFilterValidation:
mock_renderable.render_for_tag_async = mocker.AsyncMock(return_value="content")
mock_renderable.default_tag_name = "default_name"
- result = await tag(context, mock_renderable, tag_name="override_name")
+ result = await tag(context, value=mock_renderable, tag_name="override_name")
assert "<override_name>" in result
assert "default_name" not in result
@@ -123,7 +123,7 @@ class TestApplyTagStyle:
"""Test NO_TAG style returns value unchanged."""
context = self._make_context(mocker, TagStyle.NO_TAG)
- result = apply_tag_style(context, "hello", "my_tag")
+ result = apply_tag_style(context=context, value="hello", tag_name="my_tag")
assert result == "hello"
@@ -131,7 +131,7 @@ class TestApplyTagStyle:
"""Test TICKS style without tag name."""
context = self._make_context(mocker, TagStyle.TICKS)
- result = apply_tag_style(context, "content", None)
+ result = apply_tag_style(context=context, value="content", tag_name=None)
assert result == "```\ncontent\n```"
@@ -139,7 +139,7 @@ class TestApplyTagStyle:
"""Test TICKS style with tag name."""
context = self._make_context(mocker, TagStyle.TICKS)
- result = apply_tag_style(context, "content", "my_tag")
+ result = apply_tag_style(context=context, value="content", tag_name="my_tag")
assert result == "my_tag: ```\ncontent\n```"
@@ -147,7 +147,7 @@ class TestApplyTagStyle:
"""Test XML style uses 'data' as default tag name."""
context = self._make_context(mocker, TagStyle.XML)
- result = apply_tag_style(context, "content", None)
+ result = apply_tag_style(context=context, value="content", tag_name=None)
assert result == "<data>\ncontent\n</data>"
@@ -155,7 +155,7 @@ class TestApplyTagStyle:
"""Test XML style with tag name."""
context = self._make_context(mocker, TagStyle.XML)
- result = apply_tag_style(context, "content", "my_tag")
+ result = apply_tag_style(context=context, value="content", tag_name="my_tag")
assert result == "<my_tag>\ncontent\n</my_tag>"
@@ -163,7 +163,7 @@ class TestApplyTagStyle:
"""Test SQUARE_BRACKETS style uses 'data' as default tag name."""
context = self._make_context(mocker, TagStyle.SQUARE_BRACKETS)
- result = apply_tag_style(context, "content", None)
+ result = apply_tag_style(context=context, value="content", tag_name=None)
assert result == "[data]\ncontent\n[/data]"
@@ -171,7 +171,7 @@ class TestApplyTagStyle:
"""Test SQUARE_BRACKETS style with tag name."""
context = self._make_context(mocker, TagStyle.SQUARE_BRACKETS)
- result = apply_tag_style(context, "content", "my_tag")
+ result = apply_tag_style(context=context, value="content", tag_name="my_tag")
assert result == "[my_tag]\ncontent\n[/my_tag]"
@@ -182,6 +182,6 @@ class TestApplyTagStyle:
context = mocker.MagicMock(spec=Context)
context.get = lambda key, default=None: context_dict.get(key, default) # pyright: ignore[reportUnknownLambdaType, reportUnknownArgumentType]
- result = apply_tag_style(context, "content", None)
+ result = apply_tag_style(context=context, value="content", tag_name=None)
assert "```" in result # TICKS is default
diff --git a/tests/unit/pipelex/tools/test_jinja2_template_registry.py b/tests/unit/pipelex/tools/test_jinja2_template_registry.py
index f7f208516..85cfb0152 100644
--- a/tests/unit/pipelex/tools/test_jinja2_template_registry.py
+++ b/tests/unit/pipelex/tools/test_jinja2_template_registry.py
@@ -23,7 +23,7 @@ class TestTemplateRegistry:
template_key = "test/template.html.jinja2"
template_content = "<html>{{ title }}</html>"
- TemplateRegistry.register(template_key, template_content)
+ TemplateRegistry.register(key=template_key, template_source=template_content)
retrieved = TemplateRegistry.get(template_key)
assert retrieved == template_content
@@ -43,15 +43,15 @@ class TestTemplateRegistry:
assert not TemplateRegistry.is_registered(template_key)
- TemplateRegistry.register(template_key, template_content)
+ TemplateRegistry.register(key=template_key, template_source=template_content)
assert TemplateRegistry.is_registered(template_key)
def test_keys(self) -> None:
"""Test listing all registered template keys."""
- TemplateRegistry.register("key1", "content1")
- TemplateRegistry.register("key2", "content2")
- TemplateRegistry.register("key3", "content3")
+ TemplateRegistry.register(key="key1", template_source="content1")
+ TemplateRegistry.register(key="key2", template_source="content2")
+ TemplateRegistry.register(key="key3", template_source="content3")
keys = TemplateRegistry.keys()
@@ -62,8 +62,8 @@ class TestTemplateRegistry:
def test_clear(self) -> None:
"""Test clearing the registry."""
- TemplateRegistry.register("key1", "content1")
- TemplateRegistry.register("key2", "content2")
+ TemplateRegistry.register(key="key1", template_source="content1")
+ TemplateRegistry.register(key="key2", template_source="content2")
assert len(TemplateRegistry.keys()) == 2
@@ -73,8 +73,8 @@ class TestTemplateRegistry:
def test_get_dict_loader(self) -> None:
"""Test that DictLoader is created from registry."""
- TemplateRegistry.register("base.html", "<html>{% block content %}{% endblock %}</html>")
- TemplateRegistry.register("child.html", "{% extends 'base.html' %}{% block content %}Hello{% endblock %}")
+ TemplateRegistry.register(key="base.html", template_source="<html>{% block content %}{% endblock %}</html>")
+ TemplateRegistry.register(key="child.html", template_source="{% extends 'base.html' %}{% block content %}Hello{% endblock %}")
loader = TemplateRegistry.get_dict_loader()
@@ -87,8 +87,8 @@ class TestTemplateRegistry:
def test_dict_loader_supports_includes(self) -> None:
"""Test that DictLoader enables {% include %} statements."""
# Register templates
- TemplateRegistry.register("_partial.html", "<div>Partial content</div>")
- TemplateRegistry.register("main.html", "<html>{% include '_partial.html' %}</html>")
+ TemplateRegistry.register(key="_partial.html", template_source="<div>Partial content</div>")
+ TemplateRegistry.register(key="main.html", template_source="<html>{% include '_partial.html' %}</html>")
# Create environment with DictLoader
loader = TemplateRegistry.get_dict_loader()
@@ -105,10 +105,10 @@ class TestTemplateRegistry:
"""Test that registering with same key overwrites."""
template_key = "test/overwrite.jinja2"
- TemplateRegistry.register(template_key, "original content")
+ TemplateRegistry.register(key=template_key, template_source="original content")
assert TemplateRegistry.get(template_key) == "original content"
- TemplateRegistry.register(template_key, "new content")
+ TemplateRegistry.register(key=template_key, template_source="new content")
assert TemplateRegistry.get(template_key) == "new content"
diff --git a/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py b/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py
index b867a8fc7..9f39f159b 100644
--- a/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py
+++ b/tests/unit/pipelex/tools/test_jinja2_with_images_filter.py
@@ -45,7 +45,7 @@ class TestWithImagesFilterValidation:
context = self._make_context(registry=registry)
with pytest.raises(Jinja2ContextError, match="undefined"):
- with_images(context, Undefined())
+ with_images(context, value=Undefined())
def test_with_images_raises_on_wrong_registry_type(self) -> None:
"""Test with_images raises if registry is wrong type."""
@@ -59,7 +59,7 @@ class TestWithImagesFilterValidation:
# Pass a list (which is accepted by the filter) to trigger the registry type check
with pytest.raises(Jinja2ContextError, match="Expected ImageRegistry"):
- with_images(context, [])
+ with_images(context, value=[])
def test_with_images_raises_on_string_input(self) -> None:
"""Test with_images raises error when receiving a plain string.
@@ -71,7 +71,7 @@ class TestWithImagesFilterValidation:
context = self._make_context(registry=registry)
with pytest.raises(Jinja2ContextError, match="does not implement the ImageRenderable protocol"):
- with_images(context, "This is a plain string")
+ with_images(context, value="This is a plain string")
def test_with_images_raises_on_number_input(self) -> None:
"""Test with_images raises error when receiving a number."""
@@ -79,7 +79,7 @@ class TestWithImagesFilterValidation:
context = self._make_context(registry=registry)
with pytest.raises(Jinja2ContextError, match="does not implement the ImageRenderable protocol"):
- with_images(context, 42)
+ with_images(context, value=42)
def test_with_images_raises_on_dict_input(self) -> None:
"""Test with_images raises error when receiving a plain dict."""
@@ -87,14 +87,14 @@ class TestWithImagesFilterValidation:
context = self._make_context(registry=registry)
with pytest.raises(Jinja2ContextError, match="does not implement the ImageRenderable protocol"):
- with_images(context, {"key": "value"})
+ with_images(context, value={"key": "value"})
def test_with_images_accepts_empty_list(self) -> None:
"""Test with_images handles empty list gracefully."""
registry = ImageRegistry()
context = self._make_context(registry=registry)
- result = with_images(context, [])
+ result = with_images(context, value=[])
assert result == ""
assert len(registry.images) == 0
@@ -107,7 +107,7 @@ class TestRenderSequenceWithImages:
"""Test empty list returns empty string."""
registry = ImageRegistry()
- result = _render_sequence_with_images([], registry, TextFormat.PLAIN)
+ result = _render_sequence_with_images([], registry=registry, text_format=TextFormat.PLAIN)
assert result == ""
assert len(registry.images) == 0
@@ -116,7 +116,7 @@ class TestRenderSequenceWithImages:
"""Test empty tuple returns empty string."""
registry = ImageRegistry()
- result = _render_sequence_with_images((), registry, TextFormat.PLAIN)
+ result = _render_sequence_with_images((), registry=registry, text_format=TextFormat.PLAIN)
assert result == ""
assert len(registry.images) == 0
@@ -125,7 +125,7 @@ class TestRenderSequenceWithImages:
"""Test that non-ImageRenderable items are converted to string."""
registry = ImageRegistry()
- result = _render_sequence_with_images(["hello", 42, None], registry, TextFormat.PLAIN)
+ result = _render_sequence_with_images(["hello", 42, None], registry=registry, text_format=TextFormat.PLAIN)
# Items that convert to truthy strings are included
assert "hello" in result
diff --git a/tests/unit/pipelex/tools/typing/test_class_utils.py b/tests/unit/pipelex/tools/typing/test_class_utils.py
index 383e2cd20..fd28be258 100644
--- a/tests/unit/pipelex/tools/typing/test_class_utils.py
+++ b/tests/unit/pipelex/tools/typing/test_class_utils.py
@@ -98,7 +98,7 @@ class TestAreClassesEquivalent:
name: str
age: int
- assert are_classes_equivalent(MyModel, MyModel) is True
+ assert are_classes_equivalent(MyModel, class_2=MyModel) is True
def test_classes_with_same_structure_are_equivalent(self):
"""Test that two classes with the same fields are equivalent."""
@@ -111,7 +111,7 @@ class TestAreClassesEquivalent:
name: str
value: int
- assert are_classes_equivalent(ModelA, ModelB) is True
+ assert are_classes_equivalent(ModelA, class_2=ModelB) is True
def test_classes_with_different_fields_are_not_equivalent(self):
"""Test that classes with different field names are not equivalent."""
@@ -122,7 +122,7 @@ class TestAreClassesEquivalent:
class ModelB(BaseModel):
title: str
- assert are_classes_equivalent(ModelA, ModelB) is False
+ assert are_classes_equivalent(ModelA, class_2=ModelB) is False
def test_classes_with_different_types_are_not_equivalent(self):
"""Test that classes with different field types are not equivalent."""
@@ -133,7 +133,7 @@ class TestAreClassesEquivalent:
class ModelB(BaseModel):
value: str
- assert are_classes_equivalent(ModelA, ModelB) is False
+ assert are_classes_equivalent(ModelA, class_2=ModelB) is False
def test_classes_with_different_descriptions_are_equivalent(self):
"""Test that field descriptions don't affect equivalence."""
@@ -144,7 +144,7 @@ class TestAreClassesEquivalent:
class ModelB(BaseModel):
name: str = Field(description="A completely different description")
- assert are_classes_equivalent(ModelA, ModelB) is True
+ assert are_classes_equivalent(ModelA, class_2=ModelB) is True
def test_classes_with_different_required_fields_are_not_equivalent(self):
"""Test that required vs optional fields matter."""
@@ -155,7 +155,7 @@ class TestAreClassesEquivalent:
class ModelB(BaseModel):
name: str | None = None
- assert are_classes_equivalent(ModelA, ModelB) is False
+ assert are_classes_equivalent(ModelA, class_2=ModelB) is False
def test_non_pydantic_classes(self):
"""Test that non-Pydantic classes are compared by identity."""
@@ -163,9 +163,9 @@ class TestAreClassesEquivalent:
class RegularClass:
pass
- assert are_classes_equivalent(RegularClass, RegularClass) is True
- assert are_classes_equivalent(str, str) is True
- assert are_classes_equivalent(str, int) is False
+ assert are_classes_equivalent(RegularClass, class_2=RegularClass) is True
+ assert are_classes_equivalent(str, class_2=str) is True
+ assert are_classes_equivalent(str, class_2=int) is False
class TestHasCompatibleField:
@@ -180,7 +180,7 @@ class TestHasCompatibleField:
class Outer(BaseModel):
data: Inner
- assert has_compatible_field(Outer, Inner) is True
+ assert has_compatible_field(Outer, target_type=Inner) is True
def test_subclass_match(self):
"""Test that a field with subclass type is found."""
@@ -194,7 +194,7 @@ class TestHasCompatibleField:
class Container(BaseModel):
item: Child
- assert has_compatible_field(Container, Parent) is True
+ assert has_compatible_field(Container, target_type=Parent) is True
def test_no_match(self):
"""Test that no match is found when field types don't match."""
@@ -208,7 +208,7 @@ class TestHasCompatibleField:
class Container(BaseModel):
data: TypeA
- assert has_compatible_field(Container, TypeB) is False
+ assert has_compatible_field(Container, target_type=TypeB) is False
def test_structural_equivalence_match(self):
"""Test that structurally equivalent types are found."""
@@ -225,7 +225,7 @@ class TestHasCompatibleField:
data: StructureA
# StructureA and StructureB have the same structure
- assert has_compatible_field(Container, StructureB) is True
+ assert has_compatible_field(Container, target_type=StructureB) is True
def test_optional_field_match(self):
"""Test that optional fields are checked correctly."""
@@ -236,7 +236,7 @@ class TestHasCompatibleField:
class Outer(BaseModel):
data: Inner | None = None
- assert has_compatible_field(Outer, Inner) is True
+ assert has_compatible_field(Outer, target_type=Inner) is True
def test_non_pydantic_class(self):
"""Test that non-Pydantic classes return False."""
@@ -247,7 +247,7 @@ class TestHasCompatibleField:
class PydanticClass(BaseModel):
name: str
- assert has_compatible_field(RegularClass, PydanticClass) is False # type: ignore[arg-type]
+ assert has_compatible_field(RegularClass, target_type=PydanticClass) is False # type: ignore[arg-type]
class TestAreClassesEquivalentWithOptionalFields:
@@ -264,7 +264,7 @@ class TestAreClassesEquivalentWithOptionalFields:
name: str
nickname: str | None = None
- assert are_classes_equivalent(ModelA, ModelB) is True
+ assert are_classes_equivalent(ModelA, class_2=ModelB) is True
def test_classes_with_same_fields_different_defaults_may_differ(self):
"""Test that default values don't affect JSON schema equivalence (they're in 'default' key)."""
@@ -278,6 +278,6 @@ class TestAreClassesEquivalentWithOptionalFields:
# JSON schema includes 'default' key, so these may or may not be equivalent
# depending on whether defaults are in the schema properties
# This test documents the actual behavior
- result = are_classes_equivalent(ModelA, ModelB)
+ result = are_classes_equivalent(ModelA, class_2=ModelB)
# The behavior depends on Pydantic's schema generation
assert isinstance(result, bool)
diff --git a/tests/unit/pipelex/tools/typing/test_structure_printer.py b/tests/unit/pipelex/tools/typing/test_structure_printer.py
index 3e1692278..6fdb9f6f2 100644
--- a/tests/unit/pipelex/tools/typing/test_structure_printer.py
+++ b/tests/unit/pipelex/tools/typing/test_structure_printer.py
@@ -189,8 +189,8 @@ class TestStructurePrinter:
' LOW = "LOW"',
]
- pretty_print(result, "results")
- pretty_print(expected, "expected")
+ pretty_print(result, title="results")
+ pretty_print(expected, title="expected")
assert result == expected, f"Expected:\n{''.join(expected)}\n\nGot:\n{''.join(result)}"
def test_list_content(self):
diff --git a/wip/README.md b/wip/README.md
index 908bc4477..5d97b25ff 100644
--- a/wip/README.md
+++ b/wip/README.md
@@ -15,6 +15,7 @@ This folder holds the **active** planning, design, and current-state docs for th
- **[concurrency/](concurrency/)** — direct-mode batching / backpressure design. The retry-jitter quick win shipped; the remaining design work is split into fan-out scheduling, rate limiting, and batch partial-failure docs. Status: design scoping.
- **[csv-support/](csv-support/)** — reading `.csv` files into typed `ListContent` and writing flat list outputs back out via `--save-csv`. Its [README](csv-support/README.md) is the feature + reviewer reference (codec, core input hook, CLI output hook, the I/O contract, locked decisions); the folder also holds the design rationale and the deferred review/security follow-ups. Landed in #955.
- **[runtime-bridge/](runtime-bridge/)** — review-triage and deferred-items record for the framework-agnostic `pipelex/runtime_bridge/` extraction (`feature/Runtime-bridge-extraction`, PR #969). Its [README](runtime-bridge/README.md) is the full triage of the SWE-agent review comments. The mechanical fixes and the design-fork resolutions (DIRECT-mode router scoping, the `graph_context`→`trace_context` contract, trace-flush false-positive) have all landed; what remains are the genuinely-deferred items, each with its own doc — notably the half-built-singleton boot race.
+- **[keyword-only-arguments/](keyword-only-arguments/)** — the keyword-only-arguments refactor on `refactor/Function-calling-4`: every non-subject parameter across `pipelex/` is keyword-only, enforced by the `check-keyword-only` AST guard (in `agent-check` + CI) and a `PostToolUse` hook. Its [README](keyword-only-arguments/README.md) maps the track; the folder also holds the co-developer [HTML explainer](keyword-only-arguments/keyword-only-arguments.html), the resolved positional-subject-suspects record, the cross-repo downstream-breakage log, and the raw `audit/` artifacts. Landed on the branch; the one open item is the at-release pin swap for the four consumer repos.
## Standalone docs
@@ -24,6 +25,7 @@ This folder holds the **active** planning, design, and current-state docs for th
- **[structured-logging.md](structured-logging.md)** — kickoff briefing for replacing string-interpolated log context with structured logging + contextvars. Kicked off, not started; sequenced after the error-handling stack merges.
- **[stuffs-as-nodespec.md](stuffs-as-nodespec.md)** — future graph-model rework to make stuffs first-class `NodeSpec` instances. A starter, not a worked plan.
- **[blueprint-elaboration-directives.md](blueprint-elaboration-directives.md)** — extending the build-time blueprint-elaboration system: first-class synthetic-pipe handling, a directive plugin registry, and supporting tooling.
+- **[doctor-output-ansi-under-force-color.md](doctor-output-ansi-under-force-color.md)** — deferred decision: `pipelex doctor` emits ANSI when captured under `FORCE_COLOR` (an env artifact, not a pipelex defect — it's plain when piped without it). Records the evidence and the one optional follow-up (a `--plain`/`--no-color` flag for diagnostics). Low priority. Surfaced by pipelex-worker PR #23.
- **[pathlib-refactor.workflow.js](pathlib-refactor.workflow.js)** — a runnable multi-agent workflow that refactors filesystem path handling to `pathlib.Path` across `pipelex/` (intended for the `refactor/Paths` branch). Tooling, not a doc.
## Suggested priorities
diff --git a/wip/doctor-output-ansi-under-force-color.md b/wip/doctor-output-ansi-under-force-color.md
new file mode 100644
index 000000000..09db34c21
--- /dev/null
+++ b/wip/doctor-output-ansi-under-force-color.md
@@ -0,0 +1,45 @@
+# `pipelex doctor` — ANSI in captured output under `FORCE_COLOR`, and whether to offer a plain mode
+
+**Status:** deferred to a follow-up PR — investigation done, decision pending. **Low priority.**
+**Origin:** surfaced while bringing `pipelex-worker` onto the keyword-only branch pin (PR #23). Its `pipelex doctor` config-health smoke test failed because the captured output contained ANSI codes that defeated a section regex.
+
+## TL;DR (corrected conclusion)
+
+**This is not a pipelex defect.** `pipelex doctor` already honors rich's standard, env-driven color detection: when stdout is not a TTY it emits **plain text**, and it respects both `NO_COLOR` and `FORCE_COLOR`. The ANSI codes we saw in captured `doctor` output came from **`FORCE_COLOR=3` set in the agent/session environment**, which rich (correctly) obeys even when stdout is piped. In a vanilla CI/piped context with no `FORCE_COLOR`, `doctor` output is already plain and the worker's original regex would have matched.
+
+So there is **likely nothing to fix in pipelex**. The only open question is an optional ergonomics one (below).
+
+## Evidence
+
+`pipelex doctor` run against the pipelex-worker `.pipelex/` config, output redirected to a file (non-TTY), counting ANSI escape sequences (`\x1b[…m`):
+
+| Condition | ANSI escapes | `Configuration Files ✓` regex matches? |
+| --- | ---: | --- |
+| `FORCE_COLOR=3` set (this agent env) | 114 | no |
+| `FORCE_COLOR` unset, piped (vanilla CI-like) | 0 | **yes** |
+| `FORCE_COLOR` unset + `NO_COLOR=1` | 0 | yes |
+
+With `FORCE_COLOR` set, adding `NO_COLOR=1` dropped the color codes but left bold/reset (`\x1b[1m`/`\x1b[0m`) — rich still considers the stream a terminal, so it keeps non-color styling. That residual reset between `Configuration Files` and the `✓` is what broke the regex.
+
+The console is built without any `force_terminal`: `pipelex/cli/commands/doctor_cmd.py` renders via `get_console()`, which in `pipelex/hub.py` returns a plain `Console(file=sys.stdout)` / `Console(stderr=True)`. Rich's env-driven detection does the rest. (For contrast, `pipelex/tools/misc/pretty.py` already pins `force_terminal=False` on its export consoles — the right call for capture.)
+
+## What we already did (no further action needed for it)
+
+`pipelex-worker/tests/test_config_health.py` now strips ANSI before matching (PR #23). That is a good **defensive** fix and should stay regardless of the decision below: agent/CI runners sometimes set `FORCE_COLOR`, and a smoke test that asserts on captured CLI text should normalize ANSI so it isn't hostage to the runner's color env.
+
+## The genuine (optional) question for the next PR
+
+Should a **diagnostic** command like `pipelex doctor` — whose output is frequently captured (CI smoke tests, support bundles, log scrapers) — produce deterministic plain output even when `FORCE_COLOR` is set in the environment?
+
+- **(a) Do nothing.** Current behavior is standard and idiomatic; consumers that capture `doctor` output normalize ANSI themselves (the worker now does). **Recommended baseline** unless we get bitten again.
+- **(b) Add a `--plain` / `--no-color` flag** to `doctor` (and perhaps other diagnostic commands) that forces a non-styled console for the command's duration — e.g. `Console(file=sys.stdout, no_color=True, force_terminal=False)`. Small, self-contained, nicer for CI/scripting; lets callers get clean output without env juggling. Pick this if we want first-class machine-friendly diagnostics.
+- **(c) Make `doctor` ignore `FORCE_COLOR` and key purely off `isatty`.** **Rejected** — it overrides the user's explicit `FORCE_COLOR` and is surprising.
+
+**Recommendation:** ship **(a)** as the baseline (i.e. nothing), and reach for **(b)** only if/when we want first-class capturable diagnostics or hit this again.
+
+## Where to look if we do (b)
+
+- `pipelex/cli/commands/doctor_cmd.py` — the doctor command; renders via `get_console()` with rich markup.
+- `pipelex/hub.py` — `get_console()` (~`:255`), `set_console_print_target` / `set_console` (~`:148`). A `--plain` flag would set a `Console(no_color=True, force_terminal=False, file=sys.stdout)` on the hub for the command, then restore.
+- `pipelex/cli/agent_cli/commands/doctor_cmd.py` — the agent-CLI twin; keep behavior consistent if we add a flag.
+- Precedent for capture-safe consoles: `pipelex/tools/misc/pretty.py` (`force_terminal=False`).
diff --git a/wip/dry-run-refactor/followup-dry-validate-hardening.md b/wip/dry-run-refactor/followup-dry-validate-hardening.md
index 182b47ebb..b0b2d3316 100644
--- a/wip/dry-run-refactor/followup-dry-validate-hardening.md
+++ b/wip/dry-run-refactor/followup-dry-validate-hardening.md
@@ -45,3 +45,16 @@ One dict for all libraries: load overwrites entries, teardown pops by `pipe_ref`
Root-caused 2026-06-10 (CI py3.11–3.14 hang on the three GraphSpec-crossing tests): an exception raised by the data converter while decoding an activity result fails the *workflow task*, which Temporal retries indefinitely — the submitter's `execute_workflow` never returns. The trigger was environmental (`ZoneInfoNotFoundError`: no IANA tzdata on the runner for py3.11+), and kajson 0.7.0 structurally eliminated that trigger class: its self-sufficient timezone wire format carries the UTC offset, so decoding degrades gracefully to a fixed offset instead of raising, and kajson declares `tzdata` itself. But the failure *shape* is general: any deterministic decode bug (kajson registry miss, schema drift, future enum rename) will present as an infinite hang on every host, not a failed run. `dispatch_dry_validate`'s 12-minute `workflow_execution_timeout` bounds the API path; direct `execute_workflow` callers (tests, scripts) have no bound.
**Direction (design tradeoff, do not reflexively patch):** consider making deterministic conversion errors fail-fast — e.g. catch `KajsonDecoderError` in `BaseModelPayloadConverter.from_payload` and re-raise as a non-retryable shape, or document that every submitter must set `workflow_execution_timeout`. Temporal's retry-forever default exists so a code redeploy can heal a bad task; trading that away deserves a deliberate decision.
+
+## 9. The library-window teardown dance is hand-mirrored across two files (and already drifts)
+
+Surfaced during the review of the validation-api extraction (`feature/Tweaks-for-validation-api`): the in-process validate orchestration moved out of `PipelexMTHDSProtocol.validate` into the shared `validate_bundles_in_process` (`pipelex/pipeline/validate_in_process.py`), so the local runtime and the upcoming `ApiRunner.validate` share one teardown implementation. But `act_dry_validate` (`pipelex/temporal/tprl_pipe/act_dry_validate.py`) still carries its own copy of the same restore-current-library + teardown-in-`try` + suppress-teardown-error-on-body-failure block — the comments literally say "mirrors act_dry_validate" / "Mirrors act_dry_validate's finally". So the load-bearing teardown semantics now live in *two* places (the new module deliberately unified runner + API but left the Temporal activity as a by-hand mirror).
+
+The two copies have already diverged at the edges — none documented as intentional:
+
+- `validate_in_process` gates the whole block on `validation_library_id is not None and validation_library_id != prev_library_id`, then tears down unconditionally inside.
+- `act_dry_validate` gates the restore on `prev_library_id is not None and prev_library_id != library_id` (with an `else: clear_current_library()` branch the other site never executes), and gates only the teardown on `if library_id is not None`.
+
+The behavior difference is benign today and the divergence is **pre-existing** (the extracted block is byte-identical to the old `runner.py` code — the extraction introduced no new drift), but "mirrors act_dry_validate" is now aspirational, which is exactly the failure mode the docstring's "lives once, so the two backends cannot drift" claim is meant to prevent.
+
+**Direction (design tradeoff, do not reflexively patch):** collapse both sites onto one implementation — a `teardown_validation_library(*, validation_library_id, prev_library_id, body_succeeded, log_context)` helper, or a `validation_library_window(...)` context manager that owns the restore-first / teardown / suppress-on-error contract. The activity keeps its own `body_succeeded` flag; only the finally body is shared. Worth doing when `ApiRunner.validate` lands (third consumer), so the unification is proven against all three call shapes at once rather than guessed at now.
diff --git a/wip/keyword-only-arguments/README.md b/wip/keyword-only-arguments/README.md
new file mode 100644
index 000000000..36d58558c
--- /dev/null
+++ b/wip/keyword-only-arguments/README.md
@@ -0,0 +1,22 @@
+# keyword-only-arguments
+
+Track record for the **keyword-only arguments refactor** on `refactor/Function-calling-4`: every non-subject parameter across `pipelex/` source is now keyword-only, mechanically enforced by the `check-keyword-only` AST guard (in `make agent-check`, `make check`, and CI).
+
+## Status
+
+The pipelex-internal refactor is **complete and landed on the branch** — all waves done, the guard hard-blocks on any violation, and the convention is promoted to the canonical contributor doc at [`docs/contribute/keyword-only-arguments.md`](../../docs/contribute/keyword-only-arguments.md) (in the mkdocs nav). The downstream consumers were updated in lockstep (PRs #19 / #55 / #75 / #153, plus pipelex-worker #23) and **pushed**, all pinned to the branch git rev `0e32c8c0` and green on their test suites. (`pipelex-mistralai-workflows` is the one genuine out-of-scope consumer — it's on its own mistralai-2x hold track.)
+
+**One open item:** at pipelex release, swap each consumer's temporary `[tool.uv.sources]` git pin back to the released `pipelex` version. Tracked in the checklist of [`downstream-consumer-breakage.md`](downstream-consumer-breakage.md).
+
+**Follow-on (separate branch):** an `--fix` auto-fix capability was added to the guard on `feature/Tweaks-for-validation-api`. Its code review surfaced open items (incl. a latent silent-corruption bug) tracked in [`autofix-review-followups.md`](autofix-review-followups.md).
+
+## What's here
+
+- **[autofix-review-followups.md](autofix-review-followups.md)** — review follow-ups for the `--fix` auto-fix addition (the `make fko` / `check-keyword-only --fix` capability). Has open bugs (F1/F2 line-numbering corruption) and tradeoff decisions (F3–F5).
+- **[keyword-only-arguments.html](keyword-only-arguments.html)** — self-contained co-developer explainer: TL;DR, what/why, the rule, how it was enforced, the audit→consolidation→downstream-fix arc, and minimal diffs for the critical changes. Open in a browser.
+- **[downstream-consumer-breakage.md](downstream-consumer-breakage.md)** — the living cross-repo lockstep record. Which consumer call sites broke at each pipelex SHA, how each was fixed, and the at-release pin-swap checklist. This is the one doc with an open action.
+- **[positional-subject-suspects.md](positional-subject-suspects.md)** — RESOLVED. The consolidated shortlist of 59 "positional-subject abuse" suspects (functions that kept their subject positional only to satisfy the carve-out) and the adjudication that turned them all fully keyword-only.
+- **audit/** — raw process artifacts from the positional-subject audit (reference, not active):
+ - [`positional-subject-audit.md`](audit/positional-subject-audit.md) — the full machine+LLM audit of every audited function (large).
+ - [`review-prompt.md`](audit/review-prompt.md) — the sub-agent review prompt that drove the audit.
+ - [`findings/`](audit/findings/) — per-package suspect shortlists, one file per `pipelex/` package.
diff --git a/wip/keyword-only-arguments/audit/findings/base_exceptions.md b/wip/keyword-only-arguments/audit/findings/base_exceptions.md
new file mode 100644
index 000000000..43babf5a6
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/base_exceptions.md
@@ -0,0 +1,5 @@
+# Suspects — package `base_exceptions`
+
+Reviewed: 0 Section A + 1 primitive lone-subjects. Suspects: 0.
+
+No suspects.
diff --git a/wip/keyword-only-arguments/audit/findings/builder.md b/wip/keyword-only-arguments/audit/findings/builder.md
new file mode 100644
index 000000000..36cbdc98e
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/builder.md
@@ -0,0 +1,15 @@
+# Suspects — package `builder`
+
+Reviewed: 20 Section A + 2 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/builder/operations/models_ops.py:36` — `_resolve_preset_backend` — `def _resolve_preset_backend(model_deck: ModelDeck, *, model_handle: str, model_type: ModelType) -> InferenceModelSpec | None` — The docstring says "Resolve a preset's model handle to an InferenceModelSpec": the thing being resolved is `model_handle`; `model_deck` is a lookup registry used as lookup context. Call sites confirm: `_resolve_preset_backend(model_deck, model_handle=setting.model, model_type=model_type)` — the deck reads as an unlabeled blob, while the real semantic target (`model_handle`) is buried in keyword args. Suggested fix: make fully keyword-only (`def _resolve_preset_backend(*, model_deck, model_handle, model_type)`).
+
+- `pipelex/builder/operations/output_ops.py:14` — `build_output_for_pipe` — `async def build_output_for_pipe(mthds_contents: list[str], *, pipe_code: str, output_format: ...) -> dict[str, Any]` — The function name says "for_pipe", signalling that the pipe is the semantic subject. `mthds_contents` is raw bundle source material (context/input) not the object being acted on. A caller reading `build_output_for_pipe(some_list, pipe_code="my.pipe")` must think twice about what that first list is. Pair with `build_runner_code_for_pipe` which has the same shape and semantics. Suggested fix: make fully keyword-only (`def build_output_for_pipe(*, mthds_contents, pipe_code, output_format)`), or reorder so `pipe_code` is the positional subject.
+
+- `pipelex/builder/operations/runner_code_ops.py:17` — `build_runner_code_for_pipe` — `async def build_runner_code_for_pipe(mthds_contents: list[str], *, pipe_code: str) -> str` — Same pattern as `build_output_for_pipe` above: the name says "for_pipe", the pipe is the semantic object, but `mthds_contents` (the source bundle data) was made positional. Suggested fix: make fully keyword-only, or promote `pipe_code` to the positional subject.
+
+## Medium / low confidence
+
+- `pipelex/builder/operations/models_ops.py:101` — `_build_presets_for_category` (and the parallel `_build_aliases_for_category` line 135, `_build_waterfalls_for_category` line 160) — `def _build_presets_for_category(model_deck: ModelDeck, *, category: ModelCategory, backend: str | None)` — The function name says "for_category"; the function matches on `category` to select which field of the deck to read. `model_deck` is the data source/registry, `category` is what drives the behavior. At call sites (`_build_presets_for_category(model_deck, category=ModelCategory.LLM, backend=backend)`) the deck reads as an unnamed blob. Lower confidence than the `_resolve_preset_backend` case because the deck is a richer object (not just a registry lookup), so it has a plausible claim to being the "subject" that is queried. Suggested fix: make fully keyword-only.
diff --git a/wip/keyword-only-arguments/audit/findings/cli.md b/wip/keyword-only-arguments/audit/findings/cli.md
new file mode 100644
index 000000000..971ad58f7
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/cli.md
@@ -0,0 +1,15 @@
+# Suspects — package `cli`
+
+Reviewed: 112 Section A + 30 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/cli/cli_factory.py:31` — `make_pipelex_for_cli` — `def make_pipelex_for_cli(context: ErrorContext, *, library_dirs: ..., needs_inference: bool, ...) -> Pipelex` — `context` is error-reporting metadata (an `ErrorContext` enum used to shape error messages), not the object being created. The function builds a `Pipelex` instance; `context` is a side-channel tag. Every call site uses `context=...` as a keyword (confirmed across all call sites). Suggested fix: make fully keyword-only (`def make_pipelex_for_cli(*, context: ErrorContext, library_dirs: ..., ...)`)
+
+- `pipelex/cli/agent_cli/commands/run/_output_helpers.py:14` — `build_run_output` — `def build_run_output(with_memory: bool, *, main_stuff_json: dict, working_memory_dump: dict, compact_result: ..., extra_metadata: ...) -> dict` — `with_memory: bool` is a mode flag, not the semantic object being assembled. Both call sites pass it as `with_memory=with_memory` (keyword). `main_stuff_json` is arguably the more central data. Suggested fix: move `*` before `with_memory` (make it keyword-only too).
+
+- `pipelex/cli/commands/init/command.py:182` — `determine_needs` — `def determine_needs(reset: bool, *, check_config: bool, check_inference: bool, ...) -> tuple[bool, bool, bool, bool]` — `reset: bool` is a mode flag among several other boolean flags; it's not semantically more "the subject" than `check_config`, `check_inference`, etc. The single call site passes it as `reset=reset` (keyword). Suggested fix: move `*` before `reset` (make it keyword-only too, consistent with the other boolean flags).
+
+## Medium / low confidence
+
+- `pipelex/cli/agent_cli/commands/init_cmd.py:173` — `_configure_backends` — `def _configure_backends(config: dict[str, Any], *, backends_toml_path: Path, template_backends_path: Path) -> list[str]` — the function's primary action is modifying `backends_toml_path`; `config: dict` is read-only input/context from which backend selection is extracted. The call site passes it as `_configure_backends(parsed_config, backends_toml_path=..., ...)` (positional use). This is a private helper so the impact is contained, and `config` as "data being acted upon" is defensible. Low confidence — calling convention is actually used positionally here, so no immediate caller-side benefit.
diff --git a/wip/keyword-only-arguments/audit/findings/cogt.md b/wip/keyword-only-arguments/audit/findings/cogt.md
new file mode 100644
index 000000000..bdc0e10ef
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/cogt.md
@@ -0,0 +1,13 @@
+# Suspects — package `cogt`
+
+Reviewed: 119 Section A + 42 primitive lone-subjects. Suspects: 3.
+
+## High confidence
+
+- `pipelex/cogt/usage/costs_per_token.py:4` — `model_cost_per_token` — `def model_cost_per_token(costs: CostsByCategoryDict, *, cost_category: CostCategory) -> float` — `costs` is a dict used purely as a lookup table; the function dispatches on `cost_category` and returns `costs.get(cost_category) / 1_000_000`. The real "subject" the function acts on is `cost_category`, while `costs` is context/registry. All three real call sites already use `costs=...` as a keyword. Suggested fix: move `*` before `costs` too — `def model_cost_per_token(*, costs: CostsByCategoryDict, cost_category: CostCategory) -> float` — or reorder with `cost_category` first.
+
+- `pipelex/cogt/llm/reasoning_config_base.py:40` — `get_reasoning_level_str` — `def get_reasoning_level_str(effort_to_level_map: EffortToLevelMap, *, effort: ReasoningEffort) -> str | None` — `effort_to_level_map` is a `dict[str, str]` passed as contextual configuration; the function body is simply `effort_to_level_map.get(effort)`. The semantic object is `effort` (the query), while the map is a lookup table. All four call sites pass the map positionally via `self.effort_to_level_map` without a label, which reads opaquely. Suggested fix: fully keyword-only `def get_reasoning_level_str(*, effort_to_level_map: EffortToLevelMap, effort: ReasoningEffort)`.
+
+## Medium / low confidence
+
+- `pipelex/cogt/model_backends/backend_credentials.py:26` — `BackendCredentialsErrorMsgFactory.make_one_variable_missing_error_msg` — `def make_one_variable_missing_error_msg(cls, secrets_provider: SecretsProviderAbstract, *, backend_name: str | None, var_name: str) -> str` — `secrets_provider` acts as a dispatch context (the function `isinstance`-branches on its type to select message wording), while `backend_name` and `var_name` are the real domain objects the message describes. The sole call site already uses `secrets_provider=secrets_provider` as a keyword. This is lower-confidence because `secrets_provider` does meaningfully control branching. Suggested fix: fully keyword-only, or at least keep asymmetry noted; low urgency.
diff --git a/wip/keyword-only-arguments/audit/findings/core.md b/wip/keyword-only-arguments/audit/findings/core.md
new file mode 100644
index 000000000..b41b40bbb
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/core.md
@@ -0,0 +1,13 @@
+# Suspects — package `core`
+
+Reviewed: 95 Section A + 66 primitive lone-subjects. Suspects: 3.
+
+## High confidence
+
+- `pipelex/core/stuffs/stuff_content.py:64` — `StuffContent.rendered_markdown` — `def rendered_markdown(self, level: int=1, *, is_pretty: bool=False) -> str` — `level` and `is_pretty` are both optional rendering options; neither is "the subject" (self is). All call sites already use `rendered_markdown(level=..., is_pretty=...)` keyword form or the no-arg default. `rendered_markdown(2)` is opaque. Suggested fix: move `*` before `level` so both params are keyword-only.
+
+- `pipelex/core/stuffs/stuff_content.py:113` — `StuffContent.rendered_markdown_async` — `async def rendered_markdown_async(self, level: int=1, *, is_pretty: bool=False) -> str` — same issue as `rendered_markdown`; parallel async signature, all call sites use keyword form. Suggested fix: move `*` before `level`.
+
+## Medium / low confidence
+
+- `pipelex/core/concepts/concept.py:194` — `Concept.render_concept_representation` — `def render_concept_representation(self, output_format: ConceptRepresentationFormat, *, is_multiple: bool=False) -> tuple[dict[str, Any], set[str]]` — `self` (Concept) is the real subject; `output_format` and `is_multiple` are both rendering options of equal standing. All call sites use `render_concept_representation(output_format=..., is_multiple=...)` keyword form. Positional `output_format` adds no clarity. Suggested fix: move `*` before `output_format` (make fully keyword-only).
diff --git a/wip/keyword-only-arguments/audit/findings/errors.md b/wip/keyword-only-arguments/audit/findings/errors.md
new file mode 100644
index 000000000..57dd5150c
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/errors.md
@@ -0,0 +1,5 @@
+# Suspects — package `errors`
+
+Reviewed: 5 Section A + 2 primitive lone-subjects. Suspects: 0.
+
+No suspects.
diff --git a/wip/keyword-only-arguments/audit/findings/graph.md b/wip/keyword-only-arguments/audit/findings/graph.md
new file mode 100644
index 000000000..4258018cd
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/graph.md
@@ -0,0 +1,11 @@
+# Suspects — package `graph`
+
+Reviewed: 40 Section A + 12 primitive lone-subjects. Suspects: 1.
+
+## High confidence
+
+_(none)_
+
+## Medium / low confidence
+
+- `pipelex/graph/graph_tracer_manager.py:266` — `GraphTracerManager.on_pipe_end_success` — `def on_pipe_end_success(self, lookup_key: str, *, node_id: str | None, ...)` — `lookup_key` is a registry dispatch key used to route to the correct `GraphTracer` instance via `self._get_tracer(lookup_key)`; the semantic subject is `node_id` (the node whose execution ended), which sits in the keyword args. Same pattern applies to `on_pipe_end_error` (line 325), `register_execution_data` (line 304), `add_edge` (line 360), `register_controller_output` (line 389), `register_batch_item_extraction` (line 411), `register_batch_aggregation` (line 440), and `register_parallel_combine` (line 469). All call sites already pass `lookup_key=` as a keyword argument (e.g. `pipe_abstract.py:116`), so no opacity exists today. The case for making `lookup_key` keyword-only too is that it is a dispatch/lookup concern rather than the semantic object of the operation, and the naming asymmetry between these manager methods and the underlying `GraphTracerProtocol` methods (which take `node_id` positionally) is a mild source of confusion. Low confidence overall — the call-site pattern is already keyword-explicit, and `lookup_key` as first-positional is a coherent "which tracer" discriminant. Suggested fix if desired: make `lookup_key` keyword-only across all eight manager dispatch methods (fully keyword-only signatures), mirroring the symmetry with the protocol layer.
diff --git a/wip/keyword-only-arguments/audit/findings/hub.md b/wip/keyword-only-arguments/audit/findings/hub.md
new file mode 100644
index 000000000..cc713582f
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/hub.md
@@ -0,0 +1,5 @@
+# Suspects — package `hub`
+
+Reviewed: 1 Section A + 14 primitive lone-subjects. Suspects: 0.
+
+No suspects.
diff --git a/wip/keyword-only-arguments/audit/findings/kit.md b/wip/keyword-only-arguments/audit/findings/kit.md
new file mode 100644
index 000000000..365798c02
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/kit.md
@@ -0,0 +1,11 @@
+# Suspects — package `kit`
+
+Reviewed: 8 Section A + 0 primitive lone-subjects. Suspects: 2.
+
+## High confidence
+
+- `pipelex/kit/single_file_agent_rules.py:12` — `_read_agent_file` — `def _read_agent_file(agents_dir: Traversable, *, name: str) -> str` — `agents_dir` is a lookup-table/context directory; `name` is the file being read — the real acted-on object. The pattern "read [name] from [agents_dir]" has the semantic subject keyworded and the context positional. Call site (line 79): `_read_agent_file(agents_dir, name=name)` confirms `name` carries the meaning. Suggested fix: make fully keyword-only — `def _read_agent_file(*, agents_dir: Traversable, name: str) -> str`
+
+## Medium / low confidence
+
+- `pipelex/kit/single_file_agent_rules.py:49` — `build_merged_rules` — `def build_merged_rules(kit_index: KitIndex, *, agent_set: str | None=None, file_list: list[str] | None=None) -> str` — `kit_index` is a configuration/registry object used as a data source and lookup table, not the semantic object being acted on. The function "builds merged rules" by consulting the index; `kit_index` reads more like a context/config argument than a subject. Lower confidence because a KitIndex could reasonably be seen as "the thing being merged from". Suggested fix: make fully keyword-only — `def build_merged_rules(*, kit_index: KitIndex, agent_set: str | None=None, file_list: list[str] | None=None) -> str`
diff --git a/wip/keyword-only-arguments/audit/findings/language.md b/wip/keyword-only-arguments/audit/findings/language.md
new file mode 100644
index 000000000..59f3ff0b4
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/language.md
@@ -0,0 +1,5 @@
+# Suspects — package `language`
+
+Reviewed: 5 Section A + 3 primitive lone-subjects. Suspects: 0.
+
+No suspects.
diff --git a/wip/keyword-only-arguments/audit/findings/libraries.md b/wip/keyword-only-arguments/audit/findings/libraries.md
new file mode 100644
index 000000000..a8afc778b
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/libraries.md
@@ -0,0 +1,15 @@
+# Suspects — package `libraries`
+
+Reviewed: 28 Section A + 19 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/libraries/libraries/library_crate.py:39` — `LibraryCrate.compute_fingerprint_from_content` — `def compute_fingerprint_from_content(concepts: dict[str, 'ConceptBlueprint | str'], *, pipes: dict[str, PipeBlueprintUnion]) -> str` — `concepts` and `pipes` are co-equal operands (both dict inputs to a hash); neither is the semantic object of the function. Call sites already keyword both (`compute_fingerprint_from_content(concepts=concepts, pipes=pipes)`). A directional-pair with no natural subject. — suggested fix: make fully keyword-only `def compute_fingerprint_from_content(*, concepts, pipes)`
+
+## Medium / low confidence
+
+- `pipelex/libraries/concept/concept_library.py:191` — `ConceptLibrary.add_dependency_concept` — `def add_dependency_concept(self, alias: str, *, concept: Concept) -> None` — `alias` is a namespace/prefix used to build a composite key; `concept` is what is actually being added to the library. Call sites already use `alias=alias` (keyword). The real "subject" of "add" is the concept, not the alias. — suggested fix: `def add_dependency_concept(self, *, alias: str, concept: Concept)` or reorder to `def add_dependency_concept(self, concept: Concept, *, alias: str)`
+
+- `pipelex/libraries/pipe/pipe_library.py:97` — `PipeLibrary.add_dependency_pipe` — `def add_dependency_pipe(self, alias: str, *, pipe: PipeAbstract) -> None` — identical pattern to `add_dependency_concept` above: `alias` is the namespacing key, `pipe` is the actual subject being added. Call sites already use `alias=alias`. — suggested fix: same as above, make `alias` keyword-only too
+
+- `pipelex/libraries/visibility_utils.py:35` — `make_visibility_checker` — `def make_visibility_checker(manifest: MethodsManifest | None, *, blueprints: list[PipelexBundleBlueprint]) -> PackageVisibilityChecker` — `manifest` is nullable config/filter (often `None`), while `blueprints` is the primary data being inspected. Call sites always pass `manifest=manifest` already. Same pattern for `check_visibility_for_blueprints` at line 53. Low confidence: `manifest` could be argued as the filter subject. — suggested fix: make both args keyword-only for both functions
diff --git a/wip/keyword-only-arguments/audit/findings/observer.md b/wip/keyword-only-arguments/audit/findings/observer.md
new file mode 100644
index 000000000..dc928af27
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/observer.md
@@ -0,0 +1,9 @@
+# Suspects — package `observer`
+
+Reviewed: 1 Section A + 1 primitive lone-subject. Suspects: 2.
+
+## High confidence
+
+- `pipelex/observer/multi_observer.py:14` — `MultiObserver.remove_observer` — `def remove_observer(self, name: str) -> None` — Asymmetric with `add_observer(*, name, observer)` which is already fully keyword-only; `remove_observer("some_name")` passes a bare string with no keyword context at the call site. Convention consistency and readability both point toward `def remove_observer(self, *, name: str) -> None`.
+
+- `pipelex/observer/local_observer.py:22` — `LocalObserver._write_to_jsonl` — `def _write_to_jsonl(self, event_type: str, *, payload: PayloadType) -> None` — `event_type` is a routing/selector string (determines which file to write to and which key to inject into the payload), not the semantic object being written. The payload is the real subject. Call sites pass a named constant (`LocalObserverEventType.BEFORE_RUN`) so readability is acceptable, but the two-parameter shape (`event_type` positional, `payload` keyword) is inconsistent: both parameters are equally descriptive options that label different aspects of the write operation, and `_write_to_jsonl(*, event_type, payload)` would self-document the call site more clearly.
diff --git a/wip/keyword-only-arguments/audit/findings/pipe_controllers.md b/wip/keyword-only-arguments/audit/findings/pipe_controllers.md
new file mode 100644
index 000000000..8f12e7d84
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/pipe_controllers.md
@@ -0,0 +1,17 @@
+# Suspects — package `pipe_controllers`
+
+Reviewed: 6 Section A + 3 primitive lone-subjects. Suspects: 3.
+
+## High confidence
+
+- `pipelex/pipe_controllers/parallel/pipe_parallel.py:326` — `PipeParallel._register_branch_outputs_with_graph_tracer` — `def _register_branch_outputs_with_graph_tracer(self, job_metadata: JobMetadata, *, output_stuffs: dict[str, 'Stuff']) -> None` — `job_metadata` is a trace-context carrier / lookup key, not the semantic object of the function; the function acts on `output_stuffs`. All call sites (lines 210 and 309) already pass `job_metadata=job_metadata` by keyword. Suggested fix: make fully keyword-only — `def _register_branch_outputs_with_graph_tracer(self, *, job_metadata: JobMetadata, output_stuffs: dict[str, 'Stuff']) -> None`.
+
+- `pipelex/pipe_controllers/parallel/pipe_parallel.py:369` — `PipeParallel._register_parallel_combine_with_graph_tracer` — `def _register_parallel_combine_with_graph_tracer(self, job_metadata: JobMetadata, *, combined_stuff: 'Stuff', branch_stuffs: dict[str, 'Stuff']) -> None` — same pattern: `job_metadata` is a context/trace carrier; the function acts on `combined_stuff` and `branch_stuffs`. Both call sites (lines 203 and 302) use `job_metadata=job_metadata`. Suggested fix: move `*` before `job_metadata` — `def _register_parallel_combine_with_graph_tracer(self, *, job_metadata: JobMetadata, combined_stuff: 'Stuff', branch_stuffs: dict[str, 'Stuff']) -> None`.
+
+- `pipelex/pipe_controllers/sub_pipe.py:34` — `SubPipe.run_pipe` — `async def run_pipe(self, calling_pipe_code: str, *, working_memory: WorkingMemory, job_metadata: JobMetadata, sub_pipe_run_params: PipeRunParams, library_crate: 'LibraryCrate | None'=None) -> PipeOutput` — `calling_pipe_code` is caller provenance/context, not the semantic object; `self` (the SubPipe) is the object being run. Both real call sites (pipe_parallel.py:152, pipe_sequence.py:195, pipe_condition.py:328) already pass `calling_pipe_code=self.code` by keyword. Suggested fix: make fully keyword-only — `async def run_pipe(self, *, calling_pipe_code: str, working_memory: WorkingMemory, job_metadata: JobMetadata, sub_pipe_run_params: PipeRunParams, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`.
+
+## Medium / low confidence
+
+- `pipelex/pipe_controllers/pipe_controller.py:71` — `PipeController._live_run_controller_pipe` — `async def _live_run_controller_pipe(self, job_metadata: JobMetadata, *, ...)` — `job_metadata` as positional follows the same `_live_run_pipe(self, job_metadata, *, ...)` convention established on `PipeAbstract` (the base class). The single call site (pipe_controller.py:43) already uses keyword form. Medium confidence only because the `job_metadata`-as-first-non-self-param is a deliberate, codebase-wide convention on the run-pipe family; changing only the controller abstract without changing the base class `PipeAbstract` would create inconsistency. If the base family ever moves `job_metadata` to keyword-only, this should follow.
+
+- `pipelex/pipe_controllers/pipe_controller.py:83` — `PipeController._dry_run_controller_pipe` — same reasoning as `_live_run_controller_pipe` above; treat as a pair.
diff --git a/wip/keyword-only-arguments/audit/findings/pipe_operators.md b/wip/keyword-only-arguments/audit/findings/pipe_operators.md
new file mode 100644
index 000000000..ee528bfcc
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/pipe_operators.md
@@ -0,0 +1,15 @@
+# Suspects — package `pipe_operators`
+
+Reviewed: 40 Section A + 3 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:269` — `ImgGenPromptBlueprint._render_text` — `async def _render_text(self, context_provider: ContextProviderAbstract, *, template_blueprint: TemplateBlueprint, ...)` — `context_provider` is a lookup environment/registry, not the thing being rendered. `template_blueprint` is the real subject. Call sites always pass `context_provider=` as a keyword: `self._render_text(context_provider=context_provider, template_blueprint=..., ...)`. Suggested fix: make fully keyword-only — `def _render_text(self, *, context_provider, template_blueprint, ...)`.
+
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:350` — `LLMPromptBlueprint._unravel_text` — `async def _unravel_text(self, context_provider: ContextProviderAbstract, *, jinja2_blueprint: TemplateBlueprint, ...)` — identical pattern to `_render_text`: `context_provider` is the resolution environment, `jinja2_blueprint` is what gets unraveled. Call sites always use `context_provider=` as keyword. Suggested fix: make fully keyword-only — `def _unravel_text(self, *, context_provider, jinja2_blueprint, ...)`.
+
+## Medium / low confidence
+
+- `pipelex/pipe_operators/compose/structured_content_composer.py:392` — `StructuredContentComposer._expects_type` — `def _expects_type(self, expected_type: type[Any], *, target_type: type)` — symmetric type-comparison pair (`issubclass(expected_type, target_type)`); neither argument is more "subject" than the other. Call sites always pass `expected_type=expected_type` as keyword (e.g. `self._expects_type(expected_type=expected_type, target_type=StuffContent)`), suggesting both args are directional operands. Suggested fix: make fully keyword-only — `def _expects_type(self, *, expected_type, target_type)`.
+
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:65` — `ImgGenPromptBlueprint.make_img_gen_prompt` — `async def make_img_gen_prompt(self, context_provider: ContextProviderAbstract, *, extra_params, max_prompt_images)` — `context_provider` is a resolution environment, not what's being generated (the prompt is being built from `self`, the blueprint). Call site uses `context_provider=working_memory` as keyword. Lower confidence because "context to use for building" is a defensible subject role. Suggested fix: make fully keyword-only — `def make_img_gen_prompt(self, *, context_provider, ...)`.
diff --git a/wip/keyword-only-arguments/audit/findings/pipe_run.md b/wip/keyword-only-arguments/audit/findings/pipe_run.md
new file mode 100644
index 000000000..434731859
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/pipe_run.md
@@ -0,0 +1,13 @@
+# Suspects — package `pipe_run`
+
+Reviewed: 18 Section A + 3 primitive lone-subjects. Suspects: 3.
+
+## High confidence
+
+- `pipelex/pipe_run/delivery_executor.py:201` — `DeliveryExecutor._try_add_rendered_file` — `async def _try_add_rendered_file(cls, files: dict[str, ResultFile], *, filename: str, render: Awaitable[str], content_type: str) -> None` — `files` is a mutable accumulator dict (output container), not the semantic subject being acted on. The real subjects of the "add" operation are `filename`/`render`/`content_type`. At the call site: `self._try_add_rendered_file(files, filename="main_stuff.json", ...)` — the positional `files` reads as a registry/sink, not the thing the function is about. Suggested fix: make fully keyword-only — `async def _try_add_rendered_file(cls, *, files: dict[str, ResultFile], filename: str, render: Awaitable[str], content_type: str) -> None`.
+
+- `pipelex/pipe_run/delivery_executor.py:219` — `DeliveryExecutor._add_optional_text_file` — `def _add_optional_text_file(cls, files: dict[str, ResultFile], *, filename: str, text: str | None, content_type: str) -> None` — Same pattern as `_try_add_rendered_file`: `files` is the accumulator dict carried positionally, while `filename`/`text`/`content_type` are the content being added (the actual "what"). Call site: `self._add_optional_text_file(files, filename="graphspec.json", text=..., content_type=...)`. Suggested fix: make fully keyword-only — `def _add_optional_text_file(cls, *, files: dict[str, ResultFile], filename: str, text: str | None, content_type: str) -> None`.
+
+## Medium / low confidence
+
+- `pipelex/pipe_run/pipe_run_params.py:28` — `output_multiplicity_to_apply` — `def output_multiplicity_to_apply(base_multiplicity: VariableMultiplicity | None, *, override_multiplicity: VariableMultiplicity | None) -> VariableMultiplicityResolution` — This is a two-operand resolution function: `base_multiplicity` and `override_multiplicity` are both inputs to a priority merge. Neither is clearly "the object the function acts on" — the function computes a result from two equal-standing inputs. The docstring examples (`output_multiplicity_to_apply(None, None)`) also show positional calling with raw `None` values, which is opaque. Suggested fix: make fully keyword-only — `def output_multiplicity_to_apply(*, base_multiplicity: VariableMultiplicity | None, override_multiplicity: VariableMultiplicity | None) -> VariableMultiplicityResolution`.
diff --git a/wip/keyword-only-arguments/audit/findings/pipe_signature.md b/wip/keyword-only-arguments/audit/findings/pipe_signature.md
new file mode 100644
index 000000000..419b12962
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/pipe_signature.md
@@ -0,0 +1,5 @@
+# Suspects — package `pipe_signature`
+
+Reviewed: 2 Section A + 0 primitive lone-subjects. Suspects: 0.
+
+No suspects.
diff --git a/wip/keyword-only-arguments/audit/findings/pipelex.md b/wip/keyword-only-arguments/audit/findings/pipelex.md
new file mode 100644
index 000000000..069b648e1
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/pipelex.md
@@ -0,0 +1,13 @@
+# Suspects — package `pipelex`
+
+Reviewed: 3 Section A + 1 primitive lone-subject. Suspects: 2.
+
+## High confidence
+
+- `pipelex/pipelex.py:512` — `Pipelex.make` — `def make(cls, integration_mode: IntegrationMode = IntegrationMode.PYTHON, *, ...)` — `integration_mode` is a mode/configuration option, not the semantic subject of the factory (the subject is `cls` / the instance being created). All observed call sites either omit it (accepting the default) or already pass it as `integration_mode=...`. A positional call `Pipelex.make(IntegrationMode.CLI)` reads opaquely — the bare enum value conveys no context. Since this is the primary public API entry point, keyword-only is the right default. Suggested fix: `def make(cls, *, integration_mode: IntegrationMode = IntegrationMode.PYTHON, needs_inference: bool = True, ...)`.
+
+## Medium / low confidence
+
+- `pipelex/pipelex.py:145` — `Pipelex._get_validation_error_msg` — `def _get_validation_error_msg(component_name: str, *, validation_exc: Exception) -> str` — `component_name` is a descriptive string label ("routing profile library", "model deck"), not the object being operated on. It behaves more like a context parameter alongside `validation_exc`. Call sites: `self._get_validation_error_msg("routing profile library", validation_exc=exc)` — the bare positional string reads somewhat opaquely without the label. Private method, low call-site count, but the pattern is inconsistent: `validation_exc` is already keyword-only while `component_name` is not, despite both being descriptive context params. Suggested fix: `def _get_validation_error_msg(*, component_name: str, validation_exc: Exception) -> str`.
+
+- `pipelex/pipelex.py:165` — `Pipelex.setup` — `def setup(self, integration_mode: IntegrationMode, *, ...)` — same logic as `make`: `integration_mode` is a mode-flag, not the subject (`self` is the subject). The sole internal call site (line 588) already uses `integration_mode=integration_mode` as keyword. Part of the public API surface (though `make` is the primary entry point). Suggested fix: `def setup(self, *, integration_mode: IntegrationMode, ...)`.
diff --git a/wip/keyword-only-arguments/audit/findings/pipeline.md b/wip/keyword-only-arguments/audit/findings/pipeline.md
new file mode 100644
index 000000000..f29fc1904
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/pipeline.md
@@ -0,0 +1,11 @@
+# Suspects — package `pipeline`
+
+Reviewed: 18 Section A + 4 primitive lone-subjects. Suspects: 1.
+
+## High confidence
+
+None.
+
+## Medium / low confidence
+
+- `pipelex/pipeline/job_metadata.py:89` — `JobMetadata.copy_with_update` — `def copy_with_update(self, otel_context: OtelContext | None, *, trace_context: TraceContext | None = None, **updates: Any)` — `otel_context` is not the subject being acted on (that's `self`, the metadata object); it's one of two context fields being updated, asymmetrically split from `trace_context` across the `*` boundary. Call sites always pass it as a keyword (`otel_context=...`) and the docstring justifies the asymmetry semantically (different inheritance semantics), but from a signature-readability standpoint both context args are peers. Suggested fix: make fully keyword-only — `def copy_with_update(self, *, otel_context: OtelContext | None, trace_context: TraceContext | None = None, **updates: Any)`.
diff --git a/wip/keyword-only-arguments/audit/findings/plugins.md b/wip/keyword-only-arguments/audit/findings/plugins.md
new file mode 100644
index 000000000..8ccd439e1
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/plugins.md
@@ -0,0 +1,15 @@
+# Suspects — package `plugins`
+
+Reviewed: 49 Section A + 15 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/plugins/gateway/gateway_completions_factory.py:138` — `GatewayCompletionsFactory.make_extract_output_from_response` — `def make_extract_output_from_response(cls, inference_model: InferenceModelSpec, *, response: GenericResponse) -> ExtractOutput` — The function name is "from_response", strongly signalling that `response` is the primary operand (the thing being processed/extracted from). `inference_model` is used only as a lookup key to select which extraction sub-method to call (via `GatewayExtractProtocol.make_from_model_handle`). Swapping `inference_model` and `response` so the response is the subject, or making both keyword-only, would match the semantics. Suggested fix: make fully keyword-only `def make_extract_output_from_response(cls, *, inference_model: InferenceModelSpec, response: GenericResponse)`.
+
+## Medium / low confidence
+
+- `pipelex/plugins/anthropic/anthropic_factory.py:244` — `AnthropicFactory.make_nb_tokens_by_category_from_nb` — `def make_nb_tokens_by_category_from_nb(nb_input: int, *, nb_output: int) -> NbTokensByCategoryDict` — Symmetric directional pair (`nb_input` / `nb_output`); neither operand is more "the subject" than the other. Splitting them across the `*` barrier is arbitrary and reads oddly. Suggested fix: make fully keyword-only `def make_nb_tokens_by_category_from_nb(*, nb_input: int, nb_output: int)`. Note: no external call sites found in the codebase, so risk is low.
+
+- `pipelex/plugins/mistral/mistral_factory.py:365` — `MistralFactory.make_mistral_document_url_chunk_from_uri` — `async def make_mistral_document_url_chunk_from_uri(cls, mistral_client: Mistral, *, uri: str) -> DocumentURLChunkTypedDict` — The function name ends in "from_uri", indicating `uri` is the primary operand. `mistral_client` is a dependency/tool passed to sub-operations (local file upload). The docstring itself labels it "required for local file uploads", framing it as an auxiliary dependency rather than the semantic subject. Suggested fix: make fully keyword-only `def make_mistral_document_url_chunk_from_uri(cls, *, mistral_client: Mistral, uri: str)`.
+
+- `pipelex/plugins/plugin_sdk_registry.py:22` — `PluginSdkRegistry.set_sdk_instance` — `def set_sdk_instance(self, plugin: Plugin, *, sdk_instance: Any) -> Any` — The registry is keyed by `plugin.sdk_handle`; `plugin` acts as an index/key, while `sdk_instance` is the actual object being stored. "Set X instance" semantically implies `sdk_instance` is the subject. Call sites already pass both as keyword args (`set_sdk_instance(plugin=plugin, sdk_instance=...)`). Suggested fix: make fully keyword-only `def set_sdk_instance(self, *, plugin: Plugin, sdk_instance: Any)`.
diff --git a/wip/keyword-only-arguments/audit/findings/reporting.md b/wip/keyword-only-arguments/audit/findings/reporting.md
new file mode 100644
index 000000000..595d4b8cc
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/reporting.md
@@ -0,0 +1,7 @@
+# Suspects — package `reporting`
+
+Reviewed: 5 Section A + 1 primitive lone-subject. Suspects: 1.
+
+## Medium / low confidence
+
+- `pipelex/reporting/reporting_manager.py:251` — `ReportingManager._emit_best_effort` — `def _emit_best_effort(event_log: EventLogProtocol, *, event: UsageReportEvent) -> None` — `event` is the semantic object being emitted; `event_log` is the target/sink the function dispatches to via `event_log.emit(event)`. Both call sites already pass `event_log` as a keyword (`_emit_best_effort(event_log=..., event=...)`), suggesting callers don't treat it as an obvious positional subject. The function name "emit best effort" designates the action, not the receiver, so neither arg has a clear claim as the one true subject — suggested fix: make fully keyword-only (`def _emit_best_effort(*, event_log: EventLogProtocol, event: UsageReportEvent)`).
diff --git a/wip/keyword-only-arguments/audit/findings/runtime_bridge.md b/wip/keyword-only-arguments/audit/findings/runtime_bridge.md
new file mode 100644
index 000000000..b8de67be9
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/runtime_bridge.md
@@ -0,0 +1,11 @@
+# Suspects — package `runtime_bridge`
+
+Reviewed: 12 Section A + 0 primitive lone-subjects. Suspects: 1.
+
+## High confidence
+
+_(none)_
+
+## Medium / low confidence
+
+- `pipelex/runtime_bridge/primitives/hydration.py:17` — `_validate_as_known_class` — `def _validate_as_known_class(item_class: type[StuffContent], *, raw_item: StuffContent | dict[str, Any]) -> StuffContent` — `item_class` is a type/schema used to validate, not the data being acted on; `raw_item` is the actual object being processed. The function "validates raw_item into item_class", so `raw_item` is arguably the semantic subject. Call sites read `_validate_as_known_class(item_class_or_none, raw_item=raw_item)` which is passable but unusual (a type as the positional subject). — suggested fix: `def _validate_as_known_class(*, item_class: type[StuffContent], raw_item: StuffContent | dict[str, Any]) -> StuffContent` (fully keyword-only) or reorder to `def _validate_as_known_class(raw_item: ..., *, item_class: ...)`.
diff --git a/wip/keyword-only-arguments/audit/findings/system.md b/wip/keyword-only-arguments/audit/findings/system.md
new file mode 100644
index 000000000..b4b516ad5
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/system.md
@@ -0,0 +1,15 @@
+# Suspects — package `system`
+
+Reviewed: 38 Section A + 27 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/system/pipelex_service/gateway_config_merger.py:69` — `GatewayConfigMerger._apply_overrides_to_model` — `def _apply_overrides_to_model(cls, model_name: str, *, gateway_model_specs: BackendModelSpecs, local_model_config: BackendModelSpecs) -> None` — `model_name` is a string identifier used only in log/warning messages; the real operands being acted on are the two keyword args `gateway_model_specs` and `local_model_config`. The sole call site already passes `model_name=model_name` as a keyword. Suggested fix: make fully keyword-only (`def _apply_overrides_to_model(cls, *, model_name, gateway_model_specs, local_model_config)`).
+
+## Medium / low confidence
+
+- `pipelex/system/pipelex_service/pipelex_service_agreement.py:29` — `update_service_terms_acceptance` — `def update_service_terms_acceptance(accepted: bool, *, config_dir: Path | None=None) -> None` — `accepted` is a bare `bool` positional; `update_service_terms_acceptance(True)` is opaque without the keyword. All actual call sites already use `accepted=True/False` as keyword. Suggested fix: move `*` before `accepted` (make fully keyword-only).
+
+- `pipelex/system/pipelex_service/pipelex_service_agreement.py:53` — `update_inference_setup_completed` — `def update_inference_setup_completed(completed: bool, *, config_dir: Path | None=None) -> None` — same pattern as above: bare `bool` positional, always called as `completed=True` at every call site. Suggested fix: make fully keyword-only.
+
+- `pipelex/system/configuration/config_check.py:12` — `check_is_initialized` — `def check_is_initialized(print_warning_if_not: bool=True) -> bool` — Section B: single `bool` param with a descriptive name, but `check_is_initialized(False)` would be opaque; every call site in tests already uses `print_warning_if_not=False/True` or the no-arg default form. Low priority since it has a default and callers always keyword it — but making it keyword-only would enforce that. Suggested fix: `def check_is_initialized(*, print_warning_if_not: bool=True)`.
diff --git a/wip/keyword-only-arguments/audit/findings/temporal.md b/wip/keyword-only-arguments/audit/findings/temporal.md
new file mode 100644
index 000000000..54815c86f
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/temporal.md
@@ -0,0 +1,17 @@
+# Suspects — package `temporal`
+
+Reviewed: 39 Section A + 13 primitive lone-subjects. Suspects: 5.
+
+## High confidence
+
+- `pipelex/temporal/task_manager.py:36` — `TaskManager.run_worker` — `async def run_worker(self, is_not_sandboxed: bool, *, is_unit_testing: bool, ...)` — `is_not_sandboxed` is a boolean flag that reads opaquely positionally: `run_worker(True)` reveals nothing. It's not the semantic object the method acts on; the worker it launches is. Both real call sites already pass it as `is_not_sandboxed=...`. The `temporal_task_manager.py` override (which carries `@override` and is thus skip-exempt) would track automatically once the Protocol base is fixed. Suggested fix: make the signature fully keyword-only — `async def run_worker(self, *, is_not_sandboxed: bool, is_unit_testing: bool, ...)`.
+
+- `pipelex/temporal/tprl/workflow_caller.py:298` — `WorkflowExecutorFactory.create_executor` — `def create_executor(cls, task_queue: str | None = None, *, workflow_execution_timeout, retry_policy, ...)` — `task_queue` is one of many configuration options for the executor being created; `create_executor` doesn't designate it as the subject (no "for this queue" or "on this queue" semantic). All four existing call sites pass it as `task_queue=...`. Suggested fix: move `task_queue` after `*` — `def create_executor(cls, *, task_queue: str | None = None, workflow_execution_timeout, ...)`.
+
+- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:127` — `make_temporal_pipe_router` — `def make_temporal_pipe_router(task_queue: str | None = None, *, workflow_execution_timeout, retry_policy, ...)` — same pattern as `create_executor`: `task_queue` is a configuration option defaulting to `None`, not the semantic object of a "make router" call. Suggested fix: `def make_temporal_pipe_router(*, task_queue: str | None = None, workflow_execution_timeout, ...)`.
+
+- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:131` — `make_temporal_pipe_run` — `def make_temporal_pipe_run(task_queue: str | None = None, *, workflow_execution_timeout, retry_policy, ...)` — same pattern as `make_temporal_pipe_router`. Suggested fix: `def make_temporal_pipe_run(*, task_queue: str | None = None, workflow_execution_timeout, ...)`.
+
+## Medium / low confidence
+
+- `pipelex/temporal/worker_cli.py:25` — `run_worker` — `async def run_worker(project: str | None = None, *, is_not_sandboxed: bool, is_unit_testing: bool, ...)` — `project` defaults to `None` and is looked up from pyproject.toml when absent. Its role is closer to a context/config override than the semantic subject of "run a worker". The one real call site passes it positionally (`run_worker(project, is_not_sandboxed=...)`) from the Typer command, but a fully keyword-only form would be equally natural. Medium confidence — `project` does describe which project's worker to run, so the positional reading is defensible.
diff --git a/wip/keyword-only-arguments/audit/findings/tools.md b/wip/keyword-only-arguments/audit/findings/tools.md
new file mode 100644
index 000000000..70c9f65a6
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/tools.md
@@ -0,0 +1,15 @@
+# Suspects — package `tools`
+
+Reviewed: 128 Section A + 77 primitive lone-subjects. Suspects: 4.
+
+## High confidence
+
+- `pipelex/tools/jinja2/jinja2_required_variables.py:121` — `detect_jinja2_required_variables` — `def detect_jinja2_required_variables(template_category: TemplateCategory, *, template_source: str) -> set[str]` — `template_source` is the object being analyzed; `template_category` is a configuration/mode parameter. All call sites already pass `template_category=` as a keyword — the positional exemption provides zero benefit and buries the real subject keyword-only. Suggested fix: `def detect_jinja2_required_variables(template_source: str, *, template_category: TemplateCategory) -> set[str]`
+
+- `pipelex/tools/jinja2/jinja2_required_variables.py:255` — `detect_jinja2_variable_references` — `def detect_jinja2_variable_references(template_category: TemplateCategory, *, template_source: str) -> list[VariableReference]` — same pattern as above: template_source is the object analyzed, template_category is configuration. All call sites use `template_category=` as keyword. Suggested fix: swap order so `template_source` is the positional subject.
+
+- `pipelex/tools/jinja2/jinja2_filters.py:110` — `apply_tag_style` — `def apply_tag_style(context: Context, *, value: str, tag_name: str | None=None) -> str` — `context` is a Jinja2 `Context` used only as a lookup table to retrieve `TAG_STYLE`; `value` is the string being wrapped. The real subject is `value`, not `context`. Single call site already passes `context` positionally (framework-driven), but conceptually the positional arg is a lookup registry, not the acted-on object. Suggested fix: fully keyword-only `def apply_tag_style(*, context: Context, value: str, tag_name: str | None = None)`.
+
+## Medium / low confidence
+
+- `pipelex/tools/jinja2/jinja2_environment.py:9` — `make_jinja2_env_from_loader` — `def make_jinja2_env_from_loader(template_category: TemplateCategory, *, loader: BaseLoader, enable_async: bool=True) -> Environment` — the function name says "from loader", which points to `loader` as the operative argument; `template_category` is a configuration parameter. Minor — `template_category` is a valid configuration object that drives the env construction, so reasonable to keep it positional. Suggested fix: `def make_jinja2_env_from_loader(loader: BaseLoader, *, template_category: TemplateCategory, enable_async: bool = True)` or fully keyword-only.
diff --git a/wip/keyword-only-arguments/audit/findings/tracing.md b/wip/keyword-only-arguments/audit/findings/tracing.md
new file mode 100644
index 000000000..f7e3a7803
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/findings/tracing.md
@@ -0,0 +1,5 @@
+# Suspects — package `tracing`
+
+Reviewed: 5 Section A + 4 primitive lone-subjects. Suspects: 0.
+
+No suspects.
diff --git a/wip/keyword-only-arguments/audit/positional-subject-audit.md b/wip/keyword-only-arguments/audit/positional-subject-audit.md
new file mode 100644
index 000000000..f555a0d9e
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/positional-subject-audit.md
@@ -0,0 +1,2062 @@
+# Keyword-Only Refactor — Positional-Subject Audit
+
+Every `pipelex/` function/method where the **first true parameter (after dropping `self`/`cls`) was kept positional** — i.e. where Exception 1 of the keyword-only convention ("the subject may stay positional") is in effect. This is the population to audit for the worry: *was the first arg really the semantically obvious object of the call, or was it made positional just to satisfy the rule?*
+
+## How this was generated
+
+An AST pass that **reuses the keyword-only guard's own carve-out detection** (`pipelex/cli/dev_cli/commands/keyword_only_guard.py`). Anything the guard skips is excluded here too, because those were never a deliberate "subject" decision:
+
+- dunder/operator methods (`__init__`, `__eq__`, …)
+- pydantic `@field_validator` / `@model_validator` / serializers
+- framework entrypoints: Typer/click commands, Temporal `@activity.defn`/`@workflow.*`, pytest fixtures, Jinja2 `@pass_context`/… filters
+- `@override` implementations (the parent's call convention governs them)
+- `# kw-only: ignore` escape-hatch defs
+
+Functions with **no** positional parameter at all (fully keyword-only `def f(*, a, b)`, zero-arg, or staticmethods with only keyword-only params) are also excluded — there is no positional subject to question.
+
+Scope: `pipelex/` source only (tests excluded, matching the refactor's locked scope).
+
+## Summary
+
+**Total positional-subject functions: 1806**
+
+| Category | Count | What it is |
+| --- | --- | --- |
+| `SUBJECT_THEN_KEYWORDS` | 797 | Subject kept positional **and** one or more other params pushed to keyword-only (`def f(subject, *, ...)`). This is where the "which arg is the subject?" decision was actually made — the **primary review target**. |
+| `LONE_SUBJECT` | 1003 | A single positional parameter and nothing else after it (`def f(subject)`, optionally `**kwargs`). No "choice" of subject was possible — only one arg exists. Lowest signal; included for completeness. A bare bool/int/str subject here is the only thing arguably worth a second look (`do_thing(True)` reads opaquely). |
+| `SYMMETRIC_ALLOWLIST` | 5 | Exception 2 — the curated symmetric-tuple allowlist (multiple positionals that read better ordered, e.g. `set_env(key, value)`). |
+| `MULTI_POSITIONAL` | 1 | Survives the guard with 2+ positionals or a `*args` — i.e. a variadic wrapper/closure, not a deliberate subject choice. |
+
+### By package
+
+| Package | SUBJECT_THEN_KEYWORDS | All categories |
+| --- | --- | --- |
+| `base_exceptions.py` | 0 | 8 |
+| `builder` | 20 | 36 |
+| `cli` | 112 | 210 |
+| `cogt` | 119 | 291 |
+| `core` | 95 | 213 |
+| `errors` | 5 | 17 |
+| `graph` | 40 | 67 |
+| `hub.py` | 1 | 45 |
+| `kit` | 8 | 12 |
+| `language` | 5 | 21 |
+| `libraries` | 28 | 74 |
+| `observer` | 1 | 5 |
+| `pipe_controllers` | 6 | 11 |
+| `pipe_operators` | 40 | 53 |
+| `pipe_run` | 18 | 27 |
+| `pipe_signature` | 2 | 2 |
+| `pipelex.py` | 3 | 4 |
+| `pipeline` | 18 | 31 |
+| `plugins` | 49 | 132 |
+| `reporting` | 5 | 12 |
+| `runtime_bridge` | 12 | 22 |
+| `system` | 38 | 100 |
+| `temporal` | 39 | 88 |
+| `test_extras` | 0 | 6 |
+| `tools` | 128 | 296 |
+| `tracing` | 5 | 23 |
+
+---
+
+## Review strategy
+
+**What this audit is asking each reviewer to decide:** for a given `def f(subject, *, ...)`, is `subject` genuinely the semantic object the function acts on (so positional reads naturally — `parse_pipe_spec(spec_data, ...)`), or was it kept positional merely to satisfy Exception 1, when the call would actually read better with that arg keyworded too?
+
+### Model grade
+
+**Sonnet 4.6 is sufficient for the per-line judgment.** This is a naming/API-taste classification, not a reasoning-heavy task — the vast majority of signatures are unambiguous from the `def` line alone. Opus-grade horsepower buys little here.
+
+The real bottleneck is **not** model IQ — it is two other things:
+
+1. **Context per line.** A signature alone settles most cases, but an ambiguous minority cannot be judged without the function body and a call site or two (e.g. `_resolve_preset_backend(model_deck, *, model_handle, model_type)` — is the deck the subject, or is this "resolve a backend *for a handle*" with the deck as a lookup table?). **Give the reviewer Read/Grep so it can open the body — do not feed it only the text line**, or even Opus will just guess.
+2. **Calibration.** A cheap pass tends to either rubber-stamp everything or over-flag. Mitigate with a tight rubric (see `docs/contribute/keyword-only-arguments.md` for worked examples) and an instruction to **default to OK and emit only the suspects**, each with a one-line reason and a suggested fix.
+
+### Triage plan (don't sweep all 1806 lines)
+
+1. **Drop most of `LONE_SUBJECT` (1003).** With a single positional param there was no "subject" choice to abuse. The only sub-slice worth a look is **primitive-typed** lone subjects (`do_thing(True)`, `f(count: int)`), which read opaquely at the call site — filter those mechanically (grep), no LLM needed.
+2. **Sonnet fan-out across packages** over the 797 `SUBJECT_THEN_KEYWORDS` (+ the primitive lone-subjects), one agent per package, each emitting only a shortlist of "this positional reads wrong" entries with reasoning + suggested fix. Parallel, cheap, consistent.
+3. **Adjudicate only the shortlist** (yourself, or Opus on just the contested few dozen). Reserve the expensive judgment for the small contested set rather than spending it uniformly across ~1800 obvious cases.
+
+---
+
+## A. `SUBJECT_THEN_KEYWORDS` — primary review target
+
+_Subject kept positional **and** one or more other params pushed to keyword-only (`def f(subject, *, ...)`). This is where the "which arg is the subject?" decision was actually made — the **primary review target**._
+
+Count: 797
+
+### `builder` (20)
+
+- `pipelex/builder/concept/concept_spec.py:198` — `ConceptStructureSpec._raise_type_mismatch_error` — `def _raise_type_mismatch_error(self, expected_type_name: str, *, actual_type_name: str) -> None`
+- `pipelex/builder/operations/inputs_ops.py:23` — `build_inputs_for_pipe` — `async def build_inputs_for_pipe(pipe_code: str | None=None, *, mthds_contents: list[str] | None=None, bundle_path: Path | None=None, library_dirs: list[Path] | None=None) -> dict[str, Any]`
+- `pipelex/builder/operations/models_ops.py:28` — `_should_include` — `def _should_include(category: ModelCategory, *, categories: list[ModelCategory] | None) -> bool`
+- `pipelex/builder/operations/models_ops.py:36` — `_resolve_preset_backend` — `def _resolve_preset_backend(model_deck: ModelDeck, *, model_handle: str, model_type: ModelType) -> InferenceModelSpec | None`
+- `pipelex/builder/operations/models_ops.py:46` — `_filter_presets_by_backend` — `def _filter_presets_by_backend(presets_list: list[dict[str, Any]], *, presets_dict: dict[str, Any], model_deck: ModelDeck, model_type: ModelType, backend: str) -> list[dict[str, Any]]`
+- `pipelex/builder/operations/models_ops.py:67` — `_filter_aliases_by_backend` — `def _filter_aliases_by_backend(aliases: dict[str, str], *, model_deck: ModelDeck, model_type: ModelType, backend: str) -> dict[str, str]`
+- `pipelex/builder/operations/models_ops.py:83` — `_filter_waterfalls_by_backend` — `def _filter_waterfalls_by_backend(waterfalls: dict[str, list[str]], *, model_deck: ModelDeck, model_type: ModelType, backend: str) -> dict[str, list[str]]`
+- `pipelex/builder/operations/models_ops.py:101` — `_build_presets_for_category` — `def _build_presets_for_category(model_deck: ModelDeck, *, category: ModelCategory, backend: str | None) -> list[dict[str, Any]]`
+- `pipelex/builder/operations/models_ops.py:135` — `_build_aliases_for_category` — `def _build_aliases_for_category(model_deck: ModelDeck, *, category: ModelCategory, backend: str | None) -> dict[str, str]`
+- `pipelex/builder/operations/models_ops.py:160` — `_build_waterfalls_for_category` — `def _build_waterfalls_for_category(model_deck: ModelDeck, *, category: ModelCategory, backend: str | None) -> dict[str, list[str]]`
+- `pipelex/builder/operations/models_ops.py:185` — `list_models` — `def list_models(categories: list[ModelCategory] | None=None, *, backend: str | None=None) -> dict[str, Any]`
+- `pipelex/builder/operations/output_ops.py:14` — `build_output_for_pipe` — `async def build_output_for_pipe(mthds_contents: list[str], *, pipe_code: str, output_format: ConceptRepresentationFormat=ConceptRepresentationFormat.SCHEMA) -> dict[str, Any]`
+- `pipelex/builder/operations/pipe_ops.py:47` — `_normalize_sub_pipe_list` — `def _normalize_sub_pipe_list(raw_value: Any, *, field_name: str) -> list[dict[str, Any]]`
+- `pipelex/builder/operations/pipe_ops.py:89` — `parse_pipe_spec` — `def parse_pipe_spec(spec_data: Any, *, pipe_type: str) -> PipeSpec`
+- `pipelex/builder/operations/pipe_ops.py:191` — `add_type_specific_fields` — `def add_type_specific_fields(pipe_spec: PipeSpec, *, pipe_table: Table) -> None`
+- `pipelex/builder/operations/runner_code_ops.py:17` — `build_runner_code_for_pipe` — `async def build_runner_code_for_pipe(mthds_contents: list[str], *, pipe_code: str) -> str`
+- `pipelex/builder/operations/validate_ops.py:53` — `validate_bundle_file` — `async def validate_bundle_file(bundle_path: Path, *, library_dirs: list[Path] | None=None) -> dict[str, Any]`
+- `pipelex/builder/operations/validate_ops.py:110` — `validate_pipe` — `async def validate_pipe(pipe_code: str, *, library_dirs: list[Path] | None=None) -> dict[str, Any]`
+- `pipelex/builder/runner_code.py:65` — `_format_representation_as_python` — `def _format_representation_as_python(representation: dict[str, Any], *, is_multiple: bool=False) -> str`
+- `pipelex/builder/runner_code.py:158` — `generate_runner_code` — `def generate_runner_code(pipe: PipeAbstract, *, output_multiplicity: bool=False, library_dir: str | None=None) -> str`
+
+### `cli` (112)
+
+- `pipelex/cli/agent_cli/commands/agent_cli_factory.py:163` — `make_pipelex_for_agent_cli` — `def make_pipelex_for_agent_cli(library_dirs: list[str] | list[Path] | None=None, *, needs_inference: bool=True, needs_model_specs: bool | None=None) -> Pipelex`
+- `pipelex/cli/agent_cli/commands/agent_output.py:218` — `_assemble_error_payload` — `def _assemble_error_payload(message: str, *, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/agent_output.py:311` — `_agent_error_json` — `def _agent_error_json(message: str, *, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> NoReturn`
+- `pipelex/cli/agent_cli/commands/agent_output.py:318` — `agent_error_markdown` — `def agent_error_markdown(message: str, *, error_type: str, cause: BaseException | None=None, **extra: Any) -> NoReturn`
+- `pipelex/cli/agent_cli/commands/agent_output.py:338` — `agent_error` — `def agent_error(message: str, *, error_type: str, cause: BaseException | None=None, **extra: Any) -> NoReturn`
+- `pipelex/cli/agent_cli/commands/agent_output.py:382` — `agent_success_formatted` — `def agent_success_formatted(result: dict[str, Any], *, markdown_renderer: Callable[[dict[str, Any]], str], output_format: CliOutputFormat) -> None`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:153` — `_copy_telemetry_template` — `def _copy_telemetry_template(target_dir: Path, *, for_project: bool) -> None`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:173` — `_configure_backends` — `def _configure_backends(config: dict[str, Any], *, backends_toml_path: Path, template_backends_path: Path) -> list[str]`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:228` — `_configure_routing` — `def _configure_routing(selected_backend_keys: list[str], *, config: dict[str, Any], target_dir: Path) -> str`
+- `pipelex/cli/agent_cli/commands/inputs/_inputs_core.py:13` — `inputs_core` — `async def inputs_core(pipe_code: str | None=None, *, bundle_path: Path | None=None, library_dirs: list[Path] | None=None) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/pipe_cmd.py:74` — `_add_type_specific_fields` — `def _add_type_specific_fields(pipe_spec: PipeSpec, *, pipe_table: tomlkit.TOMLDocument | tomlkit.items.Table) -> None`
+- `pipelex/cli/agent_cli/commands/plxt_passthrough.py:11` — `run_plxt` — `def run_plxt(subcommand: str, *, file_path: str) -> None`
+- `pipelex/cli/agent_cli/commands/run/_output_helpers.py:14` — `build_run_output` — `def build_run_output(with_memory: bool, *, main_stuff_json: dict[str, Any], working_memory_dump: dict[str, Any], compact_result: dict[str, Any] | None, extra_metadata: dict[str, Any] | None=None) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/run/_output_helpers.py:69` — `format_run_markdown` — `def format_run_markdown(result: dict[str, Any], *, with_memory: bool) -> str`
+- `pipelex/cli/agent_cli/commands/run/_run_core.py:21` — `run_pipeline_core` — `async def run_pipeline_core(pipe_code: str, *, mthds_contents: list[str] | None=None, bundle_uris: list[str] | None=None, inputs: dict[str, Any] | None=None, dry_run: bool=False, mock_inputs: bool=False, library_dirs: list[str] | None=None, graph: bool=False, costs: bool=True, with_memory: bool=False) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/run/_run_core_api.py:17` — `run_pipeline_core_api` — `async def run_pipeline_core_api(pipe_code: str, *, mthds_contents: list[str] | None=None, inputs: dict[str, Any] | None=None, with_memory: bool=False) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/run/stdin_resolver.py:116` — `parse_cli_inputs` — `def parse_cli_inputs(inputs_arg: str | None, *, stdin_fallback: bool=True, auto_inputs_path: str | None=None) -> dict[str, Any] | None`
+- `pipelex/cli/agent_cli/commands/validate/_validate_core.py:22` — `validate_all_core` — `async def validate_all_core(library_dirs: list[Path] | None=None, *, allow_signatures: bool=False) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/validate/_validate_core.py:57` — `validate_bundle_core` — `async def validate_bundle_core(bundle_path: Path, *, library_dirs: list[Path] | None=None, allow_signatures: bool=False) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/validate/_validate_core.py:97` — `validate_pipe_core` — `async def validate_pipe_core(pipe_code: str, *, library_dirs: list[Path] | None=None, allow_signatures: bool=False) -> dict[str, Any]`
+- `pipelex/cli/cli_factory.py:31` — `make_pipelex_for_cli` — `def make_pipelex_for_cli(context: ErrorContext, *, library_dirs: list[str] | list[Path] | None=None, needs_inference: bool=True, temporal_enabled: bool | None=None, needs_model_specs: bool | None=None) -> Pipelex`
+- `pipelex/cli/commands/build/inputs/_inputs_core.py:35` — `_generate_inputs_core` — `async def _generate_inputs_core(pipe_code: str | None=None, *, bundle_path: Path | None=None, output_path: Path | None=None, library_dir: list[str] | None=None) -> None`
+- `pipelex/cli/commands/build/inputs/_inputs_core.py:116` — `execute_generate_inputs` — `def execute_generate_inputs(pipe_code: str | None, *, bundle_path: Path | None, output_path: Path | None, library_dir: list[str] | None=None, telemetry_command_label: str=f'{COMMAND} {SUB_COMMAND_INPUTS}') -> None`
+- `pipelex/cli/commands/build/output/_output_core.py:35` — `_generate_output_core` — `async def _generate_output_core(pipe_code: str | None=None, *, bundle_path: Path | None=None, output_path: Path | None=None, output_format: ConceptRepresentationFormat=ConceptRepresentationFormat.JSON, library_dir: list[str] | None=None) -> None`
+- `pipelex/cli/commands/build/output/_output_core.py:130` — `execute_generate_output` — `def execute_generate_output(pipe_code: str | None, *, bundle_path: Path | None, output_path: Path | None, output_format: ConceptRepresentationFormat, library_dir: list[str] | None=None, telemetry_command_label: str=f'{COMMAND} {SUB_COMMAND_OUTPUT}') -> None`
+- `pipelex/cli/commands/build/runner/_runner_core.py:52` — `_prepare_runner_core` — `async def _prepare_runner_core(pipe_code: str | None=None, *, bundle_path: Path | None=None, output_path: Path | None=None, library_dirs: list[Path] | None=None) -> None`
+- `pipelex/cli/commands/build/runner/_runner_core.py:175` — `execute_prepare_runner` — `def execute_prepare_runner(pipe_code: str | None, *, bundle_path: Path | None, output_path: Path | None, library_dirs: list[Path] | None=None, telemetry_command_label: str=f'{COMMAND} {SUB_COMMAND_RUNNER}') -> None`
+- `pipelex/cli/commands/build/structures_cmd.py:50` — `_build_concept_ref_to_class_info` — `def _build_concept_ref_to_class_info(blueprints: list['PipelexBundleBlueprint'], *, output_directory: Path) -> dict[str, ConceptClassInfo]`
+- `pipelex/cli/commands/build/structures_cmd.py:105` — `generate_structures_from_blueprints` — `def generate_structures_from_blueprints(blueprints: list['PipelexBundleBlueprint'], *, output_directory: Path, target_path: Path | None=None, skip_existing_check: bool=False, quiet: bool=False) -> list[tuple[str, str]]`
+- `pipelex/cli/commands/doctor_cmd.py:291` — `replace_backend_file` — `def replace_backend_file(backend_name: str, *, dry_run: bool=False, config_dir: Path | None=None) -> bool`
+- `pipelex/cli/commands/doctor_cmd.py:741` — `setup_doctor_runtime` — `def setup_doctor_runtime(log_config_overrides: Mapping[str, Any] | None=None, *, config_dir: Path | None=None) -> None`
+- `pipelex/cli/commands/graph_cmd.py:38` — `_do_graph_render` — `def _do_graph_render(input_file: Path, *, out: str | None, direction: FlowchartDirection | None, mermaidflow: bool, reactflow: bool, subgraphs: bool, open_browser: bool) -> None`
+- `pipelex/cli/commands/init/backends.py:31` — `update_backends_in_toml` — `def update_backends_in_toml(toml_doc: Any, *, selected_indices: list[int], backend_options: list[tuple[str, str]]) -> None`
+- `pipelex/cli/commands/init/command.py:129` — `prime_remote_config_cache` — `def prime_remote_config_cache(console: Console, *, target_config_dir: Path | None=None) -> None`
+- `pipelex/cli/commands/init/command.py:144` — `_check_gateway_terms_if_needed` — `def _check_gateway_terms_if_needed(console: Console, *, backends_toml_path: Path) -> None`
+- `pipelex/cli/commands/init/command.py:182` — `determine_needs` — `def determine_needs(reset: bool, *, check_config: bool, check_inference: bool, check_routing: bool, check_telemetry: bool, backends_toml_path: Path, routing_profiles_toml_path: Path, telemetry_config_path: Path, target_config_dir: Path | None=None) -> tuple[bool, bool, bool, bool]`
+- `pipelex/cli/commands/init/command.py:219` — `confirm_initialization` — `def confirm_initialization(console: Console, *, needs_config: bool, needs_inference: bool, needs_routing: bool, needs_telemetry: bool, check_credentials: bool, reset: bool, focus: InitFocus) -> bool`
+- `pipelex/cli/commands/init/command.py:277` — `execute_initialization` — `def execute_initialization(console: Console, *, needs_config: bool, needs_inference: bool, needs_routing: bool, needs_telemetry: bool, check_credentials: bool, reset: bool, check_inference: bool, check_routing: bool, backends_toml_path: Path, telemetry_config_path: Path, is_first_time_backends_setup: bool, target_config_dir: Path | None=None, for_project: bool=False)`
+- `pipelex/cli/commands/init/command.py:478` — `init_cmd` — `def init_cmd(focus: InitFocus=InitFocus.ALL, *, skip_confirmation: bool=False, local: bool=False)`
+- `pipelex/cli/commands/init/config_files.py:20` — `init_config` — `def init_config(reset: bool=False, *, dry_run: bool=False, target_dir: Path | None=None) -> int`
+- `pipelex/cli/commands/init/credentials.py:48` — `write_env_file` — `def write_env_file(env_path: Path, *, entries: dict[str, str]) -> None`
+- `pipelex/cli/commands/init/credentials.py:104` — `prompt_credentials` — `def prompt_credentials(console: Console, *, backends_toml_path: Path) -> None`
+- `pipelex/cli/commands/init/ide_extension.py:56` — `_install_extension` — `def _install_extension(ide_name: str, *, cmd: str, console: Console) -> bool`
+- `pipelex/cli/commands/init/routing.py:26` — `customize_routing_profile` — `def customize_routing_profile(selected_backend_keys: list[str], *, target_config_dir: Path | None=None) -> None`
+- `pipelex/cli/commands/init/ui/backends_ui.py:17` — `get_backend_options_from_toml` — `def get_backend_options_from_toml(template_path: Path, *, existing_path: Path | None=None) -> list[tuple[str, str]]`
+- `pipelex/cli/commands/init/ui/backends_ui.py:61` — `get_currently_enabled_backends` — `def get_currently_enabled_backends(backends_toml_path: Path, *, backend_options: list[tuple[str, str]]) -> list[int]`
+- `pipelex/cli/commands/init/ui/backends_ui.py:97` — `build_backend_selection_panel` — `def build_backend_selection_panel(backend_options: list[tuple[str, str]], *, currently_enabled: list[int] | None=None, is_first_time_setup: bool=False) -> Panel`
+- `pipelex/cli/commands/init/ui/backends_ui.py:155` — `prompt_backend_select` — `def prompt_backend_select(console: Console, *, backend_options: list[tuple[str, str]], currently_enabled: list[int] | None=None, is_first_time_setup: bool=False) -> tuple[list[int], set[str]]`
+- `pipelex/cli/commands/init/ui/general_ui.py:6` — `build_initialization_panel` — `def build_initialization_panel(needs_config: bool, *, needs_inference: bool, needs_routing: bool, needs_telemetry: bool, reset: bool, check_credentials: bool=False) -> Panel`
+- `pipelex/cli/commands/init/ui/routing_ui.py:13` — `build_primary_backend_panel` — `def build_primary_backend_panel(backend_keys: list[str], *, backend_options: list[tuple[str, str]]) -> Panel`
+- `pipelex/cli/commands/init/ui/routing_ui.py:91` — `build_fallback_order_panel` — `def build_fallback_order_panel(remaining_backends: list[str], *, backend_options: list[tuple[str, str]]) -> Panel`
+- `pipelex/cli/commands/init/ui/routing_ui.py:127` — `prompt_fallback_order` — `def prompt_fallback_order(console: Console, *, remaining_backends: list[str], backend_options: list[tuple[str, str]]) -> list[str]`
+- `pipelex/cli/commands/init/ui/routing_ui.py:198` — `display_routing_profile_result` — `def display_routing_profile_result(console: Console, *, profile_name: str, created: bool=False) -> None`
+- `pipelex/cli/commands/login/command.py:105` — `serve_until_callback` — `def serve_until_callback(server: HTTPServer, *, result: dict[str, str | None]) -> None`
+- `pipelex/cli/commands/run/_inputs_path_resolver.py:45` — `resolve_url_in_value` — `def resolve_url_in_value(value: Any, *, base_dir: Path) -> Any`
+- `pipelex/cli/commands/run/_inputs_path_resolver.py:75` — `resolve_inputs_paths` — `def resolve_inputs_paths(inputs_dict: dict[str, Any], *, base_dir: Path) -> dict[str, Any]`
+- `pipelex/cli/commands/run/_run_core.py:74` — `_execute_run` — `async def _execute_run(pipe_code: str | None, *, bundle_path: str | None, inputs: str | None, save_working_memory: bool, working_memory_path: str | None, save_main_stuff: bool, no_pretty_print: bool, graph: bool | None, graph_full_data: bool | None, output_dir: str, dry_run: bool, mock_usage: bool, mock_inputs: bool, library_dir: list[str] | None, costs: bool | None=None, dynamic_output_concept_ref: str | None=None, save_csv: str | None=None) -> None`
+- `pipelex/cli/commands/run/_run_core.py:344` — `execute_run` — `def execute_run(pipe_code: str | None, *, bundle_path: str | None, inputs: str | None, save_working_memory: bool, working_memory_path: str | None, save_main_stuff: bool, no_pretty_print: bool, graph: bool | None, graph_full_data: bool | None, output_dir: str, dry_run: bool, mock_usage: bool, mock_inputs: bool, library_dir: list[str] | None, costs: bool | None=None, telemetry_command_label: str=COMMAND, temporal: bool | None=None, dynamic_output_concept_ref: str | None=None, save_csv: str | None=None) -> None`
+- `pipelex/cli/commands/update_cmd.py:34` — `update_cmd` — `def update_cmd(local: bool=False, *, yes: bool=False, dry_run: bool=False, no_backup: bool=False) -> None`
+- `pipelex/cli/commands/update_cmd.py:102` — `_print_status_table` — `def _print_status_table(report: DeckSyncReport, *, deck_dir: Path) -> None`
+- `pipelex/cli/commands/update_cmd.py:138` — `_apply_updates` — `def _apply_updates(deck_dir: Path, *, report: DeckSyncReport, no_backup: bool) -> int`
+- `pipelex/cli/commands/update_cmd.py:187` — `_summary_panel` — `def _summary_panel(message: str, *, style: str) -> Panel`
+- `pipelex/cli/commands/validate/_validate_core.py:59` — `do_validate_all_libraries_and_dry_run` — `def do_validate_all_libraries_and_dry_run(library_dirs: list[Path] | None=None, *, allow_signatures: bool=False) -> None`
+- `pipelex/cli/commands/validate/_validate_core.py:99` — `_validate_pipe_or_bundle` — `async def _validate_pipe_or_bundle(pipe_code: str | None=None, *, bundle_path: Path | None=None, library_dirs: list[Path] | None=None, allow_signatures: bool=False) -> None`
+- `pipelex/cli/commands/validate/_validate_core.py:162` — `execute_validate` — `def execute_validate(pipe_code: str | None, *, bundle_path: Path | None, library_dirs: list[Path] | None, telemetry_command_label: str=COMMAND, allow_signatures: bool=False, temporal: bool | None=None) -> None`
+- `pipelex/cli/commands/which_cmd.py:33` — `do_which_pipe` — `def do_which_pipe(pipe_code: str, *, library_dirs: list[Path], source_label: str) -> bool`
+- `pipelex/cli/dev_cli/commands/check_config_sync_cmd.py:24` — `check_config_sync_cmd` — `def check_config_sync_cmd(show_diff: bool=True, *, leading: LeadingConfig=LeadingConfig.INSTALLED, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/check_gateway_models_cmd.py:28` — `check_gateway_models_cmd` — `def check_gateway_models_cmd(show_diff: bool=True, *, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/check_mthds_schema_cmd.py:21` — `check_mthds_schema_cmd` — `def check_mthds_schema_cmd(show_diff: bool=True, *, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/check_rules_sync_cmd.py:40` — `check_rules_sync_cmd` — `def check_rules_sync_cmd(show_diff: bool=True, *, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/check_urls_cmd.py:63` — `check_single_url_async` — `async def check_single_url_async(client: httpx.AsyncClient, *, name: str, url: str) -> URLCheckResult`
+- `pipelex/cli/dev_cli/commands/check_urls_cmd.py:118` — `check_all_urls_async` — `async def check_all_urls_async(url_pairs: list[tuple[str, str]], *, request_timeout: int) -> list[URLCheckResult]`
+- `pipelex/cli/dev_cli/commands/check_urls_cmd.py:145` — `check_urls_cmd` — `def check_urls_cmd(quiet: bool=False, *, timeout: int=DEFAULT_TIMEOUT) -> None`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:126` — `generate_pure_markdown_list.sort_by_preferred` — `def sort_by_preferred(items: list[str], *, preferred: list[str]) -> list[str]`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:165` — `generate_markdown_table.sort_by_preferred` — `def sort_by_preferred(items: set[str], *, preferred: list[str]) -> list[str]`
+- `pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py:16` — `generate_error_pages_cmd` — `def generate_error_pages_cmd(output: Path | None=None, *, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/generate_mthds_schema_cmd.py:18` — `generate_mthds_schema_cmd` — `def generate_mthds_schema_cmd(output: Path | None=None, *, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:214` — `_positional_or_keyword_count` — `def _positional_or_keyword_count(node: ast.FunctionDef | ast.AsyncFunctionDef, *, is_method: bool) -> int`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:232` — `_def_line_has_escape_hatch` — `def _def_line_has_escape_hatch(node: ast.FunctionDef | ast.AsyncFunctionDef, *, source_lines: list[str]) -> bool`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:240` — `_qualify` — `def _qualify(name: str, *, class_stack: tuple[str, ...], func_stack: tuple[str, ...]) -> str`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:245` — `_evaluate_def` — `def _evaluate_def(node: ast.FunctionDef | ast.AsyncFunctionDef, *, module_qname: str, relative_path: str, class_stack: tuple[str, ...], func_stack: tuple[str, ...], is_method: bool, source_lines: list[str]) -> Violation | None`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:327` — `find_violations_in_source` — `def find_violations_in_source(source: str, *, module_qname: str, relative_path: str) -> list[Violation]`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:381` — `relative_source_path` — `def relative_source_path(path: Path, *, root: Path | None=None) -> Path | None`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:407` — `collect_violations_for_files` — `def collect_violations_for_files(paths: Iterable[Path], *, root: Path | None=None) -> list[Violation]`
+- `pipelex/cli/dev_cli/commands/kit_cmd.py:31` — `_sync_agent_rules` — `def _sync_agent_rules(repo_root: Path | None, *, agent_set: str | None, cleanup: bool, kit_index: KitIndex | None=None, targets_filter: list[AgentTarget] | None=None) -> None`
+- `pipelex/cli/dev_cli/commands/kit_cmd.py:91` — `_cleanup_other_targets` — `def _cleanup_other_targets(repo_root: Path, *, kit_index: KitIndex, preferred_targets: list[AgentTarget]) -> None`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:247` — `_process_collections_from_toml` — `def _process_collections_from_toml(collections_raw: Any, *, collections: dict[str, dict[str, list[str]]]) -> None`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:292` — `_resolve_model_list` — `def _resolve_model_list(raw_list: list[str], *, collections: dict[str, list[str]], backend_models: dict[str, list[str]], all_known_models: list[str]) -> list[str]`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:367` — `_filter_models_by_profile` — `def _filter_models_by_profile(availability: dict[str, Any], *, profile: dict[str, Any], collections: dict[str, dict[str, list[str]]]) -> dict[str, list[tuple[str, str]]]`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:498` — `_generate_fixtures_python` — `def _generate_fixtures_python(combo_pairs: dict[str, list[tuple[str, str]]], *, profile_name: str) -> str`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:561` — `_display_summary` — `def _display_summary(availability: dict[str, Any], *, combo_pairs: dict[str, list[tuple[str, str]]], profile_name: str, console: Console) -> None`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:611` — `preprocess_test_models_cmd` — `def preprocess_test_models_cmd(profile: str='dev', *, generate_fixtures: bool=False, output_json: bool=False, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:86` — `_validate_version` — `def _validate_version(name: str, *, value: str) -> str`
+- `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:106` — `_fetch` — `def _fetch(url: str, *, timeout: float=30.0) -> bytes`
+- `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:148` — `refresh_graph_ui_sri_cmd` — `def refresh_graph_ui_sri_cmd(mthds_ui_version: str | None=None, *, elkjs_version: str | None=None, output_path: Path | None=None, quiet: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py:20` — `_display_result` — `def _display_result(result: MirrorDirResult, *, quiet: bool) -> None`
+- `pipelex/cli/dev_cli/commands/sync_kit_configs_cmd.py:86` — `sync_kit_configs_cmd` — `def sync_kit_configs_cmd(quiet: bool=False, *, dry_run: bool=False) -> None`
+- `pipelex/cli/dev_cli/commands/sync_main_config_cmd.py:38` — `_display_sync_result` — `def _display_sync_result(result: TomlSyncResult, *, target_label: str, show_diff: bool, quiet: bool) -> None`
+- `pipelex/cli/dev_cli/commands/sync_main_config_cmd.py:77` — `sync_main_config_cmd` — `def sync_main_config_cmd(target: SyncTarget=SyncTarget.ALL, *, dry_run: bool=False, quiet: bool=False, show_diff: bool=True) -> None`
+- `pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py:41` — `_all_references_up_to_date` — `def _all_references_up_to_date(reference_files: list[tuple[Path, Path]], *, expected_html: str, expected_plain: str) -> bool`
+- `pipelex/cli/error_handlers.py:86` — `display_error_panel` — `def display_error_panel(console: Console, *, title: str, fields: list[tuple[str, str]], error_message: str | None, tip: str, links: list[tuple[str, str]]) -> None`
+- `pipelex/cli/error_handlers.py:125` — `handle_model_choice_error` — `def handle_model_choice_error(exc: PipeOperatorModelChoiceError, *, context: ErrorContext) -> NoReturn`
+- `pipelex/cli/error_handlers.py:156` — `handle_model_availability_error` — `def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *, context: ErrorContext) -> NoReturn`
+- `pipelex/cli/error_handlers.py:193` — `handle_model_deck_preset_error` — `def handle_model_deck_preset_error(exc: ModelDeckPresetValidatonError, *, context: ErrorContext) -> NoReturn`
+- `pipelex/cli/error_handlers.py:248` — `_display_validation_error_details` — `def _display_validation_error_details(console: Console, *, exc: ValidateBundleError) -> None`
+- `pipelex/cli/error_handlers.py:325` — `handle_signatures_not_allowed_error` — `def handle_signatures_not_allowed_error(exc: SignaturesNotAllowedError, *, context: ErrorContext) -> NoReturn`
+- `pipelex/cli/error_handlers.py:343` — `handle_validate_bundle_error` — `def handle_validate_bundle_error(exc: ValidateBundleError, *, bundle_path: Path | None=None) -> NoReturn`
+- `pipelex/cli/installed_methods.py:43` — `discover_installed_methods` — `def discover_installed_methods(include_global: bool=True, *, include_project: bool=True, extra_search_dirs: list[Path] | None=None) -> list[InstalledMethod]`
+- `pipelex/cli/installed_methods.py:112` — `discover_method_at` — `def discover_method_at(method_dir: Path, *, seen_dirs: set[Path]) -> InstalledMethod | None`
+- `pipelex/cli/installed_methods.py:184` — `find_method_by_full_address` — `def find_method_by_full_address(full_address: str, *, methods: list[InstalledMethod] | None=None, extra_search_dirs: list[Path] | None=None) -> InstalledMethod | None`
+- `pipelex/cli/installed_methods.py:216` — `find_method_by_name` — `def find_method_by_name(method_name: str, *, methods: list[InstalledMethod] | None=None, library_dirs: list[str] | None=None) -> InstalledMethod`
+- `pipelex/cli/method_resolver.py:227` — `resolve_method_target` — `def resolve_method_target(method_name: str, *, pipe_override: str | None=None, library_dirs: list[str] | None=None) -> tuple[str, list[str], InstalledMethod]`
+
+### `cogt` (119)
+
+- `pipelex/cogt/config_cogt.py:30` — `ImgGenConfig.get_num_inference_steps` — `def get_num_inference_steps(self, model_name: str, *, quality: Quality) -> int`
+- `pipelex/cogt/config_cogt.py:96` — `LLMConfig.get_reasoning_budget` — `def get_reasoning_budget(self, prompting_target: str, *, effort: ReasoningEffort) -> int`
+- `pipelex/cogt/content_generation/assignment_models.py:87` — `ObjectAssignment.make_for_class` — `def make_for_class(object_class: type[BaseModel], *, llm_assignment: LLMAssignment, nb_items: int | None=None) -> 'ObjectAssignment'`
+- `pipelex/cogt/content_generation/assignment_models.py:177` — `SearchObjectAssignment.make_for_class` — `def make_for_class(output_class: type[BaseModel], *, search_assignment: SearchAssignment) -> 'SearchObjectAssignment'`
+- `pipelex/cogt/content_generation/content_generator.py:44` — `_revalidate_against_object_class` — `def _revalidate_against_object_class(raw_obj: BaseModel, *, object_class: type[BaseModelTypeVar], is_mock_built: bool) -> BaseModelTypeVar`
+- `pipelex/cogt/content_generation/dry_mock.py:143` — `report_dry_llm_job` — `def report_dry_llm_job(job_metadata: JobMetadata, *, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None`
+- `pipelex/cogt/content_generation/dry_mock.py:155` — `report_mock_usage_llm_job` — `def report_mock_usage_llm_job(job_metadata: JobMetadata, *, llm_setting: LLMSetting, llm_prompt: LLMPrompt) -> None`
+- `pipelex/cogt/content_generation/dry_mock.py:186` — `build_mock_objects` — `def build_mock_objects(model_class: type[BaseModelTypeVar], *, count: int) -> list[BaseModelTypeVar]`
+- `pipelex/cogt/content_generation/dry_mock.py:240` — `_leaf_gen_object` — `def _leaf_gen_object(object_assignment: ObjectAssignment, *, report_func: _ReportLLMJobFunc) -> BaseModel`
+- `pipelex/cogt/content_generation/dry_mock.py:262` — `_leaf_gen_object_list` — `def _leaf_gen_object_list(object_assignment: ObjectAssignment, *, report_func: _ReportLLMJobFunc) -> list[BaseModel]`
+- `pipelex/cogt/content_generation/dry_mock.py:343` — `_dry_image_content` — `def _dry_image_content(image_url: str, *, img_gen_assignment: ImgGenAssignment | None=None) -> ImageContent`
+- `pipelex/cogt/content_generation/dry_run_factory.py:197` — `DryRunFactory._find_nested_base_model_classes` — `def _find_nested_base_model_classes(cls, object_class: type[BaseModel], *, visited: set[type[BaseModel]] | None=None) -> set[type[BaseModel]]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:339` — `DryRunFactory.make_dry_run_factory` — `def make_dry_run_factory(cls, object_class: type[BaseModelTypeVar], *, snake_case_field_names: set[str] | None=None, pascal_case_field_names: set[str] | None=None) -> type[ModelFactory[BaseModelTypeVar]]`
+- `pipelex/cogt/content_generation/extract_generate.py:21` — `extract_gen_pages_and_store` — `async def extract_gen_pages_and_store(extract_assignment: ExtractAssignment, *, generated_content_factory: GeneratedContentFactory) -> list[PageContent]`
+- `pipelex/cogt/content_generation/generated_content_factory.py:25` — `GeneratedContentFactory._build_storage_key` — `def _build_storage_key(self, primary_id: str, *, secondary_id: str, data: bytes, mime_type: str | None, image_format: ImageFormat | None) -> str`
+- `pipelex/cogt/content_generation/generated_content_factory.py:68` — `GeneratedContentFactory.make_image_content` — `async def make_image_content(self, primary_id: str, *, secondary_id: str, raw_details: GeneratedImageRawDetails) -> ImageContent`
+- `pipelex/cogt/content_generation/generated_content_factory.py:161` — `GeneratedContentFactory.make_page_contents` — `async def make_page_contents(self, primary_id: str, *, secondary_id: str, extract_output: ExtractOutput) -> list[PageContent]`
+- `pipelex/cogt/content_generation/img_gen_generate.py:40` — `img_gen_single_image_and_store` — `async def img_gen_single_image_and_store(img_gen_assignment: ImgGenAssignment, *, generated_content_factory: GeneratedContentFactory) -> ImageContent`
+- `pipelex/cogt/content_generation/img_gen_generate.py:66` — `img_gen_image_list_and_store` — `async def img_gen_image_list_and_store(img_gen_assignment: ImgGenAssignment, *, generated_content_factory: GeneratedContentFactory) -> list[ImageContent]`
+- `pipelex/cogt/content_generation/render_generate.py:17` — `render_page_views_and_store` — `async def render_page_views_and_store(render_assignment: RenderPageViewsAssignment, *, generated_content_factory: GeneratedContentFactory) -> list[ImageContent]`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:82` — `SchemaToModelFactory.make_from_json_schema` — `def make_from_json_schema(cls, schema: dict[str, Any], *, class_name: str) -> type[BaseModel]`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:126` — `SchemaToModelFactory._collect_unsafe_extension_paths` — `def _collect_unsafe_extension_paths(cls, node: Any, *, path: str, found: list[str]) -> None`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:319` — `SchemaToModelFactory._exec_and_extract_class` — `def _exec_and_extract_class(cls, source_code: str, *, class_name: str) -> type[BaseModel]`
+- `pipelex/cogt/document/prompt_document_factory.py:18` — `PromptDocumentFactory.make_prompt_document` — `def make_prompt_document(cls, uri: str | None=None, *, base64_data: str | None=None, raw_bytes: bytes | None=None, mime_type: str | None=None) -> PromptDocument`
+- `pipelex/cogt/document/prompt_document_utils.py:30` — `prepare_prompt_document` — `async def prepare_prompt_document(prompt_document: PromptDocument, *, is_http_url_enabled: bool) -> PreparedFile`
+- `pipelex/cogt/document/prompt_document_utils.py:96` — `prep_prompt_documents` — `async def prep_prompt_documents(prompt_documents: list[PromptDocument], *, is_http_url_enabled: bool) -> list[PreparedFile]`
+- `pipelex/cogt/exceptions.py:68` — `CogtError.fill_model_and_provider` — `def fill_model_and_provider(self, model_handle: str | None, *, backend_name: str | None) -> None`
+- `pipelex/cogt/extract/extract_job_factory.py:9` — `ExtractJobFactory.make_extract_job` — `def make_extract_job(cls, extract_input: ExtractInput, *, job_metadata: JobMetadata, extract_job_params: ExtractJobParams | None=None, extract_job_config: ExtractJobConfig | None=None) -> ExtractJob`
+- `pipelex/cogt/extract/extract_worker_factory.py:13` — `ExtractWorkerFactory.make_extract_worker` — `def make_extract_worker(cls, inference_model: InferenceModelSpec, *, reporting_delegate: ReportingProtocol | None=None) -> ExtractWorkerAbstract`
+- `pipelex/cogt/file/file_preparation_utils.py:24` — `prepare_file_from_uri` — `async def prepare_file_from_uri(uri: str, *, keep_http_url: bool, keep_local_path: bool) -> PreparedFile`
+- `pipelex/cogt/image/generated_image.py:61` — `GeneratedImageRawDetails.make_from_pil_image` — `def make_from_pil_image(cls, pil_image: Image.Image, *, image_format: ImageFormat) -> GeneratedImageRawDetails`
+- `pipelex/cogt/image/prompt_image_factory.py:18` — `PromptImageFactory.make_prompt_image` — `def make_prompt_image(cls, uri: str | None=None, *, base64_data: str | None=None, raw_bytes: bytes | None=None) -> PromptImage`
+- `pipelex/cogt/image/prompt_image_utils.py:30` — `prepare_prompt_image` — `async def prepare_prompt_image(prompt_image: PromptImage, *, is_http_url_enabled: bool) -> PreparedFile`
+- `pipelex/cogt/image/prompt_image_utils.py:97` — `prep_prompt_images` — `async def prep_prompt_images(prompt_images: list[PromptImage], *, is_http_url_enabled: bool) -> list[PreparedFile]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:49` — `ImgGenArgsFactory.make_args_for_model` — `async def make_args_for_model(cls, model_rules: ImgGenModelRules, *, img_gen_job: ImgGenJob, nb_images: int, model_id: str, model_name: str) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:199` — `ImgGenArgsFactory.make_args_from_num_images` — `def make_args_from_num_images(cls, num_images_taxonomy: NumImagesTaxonomy, *, nb_images: int) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:208` — `ImgGenArgsFactory.make_args_from_prompt` — `def make_args_from_prompt(cls, prompt_taxonomy: PromptTaxonomy, *, positive_text: str, negative_text: str | None) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:238` — `ImgGenArgsFactory.make_args_from_model_name` — `def make_args_from_model_name(cls, model_name_taxonomy: ModelChoiceTaxonomy, *, model_id: str, model_name: str) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:253` — `ImgGenArgsFactory.make_args_from_background` — `def make_args_from_background(cls, background_taxonomy: BackgroundTaxonomy, *, background: Background, model_name: str) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:270` — `ImgGenArgsFactory.make_args_from_aspect_ratio` — `def make_args_from_aspect_ratio(cls, aspect_ratio_taxonomy: AspectRatioTaxonomy, *, aspect_ratio: AspectRatio, size: ImageSize | None, model_name: str) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:373` — `ImgGenArgsFactory.make_args_from_inference` — `def make_args_from_inference(cls, inference_taxonomy: InferenceTaxonomy, *, num_inference_steps: int | None, quality: Quality | None, guidance_scale: float | None, is_raw: bool | None) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:425` — `ImgGenArgsFactory.make_args_from_safety_checker` — `def make_args_from_safety_checker(cls, safety_checker_taxonomy: SafetyCheckerTaxonomy, *, is_moderated: bool | None, safety_tolerance: int | None) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:454` — `ImgGenArgsFactory.make_args_from_output_format` — `def make_args_from_output_format(cls, output_format_taxonomy: OutputFormatTaxonomy, *, output_format: ImageFormat | None) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:525` — `ImgGenArgsFactory.make_args_from_input_images` — `async def make_args_from_input_images(cls, input_images_taxonomy: InputImagesTaxonomy, *, input_images: list[PromptImage] | None) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:584` — `ImgGenArgsFactory.make_args_from_input_fidelity` — `def make_args_from_input_fidelity(cls, input_fidelity_taxonomy: InputFidelityTaxonomy, *, input_fidelity: InputFidelity | None, model_name: str) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_job_factory.py:10` — `ImgGenJobFactory.make_img_gen_job_from_prompt` — `def make_img_gen_job_from_prompt(cls, img_gen_prompt: ImgGenPrompt, *, job_metadata: JobMetadata, img_gen_job_params: ImgGenJobParams | None=None, img_gen_job_config: ImgGenJobConfig | None=None) -> ImgGenJob`
+- `pipelex/cogt/img_gen/img_gen_job_factory.py:32` — `ImgGenJobFactory.make_img_gen_job_from_prompt_contents` — `def make_img_gen_job_from_prompt_contents(cls, positive_text: str, *, negative_text: str | None, job_metadata: JobMetadata, img_gen_job_params: ImgGenJobParams | None=None, img_gen_job_config: ImgGenJobConfig | None=None) -> ImgGenJob`
+- `pipelex/cogt/img_gen/img_gen_worker_abstract.py:81` — `ImgGenWorkerAbstract.gen_image_list` — `async def gen_image_list(self, img_gen_job: ImgGenJob, *, nb_images: int) -> list[GeneratedImageRawDetails]`
+- `pipelex/cogt/img_gen/img_gen_worker_abstract.py:116` — `ImgGenWorkerAbstract._gen_image_list` — `async def _gen_image_list(self, img_gen_job: ImgGenJob, *, nb_images: int) -> list[GeneratedImageRawDetails]`
+- `pipelex/cogt/img_gen/img_gen_worker_factory.py:14` — `ImgGenWorkerFactory.make_img_gen_worker` — `def make_img_gen_worker(cls, inference_model: InferenceModelSpec, *, reporting_delegate: ReportingProtocol | None=None) -> ImgGenWorkerAbstract`
+- `pipelex/cogt/inference/error_classification.py:47` — `_resolve_sdk_exception_type` — `def _resolve_sdk_exception_type(exc: BaseException, *, status_code: int | None) -> str`
+- `pipelex/cogt/inference/error_classification.py:249` — `_is_quota_exhaustion_mistral` — `def _is_quota_exhaustion_mistral(error_message: str, *, status_code: int) -> bool`
+- `pipelex/cogt/inference/error_classification.py:261` — `_is_quota_exhaustion_aws` — `def _is_quota_exhaustion_aws(error_message: str, *, provider_error_code: str | None) -> bool`
+- `pipelex/cogt/inference/error_classification.py:276` — `_is_quota_exhaustion_gateway` — `def _is_quota_exhaustion_gateway(error_message: str, *, status_code: int) -> bool`
+- `pipelex/cogt/inference/error_classification.py:586` — `extract_azure_metadata_from_response` — `def extract_azure_metadata_from_response(response: Any, *, sdk_exception_type: str, message: str) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:597` — `_build_azure_metadata` — `def _build_azure_metadata(response: Any, *, sdk_exception_type: str, message: str) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:878` — `extract_local_extract_metadata` — `def extract_local_extract_metadata(exc: BaseException, *, provider: ProviderName) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_render.py:53` — `_format_message` — `def _format_message(metadata: SDKErrorEnvelope, *, model_desc: str) -> str`
+- `pipelex/cogt/inference/error_render.py:59` — `_render_detail` — `def _render_detail(metadata: SDKErrorEnvelope, *, classification: ClassificationResult) -> str`
+- `pipelex/cogt/inference/error_render.py:80` — `render_inference_error` — `def render_inference_error(metadata: SDKErrorEnvelope, *, classification: ClassificationResult, family: InferenceErrorFamily, model_desc: str, model_handle: str) -> CogtError`
+- `pipelex/cogt/inference/inference_manager_protocol.py:21` — `InferenceManagerProtocol.set_llm_worker_from_external_plugin` — `def set_llm_worker_from_external_plugin(self, llm_handle: str, *, llm_worker_class: type[LLMWorkerAbstract], should_warn_if_already_registered: bool=True)`
+- `pipelex/cogt/inference/transport_retry.py:110` — `request_with_transport_retry` — `async def request_with_transport_retry(send_request: Callable[[], Awaitable[httpx.Response]], *, max_retries: int, retry_on_ambiguous_failure: bool=True) -> httpx.Response`
+- `pipelex/cogt/llm/llm_job_factory.py:10` — `LLMJobFactory.make_llm_job` — `def make_llm_job(cls, llm_prompt: LLMPrompt, *, job_metadata: JobMetadata, llm_job_params: LLMJobParams, llm_job_config: LLMJobConfig | None=None) -> LLMJob`
+- `pipelex/cogt/llm/llm_prompt_template.py:58` — `LLMPromptTemplate._make_llm_prompt` — `async def _make_llm_prompt(self, system_text: str | None=None, *, user_text: str | None=None, user_images: list[PromptImage] | None=None, is_user_images_append: bool | None=None, template_inputs: LLMPromptTemplateInputs | None=None) -> LLMPrompt`
+- `pipelex/cogt/llm/llm_setting.py:95` — `LLMSettingChoices.make_completed_with_defaults` — `def make_completed_with_defaults(cls, for_text: LLMModelChoice | None=None, *, for_object: LLMModelChoice | None=None) -> Self`
+- `pipelex/cogt/llm/llm_worker_abstract.py:86` — `LLMWorkerAbstract._start_otel_span_llm` — `def _start_otel_span_llm(self, llm_job: LLMJob, *, output_type: InferenceOutputType, output_class_name: str | None=None) -> Span | None`
+- `pipelex/cogt/llm/llm_worker_abstract.py:231` — `LLMWorkerAbstract._end_otel_span_with_completion_text` — `def _end_otel_span_with_completion_text(self, span: Span | None, *, llm_job: LLMJob, completion_text: str) -> None`
+- `pipelex/cogt/llm/llm_worker_abstract.py:262` — `LLMWorkerAbstract._end_otel_span_with_completion_object` — `def _end_otel_span_with_completion_object(self, span: Span | None, *, llm_job: LLMJob, completion_object: BaseModel) -> None`
+- `pipelex/cogt/llm/llm_worker_abstract.py:294` — `LLMWorkerAbstract._end_otel_span_with_error` — `def _end_otel_span_with_error(self, span: Span | None, *, llm_job: LLMJob, error: BaseException) -> None`
+- `pipelex/cogt/llm/llm_worker_abstract.py:398` — `LLMWorkerAbstract.gen_object` — `async def gen_object(self, llm_job: LLMJob, *, schema: type[BaseModelTypeVar]) -> BaseModelTypeVar`
+- `pipelex/cogt/llm/llm_worker_abstract.py:436` — `LLMWorkerAbstract._gen_object` — `async def _gen_object(self, llm_job: LLMJob, *, schema: type[BaseModelTypeVar]) -> BaseModelTypeVar`
+- `pipelex/cogt/llm/llm_worker_factory.py:13` — `LLMWorkerFactory.make_llm_worker` — `def make_llm_worker(inference_model: InferenceModelSpec, *, reporting_delegate: ReportingProtocol | None=None) -> LLMWorkerInternalAbstract`
+- `pipelex/cogt/llm/reasoning_config_base.py:9` — `validate_effort_to_level_map` — `def validate_effort_to_level_map(effort_to_level_map: EffortToLevelMap, *, config_name: str, level_type: type[StrEnum] | None=None) -> EffortToLevelMap`
+- `pipelex/cogt/llm/reasoning_config_base.py:40` — `get_reasoning_level_str` — `def get_reasoning_level_str(effort_to_level_map: EffortToLevelMap, *, effort: ReasoningEffort) -> str | None`
+- `pipelex/cogt/model_backends/backend_credentials.py:26` — `BackendCredentialsErrorMsgFactory.make_one_variable_missing_error_msg` — `def make_one_variable_missing_error_msg(cls, secrets_provider: SecretsProviderAbstract, *, backend_name: str | None, var_name: str) -> str`
+- `pipelex/cogt/model_backends/backend_credentials.py:78` — `BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg` — `def make_comprehensive_error_msg(cls, backend_credential_reports: dict[str, BackendCredentialsReport], *, secrets_provider: SecretsProviderAbstract | None=None) -> str`
+- `pipelex/cogt/model_backends/backend_factory.py:39` — `InferenceBackendFactory.make_inference_backend` — `def make_inference_backend(cls, name: str, *, blueprint: InferenceBackendBlueprint, extra_config: dict[str, Any], model_specs: dict[str, InferenceModelSpec]) -> InferenceBackend`
+- `pipelex/cogt/model_backends/backend_library.py:58` — `InferenceBackendLibrary.load` — `def load(self, secrets_provider: SecretsProviderAbstract, *, backends_library_path: str, backends_dir_path: str, include_disabled: bool=False, gateway_config: GatewayConfig | None=None, lenient: bool=False)`
+- `pipelex/cogt/model_backends/backend_library.py:228` — `InferenceBackendLibrary._load_gateway_model_specs` — `def _load_gateway_model_specs(self, gateway_config: GatewayConfig, *, backends_dir_path: str, substitute_vars_with_provider: Any) -> tuple[BackendModelSpecs, str]`
+- `pipelex/cogt/model_backends/backend_library.py:267` — `InferenceBackendLibrary._load_local_model_specs` — `def _load_local_model_specs(self, backend_name: str, *, backends_dir_path: str, substitute_vars_with_provider: Any) -> tuple[BackendModelSpecs, str]`
+- `pipelex/cogt/model_backends/backend_library.py:300` — `InferenceBackendLibrary.check_backend_credentials` — `def check_backend_credentials(self, path: str, *, include_disabled: bool=False) -> CredentialsValidationReport`
+- `pipelex/cogt/model_backends/model_lists.py:17` — `ModelLister.list_models` — `async def list_models(cls, backend_name: str, *, flat: bool=False) -> None`
+- `pipelex/cogt/model_backends/model_lists.py:194` — `ModelLister._display_unsupported_sdks_message` — `def _display_unsupported_sdks_message(any_listed: bool, *, unsupported_sdks: list[str], backend_name: str, models_by_sdk: dict[str, list[str]], flat: bool) -> None`
+- `pipelex/cogt/model_backends/model_spec_factory.py:78` — `InferenceModelSpecFactory.make_inference_model_spec` — `def make_inference_model_spec(cls, backend_name: str, *, name: str, blueprint: InferenceModelSpecBlueprint, backend_listed_constraints: list[ListedConstraint], backend_valued_constraints: dict[ValuedConstraint, Any], extra_headers: dict[str, str] | None=None) -> InferenceModelSpec`
+- `pipelex/cogt/model_routing/routing_profile.py:25` — `RoutingProfile.get_backend_match_for_model` — `def get_backend_match_for_model(self, enabled_backends: list[str], *, model_name: str) -> BackendMatchForModel | None`
+- `pipelex/cogt/model_routing/routing_profile_factory.py:38` — `RoutingProfileFactory.make_routing_profile` — `def make_routing_profile(cls, name: str, *, blueprint: RoutingProfileBlueprint) -> RoutingProfile`
+- `pipelex/cogt/model_routing/routing_profile_loader.py:11` — `load_active_routing_profile` — `def load_active_routing_profile(routing_profile_library_path: str, *, enabled_backends: list[str], lenient: bool=False) -> RoutingProfile`
+- `pipelex/cogt/models/deck_manifest.py:155` — `write_manifest` — `def write_manifest(manifest: DeckManifest, *, deck_dir: Path) -> None`
+- `pipelex/cogt/models/deck_manifest.py:179` — `_is_manifest_older` — `def _is_manifest_older(manifest_version: str, *, current_version: str) -> bool`
+- `pipelex/cogt/models/model_deck.py:135` — `ModelDeck.is_model_handle_defined` — `def is_model_handle_defined(self, model_handle: str, *, model_type: ModelType) -> bool`
+- `pipelex/cogt/models/model_deck.py:219` — `ModelDeck._raise_handle_not_found_error` — `def _raise_handle_not_found_error(self, ref: ModelReference, *, model_type: ModelType, presets: dict[str, LLMSetting] | dict[str, ExtractSetting] | dict[str, ImgGenSetting] | dict[str, SearchSetting]) -> NoReturn`
+- `pipelex/cogt/models/model_deck.py:250` — `ModelDeck.check_llm_choice` — `def check_llm_choice(self, llm_choice: LLMModelChoice, *, is_disabled_allowed: bool=False)`
+- `pipelex/cogt/models/model_deck.py:524` — `ModelDeck._validate_llm_setting` — `def _validate_llm_setting(cls, llm_setting: LLMSetting, *, inference_model: InferenceModelSpec)`
+- `pipelex/cogt/models/model_deck.py:689` — `ModelDeck._is_model_available_in_backend` — `def _is_model_available_in_backend(self, model_handle: str, *, backend_name: str) -> bool | None`
+- `pipelex/cogt/models/model_deck.py:715` — `ModelDeck._resolve_waterfall` — `def _resolve_waterfall(self, waterfall_name: str, *, fallback_list: list[str], model_type: ModelType) -> InferenceModelSpec | None`
+- `pipelex/cogt/models/model_deck.py:774` — `ModelDeck.get_optional_inference_model` — `def get_optional_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec | None`
+- `pipelex/cogt/models/model_deck.py:786` — `ModelDeck._get_optional_inference_model` — `def _get_optional_inference_model(self, model_handle: str, *, model_type: ModelType, _visited: frozenset[str]) -> InferenceModelSpec | None`
+- `pipelex/cogt/models/model_deck.py:862` — `ModelDeck.is_handle_defined` — `def is_handle_defined(self, model_handle: str, *, model_type: ModelType) -> bool`
+- `pipelex/cogt/models/model_deck.py:866` — `ModelDeck.get_required_inference_model` — `def get_required_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec`
+- `pipelex/cogt/models/model_deck_check.py:17` — `_raise_model_choice_not_found` — `def _raise_model_choice_not_found(msg: str, *, model_deck: ModelDeck, model_type: ModelType, raw_choice: str, name: str, reference_kind: ModelReferenceKind, available_options: list[str]) -> NoReturn`
+- `pipelex/cogt/models/model_manager.py:100` — `ModelManager._enforce_gateway_model_membership` — `def _enforce_gateway_model_membership(self, gateway_config: GatewayConfig | None, *, gateway_config_source: RemoteConfigSource | None) -> None`
+- `pipelex/cogt/models/model_manager.py:193` — `ModelManager._resolve_terminal_candidates` — `def _resolve_terminal_candidates(cls, deck: ModelDeck, *, ref: ModelReference, model_type: ModelType) -> list[str]`
+- `pipelex/cogt/models/model_manager.py:226` — `ModelManager._collect_candidates` — `def _collect_candidates(cls, ref: ModelReference, *, aliases: dict[str, str], waterfalls: dict[str, list[str]], is_fallback_enabled: bool, visited: set[tuple[ModelReferenceKind, str]]) -> list[str]`
+- `pipelex/cogt/models/model_manager.py:302` — `ModelManager.build_deck` — `def build_deck(self, model_deck_blueprint: ModelDeckBlueprint, *, enabled_backends: list[str]) -> ModelDeck`
+- `pipelex/cogt/models/model_manager_abstract.py:22` — `ModelManagerAbstract.setup` — `def setup(self, secrets_provider: SecretsProviderAbstract, *, gateway_config: GatewayConfig | None, gateway_config_source: RemoteConfigSource | None, needs_inference: bool=True) -> None`
+- `pipelex/cogt/models/model_manager_abstract.py:33` — `ModelManagerAbstract.get_inference_model` — `def get_inference_model(self, model_handle: str, *, model_type: ModelType) -> InferenceModelSpec`
+- `pipelex/cogt/models/model_suggestion.py:33` — `get_collection_keys` — `def get_collection_keys(model_deck: ModelDeck, *, model_type: ModelType, kind: ModelReferenceKind) -> list[str]`
+- `pipelex/cogt/models/model_suggestion.py:75` — `suggest_model_alternatives` — `def suggest_model_alternatives(model_deck: ModelDeck, *, model_type: ModelType, name: str, kind: ModelReferenceKind) -> tuple[list[str], list[str], list[str]]`
+- `pipelex/cogt/search/search_job_factory.py:8` — `SearchJobFactory.make_search_job` — `def make_search_job(cls, query: str, *, search_setting: SearchSetting, job_metadata: JobMetadata, include_domains: list[str] | None=None, exclude_domains: list[str] | None=None, from_date: str | None=None, to_date: str | None=None) -> SearchJob`
+- `pipelex/cogt/search/search_worker_abstract.py:53` — `SearchWorkerAbstract.search_structured` — `async def search_structured(self, search_job: SearchJob, *, schema: type[BaseModelTypeVar]) -> dict[str, Any]`
+- `pipelex/cogt/search/search_worker_abstract.py:85` — `SearchWorkerAbstract._search_structured` — `async def _search_structured(self, search_job: SearchJob, *, schema: type[BaseModelTypeVar]) -> dict[str, Any]`
+- `pipelex/cogt/templating/template_preprocessor.py:91` — `_validate_at_sigil_alone_on_line` — `def _validate_at_sigil_alone_on_line(template: str, *, declared_inputs: set[str]) -> None`
+- `pipelex/cogt/templating/template_preprocessor.py:145` — `validate_template_sigils` — `def validate_template_sigils(template: str, *, declared_inputs: set[str]) -> None`
+- `pipelex/cogt/templating/template_preprocessor.py:176` — `preprocess_template` — `def preprocess_template(template: str, *, declared_inputs: set[str] | None=None) -> str`
+- `pipelex/cogt/templating/template_rendering.py:10` — `render_template` — `async def render_template(template: str, *, category: TemplateCategory, context: dict[str, Any], templating_style: TemplatingStyle | None=None, finalize: Callable[[Any], Any] | None=None) -> str`
+- `pipelex/cogt/usage/cost_registry.py:64` — `CostRegistry.generate_report` — `def generate_report(cls, pipeline_run_id: str, *, tokens_usages: Sequence[TokensUsage], unit_scale: float, cost_report_file_path: Path | None=None, print_to_console: bool=True)`
+- `pipelex/cogt/usage/cost_registry.py:88` — `CostRegistry.render_report` — `def render_report(cls, aggregated: AggregatedCosts, *, pipeline_run_id: str, unit_scale: float, cost_report_file_path: Path | None=None, print_to_console: bool=True) -> None`
+- `pipelex/cogt/usage/cost_registry.py:195` — `CostRegistry.save_to_csv` — `def save_to_csv(records: list[dict[str, Any]], *, file_path: Path) -> None`
+- `pipelex/cogt/usage/costs_per_token.py:4` — `model_cost_per_token` — `def model_cost_per_token(costs: CostsByCategoryDict, *, cost_category: CostCategory) -> float`
+
+### `core` (95)
+
+- `pipelex/core/bundles/pipelex_bundle_blueprint.py:201` — `PipelexBundleBlueprint._collect_local_refs_from_concept` — `def _collect_local_refs_from_concept(self, concept_code: str, *, concept_blueprint: ConceptBlueprint | str) -> list[tuple[str, str]]`
+- `pipelex/core/bundles/pipelex_bundle_blueprint.py:224` — `PipelexBundleBlueprint._collect_local_refs_from_pipe` — `def _collect_local_refs_from_pipe(self, pipe_code: str, *, pipe_blueprint: PipeBlueprintUnion) -> list[tuple[str, str]]`
+- `pipelex/core/concepts/concept.py:194` — `Concept.render_concept_representation` — `def render_concept_representation(self, output_format: ConceptRepresentationFormat, *, is_multiple: bool=False) -> tuple[dict[str, Any], set[str]]`
+- `pipelex/core/concepts/concept_factory.py:88` — `ConceptFactory.make` — `def make(cls, concept_code: str, *, domain_code: str, description: str, structure_class_name: str, refines: str | None=None) -> Concept`
+- `pipelex/core/concepts/concept_factory.py:187` — `ConceptFactory.make_domain_and_concept_code_from_concept_ref_or_code` — `def make_domain_and_concept_code_from_concept_ref_or_code(cls, concept_ref_or_code: str, *, domain_code: str | None=None) -> DomainAndConceptCode`
+- `pipelex/core/concepts/concept_factory.py:243` — `ConceptFactory.make_refine` — `def make_refine(cls, refine: str, *, domain_code: str) -> str`
+- `pipelex/core/concepts/concept_factory.py:274` — `ConceptFactory._handle_structure_with_classname` — `def _handle_structure_with_classname(cls, blueprint: ConceptBlueprint, *, concept_code: str, domain_code: str) -> str`
+- `pipelex/core/concepts/concept_factory.py:301` — `ConceptFactory._handle_blueprint_with_structure` — `def _handle_blueprint_with_structure(cls, blueprint: ConceptBlueprint, *, concept_code: str, domain_code: str) -> str`
+- `pipelex/core/concepts/concept_factory.py:345` — `ConceptFactory._handle_basic_blueprint` — `def _handle_basic_blueprint(cls, concept_code: str, *, domain_code: str, description: str) -> StructureNameAndRefine`
+- `pipelex/core/concepts/concept_factory.py:386` — `ConceptFactory._handle_refines` — `def _handle_refines(cls, blueprint: ConceptBlueprint, *, concept_code: str, domain_code: str) -> StructureNameAndRefine`
+- `pipelex/core/concepts/concept_representation_generator.py:50` — `ConceptRepresentationGenerator.generate_representation` — `def generate_representation(self, concept_ref: str, *, structure_class: type[StuffContent], include_optional: bool=True) -> dict[str, Any]`
+- `pipelex/core/concepts/concept_representation_generator.py:75` — `ConceptRepresentationGenerator.generate_class_representation` — `def generate_class_representation(self, content_class: type[StuffContent], *, include_optional: bool=True) -> dict[str, Any] | str`
+- `pipelex/core/concepts/concept_representation_generator.py:107` — `ConceptRepresentationGenerator._generate_fields_dict` — `def _generate_fields_dict(self, content_class: type[StuffContent], *, include_optional: bool=True) -> dict[str, Any]`
+- `pipelex/core/concepts/concept_representation_generator.py:135` — `ConceptRepresentationGenerator.generate_field_value` — `def generate_field_value(self, field_type: Any, *, field_name: str) -> Any`
+- `pipelex/core/concepts/concept_representation_generator.py:199` — `ConceptRepresentationGenerator._generate_list_value` — `def _generate_list_value(self, args: tuple[Any, ...], *, field_name: str) -> list[Any]`
+- `pipelex/core/concepts/concept_representation_generator.py:238` — `ConceptRepresentationGenerator._generate_literal_value` — `def _generate_literal_value(self, literal_args: tuple[Any, ...], *, field_name: str) -> Any`
+- `pipelex/core/concepts/concept_representation_generator.py:253` — `ConceptRepresentationGenerator._generate_enum_value` — `def _generate_enum_value(self, enum_type: type[StrEnum], *, field_name: str) -> str`
+- `pipelex/core/concepts/concept_representation_generator.py:293` — `ConceptRepresentationGenerator._generate_basic_value` — `def _generate_basic_value(self, actual_type: Any, *, field_name: str) -> Any`
+- `pipelex/core/concepts/concept_representation_generator.py:329` — `ConceptRepresentationGenerator._format_as_python` — `def _format_as_python(self, class_name: str, *, fields: dict[str, Any]) -> str`
+- `pipelex/core/concepts/concept_representation_generator.py:394` — `generate_json_representation` — `def generate_json_representation(concept_ref: str, *, structure_class: type[StuffContent]) -> dict[str, Any]`
+- `pipelex/core/concepts/concept_representation_generator.py:412` — `generate_python_representation` — `def generate_python_representation(concept_ref: str, *, structure_class: type[StuffContent]) -> tuple[dict[str, Any], set[str]]`
+- `pipelex/core/concepts/concept_structure_blueprint.py:188` — `ConceptStructureBlueprint._raise_type_mismatch_error` — `def _raise_type_mismatch_error(self, expected_type_name: str, *, actual_type_name: str) -> None`
+- `pipelex/core/concepts/helpers.py:13` — `get_structure_class_name_from_blueprint` — `def get_structure_class_name_from_blueprint(blueprint_or_string_description: ConceptBlueprint | str, *, concept_ref_or_code: str) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:144` — `StructureGenerator.validate_generated_code` — `def validate_generated_code(self, python_code: str, *, expected_class_name: str, base_class_name: str | None=None) -> type`
+- `pipelex/core/concepts/structure_generation/generator.py:211` — `StructureGenerator._format_class_docstring` — `def _format_class_docstring(self, docstring: str, *, indent: str=' ') -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:249` — `StructureGenerator._generate_class_source_code_from_blueprint` — `def _generate_class_source_code_from_blueprint(self, class_name: str, *, structure_blueprint: dict[str, ConceptStructureBlueprint], base_class_name: str | None=None, description: str='') -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:311` — `StructureGenerator._generate_field_from_blueprint` — `def _generate_field_from_blueprint(self, field_name: str, *, field_blueprint: ConceptStructureBlueprint) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:480` — `StructureGenerator._generate_field` — `def _generate_field(self, field_name: str, *, field_def: dict[str, Any] | str) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:530` — `StructureGenerator._get_python_type` — `def _get_python_type(self, field_type: Any, *, field_def: dict[str, Any]) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:614` — `StructureGenerator._validate_execution` — `def _validate_execution(self, python_code: str, *, expected_class_name: str, base_class_name: str | None=None) -> type`
+- `pipelex/core/interpreter/bundle_elaborator.py:105` — `BundleElaborator._elaborate_preliminary_text` — `def _elaborate_preliminary_text(cls, pipe_code: str, *, pipe_blueprint: PipeLLMBlueprint, new_pipe_dict: dict[str, PipeBlueprintUnion], elaboration_metadata: dict[str, ElaborationMetadata], existing_codes: set[str]) -> None`
+- `pipelex/core/interpreter/interpreter.py:22` — `PipelexInterpreter.make_pipelex_bundle_blueprint` — `def make_pipelex_bundle_blueprint(cls, bundle_path: Path | None=None, *, mthds_content: str | None=None) -> PipelexBundleBlueprint`
+- `pipelex/core/interpreter/validation_error_categorizer.py:27` — `_categorize_input_validation_error` — `def _categorize_input_validation_error(message: str, *, domain: str | None, source: str | None, pipe_code: str | None) -> PipelexBundleBlueprintValidationErrorData | None`
+- `pipelex/core/interpreter/validation_error_categorizer.py:74` — `_categorize_syntax_validation_error` — `def _categorize_syntax_validation_error(message: str, *, domain: str | None, source: str | None) -> PipelexBundleBlueprintValidationErrorData | None`
+- `pipelex/core/interpreter/validation_error_categorizer.py:127` — `_categorize_concept_validation_error` — `def _categorize_concept_validation_error(loc: tuple[int | str, ...], *, message: str, domain: str | None, source: str | None) -> PipelexBundleBlueprintValidationErrorData | None`
+- `pipelex/core/interpreter/validation_error_categorizer.py:172` — `categorize_blueprint_validation_error` — `def categorize_blueprint_validation_error(error: ErrorDetails, *, blueprint_dict: dict[str, Any]) -> PipelexBundleBlueprintValidationErrorData | None`
+- `pipelex/core/memory/working_memory.py:146` — `WorkingMemory.set_new_main_stuff` — `def set_new_main_stuff(self, stuff: Stuff, *, name: str | None=None)`
+- `pipelex/core/memory/working_memory.py:157` — `WorkingMemory.set_alias` — `def set_alias(self, alias: str, *, target: str) -> None`
+- `pipelex/core/memory/working_memory.py:167` — `WorkingMemory.add_alias` — `def add_alias(self, alias: str, *, target: str) -> None`
+- `pipelex/core/memory/working_memory.py:329` — `WorkingMemory._get_typed_items_from_list_content` — `def _get_typed_items_from_list_content(self, list_content: ListContent[Any], *, wanted_type: type[Any] | None) -> list[Any] | None`
+- `pipelex/core/memory/working_memory.py:370` — `WorkingMemory.get_stuff_as` — `def get_stuff_as(self, name: str, *, content_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/memory/working_memory.py:374` — `WorkingMemory.get_stuff_as_list` — `def get_stuff_as_list(self, name: str, *, item_type: type[StuffContentType]) -> ListContent[StuffContentType]`
+- `pipelex/core/memory/working_memory.py:380` — `WorkingMemory.get_list_stuff_first_item_as` — `def get_list_stuff_first_item_as(self, name: str, *, item_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/memory/working_memory_factory.py:39` — `WorkingMemoryFactory.make_from_multiple_stuffs` — `def make_from_multiple_stuffs(cls, stuff_list: list[Stuff], *, main_name: str | None=None, is_ignore_unnamed: bool=False) -> WorkingMemory`
+- `pipelex/core/memory/working_memory_factory.py:68` — `WorkingMemoryFactory.make_from_pipeline_inputs` — `def make_from_pipeline_inputs(cls, pipeline_inputs: PipelineInputs, *, search_domain_codes: list[str] | None=None) -> WorkingMemory`
+- `pipelex/core/memory/working_memory_factory.py:150` — `WorkingMemoryFactory.convert_stuff_spec_to_typed_named` — `def convert_stuff_spec_to_typed_named(cls, stuff_spec: StuffSpec, *, name: str) -> TypedNamedStuffSpec`
+- `pipelex/core/pipes/handle_pipe_errors.py:119` — `_handle_pipe_errors` — `def _handle_pipe_errors(error: ErrorDetails, *, pipe_code: str | None) -> PipesAndConceptValidationErrorData`
+- `pipelex/core/pipes/inputs/input_renderer.py:5` — `render_inputs` — `def render_inputs(the_pipe: PipeAbstract, *, indent: int=2) -> str`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:26` — `TypedNamedStuffSpec.make_from_named` — `def make_from_named(cls, named: NamedStuffSpec, *, structure_class: type[StuffContent]) -> 'TypedNamedStuffSpec'`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:84` — `InputStuffSpecs.add_stuff_spec` — `def add_stuff_spec(self, variable_name: str, *, concept: Concept, multiplicity: VariableMultiplicity | None=None)`
+- `pipelex/core/pipes/output/output_renderer.py:16` — `_collect_possible_outputs` — `def _collect_possible_outputs(the_pipe: PipeAbstract, *, output_format: ConceptRepresentationFormat=ConceptRepresentationFormat.JSON) -> list[dict[str, Any]]`
+- `pipelex/core/pipes/output/output_renderer.py:119` — `render_output` — `def render_output(the_pipe: PipeAbstract, *, indent: int=2, output_format: ConceptRepresentationFormat=ConceptRepresentationFormat.JSON) -> str`
+- `pipelex/core/pipes/output/output_renderer.py:154` — `_render_json_output` — `def _render_json_output(the_pipe: PipeAbstract, *, indent: int=2) -> str`
+- `pipelex/core/pipes/output/output_renderer.py:240` — `_render_schema_output` — `def _render_schema_output(the_pipe: PipeAbstract, *, indent: int=2) -> str`
+- `pipelex/core/pipes/pipe_abstract.py:103` — `PipeAbstract._register_execution_data` — `def _register_execution_data(self, job_metadata: JobMetadata, *, execution_data: dict[str, Any]) -> None`
+- `pipelex/core/pipes/pipe_abstract.py:316` — `PipeAbstract.validate_before_run` — `async def validate_before_run(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None)`
+- `pipelex/core/pipes/pipe_abstract.py:369` — `PipeAbstract._validate_before_run` — `async def _validate_before_run(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None)`
+- `pipelex/core/pipes/pipe_abstract.py:380` — `PipeAbstract.validate_after_run` — `async def validate_after_run(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None)`
+- `pipelex/core/pipes/pipe_abstract.py:393` — `PipeAbstract._validate_after_run` — `async def _validate_after_run(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None)`
+- `pipelex/core/pipes/pipe_abstract.py:441` — `PipeAbstract.run_pipe` — `async def run_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/core/pipes/pipe_abstract.py:467` — `PipeAbstract._run_pipe_traced` — `async def _run_pipe_traced(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/core/pipes/pipe_abstract.py:630` — `PipeAbstract.live_run_pipe` — `async def live_run_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/core/pipes/pipe_abstract.py:703` — `PipeAbstract.dry_run_pipe` — `async def dry_run_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/core/pipes/pipe_abstract.py:723` — `PipeAbstract._live_run_pipe` — `async def _live_run_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/core/pipes/pipe_abstract.py:735` — `PipeAbstract._dry_run_pipe` — `async def _dry_run_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/core/pipes/pipe_abstract.py:746` — `PipeAbstract._start_pipe_span` — `def _start_pipe_span(self, parent_otel_context: OtelContext, *, pipeline_run_id: str, working_memory: WorkingMemory) -> tuple[Span | None, bool]`
+- `pipelex/core/pipes/pipe_abstract.py:862` — `PipeAbstract._end_pipe_span_success` — `def _end_pipe_span_success(self, span: Span | None, *, pipe_output: PipeOutput, is_root_span: bool) -> None`
+- `pipelex/core/pipes/pipe_abstract.py:896` — `PipeAbstract._end_pipe_span_error` — `def _end_pipe_span_error(self, span: Span | None, *, error: Exception, is_root_span: bool=False) -> None`
+- `pipelex/core/pipes/pipe_factory.py:27` — `PipeFactoryProtocol.make` — `def make(cls, pipe_category: Any, *, pipe_type: str, pipe_code: str, domain_code: str, description: str, inputs: InputStuffSpecs, output: StuffSpec, blueprint: PipeBlueprintType) -> PipeAbstractType`
+- `pipelex/core/pipes/validation.py:4` — `is_variable_satisfied_by_inputs` — `def is_variable_satisfied_by_inputs(variable_path: str, *, input_names: set[str]) -> bool`
+- `pipelex/core/pipes/validation.py:32` — `is_input_used_by_variables` — `def is_input_used_by_variables(input_name: str, *, variable_paths: set[str]) -> bool`
+- `pipelex/core/pipes/variable_multiplicity.py:170` — `format_concept_with_multiplicity` — `def format_concept_with_multiplicity(concept_code_or_string: str, *, multiplicity: VariableMultiplicity | None) -> str`
+- `pipelex/core/qualified_ref.py:136` — `QualifiedRef.from_domain_and_code` — `def from_domain_and_code(cls, domain_path: str, *, local_code: str) -> 'QualifiedRef'`
+- `pipelex/core/stuffs/image_content.py:71` — `ImageContent.render_with_images` — `def render_with_images(self, registry: ImageRegistry, *, text_format: TextFormat) -> str`
+- `pipelex/core/stuffs/image_field_search.py:10` — `search_for_nested_image_fields` — `def search_for_nested_image_fields(content_class: type[StuffContent], *, current_path: str='') -> list[str]`
+- `pipelex/core/stuffs/list_content.py:141` — `ListContent.render_with_images` — `def render_with_images(self, registry: ImageRegistry, *, text_format: TextFormat) -> str`
+- `pipelex/core/stuffs/structured_content.py:121` — `StructuredContent.render_with_images` — `def render_with_images(self, registry: ImageRegistry, *, text_format: TextFormat) -> str`
+- `pipelex/core/stuffs/structured_content.py:150` — `StructuredContent._render_value_with_images` — `def _render_value_with_images(self, value: Any, *, registry: ImageRegistry, text_format: TextFormat) -> str`
+- `pipelex/core/stuffs/stuff.py:100` — `Stuff.verify_content_type` — `def verify_content_type(cls, content: StuffContent, *, content_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/stuffs/stuff_artefact.py:195` — `StuffArtefact.get` — `def get(self, key: str, *, default: Any=None) -> Any`
+- `pipelex/core/stuffs/stuff_artefact.py:350` — `StuffArtefact.render_with_images` — `def render_with_images(self, registry: ImageRegistry, *, text_format: TextFormat) -> str`
+- `pipelex/core/stuffs/stuff_content.py:64` — `StuffContent.rendered_markdown` — `def rendered_markdown(self, level: int=1, *, is_pretty: bool=False) -> str`
+- `pipelex/core/stuffs/stuff_content.py:113` — `StuffContent.rendered_markdown_async` — `async def rendered_markdown_async(self, level: int=1, *, is_pretty: bool=False) -> str`
+- `pipelex/core/stuffs/stuff_content_factory.py:12` — `StuffContentFactory.make_content_from_value` — `def make_content_from_value(cls, stuff_content_subclass: type[StuffContent], *, value: dict[str, Any] | str) -> StuffContent`
+- `pipelex/core/stuffs/stuff_content_factory.py:18` — `StuffContentFactory.make_stuff_content_from_concept_required` — `def make_stuff_content_from_concept_required(cls, concept: Concept, *, value: dict[str, Any] | str) -> StuffContent`
+- `pipelex/core/stuffs/stuff_content_factory.py:27` — `StuffContentFactory.make_stuff_content_from_concept_with_fallback` — `def make_stuff_content_from_concept_with_fallback(cls, concept: Concept, *, value: dict[str, Any] | str) -> StuffContent`
+- `pipelex/core/stuffs/stuff_factory.py:51` — `StuffFactory.make_from_str` — `def make_from_str(cls, str_value: str, *, name: str) -> Stuff`
+- `pipelex/core/stuffs/stuff_factory.py:59` — `StuffFactory.make_from_concept_ref` — `def make_from_concept_ref(cls, concept_ref: str, *, name: str, content: StuffContent) -> Stuff`
+- `pipelex/core/stuffs/stuff_factory.py:69` — `StuffFactory.make_stuff` — `def make_stuff(cls, concept: Concept, *, content: StuffContent, name: str | None=None, code: str | None=None) -> Stuff`
+- `pipelex/core/stuffs/stuff_factory.py:115` — `StuffFactory.combine_stuffs` — `def combine_stuffs(cls, stuff_contents: dict[str, StuffContent], *, concept: Concept, name: str | None=None) -> Stuff`
+- `pipelex/core/stuffs/stuff_factory.py:136` — `StuffFactory._try_make_csv_list_stuff` — `def _try_make_csv_list_stuff(cls, concept: Concept, *, content: dict[str, Any], name: str | None, code: str | None) -> Stuff | None`
+- `pipelex/core/stuffs/stuff_factory.py:227` — `StuffFactory.make_stuff_from_stuff_content_or_data` — `def make_stuff_from_stuff_content_or_data(cls, stuff_content_or_data: StuffContentOrData, *, name: str | None=None, code: str | None=None, search_domain_codes: list[str] | None=None) -> Stuff`
+- `pipelex/core/stuffs/stuff_viewer.py:21` — `render_stuff_viewer` — `async def render_stuff_viewer(stuff: Stuff, *, title: str | None=None, subtitle: str | None=None) -> str`
+- `pipelex/core/stuffs/stuff_viewer.py:72` — `render_stuff_content_viewer` — `async def render_stuff_content_viewer(stuff_data: str | dict[str, Any] | list[str] | list[dict[str, Any]], *, stuff_data_text: str, stuff_data_html: str, content_type: str | None=None, title: str='Stuff Content', subtitle: str | None=None) -> str`
+- `pipelex/core/stuffs/text_and_images_content.py:76` — `TextAndImagesContent.render_with_images` — `def render_with_images(self, registry: ImageRegistry, *, text_format: TextFormat) -> str`
+
+### `errors` (5)
+
+- `pipelex/errors/error_pages_generator.py:253` — `generate_error_pages` — `def generate_error_pages(output_dir: Path, *, classes: Iterable[type[PipelexError]] | None=None) -> ErrorPagesReport`
+- `pipelex/errors/error_pages_generator.py:333` — `_remove_orphans` — `def _remove_orphans(output_dir: Path, *, expected_stems: set[str], report: ErrorPagesReport) -> None`
+- `pipelex/errors/error_pages_generator.py:355` — `_commit_page` — `def _commit_page(target: Path, *, new_content: str, report: ErrorPagesReport) -> None`
+- `pipelex/errors/error_pages_generator.py:448` — `_subsystems_for_macro` — `def _subsystems_for_macro(macro_slug: str, *, by_subsystem: dict[str, list[type[PipelexError]]]) -> list[tuple[str, list[type[PipelexError]]]]`
+- `pipelex/errors/error_pages_generator.py:473` — `render_macro_page` — `def render_macro_page(macro_heading: str, *, sections: list[tuple[str, list[type[PipelexError]]]]) -> str`
+
+### `graph` (40)
+
+- `pipelex/graph/graph_factory.py:45` — `generate_graph_outputs` — `async def generate_graph_outputs(graph_spec: GraphSpec, *, graph_config: GraphConfig, pipe_code: str='', title: str | None=None, direction: FlowchartDirection | None=None, include_subgraphs: bool=True) -> GraphOutputs`
+- `pipelex/graph/graph_factory.py:135` — `save_graph_outputs_to_dir` — `def save_graph_outputs_to_dir(graph_outputs: GraphOutputs, *, output_dir: Path) -> dict[str, Path]`
+- `pipelex/graph/graph_rendering.py:40` — `render_graph_from_spec` — `async def render_graph_from_spec(graph_spec: GraphSpec, *, graph_config: GraphConfig, include_mermaidflow: bool, include_reactflow: bool, output_dir: Path, pipe_code: str='', title: str | None=None, direction: FlowchartDirection | None=None, include_subgraphs: bool=True) -> dict[str, Path]`
+- `pipelex/graph/graph_rendering.py:103` — `_dry_run_bundle` — `async def _dry_run_bundle(bundle_path: Path, *, library_dirs: list[str] | None=None) -> tuple[GraphSpec, str]`
+- `pipelex/graph/graph_rendering.py:140` — `generate_graph_for_bundle` — `async def generate_graph_for_bundle(bundle_path: Path, *, graph_format: GraphFormat, library_dirs: list[str] | None=None, direction: FlowchartDirection | None=None, graph_name: str='dry_run.html') -> dict[str, Any]`
+- `pipelex/graph/graph_rendering.py:215` — `generate_view_for_bundle` — `async def generate_view_for_bundle(bundle_path: Path, *, library_dirs: list[str] | None=None, direction: FlowchartDirection | None=None) -> dict[str, Any]`
+- `pipelex/graph/graph_tracer.py:907` — `GraphTracer.add_selected_outcome_edge` — `def add_selected_outcome_edge(self, condition_node_id: str, *, outcome_node_id: str, outcome_value: str) -> None`
+- `pipelex/graph/graph_tracer_manager.py:94` — `GraphTracerManager.open_tracer` — `def open_tracer(self, graph_id: str, *, data_inclusion: DataInclusionConfig, pipeline_ref_domain: str | None=None, pipeline_ref_main_pipe: str | None=None, event_log: 'EventLogProtocol | None'=None, workflow_id: str='direct', pipeline_run_id: str | None=None, tracer_key: str | None=None, emit_graph_events: bool=True, emit_usage_events: bool=True) -> TraceContext`
+- `pipelex/graph/graph_tracer_manager.py:218` — `GraphTracerManager.on_pipe_start` — `def on_pipe_start(self, trace_context: TraceContext, *, pipe_code: str, pipe_type: str, node_kind: NodeKind, started_at: datetime, input_specs: list[IOSpec] | None=None, pipe_data: dict[str, Any] | None=None, concept_data: list[dict[str, Any]] | None=None, description: str | None=None, domain_code: str | None=None) -> tuple[str | None, TraceContext | None]`
+- `pipelex/graph/graph_tracer_manager.py:266` — `GraphTracerManager.on_pipe_end_success` — `def on_pipe_end_success(self, lookup_key: str, *, node_id: str | None, ended_at: datetime, output_preview: str | None=None, metrics: dict[str, float] | None=None, output_spec: IOSpec | None=None, output_concept_data: dict[str, Any] | None=None) -> None`
+- `pipelex/graph/graph_tracer_manager.py:304` — `GraphTracerManager.register_execution_data` — `def register_execution_data(self, lookup_key: str, *, node_id: str | None, execution_data: dict[str, Any]) -> None`
+- `pipelex/graph/graph_tracer_manager.py:325` — `GraphTracerManager.on_pipe_end_error` — `def on_pipe_end_error(self, lookup_key: str, *, node_id: str | None, ended_at: datetime, error_type: str, error_message: str, error_stack: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_manager.py:360` — `GraphTracerManager.add_edge` — `def add_edge(self, lookup_key: str, *, source_node_id: str, target_node_id: str, edge_kind: EdgeKind, label: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_manager.py:389` — `GraphTracerManager.register_controller_output` — `def register_controller_output(self, lookup_key: str, *, node_id: str, output_spec: IOSpec) -> None`
+- `pipelex/graph/graph_tracer_manager.py:411` — `GraphTracerManager.register_batch_item_extraction` — `def register_batch_item_extraction(self, lookup_key: str, *, list_stuff_code: str, item_stuff_code: str, item_index: int, batch_controller_node_id: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_manager.py:440` — `GraphTracerManager.register_batch_aggregation` — `def register_batch_aggregation(self, lookup_key: str, *, output_list_stuff_code: str, item_stuff_code: str, item_index: int, batch_controller_node_id: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_manager.py:469` — `GraphTracerManager.register_parallel_combine` — `def register_parallel_combine(self, lookup_key: str, *, combined_stuff_code: str, branch_stuff_codes: list[str], parallel_controller_node_id: str) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:19` — `GraphTracerProtocol.setup` — `def setup(self, graph_id: str, *, data_inclusion: DataInclusionConfig, pipeline_ref_domain: str | None=None, pipeline_ref_main_pipe: str | None=None, event_log: 'EventLogProtocol | None'=None, workflow_id: str='direct', pipeline_run_id: str | None=None, emit_graph_events: bool=True, emit_usage_events: bool=True) -> TraceContext`
+- `pipelex/graph/graph_tracer_protocol.py:60` — `GraphTracerProtocol.on_pipe_start` — `def on_pipe_start(self, trace_context: TraceContext, *, pipe_code: str, pipe_type: str, node_kind: NodeKind, started_at: datetime, input_specs: list[IOSpec] | None=None, pipe_data: dict[str, Any] | None=None, concept_data: list[dict[str, Any]] | None=None, description: str | None=None, domain_code: str | None=None) -> tuple[str, TraceContext]`
+- `pipelex/graph/graph_tracer_protocol.py:93` — `GraphTracerProtocol.on_pipe_end_success` — `def on_pipe_end_success(self, node_id: str, *, ended_at: datetime, output_preview: str | None=None, metrics: dict[str, float] | None=None, output_spec: IOSpec | None=None, output_concept_data: dict[str, Any] | None=None) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:115` — `GraphTracerProtocol.on_pipe_end_error` — `def on_pipe_end_error(self, node_id: str, *, ended_at: datetime, error_type: str, error_message: str, error_stack: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:157` — `GraphTracerProtocol.register_controller_output` — `def register_controller_output(self, node_id: str, *, output_spec: IOSpec) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:174` — `GraphTracerProtocol.register_batch_item_extraction` — `def register_batch_item_extraction(self, list_stuff_code: str, *, item_stuff_code: str, item_index: int, batch_controller_node_id: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:193` — `GraphTracerProtocol.register_batch_aggregation` — `def register_batch_aggregation(self, output_list_stuff_code: str, *, item_stuff_code: str, item_index: int, batch_controller_node_id: str | None=None) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:213` — `GraphTracerProtocol.register_parallel_combine` — `def register_parallel_combine(self, combined_stuff_code: str, *, branch_stuff_codes: list[str], parallel_controller_node_id: str) -> None`
+- `pipelex/graph/graph_tracer_protocol.py:232` — `GraphTracerProtocol.register_execution_data` — `def register_execution_data(self, node_id: str, *, execution_data: dict[str, Any]) -> None`
+- `pipelex/graph/graphspec.py:128` — `_truncate_string` — `def _truncate_string(value: str | None, *, max_length: int) -> str | None`
+- `pipelex/graph/mermaidflow/mermaid_html.py:21` — `render_mermaid_html` — `def render_mermaid_html(mermaid_code: str, *, title: str='Pipelex Graph', theme: str='dark') -> str`
+- `pipelex/graph/mermaidflow/mermaid_html.py:54` — `render_mermaid_html_async` — `async def render_mermaid_html_async(mermaid_code: str, *, title: str='Pipelex Graph', theme: str='dark') -> str`
+- `pipelex/graph/mermaidflow/mermaid_html.py:86` — `render_mermaid_html_with_data_async` — `async def render_mermaid_html_with_data_async(mermaid_code: str, *, stuff_data: dict[str, str | dict[str, object] | list[str] | list[dict[str, object]] | None] | None=None, stuff_data_text: dict[str, str] | None=None, stuff_data_html: dict[str, str] | None=None, stuff_metadata: dict[str, dict[str, str]] | None=None, stuff_content_type: dict[str, str] | None=None, title: str='Pipelex Graph', theme: str='dark') -> str`
+- `pipelex/graph/mermaidflow/mermaidflow_factory.py:53` — `MermaidflowFactory.make_from_graphspec` — `def make_from_graphspec(cls, graph: GraphSpec, *, graph_config: GraphConfig, direction: FlowchartDirection | None=None, show_stuff_codes: bool=False, include_subgraphs: bool=True) -> Mermaidflow`
+- `pipelex/graph/mermaidflow/mermaidflow_factory.py:349` — `MermaidflowFactory._render_node` — `def _render_node(cls, node: NodeSpec, *, mermaid_id: str, indent: str=' ') -> str`
+- `pipelex/graph/mermaidflow/mermaidflow_factory.py:389` — `MermaidflowFactory._render_stuff_node` — `def _render_stuff_node(cls, digest: str, *, name: str, concept: str | None, stuff_id_mapping: dict[str, str], show_stuff_codes: bool, indent: str=' ') -> str`
+- `pipelex/graph/mermaidflow/mermaidflow_factory.py:427` — `MermaidflowFactory._render_dashed_edges` — `def _render_dashed_edges(cls, edges: list[EdgeSpec], *, lines: list[str], stuff_id_mapping: dict[str, str], all_stuff_info: dict[str, tuple[str, str | None]], show_stuff_codes: bool) -> None`
+- `pipelex/graph/mermaidflow/mermaidflow_factory.py:487` — `MermaidflowFactory._render_subgraph_recursive` — `def _render_subgraph_recursive(cls, node_id: str, *, nodes_by_id: dict[str, NodeSpec], id_mapping: dict[str, str], children_map: dict[str, list[str]], stuff_registry: dict[str, tuple[str, str | None]], stuff_producers: dict[str, str], stuff_consumers: dict[str, list[str]], stuff_id_mapping: dict[str, str], subgraph_depths: dict[str, int], show_stuff_codes: bool, rendered_orphan_stuffs: set[str], controller_output_stuffs: dict[str, dict[str, tuple[str, str | None]]], indent_level: int=1, depth: int=0) -> list[str]`
+- `pipelex/graph/mermaidflow/stuff_collector.py:18` — `_collect_stuff_field` — `def _collect_stuff_field(graph: GraphSpec, *, extractor: Callable[[IOSpec], T | None]) -> dict[str, T]`
+- `pipelex/graph/reactflow/reactflow_html.py:34` — `_build_templating_context` — `def _build_templating_context(graphspec: GraphSpec, *, config: ReactFlowRenderingConfig, title: str | None) -> dict[str, object]`
+- `pipelex/graph/reactflow/reactflow_html.py:51` — `generate_reactflow_html` — `def generate_reactflow_html(graphspec: GraphSpec, *, config: ReactFlowRenderingConfig, title: str | None=None) -> str`
+- `pipelex/graph/reactflow/reactflow_html.py:75` — `generate_reactflow_html_async` — `async def generate_reactflow_html_async(graphspec: GraphSpec, *, config: ReactFlowRenderingConfig, title: str | None=None) -> str`
+- `pipelex/graph/trace_context.py:66` — `TraceContext.copy_for_child` — `def copy_for_child(self, child_node_id: str, *, next_sequence: int) -> 'TraceContext'`
+
+### `hub.py` (1)
+
+- `pipelex/hub.py:121` — `PipelexHub.setup_config` — `def setup_config(self, config_cls: type[ConfigRoot], *, config_overrides: dict[str, Any] | None=None, config_dir: Path | None=None)`
+
+### `kit` (8)
+
+- `pipelex/kit/cursor_rules.py:34` — `_front_matter_for` — `def _front_matter_for(name: str, *, kit_index: KitIndex) -> dict[str, Any]`
+- `pipelex/kit/cursor_rules.py:77` — `update_cursor_rules` — `def update_cursor_rules(repo_root: Path, *, kit_index: KitIndex, agent_set: str) -> None`
+- `pipelex/kit/cursor_rules.py:113` — `remove_cursor_rules` — `def remove_cursor_rules(repo_root: Path, *, kit_index: KitIndex | None=None) -> None`
+- `pipelex/kit/single_file_agent_rules.py:12` — `_read_agent_file` — `def _read_agent_file(agents_dir: Traversable, *, name: str) -> str`
+- `pipelex/kit/single_file_agent_rules.py:25` — `_demote_headings` — `def _demote_headings(md_content: str, *, levels: int) -> str`
+- `pipelex/kit/single_file_agent_rules.py:49` — `build_merged_rules` — `def build_merged_rules(kit_index: KitIndex, *, agent_set: str | None=None, file_list: list[str] | None=None) -> str`
+- `pipelex/kit/single_file_agent_rules.py:107` — `update_single_file_agent_rules` — `def update_single_file_agent_rules(repo_root: Path, *, kit_index: KitIndex, agent_set: str, targets: dict[str, Target]) -> None`
+- `pipelex/kit/single_file_agent_rules.py:145` — `remove_from_targets` — `def remove_from_targets(repo_root: Path, *, targets: dict[str, Target]) -> None`
+
+### `language` (5)
+
+- `pipelex/language/mthds_factory.py:52` — `MthdsFactory.convert_dicts_to_inline_tables` — `def convert_dicts_to_inline_tables(cls, value: Any, *, field_ordering: list[str] | None=None) -> Any`
+- `pipelex/language/mthds_factory.py:91` — `MthdsFactory.convert_mapping_to_table` — `def convert_mapping_to_table(cls, mapping: Mapping[str, Any], *, field_ordering: list[str] | None=None) -> Any`
+- `pipelex/language/mthds_schema_generator.py:89` — `_remove_from_required` — `def _remove_from_required(schema_obj: dict[str, Any], *, field_names: set[str]) -> None`
+- `pipelex/language/mthds_schema_generator.py:310` — `_walk_schema` — `def _walk_schema(node: dict[str, Any] | list[Any] | Any, *, visitor: Callable[[dict[str, Any]], None]) -> None`
+- `pipelex/language/toml_string_utils.py:14` — `format_toml_string` — `def format_toml_string(text: str, *, force_multiline: bool=False, length_limit_to_multiline: int=100, ensure_trailing_newline: bool=True, ensure_leading_blank_line: bool=True, prefer_literal: bool=False) -> Any`
+
+### `libraries` (28)
+
+- `pipelex/libraries/concept/concept_library.py:191` — `ConceptLibrary.add_dependency_concept` — `def add_dependency_concept(self, alias: str, *, concept: Concept) -> None`
+- `pipelex/libraries/concept/concept_library_abstract.py:33` — `ConceptLibraryAbstract.is_compatible` — `def is_compatible(self, tested_concept: Concept, *, wanted_concept: Concept, strict: bool=False) -> bool`
+- `pipelex/libraries/concept/concept_library_abstract.py:53` — `ConceptLibraryAbstract.get_required_concept_from_concept_ref_or_code` — `def get_required_concept_from_concept_ref_or_code(self, concept_ref_or_code: str, *, search_domain_codes: list[str] | None=None) -> Concept`
+- `pipelex/libraries/concept_reference_validation.py:8` — `validate_concept_references_in_blueprints` — `def validate_concept_references_in_blueprints(blueprints: list[PipelexBundleBlueprint], *, already_loaded_concept_refs: set[str] | None=None) -> None`
+- `pipelex/libraries/contract_match.py:24` — `_canonical_concept_spec` — `def _canonical_concept_spec(spec: str, *, domain_code: str) -> str`
+- `pipelex/libraries/library_crate.py:39` — `LibraryCrate.compute_fingerprint_from_content` — `def compute_fingerprint_from_content(concepts: dict[str, 'ConceptBlueprint | str'], *, pipes: dict[str, PipeBlueprintUnion]) -> str`
+- `pipelex/libraries/library_crate_factory.py:150` — `LibraryCrateFactory._reconcile_pipe_collision` — `def _reconcile_pipe_collision(cls, pipe_ref: str, *, existing: PipeDeclaration, incoming: PipeDeclaration, domain_code: str) -> PipeDeclaration`
+- `pipelex/libraries/library_crate_factory.py:204` — `LibraryCrateFactory._contract_mismatch_msg` — `def _contract_mismatch_msg(pipe_ref: str, *, existing: PipeDeclaration, incoming: PipeDeclaration) -> str`
+- `pipelex/libraries/library_manager.py:764` — `LibraryManager._load_mthds_files_into_library` — `def _load_mthds_files_into_library(self, library_id: str, *, valid_mthds_paths: list[Path]) -> list[PipeAbstract]`
+- `pipelex/libraries/library_manager.py:839` — `LibraryManager._warn_if_mthds_version_unsatisfied` — `def _warn_if_mthds_version_unsatisfied(self, mthds_version_constraint: str, *, package_address: str) -> None`
+- `pipelex/libraries/library_manager.py:860` — `LibraryManager._check_package_visibility` — `def _check_package_visibility(self, blueprints: list[PipelexBundleBlueprint], *, mthds_paths: list[Path]) -> MethodsManifest | None`
+- `pipelex/libraries/library_manager.py:945` — `LibraryManager._load_dependency_packages` — `def _load_dependency_packages(self, library_id: str, *, manifest: MethodsManifest, package_root: Path) -> None`
+- `pipelex/libraries/library_manager.py:981` — `LibraryManager._load_single_dependency` — `def _load_single_dependency(self, library: Library, *, resolved_dep: ResolvedDependency) -> None`
+- `pipelex/libraries/library_manager.py:1142` — `LibraryManager._load_address_based_dependencies` — `def _load_address_based_dependencies(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> None`
+- `pipelex/libraries/library_manager.py:1193` — `LibraryManager._load_address_based_dependency` — `def _load_address_based_dependency(self, library: 'Library', *, full_address: str, extra_search_dirs: list[Path] | None=None) -> bool`
+- `pipelex/libraries/library_manager.py:1357` — `LibraryManager._detect_concept_cycles.check_for_cycle` — `def check_for_cycle(concept_ref: str, *, visiting: set[str], path: list[str]) -> None`
+- `pipelex/libraries/library_manager_abstract.py:84` — `LibraryManagerAbstract.load_from_crate` — `def load_from_crate(self, library_id: str, *, crate: LibraryCrate) -> list[PipeAbstract]`
+- `pipelex/libraries/library_manager_abstract.py:96` — `LibraryManagerAbstract.load_from_blueprints` — `def load_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list[PipeAbstract]`
+- `pipelex/libraries/library_manager_abstract.py:100` — `LibraryManagerAbstract.load_concepts_only_from_blueprints` — `def load_concepts_only_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> list['Concept']`
+- `pipelex/libraries/library_manager_abstract.py:116` — `LibraryManagerAbstract._remove_from_blueprint` — `def _remove_from_blueprint(self, library_id: str, *, blueprint: PipelexBundleBlueprint) -> None`
+- `pipelex/libraries/library_manager_abstract.py:120` — `LibraryManagerAbstract._remove_from_blueprints` — `def _remove_from_blueprints(self, library_id: str, *, blueprints: list[PipelexBundleBlueprint]) -> None`
+- `pipelex/libraries/library_manager_abstract.py:124` — `LibraryManagerAbstract.load_libraries` — `def load_libraries(self, library_id: str, *, library_dirs: list[Path] | None=None, library_file_paths: list[Path] | None=None) -> list[PipeAbstract]`
+- `pipelex/libraries/library_manager_abstract.py:134` — `LibraryManagerAbstract.load_libraries_concepts_only` — `def load_libraries_concepts_only(self, library_id: str, *, library_dirs: list[Path] | None=None, library_file_paths: list[Path] | None=None) -> list['Concept']`
+- `pipelex/libraries/library_utils.py:24` — `get_pipelex_mthds_files_from_package._find_mthds_in_traversable` — `def _find_mthds_in_traversable(traversable: Traversable, *, collected: list[Path]) -> None`
+- `pipelex/libraries/pipe/pipe_library.py:97` — `PipeLibrary.add_dependency_pipe` — `def add_dependency_pipe(self, alias: str, *, pipe: PipeAbstract) -> None`
+- `pipelex/libraries/pipe/pipe_library.py:137` — `PipeLibrary.pretty_list_pipes._format_concept_code` — `def _format_concept_code(concept_code: str | None, *, current_domain: str) -> str`
+- `pipelex/libraries/visibility_utils.py:35` — `make_visibility_checker` — `def make_visibility_checker(manifest: MethodsManifest | None, *, blueprints: list[PipelexBundleBlueprint]) -> PackageVisibilityChecker`
+- `pipelex/libraries/visibility_utils.py:53` — `check_visibility_for_blueprints` — `def check_visibility_for_blueprints(manifest: MethodsManifest | None, *, blueprints: list[PipelexBundleBlueprint]) -> list[VisibilityError]`
+
+### `observer` (1)
+
+- `pipelex/observer/local_observer.py:22` — `LocalObserver._write_to_jsonl` — `def _write_to_jsonl(self, event_type: str, *, payload: PayloadType) -> None`
+
+### `pipe_controllers` (6)
+
+- `pipelex/pipe_controllers/batch/pipe_batch.py:152` — `PipeBatch._live_run_controller_pipe._run_branch` — `async def _run_branch(item_input_stuff: 'Stuff', *, branch_output_item_code: str) -> PipeOutput`
+- `pipelex/pipe_controllers/parallel/pipe_parallel.py:326` — `PipeParallel._register_branch_outputs_with_graph_tracer` — `def _register_branch_outputs_with_graph_tracer(self, job_metadata: JobMetadata, *, output_stuffs: dict[str, 'Stuff']) -> None`
+- `pipelex/pipe_controllers/parallel/pipe_parallel.py:369` — `PipeParallel._register_parallel_combine_with_graph_tracer` — `def _register_parallel_combine_with_graph_tracer(self, job_metadata: JobMetadata, *, combined_stuff: 'Stuff', branch_stuffs: dict[str, 'Stuff']) -> None`
+- `pipelex/pipe_controllers/pipe_controller.py:71` — `PipeController._live_run_controller_pipe` — `async def _live_run_controller_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/pipe_controllers/pipe_controller.py:83` — `PipeController._dry_run_controller_pipe` — `async def _dry_run_controller_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+- `pipelex/pipe_controllers/sub_pipe.py:34` — `SubPipe.run_pipe` — `async def run_pipe(self, calling_pipe_code: str, *, working_memory: WorkingMemory, job_metadata: JobMetadata, sub_pipe_run_params: PipeRunParams, library_crate: 'LibraryCrate | None'=None) -> PipeOutput`
+
+### `pipe_operators` (40)
+
+- `pipelex/pipe_operators/compose/pipe_compose.py:165` — `PipeCompose._run_template_mode` — `async def _run_template_mode(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None) -> PipeComposeOutput`
+- `pipelex/pipe_operators/compose/pipe_compose.py:224` — `PipeCompose._run_construct_mode` — `async def _run_construct_mode(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None) -> PipeComposeOutput`
+- `pipelex/pipe_operators/compose/pipe_compose.py:318` — `PipeCompose._make_mock_construct_output` — `def _make_mock_construct_output(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, output_name: str | None) -> PipeComposeOutput`
+- `pipelex/pipe_operators/compose/pipe_compose_factory.py:52` — `PipeComposeFactory._make_template_mode` — `def _make_template_mode(cls, pipe_code: str, *, domain_code: str, description: str, inputs: InputStuffSpecs, output: StuffSpec, blueprint: PipeComposeBlueprint) -> PipeCompose`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:119` — `StructuredContentComposer._resolve_field` — `async def _resolve_field(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> Any`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:145` — `StructuredContentComposer._resolve_from_var` — `def _resolve_from_var(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> Any`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:187` — `StructuredContentComposer._convert_list_to_dict_keyed_by` — `def _convert_list_to_dict_keyed_by(self, value: Any, *, key_attr: str) -> dict[str, Any]`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:243` — `StructuredContentComposer._resolve_dotted_path` — `def _resolve_dotted_path(self, path: str, *, expected_type: type[Any] | None) -> Any`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:283` — `StructuredContentComposer._resolve_from_stuff_name` — `def _resolve_from_stuff_name(self, name: str, *, expected_type: type[Any] | None) -> StuffContent | list[dict[str, Any]] | str`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:298` — `StructuredContentComposer._convert_for_target_type` — `def _convert_for_target_type(self, stuff_content: StuffContent, *, expected_type: type[Any] | None) -> StuffContent | list[dict[str, Any]] | str`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:324` — `StructuredContentComposer._convert_text_content` — `def _convert_text_content(self, text_content: TextContent, *, expected_type: Any) -> TextContent | str`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:348` — `StructuredContentComposer._convert_list_content` — `def _convert_list_content(self, list_content: ListContent[StuffContent], *, expected_type: type[Any] | None) -> ListContent[StuffContent] | list[dict[str, Any]]`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:392` — `StructuredContentComposer._expects_type` — `def _expects_type(self, expected_type: type[Any], *, target_type: type) -> bool`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:410` — `StructuredContentComposer._convert_content_for_field` — `def _convert_content_for_field(self, stuff_content: StuffContent, *, expected_type: type[StuffContent]) -> StuffContent`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:501` — `StructuredContentComposer._convert_list_items_as_dicts` — `def _convert_list_items_as_dicts(self, items: list[StuffContent], *, expected_item_type: type[Any] | None) -> list[dict[str, Any]]`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:528` — `StructuredContentComposer._convert_list_items_as_objects` — `def _convert_list_items_as_objects(self, items: list[StuffContent], *, expected_item_type: type[Any] | None) -> list[StuffContent]`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:555` — `StructuredContentComposer._validate_item_compatibility` — `def _validate_item_compatibility(self, item: StuffContent, *, expected_type: type[Any], idx: int) -> None`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:599` — `StructuredContentComposer._convert_single_item_as_object` — `def _convert_single_item_as_object(self, item: StuffContent, *, expected_type: type[Any], idx: int) -> StuffContent`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:662` — `StructuredContentComposer._resolve_nested` — `async def _resolve_nested(self, field_blueprint: ConstructFieldBlueprint, *, field_name: str) -> StuffContent`
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:65` — `ImgGenPromptBlueprint.make_img_gen_prompt` — `async def make_img_gen_prompt(self, context_provider: ContextProviderAbstract, *, extra_params: dict[str, Any] | None=None, max_prompt_images: int | None=None) -> ImgGenPrompt`
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:198` — `ImgGenPromptBlueprint._extract_direct_image` — `def _extract_direct_image(self, image_ref: ImageReference, *, context_provider: ContextProviderAbstract, image_registry: ImageRegistry, image_registry_indices: dict[str, int]) -> None`
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:224` — `ImgGenPromptBlueprint._extract_direct_list_images` — `def _extract_direct_list_images(self, image_ref: ImageReference, *, context_provider: ContextProviderAbstract, image_registry: ImageRegistry, image_registry_indices: dict[str, int]) -> None`
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:269` — `ImgGenPromptBlueprint._render_text` — `async def _render_text(self, context_provider: ContextProviderAbstract, *, template_blueprint: TemplateBlueprint, extra_params: dict[str, Any] | None=None, image_registry: ImageRegistry | None=None) -> str`
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:61` — `LLMPromptBlueprint.make_llm_prompt` — `async def make_llm_prompt(self, output_concept_ref: str, *, context_provider: ContextProviderAbstract, output_structure_prompt: str | None=None, extra_params: dict[str, Any] | None=None) -> LLMPrompt`
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:279` — `LLMPromptBlueprint._extract_direct_image` — `def _extract_direct_image(self, image_ref: ImageReference, *, context_provider: ContextProviderAbstract, image_registry: ImageRegistry, image_registry_indices: dict[str, int]) -> None`
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:305` — `LLMPromptBlueprint._extract_direct_list_images` — `def _extract_direct_list_images(self, image_ref: ImageReference, *, context_provider: ContextProviderAbstract, image_registry: ImageRegistry, image_registry_indices: dict[str, int]) -> None`
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:350` — `LLMPromptBlueprint._unravel_text` — `async def _unravel_text(self, context_provider: ContextProviderAbstract, *, jinja2_blueprint: TemplateBlueprint, extra_params: dict[str, Any] | None=None, image_registry: ImageRegistry | None=None) -> str`
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:382` — `LLMPromptBlueprint._extract_direct_document` — `def _extract_direct_document(self, doc_ref: DocumentReference, *, context_provider: ContextProviderAbstract, prompt_user_documents: dict[str, PromptDocument]) -> None`
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:410` — `LLMPromptBlueprint._extract_direct_list_documents` — `def _extract_direct_list_documents(self, doc_ref: DocumentReference, *, context_provider: ContextProviderAbstract, prompt_user_documents: dict[str, PromptDocument]) -> None`
+- `pipelex/pipe_operators/llm/pipe_llm.py:330` — `PipeLLM._llm_gen_object_stuff_content` — `async def _llm_gen_object_stuff_content(self, job_metadata: JobMetadata, *, pipe_run_params: PipeRunParams, is_multiple_output: bool, fixed_nb_output: int | None, output_class_name: str, llm_setting_for_object: LLMSetting, llm_prompt_for_object: LLMPrompt, content_generator: ContentGeneratorProtocol) -> StuffContent`
+- `pipelex/pipe_operators/llm/pipe_llm.py:386` — `PipeLLM._format_llm_error` — `def _format_llm_error(self, exc: LLMCompletionError, *, settings: list[LLMSetting]) -> str`
+- `pipelex/pipe_operators/llm/template_document_analyzer.py:31` — `TemplateDocumentAnalyzer.analyze_template_for_documents` — `def analyze_template_for_documents(cls, template_source: str, *, input_specs: dict[str, str], domain_code: str) -> list[DocumentReference]`
+- `pipelex/pipe_operators/llm/template_document_analyzer.py:107` — `TemplateDocumentAnalyzer._resolve_concept` — `def _resolve_concept(cls, concept_ref_or_code: str, *, domain_code: str) -> Concept`
+- `pipelex/pipe_operators/llm/template_document_analyzer.py:128` — `TemplateDocumentAnalyzer._resolve_variable_type` — `def _resolve_variable_type(cls, var_path: str, *, root_var: str, root_concept: Concept) -> tuple[bool, bool] | None`
+- `pipelex/pipe_operators/pipe_operator.py:101` — `PipeOperator._live_run_operator_pipe` — `async def _live_run_operator_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None) -> PipeOperatorOutputType`
+- `pipelex/pipe_operators/pipe_operator.py:111` — `PipeOperator._dry_run_operator_pipe` — `async def _dry_run_operator_pipe(self, job_metadata: JobMetadata, *, working_memory: WorkingMemory, pipe_run_params: PipeRunParams, output_name: str | None=None) -> PipeOperatorOutputType`
+- `pipelex/pipe_operators/shared/template_image_analyzer.py:34` — `TemplateImageAnalyzer.analyze_template_for_images` — `def analyze_template_for_images(cls, template_source: str, *, input_specs: dict[str, str], domain_code: str, template_category: TemplateCategory=TemplateCategory.LLM_PROMPT) -> list[ImageReference]`
+- `pipelex/pipe_operators/shared/template_image_analyzer.py:137` — `TemplateImageAnalyzer.validate_unused_inputs` — `def validate_unused_inputs(cls, template_sources: list[str], *, input_specs: dict[str, str], template_category: TemplateCategory=TemplateCategory.LLM_PROMPT) -> None`
+- `pipelex/pipe_operators/shared/template_image_analyzer.py:174` — `TemplateImageAnalyzer._resolve_concept` — `def _resolve_concept(cls, concept_ref_or_code: str, *, domain_code: str) -> Concept`
+- `pipelex/pipe_operators/shared/template_image_analyzer.py:195` — `TemplateImageAnalyzer._resolve_variable_type` — `def _resolve_variable_type(cls, var_path: str, *, root_var: str, root_concept: Concept) -> tuple[bool, bool, bool, list[str] | None] | None`
+
+### `pipe_run` (18)
+
+- `pipelex/pipe_run/delivery_executor.py:40` — `DeliveryExecutor.execute` — `async def execute(self, pipe_output: PipeOutput | None, *, user_id: str, pipeline_run_id: str, delivery_assignment: DeliveryAssignment, status: DeliveryStatus, error_report: ErrorReport | None=None, request_id: str | None=None) -> None`
+- `pipelex/pipe_run/delivery_executor.py:163` — `DeliveryExecutor._generate_main_stuff_files_from_raw` — `def _generate_main_stuff_files_from_raw(cls, raw_main_stuff: dict[str, Any], *, files: dict[str, ResultFile]) -> None`
+- `pipelex/pipe_run/delivery_executor.py:178` — `DeliveryExecutor._generate_main_stuff_files` — `async def _generate_main_stuff_files(self, main_stuff: Stuff, *, files: dict[str, ResultFile]) -> None`
+- `pipelex/pipe_run/delivery_executor.py:185` — `DeliveryExecutor._generate_graph_files` — `async def _generate_graph_files(self, graph_spec: Any, *, files: dict[str, ResultFile]) -> None`
+- `pipelex/pipe_run/delivery_executor.py:201` — `DeliveryExecutor._try_add_rendered_file` — `async def _try_add_rendered_file(cls, files: dict[str, ResultFile], *, filename: str, render: Awaitable[str], content_type: str) -> None`
+- `pipelex/pipe_run/delivery_executor.py:219` — `DeliveryExecutor._add_optional_text_file` — `def _add_optional_text_file(cls, files: dict[str, ResultFile], *, filename: str, text: str | None, content_type: str) -> None`
+- `pipelex/pipe_run/delivery_executor.py:226` — `DeliveryExecutor._store_results` — `async def _store_results(self, pipe_output: PipeOutput, *, user_id: str, pipeline_run_id: str, storage: StorageTarget, request_id: str | None=None) -> str`
+- `pipelex/pipe_run/dry_run_in_process.py:33` — `best_effort_graph_spec` — `async def best_effort_graph_spec(pipe_ref: str | None, *, library_id: str | None, log_context: str) -> GraphSpec | None`
+- `pipelex/pipe_run/dry_run_in_process.py:69` — `dry_run_pipe_in_process` — `async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> GraphSpec`
+- `pipelex/pipe_run/pipe_job_factory.py:13` — `PipeJobFactory.make_pipe_job` — `def make_pipe_job(cls, pipe: PipeAbstract, *, job_metadata: JobMetadata, pipe_run_params: PipeRunParams | None=None, working_memory: WorkingMemory | None=None, output_name: str | None=None, library_crate: LibraryCrate | None=None) -> PipeJob`
+- `pipelex/pipe_run/pipe_router_protocol.py:24` — `PipeRouterProtocol._after_successful_run` — `async def _after_successful_run(self, pipe_job: PipeJob, *, pipe_output: PipeOutput) -> None`
+- `pipelex/pipe_run/pipe_router_protocol.py:37` — `PipeRouterProtocol._after_failing_run` — `async def _after_failing_run(self, pipe_job: PipeJob, *, error: Exception) -> None`
+- `pipelex/pipe_run/pipe_run_params.py:28` — `output_multiplicity_to_apply` — `def output_multiplicity_to_apply(base_multiplicity: VariableMultiplicity | None, *, override_multiplicity: VariableMultiplicity | None) -> VariableMultiplicityResolution`
+- `pipelex/pipe_run/pipe_run_params.py:121` — `BatchParams.make_batch_params` — `def make_batch_params(cls, input_list_name: str, *, input_item_name: str) -> BatchParams`
+- `pipelex/pipe_run/pipe_run_params.py:206` — `PipeRunParams.copy_by_injecting_multiplicity` — `def copy_by_injecting_multiplicity(cls, pipe_run_params: Self, *, applied_output_multiplicity: VariableMultiplicity | None) -> Self`
+- `pipelex/pipe_run/pipe_run_protocol.py:20` — `PipeRunProtocol.run` — `async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None=None) -> PipeOutput`
+- `pipelex/pipe_run/tracing_assembly.py:51` — `assemble_tracing` — `def assemble_tracing(pipeline_run_id: str, *, assemble_graph: bool, assemble_usage: bool, domain_code: str | None=None, main_pipe_code: str | None=None) -> TracingAssembly`
+- `pipelex/pipe_run/tracing_assembly.py:142` — `assemble_tracing_on_output` — `def assemble_tracing_on_output(pipe_output: PipeOutput, *, pipeline_run_id: str, assemble_graph: bool, assemble_usage: bool, domain_code: str | None=None, main_pipe_code: str | None=None) -> None`
+
+### `pipe_signature` (2)
+
+- `pipelex/pipe_signature/signature_walk.py:14` — `collect_signature_refs` — `def collect_signature_refs(pipe: PipeAbstract, *, visited: set[str] | None=None) -> set[str]`
+- `pipelex/pipe_signature/signature_walk.py:40` — `collect_signature_paths` — `def collect_signature_paths(pipe: PipeAbstract, *, current_path: list[str] | None=None, paths: dict[str, list[str]] | None=None) -> dict[str, list[str]]`
+
+### `pipelex.py` (3)
+
+- `pipelex/pipelex.py:145` — `Pipelex._get_validation_error_msg` — `def _get_validation_error_msg(component_name: str, *, validation_exc: Exception) -> str`
+- `pipelex/pipelex.py:165` — `Pipelex.setup` — `def setup(self, integration_mode: IntegrationMode, *, needs_inference: bool=True, temporal_enabled: bool | None=None, needs_model_specs: bool | None=None, class_registry: ClassRegistryAbstract | None=None, secrets_provider: SecretsProviderAbstract | None=None, storage_provider: StorageProviderAbstract | None=None, models_manager: ModelManagerAbstract | None=None, inference_manager: InferenceManager | None=None, content_generator: ContentGeneratorProtocol | None=None, pipeline_manager: PipelineManagerAbstract | None=None, pipe_router: PipeRouterProtocol | None=None, reporting_delegate: ReportingProtocol | None=None, telemetry_config: TelemetryConfig | None=None, telemetry_manager: TelemetryManagerAbstract | None=None, observers: dict[str, ObserverProtocol] | None=None, library_manager: LibraryManagerAbstract | None=None, library_dirs: list[str] | list[Path] | None=None, **kwargs: Any)`
+- `pipelex/pipelex.py:512` — `Pipelex.make` — `def make(cls, integration_mode: IntegrationMode=IntegrationMode.PYTHON, *, needs_inference: bool=True, temporal_enabled: bool | None=None, needs_model_specs: bool | None=None, class_registry: ClassRegistryAbstract | None=None, secrets_provider: SecretsProviderAbstract | None=None, storage_provider: StorageProviderAbstract | None=None, models_manager: ModelManagerAbstract | None=None, inference_manager: InferenceManager | None=None, content_generator: ContentGeneratorProtocol | None=None, pipeline_manager: PipelineManager | None=None, pipe_router: PipeRouterProtocol | None=None, reporting_delegate: ReportingProtocol | None=None, telemetry_config: TelemetryConfig | None=None, telemetry_manager: TelemetryManagerAbstract | None=None, observers: dict[str, ObserverProtocol] | None=None, library_dirs: list[str] | list[Path] | None=None, config_overrides: dict[str, Any] | None=None, **kwargs: Any) -> Self`
+
+### `pipeline` (18)
+
+- `pipelex/pipeline/bundle_validator.py:171` — `BundleValidator.validate_pipes` — `async def validate_pipes(self, pipes: list[PipeAbstract], *, library_id: str, allow_signatures: bool=False) -> dict[str, DryRunOutput]`
+- `pipelex/pipeline/dry_run_pipeline.py:26` — `dry_run_pipeline` — `async def dry_run_pipeline(mthds_contents: list[str] | None=None, *, bundle_uris: list[str] | None=None, library_dirs: list[str] | None=None) -> tuple[GraphSpec, str]`
+- `pipelex/pipeline/execution_seams.py:55` — `acquire_library` — `def acquire_library(library_id: str, *, library_dirs: list[str] | None=None, mthds_contents: list[str] | None=None, bundle_uris: list[str] | None=None) -> tuple[str, str | None]`
+- `pipelex/pipeline/execution_seams.py:154` — `prepare_pipe_job` — `async def prepare_pipe_job(pipe: PipeAbstract, *, library_id: str, execution_config: PipelineExecutionConfig, pipe_run_mode: PipeRunMode, pipeline_run_id: str, user_id: str, inputs: PipelineInputs | WorkingMemory | None=None, search_domain_codes: list[str] | None=None, trace_context: 'TraceContext | None'=None, otel_context: OtelContext | None=None, output_name: str | None=None, output_multiplicity: VariableMultiplicity | None=None, dynamic_output_concept_ref: str | None=None, request_id: str | None=None, is_mock_usage: bool=False) -> PipeJob`
+- `pipelex/pipeline/input_normalizer.py:61` — `_normalize_value` — `async def _normalize_value(value: Any, *, storage: StorageProviderAbstract) -> tuple[Any, bool]`
+- `pipelex/pipeline/input_normalizer.py:96` — `_normalize_structured_content` — `async def _normalize_structured_content(structured_content: StructuredContent, *, storage: StorageProviderAbstract) -> tuple[StructuredContent, bool]`
+- `pipelex/pipeline/input_normalizer.py:127` — `_normalize_list_content` — `async def _normalize_list_content(list_content: ListContent[Any], *, storage: StorageProviderAbstract) -> tuple[ListContent[Any], bool]`
+- `pipelex/pipeline/input_normalizer.py:161` — `_normalize_list` — `async def _normalize_list(items: list[Any], *, storage: StorageProviderAbstract) -> tuple[list[Any], bool]`
+- `pipelex/pipeline/input_normalizer.py:187` — `_normalize_url_content` — `async def _normalize_url_content(content: NormalizableContent, *, storage: StorageProviderAbstract) -> NormalizableContent`
+- `pipelex/pipeline/job_metadata.py:89` — `JobMetadata.copy_with_update` — `def copy_with_update(self, otel_context: OtelContext | None, *, trace_context: TraceContext | None=None, **updates: Any) -> 'JobMetadata'`
+- `pipelex/pipeline/pipeline_manager.py:35` — `PipelineManager._set_pipeline` — `def _set_pipeline(self, pipeline_run_id: str, *, pipeline: Pipeline) -> Pipeline`
+- `pipelex/pipeline/pipeline_manager_abstract.py:24` — `PipelineManagerAbstract.add_new_pipeline` — `def add_new_pipeline(self, pipe_code: str | None, *, pipeline_run_id: str | None=None) -> Pipeline`
+- `pipelex/pipeline/pipeline_response.py:36` — `PipelexRunResultExecute.from_pipe_output` — `def from_pipe_output(cls, pipe_output: PipeOutput, *, pipeline_run_id: str='', created_at: str='', state: RunState=RunState.COMPLETED, finished_at: str | None=None) -> PipelexRunResultExecute`
+- `pipelex/pipeline/pipeline_run_setup.py:43` — `pipeline_run_setup` — `async def pipeline_run_setup(execution_config: PipelineExecutionConfig, *, library_id: str | None=None, library_dirs: list[str] | None=None, pipe_code: str | None=None, mthds_contents: list[str] | None=None, bundle_uris: list[str] | None=None, inputs: PipelineInputs | WorkingMemory | None=None, output_name: str | None=None, output_multiplicity: VariableMultiplicity | None=None, dynamic_output_concept_ref: str | None=None, pipe_run_mode: PipeRunMode | None=None, is_mock_usage: bool=False, search_domain_codes: list[str] | None=None, user_id: str | None=None, pipeline_run_id: str | None=None, request_id: str | None=None) -> tuple[PipeJob, str, str]`
+- `pipelex/pipeline/validate_bundle.py:204` — `_pipes_to_dry_run` — `def _pipes_to_dry_run(loaded_pipes: list[PipeAbstract], *, dry_run_pipe_codes: list[str] | None) -> list[PipeAbstract]`
+- `pipelex/pipeline/validate_bundle.py:230` — `validate_bundle` — `async def validate_bundle(mthds_file_path: Path | None=None, *, mthds_contents: list[str] | None=None, library_dirs: Sequence[Path] | None=None, allow_signatures: bool=False, dry_run_pipe_codes: list[str] | None=None) -> ValidateBundleResult`
+- `pipelex/pipeline/validate_bundle.py:335` — `validate_bundles_from_directory` — `async def validate_bundles_from_directory(directory: Path, *, allow_signatures: bool=False) -> ValidateBundleResult`
+- `pipelex/pipeline/validate_bundle.py:378` — `load_concepts_only` — `def load_concepts_only(mthds_file_path: Path | None=None, *, mthds_contents: list[str] | None=None, library_dirs: Sequence[Path] | None=None) -> LoadConceptsOnlyResult`
+
+### `plugins` (49)
+
+- `pipelex/plugins/anthropic/anthropic_factory.py:38` — `AnthropicFactory.make_anthropic_client` — `def make_anthropic_client(plugin: Plugin, *, backend: InferenceBackend) -> AsyncAnthropic | AsyncAnthropicBedrock`
+- `pipelex/plugins/anthropic/anthropic_factory.py:105` — `AnthropicFactory._make_document_block_param` — `def _make_document_block_param(prepped_document: PreparedFile, *, title: str | None=None) -> DocumentBlockParam`
+- `pipelex/plugins/anthropic/anthropic_factory.py:169` — `AnthropicFactory.openai_typed_user_message` — `def openai_typed_user_message(cls, user_content_txt: str, *, prepped_user_images: list[PreparedFile] | None=None, prepped_user_documents: list[tuple[PreparedFile, str | None]] | None=None) -> 'ChatCompletionMessageParam'`
+- `pipelex/plugins/anthropic/anthropic_factory.py:244` — `AnthropicFactory.make_nb_tokens_by_category_from_nb` — `def make_nb_tokens_by_category_from_nb(nb_input: int, *, nb_output: int) -> NbTokensByCategoryDict`
+- `pipelex/plugins/anthropic/anthropic_list.py:20` — `list_anthropic_models` — `async def list_anthropic_models(sdk: str, *, backend_name: str, backend: InferenceBackend, flat: bool, any_listed: bool) -> None`
+- `pipelex/plugins/anthropic/anthropic_list.py:72` — `_display_anthropic_models_flat` — `def _display_anthropic_models_flat(models: list[ModelInfo], *, sdk: str, backend_name: str, any_listed: bool) -> None`
+- `pipelex/plugins/anthropic/anthropic_list.py:89` — `_display_anthropic_models_table` — `def _display_anthropic_models_table(models: list[ModelInfo], *, sdk: str, backend_name: str) -> None`
+- `pipelex/plugins/anthropic/anthropic_llm_worker.py:115` — `AnthropicLLMWorker._build_thinking_params` — `def _build_thinking_params(self, job_params: LLMJobParams, *, max_tokens: int) -> _ThinkingParams`
+- `pipelex/plugins/anthropic/anthropic_llm_worker.py:145` — `AnthropicLLMWorker._build_thinking_params_for_effort` — `def _build_thinking_params_for_effort(self, thinking_mode: ThinkingMode, *, effort: ReasoningEffort, max_tokens: int) -> _ThinkingParams`
+- `pipelex/plugins/anthropic/anthropic_llm_worker.py:200` — `AnthropicLLMWorker._build_thinking_params_for_budget` — `def _build_thinking_params_for_budget(self, thinking_mode: ThinkingMode, *, budget: int, max_tokens: int) -> _ThinkingParams`
+- `pipelex/plugins/anthropic/anthropic_llms.py:10` — `anthropic_list_available_models` — `async def anthropic_list_available_models(plugin: Plugin, *, backend: InferenceBackend) -> list[ModelInfo]`
+- `pipelex/plugins/bedrock/bedrock_client_protocol.py:9` — `BedrockClientProtocol.chat` — `async def chat(self, messages: BedrockMessageDictList, *, system_text: str | None, model: str, temperature: float, max_tokens: int | None=None) -> tuple[str, NbTokensByCategoryDict]`
+- `pipelex/plugins/bedrock/bedrock_factory.py:27` — `BedrockFactory.make_bedrock_client` — `def make_bedrock_client(cls, plugin: Plugin, *, backend: InferenceBackend) -> BedrockClientProtocol`
+- `pipelex/plugins/bedrock/bedrock_list.py:20` — `list_bedrock_models` — `def list_bedrock_models(sdk: str, *, backend_name: str, backend: InferenceBackend, flat: bool, any_listed: bool) -> None`
+- `pipelex/plugins/bedrock/bedrock_list.py:80` — `_display_bedrock_models_flat` — `def _display_bedrock_models_flat(models: list[dict[str, Any]], *, sdk: str, backend_name: str, aws_region: str, any_listed: bool) -> None`
+- `pipelex/plugins/bedrock/bedrock_list.py:99` — `_display_bedrock_models_table` — `def _display_bedrock_models_table(models: list[dict[str, Any]], *, sdk: str, aws_region: str) -> None`
+- `pipelex/plugins/bedrock/bedrock_llms.py:10` — `bedrock_list_available_models` — `def bedrock_list_available_models(plugin: Plugin, *, backend: InferenceBackend) -> list[dict[str, Any]]`
+- `pipelex/plugins/fal/fal_img_gen_worker.py:37` — `FalImgGenWorker._submit_and_get_result` — `async def _submit_and_get_result(self, img_gen_job: ImgGenJob, *, nb_images: int) -> Any`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:104` — `GatewayCompletionsFactory.make_portkey_openai_client_for_completions` — `def make_portkey_openai_client_for_completions(cls, plugin: Plugin, *, backend: InferenceBackend) -> openai.AsyncOpenAI`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:138` — `GatewayCompletionsFactory.make_extract_output_from_response` — `def make_extract_output_from_response(cls, inference_model: InferenceModelSpec, *, response: GenericResponse) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_extract_worker.py:191` — `GatewayExtractWorker._extract_base64_url` — `async def _extract_base64_url(self, extract_job: ExtractJob, *, base64_url: str, should_include_images: bool=False) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_factory.py:64` — `GatewayFactory.make_extras` — `def make_extras(cls, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str) -> tuple[dict[str, str], dict[str, Any]]`
+- `pipelex/plugins/gateway/gateway_responses_factory.py:26` — `GatewayResponsesFactory.make_portkey_openai_client_for_responses` — `def make_portkey_openai_client_for_responses(cls, plugin: Plugin, *, backend: InferenceBackend) -> openai.AsyncOpenAI`
+- `pipelex/plugins/gateway/gateway_search_worker.py:128` — `GatewaySearchWorker._extract_usage` — `def _extract_usage(self, response: GenericResponse, *, search_job: SearchJob) -> None`
+- `pipelex/plugins/gateway/gateway_search_worker.py:140` — `GatewaySearchWorker._call_relay` — `async def _call_relay(self, model: str, *, content: str) -> GenericResponse`
+- `pipelex/plugins/google/google_factory.py:79` — `GoogleFactory.extract_text_from_response` — `def extract_text_from_response(cls, response: genai_types.GenerateContentResponse, *, model_desc: str) -> str`
+- `pipelex/plugins/google/google_img_gen_factory.py:106` — `GoogleImgGenFactory.dimensions_for_aspect_ratio_and_size` — `def dimensions_for_aspect_ratio_and_size(cls, model: str, *, aspect_ratio: AspectRatio, size: GoogleImageSize) -> tuple[int, int]`
+- `pipelex/plugins/google/google_list.py:16` — `list_google_models` — `async def list_google_models(sdk: str, *, backend_name: str, backend: InferenceBackend, flat: bool, any_listed: bool) -> None`
+- `pipelex/plugins/google/google_list.py:57` — `_display_google_models_flat` — `def _display_google_models_flat(models: list[Any], *, sdk: str, backend_name: str, any_listed: bool) -> None`
+- `pipelex/plugins/google/google_list.py:75` — `_display_google_models_table` — `def _display_google_models_table(models: list[Any], *, sdk: str, backend_name: str) -> None`
+- `pipelex/plugins/google/google_llm_worker.py:111` — `GoogleLLMWorker._build_thinking_config` — `def _build_thinking_config(self, job_params: LLMJobParams, *, max_tokens: int | None) -> genai_types.ThinkingConfig | None`
+- `pipelex/plugins/google/google_llm_worker.py:135` — `GoogleLLMWorker._build_thinking_config_for_effort` — `def _build_thinking_config_for_effort(self, thinking_mode: ThinkingMode, *, effort: ReasoningEffort, max_tokens: int | None) -> genai_types.ThinkingConfig`
+- `pipelex/plugins/google/google_llm_worker.py:172` — `GoogleLLMWorker._build_thinking_config_for_budget` — `def _build_thinking_config_for_budget(self, thinking_mode: ThinkingMode, *, budget: int, max_tokens: int | None) -> genai_types.ThinkingConfig`
+- `pipelex/plugins/mistral/mistral_extract_worker.py:86` — `MistralExtractWorker._extract_pages_from_document` — `async def _extract_pages_from_document(self, document_uri: str, *, extract_job_params: ExtractJobParams) -> ExtractOutput`
+- `pipelex/plugins/mistral/mistral_factory.py:365` — `MistralFactory.make_mistral_document_url_chunk_from_uri` — `async def make_mistral_document_url_chunk_from_uri(cls, mistral_client: Mistral, *, uri: str) -> DocumentURLChunkTypedDict`
+- `pipelex/plugins/mistral/mistral_list.py:13` — `list_mistral_models` — `def list_mistral_models(sdk: str, *, backend_name: str, flat: bool, any_listed: bool) -> None`
+- `pipelex/plugins/mistral/mistral_list.py:54` — `_display_mistral_models_flat` — `def _display_mistral_models_flat(models: list[Any], *, sdk: str, backend_name: str, any_listed: bool) -> None`
+- `pipelex/plugins/mistral/mistral_list.py:70` — `_display_mistral_models_table` — `def _display_mistral_models_table(models: list[Any], *, sdk: str, backend_name: str) -> None`
+- `pipelex/plugins/openai/openai_client_factory.py:27` — `OpenAIClientFactory.make_openai_client` — `def make_openai_client(cls, plugin: Plugin, *, backend: InferenceBackend) -> openai.AsyncClient`
+- `pipelex/plugins/openai/openai_list.py:19` — `list_openai_models` — `async def list_openai_models(sdk: str, *, backend_name: str, backend: InferenceBackend, flat: bool, any_listed: bool) -> None`
+- `pipelex/plugins/openai/openai_list.py:49` — `_display_openai_models_flat` — `def _display_openai_models_flat(models: list[Model], *, sdk: str, backend_name: str, any_listed: bool) -> None`
+- `pipelex/plugins/openai/openai_list.py:70` — `_display_openai_models_table` — `def _display_openai_models_table(models: list[Model], *, sdk: str, backend_name: str) -> None`
+- `pipelex/plugins/openai/openai_llms.py:8` — `openai_list_available_models` — `async def openai_list_available_models(plugin: Plugin, *, backend: InferenceBackend) -> list[Model]`
+- `pipelex/plugins/openai/vertexai_factory.py:47` — `VertexAIFactory._make_endpoint` — `def _make_endpoint(cls, gcp_project_id: str, *, gcp_location: str) -> str`
+- `pipelex/plugins/plugin_factory_abstract.py:10` — `PluginFactoryAbstract.make_extras` — `def make_extras(self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str) -> tuple[dict[str, str], dict[str, Any]]`
+- `pipelex/plugins/plugin_sdk_registry.py:22` — `PluginSdkRegistry.set_sdk_instance` — `def set_sdk_instance(self, plugin: Plugin, *, sdk_instance: Any) -> Any`
+- `pipelex/plugins/portkey/portkey_completions_factory.py:95` — `PortkeyCompletionsFactory.make_portkey_openai_client_for_completions` — `def make_portkey_openai_client_for_completions(cls, plugin: Plugin, *, backend: InferenceBackend) -> openai.AsyncOpenAI`
+- `pipelex/plugins/portkey/portkey_factory.py:40` — `PortkeyFactory.make_extras` — `def make_extras(cls, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str) -> tuple[dict[str, str], dict[str, Any]]`
+- `pipelex/plugins/portkey/portkey_responses_factory.py:26` — `PortkeyResponsesFactory.make_portkey_openai_client_for_responses` — `def make_portkey_openai_client_for_responses(cls, plugin: Plugin, *, backend: InferenceBackend) -> openai.AsyncOpenAI`
+
+### `reporting` (5)
+
+- `pipelex/reporting/reporting_manager.py:179` — `ReportingManager._emit_usage_event` — `def _emit_usage_event(self, inference_job: InferenceJobAbstract, *, tokens_usage: AnyTokensUsage) -> None`
+- `pipelex/reporting/reporting_manager.py:229` — `ReportingManager._emit_via_registered_context` — `def _emit_via_registered_context(context: _EventLogContext, *, trace_context: TraceContext, tokens_usage: AnyTokensUsage) -> None`
+- `pipelex/reporting/reporting_manager.py:251` — `ReportingManager._emit_best_effort` — `def _emit_best_effort(event_log: EventLogProtocol, *, event: UsageReportEvent) -> None`
+- `pipelex/reporting/reporting_manager.py:265` — `ReportingManager._emit_usage_event_runner_fallback` — `def _emit_usage_event_runner_fallback(self, inference_job: InferenceJobAbstract, *, tokens_usage: AnyTokensUsage, trace_context: TraceContext) -> None`
+- `pipelex/reporting/reporting_protocol.py:16` — `ReportingProtocol.set_event_log` — `def set_event_log(self, context_key: str, *, event_log: EventLogProtocol, workflow_id: str, pipeline_run_id: str) -> None`
+
+### `runtime_bridge` (12)
+
+- `pipelex/runtime_bridge/bridge.py:106` — `run_pipe_via_bridge` — `async def run_pipe_via_bridge(input_payload: PipelexPipeRunInput, *, trace_context: TraceContext | None=None) -> PipelexPipeRunOutput`
+- `pipelex/runtime_bridge/bridge.py:160` — `build_pipe_job_from_input` — `def build_pipe_job_from_input(input_payload: PipelexPipeRunInput, *, library_crate: LibraryCrate | None, trace_context: TraceContext | None=None) -> PipeJob`
+- `pipelex/runtime_bridge/bridge.py:240` — `_validate_input` — `def _validate_input(input_payload: PipelexPipeRunInput, *, delivery_assignment: DeliveryAssignment | None) -> None`
+- `pipelex/runtime_bridge/bridge.py:270` — `_run_direct` — `async def _run_direct(pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeRunOutput`
+- `pipelex/runtime_bridge/bridge.py:297` — `_run_temporal_blocking` — `async def _run_temporal_blocking(pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeRunOutput`
+- `pipelex/runtime_bridge/bridge.py:330` — `_run_temporal_fire_and_forget` — `async def _run_temporal_fire_and_forget(pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeRunOutput`
+- `pipelex/runtime_bridge/bridge.py:358` — `_serialize_completed_output` — `def _serialize_completed_output(pipe_output: PipeOutput, *, workflow_id: str | None) -> PipelexPipeRunOutput`
+- `pipelex/runtime_bridge/bridge.py:408` — `_run_mistral_native` — `async def _run_mistral_native(pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeRunOutput`
+- `pipelex/runtime_bridge/primitives/hydration.py:17` — `_validate_as_known_class` — `def _validate_as_known_class(item_class: type[StuffContent], *, raw_item: StuffContent | dict[str, Any]) -> StuffContent`
+- `pipelex/runtime_bridge/primitives/hydration.py:75` — `hydrate_content` — `def hydrate_content(raw_content: list[Any] | dict[str, Any] | str, *, concept: Concept) -> StuffContent`
+- `pipelex/runtime_bridge/primitives/scoped_library.py:16` — `scoped_library_for_crate` — `def scoped_library_for_crate(library_crate: LibraryCrate | None, *, library_id_prefix: str) -> Generator[str | None, None, None]`
+- `pipelex/runtime_bridge/primitives/submitter_hydration.py:30` — `rehydrate_pipe_output_with_crate` — `def rehydrate_pipe_output_with_crate(pipe_output: PipeOutput, *, library_crate: 'LibraryCrate | None') -> PipeOutput`
+
+### `system` (38)
+
+- `pipelex/system/configuration/config_loader.py:90` — `ConfigLoader.resolve_config_file` — `def resolve_config_file(self, relative_path: str, *, config_dir: Path | None=None) -> Path`
+- `pipelex/system/configuration/config_loader.py:171` — `ConfigLoader._override_files_for_dir` — `def _override_files_for_dir(cls, config_dir: Path, *, include_run_mode: bool) -> list[Path]`
+- `pipelex/system/configuration/config_model.py:15` — `ConfigModel.transform_dict_str_to_enum` — `def transform_dict_str_to_enum(input_dict: dict[str, str], *, key_enum_cls: type[StrEnumType] | None=None, value_enum_cls: type[StrEnumType] | None=None) -> dict[str, StrEnumType] | dict[StrEnumType, str] | dict[StrEnumType, StrEnumType]`
+- `pipelex/system/configuration/config_model.py:43` — `ConfigModel.transform_dict_of_floats_str_to_enum` — `def transform_dict_of_floats_str_to_enum(input_dict: dict[str, float], *, key_enum_cls: type[StrEnumType]) -> dict[StrEnumType, float]`
+- `pipelex/system/configuration/config_model.py:61` — `ConfigModel.transform_dict_keys_str_to_enum` — `def transform_dict_keys_str_to_enum(input_dict: dict[str, Any], *, key_enum_cls: type[StrEnumType]) -> dict[StrEnumType, Any]`
+- `pipelex/system/configuration/config_model.py:79` — `ConfigModel.transform_list_of_str_to_enum` — `def transform_list_of_str_to_enum(input_list: list[str], *, enum_cls: type[StrEnumType]) -> list[StrEnumType]`
+- `pipelex/system/configuration/configs.py:234` — `MigrationConfig.text_in_renaming_keys` — `def text_in_renaming_keys(self, text: str, *, category: str) -> list[tuple[str, str]]`
+- `pipelex/system/configuration/configs.py:240` — `MigrationConfig.text_in_renaming_values` — `def text_in_renaming_values(self, text: str, *, category: str) -> list[tuple[str, str]]`
+- `pipelex/system/pipelex_service/gateway_config_merger.py:21` — `GatewayConfigMerger.merge` — `def merge(cls, gateway_model_specs: BackendModelSpecs, *, local_overrides: BackendModelSpecs) -> dict[str, Any]`
+- `pipelex/system/pipelex_service/gateway_config_merger.py:69` — `GatewayConfigMerger._apply_overrides_to_model` — `def _apply_overrides_to_model(cls, model_name: str, *, gateway_model_specs: BackendModelSpecs, local_model_config: BackendModelSpecs) -> None`
+- `pipelex/system/pipelex_service/pipelex_service_agreement.py:29` — `update_service_terms_acceptance` — `def update_service_terms_acceptance(accepted: bool, *, config_dir: Path | None=None) -> None`
+- `pipelex/system/pipelex_service/pipelex_service_agreement.py:53` — `update_inference_setup_completed` — `def update_inference_setup_completed(completed: bool, *, config_dir: Path | None=None) -> None`
+- `pipelex/system/pipelex_service/remote_config_fetcher.py:167` — `RemoteConfigFetcher._build_unavailable_error` — `def _build_unavailable_error(cls, fetch_error: RemoteConfigFetchError, *, cache_refused: bool=False) -> RemoteConfigUnavailableError`
+- `pipelex/system/registries/class_registry_utils.py:21` — `ClassRegistryUtils.register_classes_in_file` — `def register_classes_in_file(cls, file_path: Path, *, base_class: type[Any] | None, is_include_imported: bool) -> None`
+- `pipelex/system/registries/class_registry_utils.py:41` — `ClassRegistryUtils.register_classes_in_folder` — `def register_classes_in_folder(cls, folder_path: Path, *, base_class: type[Any] | None=None, is_recursive: bool=True, is_include_imported: bool=False, force_exclude_dirs: list[Path] | None=None) -> None`
+- `pipelex/system/registries/class_registry_utils.py:77` — `ClassRegistryUtils.import_modules_in_folder` — `def import_modules_in_folder(cls, folder_path: Path, *, force_include_dirs: list[Path] | None=None, is_recursive: bool=True, base_class_names: list[str] | None=None) -> None`
+- `pipelex/system/registries/func_registry.py:99` — `FuncRegistry.register_function` — `def register_function(self, func: Callable[..., Any], *, name: str | None=None) -> None`
+- `pipelex/system/registries/func_registry.py:200` — `FuncRegistry.is_eligible_function` — `def is_eligible_function(self, func: Any, *, require_decorator: bool=False) -> bool`
+- `pipelex/system/registries/func_registry.py:347` — `FuncRegistry.register_ineligible_function` — `def register_ineligible_function(self, func: Callable[..., Any], *, reason: str, source_file: str | None=None) -> None`
+- `pipelex/system/registries/func_registry_utils.py:18` — `FuncRegistryUtils.register_pipe_funcs_from_package` — `def register_pipe_funcs_from_package(cls, package_name: str, *, package: Any) -> int`
+- `pipelex/system/registries/func_registry_utils.py:75` — `FuncRegistryUtils.register_funcs_in_folder` — `def register_funcs_in_folder(cls, folder_path: Path, *, force_include_dirs: list[Path] | None=None, is_recursive: bool=True) -> None`
+- `pipelex/system/telemetry/otel_factory.py:32` — `OtelFactory.make_truncated_content` — `def make_truncated_content(cls, content: str, *, max_length: int | None) -> str`
+- `pipelex/system/telemetry/otel_factory.py:61` — `OtelFactory.make_inputs_json` — `def make_inputs_json(cls, working_memory: WorkingMemory, *, needed_input_names: set[str], max_length: int | None) -> str`
+- `pipelex/system/telemetry/otel_factory.py:90` — `OtelFactory.make_output_json` — `def make_output_json(cls, pipe_output: PipeOutput, *, max_length: int | None) -> str`
+- `pipelex/system/telemetry/otel_factory.py:133` — `OtelFactory.make_trace_names` — `def make_trace_names(cls, pipeline_run_id: str, *, pipe_code: str) -> tuple[str, str]`
+- `pipelex/system/telemetry/otel_factory.py:198` — `OtelFactory.make_ai_tracer` — `def make_ai_tracer(cls, user_id: str | None, *, custom_posthog_client: 'Posthog | None', custom_redaction_config: TelemetryRedactionConfig, pipelex_posthog_client: 'Posthog | None', pipelex_gateway_redaction_config: TelemetryRedactionConfig, pipelex_distinct_id: str | None, otlp_exporters: list[OtlpExporterConfig] | None, langfuse_config: LangfuseConfig | None) -> 'tuple[OTelTracer, OTelTracerProvider]'`
+- `pipelex/system/telemetry/posthog_span_exporter.py:43` — `PostHogSpanExporter._capture_event` — `def _capture_event(self, event: PostHogEvent, *, properties: dict[str, Any]) -> None`
+- `pipelex/system/telemetry/posthog_span_exporter.py:99` — `PostHogSpanExporter._build_redacted_pipe_span_name` — `def _build_redacted_pipe_span_name(self, original_span_name: str, *, pipe_type: str | None) -> str`
+- `pipelex/system/telemetry/posthog_span_exporter.py:127` — `PostHogSpanExporter._build_redacted_generation_span_name` — `def _build_redacted_generation_span_name(self, original_span_name: str, *, pipe_code: str | None, unit_job_id: str | None, model_name: str | None, output_class_name: str | None) -> str`
+- `pipelex/system/telemetry/posthog_span_exporter.py:198` — `PostHogSpanExporter._get_base_properties` — `def _get_base_properties(self, span: ReadableSpan, *, attributes: Mapping[str, AttributeValue]) -> dict[str, Any]`
+- `pipelex/system/telemetry/posthog_span_exporter.py:222` — `PostHogSpanExporter._export_generation_span` — `def _export_generation_span(self, span: ReadableSpan, *, attributes: Mapping[str, AttributeValue]) -> None`
+- `pipelex/system/telemetry/posthog_span_exporter.py:288` — `PostHogSpanExporter._export_pipe_span` — `def _export_pipe_span(self, span: ReadableSpan, *, attributes: Mapping[str, AttributeValue]) -> None`
+- `pipelex/system/telemetry/telemetry_factory.py:23` — `TelemetryFactory.make_telemetry_manager` — `def make_telemetry_manager(cls, secrets_provider: SecretsProviderAbstract, *, integration_mode: IntegrationMode, remote_config: RemoteConfig | None, is_pipelex_telemetry_enabled: bool=False, telemetry_config: TelemetryConfig | None=None, injected_telemetry_manager: TelemetryManagerAbstract | None=None) -> TelemetryManagerAbstract`
+- `pipelex/system/telemetry/telemetry_manager.py:269` — `TelemetryManager._track_anonymous_event` — `def _track_anonymous_event(self, event_name: str, *, properties: dict[str, Any])`
+- `pipelex/system/telemetry/telemetry_manager.py:277` — `TelemetryManager._track_identified_event` — `def _track_identified_event(self, event_name: str, *, properties: dict[str, Any], user_id: str)`
+- `pipelex/system/telemetry/telemetry_manager.py:284` — `TelemetryManager._track_to_pipelex` — `def _track_to_pipelex(self, event_name: str, *, properties: dict[str, Any])`
+- `pipelex/system/telemetry/telemetry_manager_abstract.py:97` — `TelemetryManagerAbstract.track_event` — `def track_event(self, event_name: EventName, *, properties: dict[EventProperty, Any] | None=None)`
+- `pipelex/system/telemetry/telemetry_manager_abstract.py:156` — `TelemetryManagerAbstract.handle_trace_start` — `def handle_trace_start(self, trace_name: str, *, trace_name_redacted: str, trace_id: int) -> None`
+
+### `temporal` (39)
+
+- `pipelex/temporal/codec/codec_server.py:31` — `_set_cors_headers` — `def _set_cors_headers(response: web.Response, *, request_origin: str, cors_origins: list[str]) -> None`
+- `pipelex/temporal/codec/codec_server.py:50` — `_error_response` — `def _error_response(request: web.Request, *, cors_origins: list[str], status: int, text: str) -> web.Response`
+- `pipelex/temporal/codec/codec_server.py:89` — `build_codec_server` — `def build_codec_server(codec: StoragePayloadCodec, *, cors_origins: list[str]) -> web.Application`
+- `pipelex/temporal/codec/storage_payload_codec.py:79` — `StoragePayloadCodec._build_storage_key` — `def _build_storage_key(self, payload: Payload, *, hash_hex: str) -> str`
+- `pipelex/temporal/config_temporal.py:469` — `WorkerConfig.resolve_queue` — `def resolve_queue(self, activity_name: str, *, routing_key: str | None=None) -> str | None`
+- `pipelex/temporal/config_temporal.py:508` — `WorkerConfig.resolve_dispatch` — `def resolve_dispatch(self, activity_name: str, *, routing_key: str | None=None, queue_options_by_queue: dict[str, 'QueueOptions'] | None=None, is_traced: bool=False) -> DispatchOptions`
+- `pipelex/temporal/task_manager.py:15` — `TaskManager.complement_catalog` — `def complement_catalog(self, extra_catalog: dict[str, TaskPack], *, extra_workflows: list[WorkflowType], extra_activities: list[ActivityType])`
+- `pipelex/temporal/task_manager.py:23` — `TaskManager.make_worker` — `def make_worker(self, temporal_client: TemporalClient, *, task_queue: str, is_not_sandboxed: bool=False, scope: WorkerScope | None=None, runtime_profile: WorkerRuntimeProfile | None=None, substitute_activities: dict[ActivityType, ActivityType] | None=None, test_workflows: WorkflowList | None=None, test_activities: ActivityList | None=None) -> Worker`
+- `pipelex/temporal/task_manager.py:36` — `TaskManager.run_worker` — `async def run_worker(self, is_not_sandboxed: bool, *, is_unit_testing: bool, task_queue: str | None=None, scope_name: str | None=None, profile_name: str | None=None)`
+- `pipelex/temporal/task_manager.py:48` — `TaskManager.workflows_and_activities` — `def workflows_and_activities(self, scope: WorkerScope | None=None, *, test_workflows: WorkflowList | None=None, test_activities: ActivityList | None=None, substitute_activities: dict[ActivityType, ActivityType] | None=None) -> tuple[list[WorkflowType], list[ActivityType]]`
+- `pipelex/temporal/temporal_connect.py:18` — `connect_to_temporal_server` — `async def connect_to_temporal_server(server_config: TemporalServerConfig, *, name: str | None=None) -> TemporalClient`
+- `pipelex/temporal/temporal_data_converter.py:64` — `BaseModelPayloadConverter._kajson_to_payload` — `def _kajson_to_payload(self, value: object, *, source_type_holder: object) -> Payload`
+- `pipelex/temporal/temporal_data_converter.py:97` — `BaseModelPayloadConverter._restore_class_source` — `def _restore_class_source(self, value: BaseModel, *, class_source_code: str) -> None`
+- `pipelex/temporal/temporal_manager.py:47` — `TemporalManager.connect_temporal` — `async def connect_temporal(self, temporal_client: TemporalClient | None=None, *, temporal_server_config: TemporalServerConfig | None=None, temporal_selected_server: str | None=None) -> TemporalClient`
+- `pipelex/temporal/temporal_tasks.py:19` — `TemporalTasks.complement_catalog` — `def complement_catalog(self, extra_catalog: dict[str, TaskPack], *, extra_workflows: list[WorkflowType], extra_activities: list[ActivityType])`
+- `pipelex/temporal/temporal_tasks.py:38` — `TemporalTasks.replace_catalog` — `def replace_catalog(self, new_catalog: dict[str, TaskPack], *, new_workflows: list[WorkflowType], new_activities: list[ActivityType])`
+- `pipelex/temporal/temporal_tasks.py:68` — `TemporalTasks._register_workflow` — `def _register_workflow(cls, all_workflows: dict[str, WorkflowType], *, workflow: WorkflowType, source: str) -> None`
+- `pipelex/temporal/temporal_tasks.py:79` — `TemporalTasks._register_activity` — `def _register_activity(cls, all_activities: dict[str, ActivityType], *, activity: ActivityType, source: str) -> None`
+- `pipelex/temporal/temporal_tasks.py:89` — `TemporalTasks.workflows_and_activities` — `def workflows_and_activities(self, scope: WorkerScope | None=None, *, test_workflows: WorkflowList | None=None, test_activities: ActivityList | None=None, substitute_activities: dict[ActivityType, ActivityType] | None=None) -> tuple[list[WorkflowType], list[ActivityType]]`
+- `pipelex/temporal/temporal_tasks.py:122` — `TemporalTasks._resolve_scope` — `def _resolve_scope(self, scope: WorkerScope, *, all_workflows: dict[str, WorkflowType], all_activities: dict[str, ActivityType]) -> tuple[set[WorkflowType], set[ActivityType]]`
+- `pipelex/temporal/tprl/namespace_check.py:71` — `format_temporal_cli_command` — `def format_temporal_cli_command(missing: Sequence[str], *, namespace: str) -> str`
+- `pipelex/temporal/tprl/namespace_check.py:84` — `format_tcld_cli_command` — `def format_tcld_cli_command(missing: Sequence[str], *, namespace: str) -> str`
+- `pipelex/temporal/tprl/namespace_check.py:94` — `check_required_search_attributes` — `async def check_required_search_attributes(temporal_client: TemporalClient, *, namespace: str, configured_attributes: Sequence[str]) -> None`
+- `pipelex/temporal/tprl/namespace_check.py:155` — `ensure_required_search_attributes_registered` — `async def ensure_required_search_attributes_registered(temporal_client: TemporalClient, *, namespace: str, configured_attributes: Sequence[str]) -> RegistrationFailure | tuple[str, ...]`
+- `pipelex/temporal/tprl/observability.py:38` — `_truncate_utf8` — `def _truncate_utf8(text: str, *, max_bytes: int) -> str`
+- `pipelex/temporal/tprl/observability.py:163` — `build_activity_summary` — `def build_activity_summary(method_label: str, *, job_metadata: JobMetadata, extras: Mapping[str, str] | None=None) -> str`
+- `pipelex/temporal/tprl/temporal_error.py:232` — `TemporalError.from_message_exception` — `def from_message_exception(cls, exc: PipelexError, *, force_non_retryable: bool=False) -> Self`
+- `pipelex/temporal/tprl/temporal_error.py:270` — `TemporalError._is_non_retryable` — `def _is_non_retryable(cls, exc: PipelexError, *, error_type: str) -> bool`
+- `pipelex/temporal/tprl/workflow_caller.py:91` — `WorkflowExecutor.execute_workflow` — `async def execute_workflow(self, workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]], *, workflow_arg: WorkflowInput, workflow_id: str, search_attributes: TypedSearchAttributes | None=None, static_summary: str | None=None, static_details: str | None=None, memo: Mapping[str, Any] | None=None) -> WorkflowOutput`
+- `pipelex/temporal/tprl/workflow_caller.py:140` — `WorkflowExecutor.start_workflow` — `async def start_workflow(self, workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]], *, workflow_arg: WorkflowInput, workflow_id: str, callbacks: Sequence[Callback] | None=None, search_attributes: TypedSearchAttributes | None=None, static_summary: str | None=None, static_details: str | None=None, memo: Mapping[str, Any] | None=None) -> WorkflowHandle[WorkflowClass[WorkflowInput, WorkflowOutput], WorkflowOutput]`
+- `pipelex/temporal/tprl/workflow_caller.py:180` — `WorkflowExecutor.execute_child_workflow` — `async def execute_child_workflow(self, workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]], *, workflow_arg: WorkflowInput, workflow_id: str, child_task_queue: str | None=None, search_attributes: TypedSearchAttributes | None=None, static_summary: str | None=None, static_details: str | None=None, memo: Mapping[str, Any] | None=None) -> WorkflowOutput`
+- `pipelex/temporal/tprl/workflow_caller.py:246` — `WorkflowExecutor.start_child_workflow` — `async def start_child_workflow(self, workflow_class: type[WorkflowClass[WorkflowInput, WorkflowOutput]], *, workflow_arg: WorkflowInput, workflow_id: str, child_task_queue: str | None=None, search_attributes: TypedSearchAttributes | None=None, static_summary: str | None=None, static_details: str | None=None, memo: Mapping[str, Any] | None=None) -> ChildWorkflowHandle[WorkflowClass[WorkflowInput, WorkflowOutput], WorkflowOutput]`
+- `pipelex/temporal/tprl/workflow_caller.py:298` — `WorkflowExecutorFactory.create_executor` — `def create_executor(cls, task_queue: str | None=None, *, workflow_execution_timeout: timedelta | None=None, retry_policy: RetryPolicy | None=None, run_timeout: timedelta | None=None, task_timeout: timedelta | None=None, start_delay: timedelta | None=None, rpc_timeout: timedelta | None=None, temporal_client: TemporalClient | None=None, should_auto_connect_temporal: bool=False, worker_environment: TemporalWorkerEnvironment=TemporalWorkerEnvironment.EXTERNAL) -> WorkflowExecutor[WorkflowInput, WorkflowOutput]`
+- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:51` — `_revalidate_against_object_class` — `def _revalidate_against_object_class(raw_obj: BaseModel, *, object_class: type[BaseModelTypeVar], is_mock_built: bool) -> BaseModelTypeVar`
+- `pipelex/temporal/tprl_pipe/dry_validate_dispatch.py:22` — `dispatch_dry_validate` — `async def dispatch_dry_validate(arg: DryValidateArg, *, task_queue: str | None=None, should_auto_connect_temporal: bool=True) -> DryValidateResult`
+- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:127` — `make_temporal_pipe_router` — `def make_temporal_pipe_router(task_queue: str | None=None, *, workflow_execution_timeout: timedelta | None=None, retry_policy: RetryPolicy | None=None, should_auto_connect_temporal: bool=True, worker_environment: TemporalWorkerEnvironment=TemporalWorkerEnvironment.EXTERNAL) -> TemporalPipeRouter`
+- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:92` — `TemporalPipeRun.start` — `async def start(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None=None) -> tuple[str, WorkflowHandle[WorkflowClass[PipeRunArg, PipeOutput], PipeOutput]]`
+- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:131` — `make_temporal_pipe_run` — `def make_temporal_pipe_run(task_queue: str | None=None, *, workflow_execution_timeout: timedelta | None=None, retry_policy: RetryPolicy | None=None, should_auto_connect_temporal: bool=True, worker_environment: TemporalWorkerEnvironment=TemporalWorkerEnvironment.EXTERNAL) -> TemporalPipeRun`
+- `pipelex/temporal/worker_cli.py:25` — `run_worker` — `async def run_worker(project: str | None=None, *, is_not_sandboxed: bool=False, is_unit_testing: bool=False, task_queue: str | None=None, scope_name: str | None=None, profile_name: str | None=None)`
+
+### `tools` (128)
+
+- `pipelex/tools/jinja2/image_renderable.py:36` — `ImageRenderable.render_with_images` — `def render_with_images(self, registry: ImageRegistry, *, text_format: TextFormat) -> str`
+- `pipelex/tools/jinja2/jinja2_environment.py:9` — `make_jinja2_env_from_loader` — `def make_jinja2_env_from_loader(template_category: TemplateCategory, *, loader: BaseLoader, enable_async: bool=True) -> Environment`
+- `pipelex/tools/jinja2/jinja2_environment.py:57` — `_register_filters` — `def _register_filters(jinja2_env: Environment, *, template_category: TemplateCategory, enable_async: bool) -> None`
+- `pipelex/tools/jinja2/jinja2_environment.py:81` — `make_jinja2_env_without_loader` — `def make_jinja2_env_without_loader(template_category: TemplateCategory, *, enable_async: bool=True) -> Environment`
+- `pipelex/tools/jinja2/jinja2_environment.py:97` — `make_jinja2_env_from_registry` — `def make_jinja2_env_from_registry(template_category: TemplateCategory, *, enable_async: bool=True) -> Environment`
+- `pipelex/tools/jinja2/jinja2_filters.py:110` — `apply_tag_style` — `def apply_tag_style(context: Context, *, value: str, tag_name: str | None=None) -> str`
+- `pipelex/tools/jinja2/jinja2_parsing.py:8` — `check_jinja2_parsing` — `def check_jinja2_parsing(template_source: str, *, template_category: TemplateCategory=TemplateCategory.LLM_PROMPT)`
+- `pipelex/tools/jinja2/jinja2_rendering.py:24` — `_add_to_templating_context` — `def _add_to_templating_context(templating_context: dict[str, Any], *, jinja2_context_key: Jinja2ContextKey, value: Any) -> None`
+- `pipelex/tools/jinja2/jinja2_rendering.py:37` — `_compile_jinja2_template` — `def _compile_jinja2_template(template_source: str, *, template_category: TemplateCategory, use_registry: bool=False, enable_async: bool=True, finalize: Callable[[Any], Any] | None=None) -> _Jinja2Template`
+- `pipelex/tools/jinja2/jinja2_rendering.py:66` — `_prepare_templating_context` — `def _prepare_templating_context(templating_context: dict[str, Any], *, templating_style: TemplatingStyle | None) -> dict[str, Any]`
+- `pipelex/tools/jinja2/jinja2_rendering.py:87` — `_make_type_error_msg` — `def _make_type_error_msg(template_source: str, *, templating_context: dict[str, Any], type_error: TypeError) -> str`
+- `pipelex/tools/jinja2/jinja2_rendering.py:97` — `_make_non_type_error_msg` — `def _make_non_type_error_msg(template_source: str, *, error_label: str, error: Jinja2StuffError | TemplateSyntaxError | UndefinedError | Jinja2ContextError) -> str`
+- `pipelex/tools/jinja2/jinja2_rendering.py:106` — `_render_template_sync` — `def _render_template_sync(template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any]) -> str`
+- `pipelex/tools/jinja2/jinja2_rendering.py:127` — `_render_template_async` — `async def _render_template_async(template_source: str, *, template: _Jinja2Template, templating_context: dict[str, Any]) -> str`
+- `pipelex/tools/jinja2/jinja2_rendering.py:148` — `render_jinja2_sync` — `def render_jinja2_sync(template_source: str, *, template_category: TemplateCategory, templating_context: dict[str, Any], templating_style: TemplatingStyle | None=None, use_registry: bool=False) -> str`
+- `pipelex/tools/jinja2/jinja2_rendering.py:173` — `render_jinja2_async` — `async def render_jinja2_async(template_source: str, *, template_category: TemplateCategory, templating_context: dict[str, Any], templating_style: TemplatingStyle | None=None, use_registry: bool=False, finalize: Callable[[Any], Any] | None=None) -> str`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:66` — `_collect_full_variable_paths` — `def _collect_full_variable_paths(node: nodes.Node, *, paths: set[str], declared_names: set[str]) -> None`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:121` — `detect_jinja2_required_variables` — `def detect_jinja2_required_variables(template_category: TemplateCategory, *, template_source: str) -> set[str]`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:185` — `_collect_variable_references` — `def _collect_variable_references(node: nodes.Node, *, references: dict[str, VariableReference], declared_names: set[str]) -> None`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:255` — `detect_jinja2_variable_references` — `def detect_jinja2_variable_references(template_category: TemplateCategory, *, template_source: str) -> list[VariableReference]`
+- `pipelex/tools/jinja2/jinja2_with_images_filter.py:78` — `_render_sequence_with_images` — `def _render_sequence_with_images(sequence: list[Any] | tuple[Any, ...], *, registry: ImageRegistry, text_format: TextFormat) -> str`
+- `pipelex/tools/log/log.py:203` — `Log.set_level_for_package` — `def set_level_for_package(self, package_name: str, *, level: LogLevel)`
+- `pipelex/tools/log/log.py:224` — `Log.verbose` — `def verbose(self, content: str | Any, *, title: str | None=None, inline: str | None=None)`
+- `pipelex/tools/log/log.py:243` — `Log.debug` — `def debug(self, content: str | Any, *, title: str | None=None, inline: str | None=None)`
+- `pipelex/tools/log/log.py:262` — `Log.dev` — `def dev(self, content: str | Any, *, title: str | None=None, inline: str | None=None)`
+- `pipelex/tools/log/log.py:281` — `Log.info` — `def info(self, content: str | Any, *, title: str | None=None, inline: str | None=None)`
+- `pipelex/tools/log/log.py:300` — `Log.warning` — `def warning(self, content: str | Any, *, title: str | None=None, inline: str | None=None, problem_id: str | None=None)`
+- `pipelex/tools/log/log.py:323` — `Log.error` — `def error(self, content: str | Any, *, title: str | None=None, inline: str | None=None, include_exception: bool=False, problem_id: str | None=None)`
+- `pipelex/tools/log/log.py:354` — `Log.critical` — `def critical(self, content: str | Any, *, title: str | None=None, inline: str | None=None, include_exception: bool=False, problem_id: str | None=None)`
+- `pipelex/tools/log/log_dispatch.py:66` — `LogDispatch.dispatch` — `def dispatch(self, content: str | Any, *, severity: int, title: str | None=None, inline: str | None=None, include_exception: bool=False)`
+- `pipelex/tools/log/log_dispatch.py:125` — `LogDispatch._log_message` — `def _log_message(self, message: str, *, severity: int, caller_info_str: str | None, title: str | None=None, inline: str | None=None, include_exception: bool=False)`
+- `pipelex/tools/log/log_dispatch.py:160` — `LogDispatch._log_data` — `def _log_data(self, data: Any, *, severity: int, caller_info_str: str | None, title: str | None=None, include_exception: bool=False)`
+- `pipelex/tools/log/log_dispatch.py:234` — `LogDispatch._log_to_console` — `def _log_to_console(self, message: str, *, severity: int)`
+- `pipelex/tools/mermaid/mermaid_utils.py:64` — `print_mermaid_url` — `def print_mermaid_url(url: str, *, title: str) -> None`
+- `pipelex/tools/mermaid/mermaid_utils.py:142` — `render_mermaid_html_generic` — `def render_mermaid_html_generic(mermaid_code: str, *, title: str='Mermaid Diagram', theme: str='default') -> str`
+- `pipelex/tools/mermaid/mermaid_utils.py:173` — `render_mermaid_html_generic_async` — `async def render_mermaid_html_generic_async(mermaid_code: str, *, title: str='Mermaid Diagram', theme: str='default') -> str`
+- `pipelex/tools/misc/async_utils.py:19` — `gather_bounded` — `async def gather_bounded(task_factories: Sequence[Callable[[], Awaitable[_T]]], *, max_concurrency: int | None) -> list[_T]`
+- `pipelex/tools/misc/attribute_utils.py:12` — `AttributePolisher._truncate_string` — `def _truncate_string(cls, value: str, *, max_length: int) -> str`
+- `pipelex/tools/misc/attribute_utils.py:19` — `AttributePolisher._truncate_bytes` — `def _truncate_bytes(cls, value: bytes, *, max_length: int) -> bytes`
+- `pipelex/tools/misc/attribute_utils.py:65` — `AttributePolisher.apply_truncation_recursive` — `def apply_truncation_recursive(cls, obj: Any, *, name: str | None=None) -> Any`
+- `pipelex/tools/misc/base64_utils.py:38` — `make_base64_url` — `def make_base64_url(base64_data: str, *, file_type: FileType) -> str`
+- `pipelex/tools/misc/context_provider_abstract.py:11` — `ContextProviderAbstract.get_typed_object_or_attribute` — `def get_typed_object_or_attribute(self, name: str, *, wanted_type: type[Any] | None=None, accept_list: bool=False) -> Any`
+- `pipelex/tools/misc/dict_utils.py:14` — `insert_before` — `def insert_before(dictionary: dict[K, V], *, target_key: K, new_key: K, new_value: V) -> dict[K, V]`
+- `pipelex/tools/misc/dict_utils.py:51` — `apply_to_strings_recursive` — `def apply_to_strings_recursive(data: Any, *, transform_func: Callable[[str], str]) -> dict[str, Any]`
+- `pipelex/tools/misc/dict_utils.py:86` — `apply_to_strings_in_list` — `def apply_to_strings_in_list(data: list[Any], *, transform_func: Callable[[str], str]) -> list[Any]`
+- `pipelex/tools/misc/dict_utils.py:102` — `substitute_nested_in_context` — `def substitute_nested_in_context(context: dict[str, Any], *, extra_params: dict[str, Any] | None=None) -> dict[str, Any]`
+- `pipelex/tools/misc/diff.py:97` — `_generate_diff_summary` — `def _generate_diff_summary(diff_content: str, *, left_is_newer: bool) -> str | None`
+- `pipelex/tools/misc/diff.py:241` — `make_diff_dirs_pretty._collect_diffs` — `def _collect_diffs(dir_comparison: filecmp.dircmp[str], *, relative_path: str='') -> None`
+- `pipelex/tools/misc/file_fetch_utils.py:7` — `fetch_file_from_url_httpx` — `async def fetch_file_from_url_httpx(url: str, *, request_timeout: int | None=None) -> bytes`
+- `pipelex/tools/misc/file_utils.py:13` — `reject_bare_str_or_path` — `def reject_bare_str_or_path(value: object, *, param_name: str) -> None`
+- `pipelex/tools/misc/file_utils.py:38` — `save_bytes_to_binary_file` — `def save_bytes_to_binary_file(byte_data: bytes, *, file_path: Path, create_directory: bool=False) -> Path`
+- `pipelex/tools/misc/file_utils.py:59` — `save_text_to_path` — `def save_text_to_path(text: str, *, path: Path, create_directory: bool=False)`
+- `pipelex/tools/misc/file_utils.py:151` — `copy_file_from_package` — `def copy_file_from_package(package_name: str, *, file_path_in_package: str, target_path: Path, overwrite: bool=True) -> None`
+- `pipelex/tools/misc/file_utils.py:167` — `copy_folder_from_package` — `def copy_folder_from_package(package_name: str, *, folder_path_in_package: str, target_dir: Path, overwrite: bool=True, non_overwrite_files: list[str] | None=None) -> None`
+- `pipelex/tools/misc/file_utils.py:460` — `get_incremental_directory_path` — `def get_incremental_directory_path(base_path: Path, *, base_name: str, start_at: int=1) -> Path`
+- `pipelex/tools/misc/file_utils.py:486` — `get_incremental_file_path` — `def get_incremental_file_path(base_path: Path, *, base_name: str, extension: str, start_at: int=1, avoid_suffix_if_possible: bool=False) -> Path`
+- `pipelex/tools/misc/file_utils.py:532` — `find_files_in_dir` — `def find_files_in_dir(dir_path: Path, *, pattern: str, is_recursive: bool=True, excluded_dirs: list[str] | None=None, force_include_dirs: list[str] | None=None) -> list[Path]`
+- `pipelex/tools/misc/hash_utils.py:4` — `hash_sha256` — `def hash_sha256(data: str | bytes, *, length: int | None=None) -> str`
+- `pipelex/tools/misc/image_utils.py:95` — `pil_image_to_bytes` — `def pil_image_to_bytes(pil_image: Image.Image, *, image_format: ImageFormat | None) -> bytes`
+- `pipelex/tools/misc/json_utils.py:71` — `clean_json_dumps` — `def clean_json_dumps(data: Any, *, indent: int | None=None) -> str`
+- `pipelex/tools/misc/json_utils.py:92` — `json_str` — `def json_str(some_object: Any, *, title: str | None=None, is_spaced: bool=False) -> str`
+- `pipelex/tools/misc/json_utils.py:128` — `save_as_json_to_path` — `def save_as_json_to_path(object_to_save: Any, *, path: Path, indent: int | None=4, is_warning_enabled: bool=True, create_directory: bool=False)`
+- `pipelex/tools/misc/json_utils.py:227` — `deep_update` — `def deep_update(target_dict: dict[str, Any], *, updates: Mapping[str, Any])`
+- `pipelex/tools/misc/json_utils.py:315` — `purify_json` — `def purify_json(data: Any, *, indent: int | None=None, is_truncate_bytes_enabled: bool=False, is_warning_enabled: bool=True) -> tuple[dict[Any, Any] | list[Any], str]`
+- `pipelex/tools/misc/json_utils.py:395` — `purify_json_list` — `def purify_json_list(data: list[Any], *, indent: int | None=None, is_truncate_bytes_enabled: bool=False) -> tuple[list[Any], str]`
+- `pipelex/tools/misc/json_utils.py:453` — `purify_json_dict` — `def purify_json_dict(data: Any, *, indent: int | None=None, is_warning_enabled: bool=True) -> tuple[dict[str, Any], str]`
+- `pipelex/tools/misc/json_utils.py:508` — `pure_json_str` — `def pure_json_str(data: Any, *, indent: int | None=None, is_warning_enabled: bool=True) -> str`
+- `pipelex/tools/misc/markdown_utils.py:7` — `convert_to_markdown` — `def convert_to_markdown(data: Any, *, level: int=1, is_pretty: bool=False) -> str`
+- `pipelex/tools/misc/pretty.py:99` — `pretty_print` — `def pretty_print(content: str | Any, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, border_style: StyleType | None=None, width: int | None=None, console_width: int | None=None)`
+- `pipelex/tools/misc/pretty.py:120` — `pretty_print_md` — `def pretty_print_md(content: str, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, border_style: StyleType | None=None, width: int | None=None, console_width: int | None=None)`
+- `pipelex/tools/misc/pretty.py:143` — `pretty_print_url` — `def pretty_print_url(url: str, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, border_style: StyleType | None=None, width: int | None=None, console_width: int | None=None)`
+- `pipelex/tools/misc/pretty.py:170` — `PrettyPrinter.pretty_print` — `def pretty_print(cls, content: str | Any, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, border_style: StyleType | None=None, width: int | None=None, console_width: int | None=None)`
+- `pipelex/tools/misc/pretty.py:198` — `PrettyPrinter.pretty_print_using_rich` — `def pretty_print_using_rich(cls, content: str | Any, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, border_style: StyleType | None=None, width: int | None=None, console_width: int | None=None)`
+- `pipelex/tools/misc/pretty.py:222` — `PrettyPrinter.pretty_width` — `def pretty_width(cls, width: int | None=None, *, depth: int | None=None) -> int`
+- `pipelex/tools/misc/pretty.py:234` — `PrettyPrinter.make_pretty_panel` — `def make_pretty_panel(cls, content: str | Any, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, border_style: StyleType | None=None, width: int | None=None, console_width: int | None=None) -> Panel`
+- `pipelex/tools/misc/pretty.py:259` — `PrettyPrinter.wrap_in_panel` — `def wrap_in_panel(cls, pretty: PrettyPrintable, *, title: TextType | None=None, subtitle: TextType | None=None, border_style: StyleType | None=None, width: int | None=None) -> Panel`
+- `pipelex/tools/misc/pretty.py:282` — `PrettyPrinter.pretty_text` — `def pretty_text(cls, pretty: PrettyPrintable, *, width: int=PRETTY_WIDTH_FOR_EXPORT) -> str`
+- `pipelex/tools/misc/pretty.py:303` — `PrettyPrinter.pretty_html` — `def pretty_html(cls, pretty: PrettyPrintable, *, width: int=PRETTY_WIDTH_FOR_EXPORT) -> str`
+- `pipelex/tools/misc/pretty.py:315` — `PrettyPrinter.pretty_svg` — `def pretty_svg(cls, pretty: PrettyPrintable, *, width: int=PRETTY_WIDTH_FOR_EXPORT) -> str`
+- `pipelex/tools/misc/pretty.py:322` — `PrettyPrinter.make_pretty` — `def make_pretty(cls, value: Any, *, inner_title: str | None=None, depth: int=0) -> PrettyPrintable`
+- `pipelex/tools/misc/pretty.py:381` — `PrettyPrinter.pretty_print_without_rich` — `def pretty_print_without_rich(cls, content: str | Any, *, title: TextType | None=None, subtitle: TextType | None=None, inner_title: str | None=None, width: int | None=None, console_width: int | None=None)`
+- `pipelex/tools/misc/pretty.py:438` — `PrettyPrinter.pretty_print_url_without_rich` — `def pretty_print_url_without_rich(cls, content: str | Any, *, title: TextType | None=None, subtitle: TextType | None=None)`
+- `pipelex/tools/misc/semver.py:59` — `version_satisfies` — `def version_satisfies(version: Version, *, constraint: SimpleSpec) -> bool`
+- `pipelex/tools/misc/semver.py:73` — `select_minimum_version` — `def select_minimum_version(available_versions: list[Version], *, constraint: SimpleSpec) -> Version | None`
+- `pipelex/tools/misc/semver.py:96` — `select_minimum_version_for_multiple_constraints` — `def select_minimum_version_for_multiple_constraints(available_versions: list[Version], *, constraints: list[SimpleSpec]) -> Version | None`
+- `pipelex/tools/misc/string_utils.py:335` — `matches_wildcard_pattern` — `def matches_wildcard_pattern(text: str, *, pattern: str) -> bool`
+- `pipelex/tools/misc/toml_sync.py:42` — `get_nested_value` — `def get_nested_value(doc: TOMLDocument | Table | dict[str, Any], *, key_path: str) -> tuple[bool, Any]`
+- `pipelex/tools/misc/toml_sync.py:69` — `set_nested_value` — `def set_nested_value(doc: TOMLDocument | Table | dict[str, Any], *, key_path: str, value: Any) -> bool`
+- `pipelex/tools/misc/toml_sync.py:120` — `collect_leaf_key_paths` — `def collect_leaf_key_paths(doc: TOMLDocument | Table | dict[str, Any], *, prefix: str='') -> list[str]`
+- `pipelex/tools/misc/toml_utils.py:67` — `save_toml_to_path` — `def save_toml_to_path(data: dict[str, Any] | tomlkit.TOMLDocument, *, path: str | Path) -> None`
+- `pipelex/tools/network/ssrf_guard.py:37` — `resolve_to_allowed_ips` — `async def resolve_to_allowed_ips(host: str, *, port: int, timeout: float | None=None) -> list[str]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:68` — `_extract_image_from_pdf_object` — `def _extract_image_from_pdf_object(image_obj: PdfImage, *, output_format: ImageFormat | None) -> ExtractedImageFromPage`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:159` — `PyPdfium2Renderer._render_pdf_pages_sync` — `def _render_pdf_pages_sync(pdf_input: PdfInput, *, scale: float) -> list[Image.Image]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:190` — `PyPdfium2Renderer._extract_embedded_images_from_page_sync` — `def _extract_embedded_images_from_page_sync(pdf_input: PdfInput, *, page_index: int, max_depth: int=DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH, output_format: ImageFormat | None=None) -> list[ExtractedImageFromPage]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:227` — `PyPdfium2Renderer._extract_embedded_images_from_pdf_sync` — `def _extract_embedded_images_from_pdf_sync(pdf_input: PdfInput, *, max_depth: int=DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH, output_format: ImageFormat | None=None) -> dict[int, list[ExtractedImageFromPage]]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:267` — `PyPdfium2Renderer.render_pdf_pages` — `async def render_pdf_pages(self, pdf_input: PdfInput, *, dpi: int) -> list[Image.Image]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:278` — `PyPdfium2Renderer.render_pdf_pages_from_uri` — `async def render_pdf_pages_from_uri(self, pdf_uri: str, *, dpi: int) -> list[Image.Image]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:287` — `PyPdfium2Renderer.extract_embedded_images_from_page` — `async def extract_embedded_images_from_page(self, pdf_input: PdfInput, *, page_index: int, max_depth: int=DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH, output_format: ImageFormat | None=None) -> list[ExtractedImageFromPage]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:316` — `PyPdfium2Renderer.extract_embedded_images_from_pdf` — `async def extract_embedded_images_from_pdf(self, pdf_input: PdfInput, *, max_depth: int=DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH, output_format: ImageFormat | None=None) -> dict[int, list[ExtractedImageFromPage]]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:342` — `PyPdfium2Renderer.extract_embedded_images_from_pdf_uri` — `async def extract_embedded_images_from_pdf_uri(self, pdf_uri: str, *, max_depth: int=DEFAULT_IMAGE_EXTRACTION_MAX_DEPTH, output_format: ImageFormat | None=None) -> dict[int, list[ExtractedImageFromPage]]`
+- `pipelex/tools/secrets/secrets_provider_abstract.py:14` — `SecretsProviderAbstract.get_required_secret_specific_version` — `def get_required_secret_specific_version(self, secret_id: str, *, version_id: str) -> str`
+- `pipelex/tools/secrets/secrets_provider_abstract.py:17` — `SecretsProviderAbstract.get_optional_secret_specific_version` — `def get_optional_secret_specific_version(self, secret_id: str, *, version_id: str) -> str | None`
+- `pipelex/tools/secrets/secrets_provider_abstract.py:20` — `SecretsProviderAbstract.set_secret_as_env_var` — `def set_secret_as_env_var(self, secret_id: str, *, version_id: str=LATEST_SECRET_VERSION_NAME)`
+- `pipelex/tools/secrets/secrets_utils.py:22` — `substitute_vars` — `def substitute_vars(content: str, *, secrets_provider: SecretsProviderAbstract, raise_on_missing_var: bool=True) -> str`
+- `pipelex/tools/secrets/secrets_utils.py:92` — `_handle_fallback_pattern` — `def _handle_fallback_pattern(var_spec: str, *, secrets_provider: SecretsProviderAbstract) -> str`
+- `pipelex/tools/secrets/secrets_utils.py:139` — `_get_secret` — `def _get_secret(secret_name: str, *, secrets_provider: SecretsProviderAbstract) -> str`
+- `pipelex/tools/storage/gcp_storage_provider.py:134` — `GcpStorageProvider._store_sync` — `def _store_sync(self, data: bytes, *, key: str, content_type: str | None) -> None`
+- `pipelex/tools/storage/storage_provider_abstract.py:97` — `StorageProviderAbstract.store` — `async def store(self, data: bytes, *, key: str, content_type: str | None=None) -> str`
+- `pipelex/tools/storage/storage_provider_abstract.py:113` — `StorageProviderAbstract._store` — `async def _store(self, data: bytes, *, key: str, content_type: str | None) -> None`
+- `pipelex/tools/tabular/csv_codec.py:141` — `_validate_header` — `def _validate_header(header: list[str], *, path: Path) -> None`
+- `pipelex/tools/tabular/csv_codec.py:160` — `_read_table` — `def _read_table(path: Path, *, delimiter: str, encoding: str) -> tuple[list[str], list[tuple[int, list[str]]]]`
+- `pipelex/tools/tabular/csv_codec.py:219` — `_row_to_dict` — `def _row_to_dict(data_row: list[str], *, header: list[str]) -> dict[str, str]`
+- `pipelex/tools/tabular/csv_codec.py:224` — `read_rows` — `def read_rows(path: Path, *, delimiter: str=DEFAULT_DELIMITER, encoding: str=DEFAULT_READ_ENCODING) -> list[dict[str, str]]`
+- `pipelex/tools/tabular/csv_codec.py:312` — `list_content_from_csv` — `def list_content_from_csv(path: Path, *, row_model: type[StuffContentType], delimiter: str=DEFAULT_DELIMITER, encoding: str=DEFAULT_READ_ENCODING) -> ListContent[StuffContentType]`
+- `pipelex/tools/tabular/csv_codec.py:379` — `csv_from_list_content` — `def csv_from_list_content(list_content: ListContent[StuffContentType], *, row_model: type[StuffContentType], path: Path, delimiter: str=DEFAULT_DELIMITER, encoding: str=DEFAULT_ENCODING) -> None`
+- `pipelex/tools/typing/class_utils.py:122` — `has_compatible_field` — `def has_compatible_field(model_cls: type[Any], *, target_type: type[Any]) -> bool`
+- `pipelex/tools/typing/module_inspector.py:100` — `find_class_names_in_file` — `def find_class_names_in_file(file_path: Path, *, base_class_names: list[str] | None=None) -> list[str]`
+- `pipelex/tools/typing/module_inspector.py:161` — `find_decorated_function_names_in_file` — `def find_decorated_function_names_in_file(file_path: Path, *, decorator_names: list[str]) -> list[str]`
+- `pipelex/tools/typing/module_inspector.py:226` — `import_module_from_file_if_has_decorated_functions` — `def import_module_from_file_if_has_decorated_functions(file_path: Path, *, decorator_names: list[str]) -> Any | None`
+- `pipelex/tools/typing/module_inspector.py:259` — `import_module_from_file_if_has_classes` — `def import_module_from_file_if_has_classes(file_path: Path, *, base_class_names: list[str] | None=None) -> Any | None`
+- `pipelex/tools/typing/module_inspector.py:294` — `find_classes_in_module` — `def find_classes_in_module(module: Any, *, base_class: type[Any] | None, include_imported: bool) -> list[type[Any]]`
+- `pipelex/tools/typing/pydantic_utils.py:31` — `empty_dict_factory_of` — `def empty_dict_factory_of(_key: type[K], *, _val: type[V] | None=None) -> Callable[[], dict[K, Any]]`
+- `pipelex/tools/typing/pydantic_utils.py:317` — `serialize_model` — `def serialize_model(obj: Any, *, field_visibility: FieldVisibility=FieldVisibility.NO_HIDDEN_FIELDS, is_stringify_enums: bool=True) -> dict[str, Any] | list[Any] | Any`
+- `pipelex/tools/typing/structure_printer.py:69` — `StructurePrinter.get_type_structure` — `def get_type_structure(self, tp: type[Any], *, seen_types: set[str] | None=None, collected_types: dict[str, type[Any]] | None=None, collected_enums: dict[str, type[Enum]] | None=None, base_class: type[Any]=BaseModel) -> list[str]`
+- `pipelex/tools/typing/validation_utils.py:4` — `has_exactly_one_among_attributes_from_list` — `def has_exactly_one_among_attributes_from_list(obj: Any, *, attributes_list: list[str]) -> bool`
+- `pipelex/tools/typing/validation_utils.py:23` — `has_more_than_one_among_attributes_from_list` — `def has_more_than_one_among_attributes_from_list(obj: Any, *, attributes_list: list[str]) -> bool`
+- `pipelex/tools/typing/validation_utils.py:42` — `has_more_than_one_among_attributes_from_lists` — `def has_more_than_one_among_attributes_from_lists(obj: Any, *, attributes_lists: list[list[str]]) -> list[str] | None`
+- `pipelex/tools/uri/uri_resolver.py:160` — `make_base64_url_from_any_uri` — `async def make_base64_url_from_any_uri(uri: str, *, storage_provider: StorageProviderAbstract | None=None) -> str`
+
+### `tracing` (5)
+
+- `pipelex/tracing/activity_event_log.py:80` — `ActivityEventLogCache.log_once_runner_fallback_engaged` — `def log_once_runner_fallback_engaged(cls, workflow_id: str, *, writer_id: str) -> None`
+- `pipelex/tracing/dynamodb_event_log.py:99` — `DynamoDBEventLog._make_sk` — `def _make_sk(workflow_id: str, *, writer_id: str, sequence: int) -> str`
+- `pipelex/tracing/event_log_factory.py:10` — `make_event_log` — `def make_event_log(tracing_config: TracingConfig, *, writer_id: str='primary') -> EventLogProtocol`
+- `pipelex/tracing/graphspec_assembler.py:116` — `GraphSpecAssembler.assemble` — `def assemble(events: Sequence[TraceEvent], *, graph_id: str, pipeline_ref: PipelineRef | None=None) -> GraphSpec`
+- `pipelex/tracing/ndjson_event_log.py:73` — `NdjsonEventLog._file_name_for` — `def _file_name_for(workflow_id: str, *, writer_id: str) -> str`
+
+## B. `LONE_SUBJECT` — single positional param (low signal)
+
+_A single positional parameter and nothing else after it (`def f(subject)`, optionally `**kwargs`). No "choice" of subject was possible — only one arg exists. Lowest signal; included for completeness. A bare bool/int/str subject here is the only thing arguably worth a second look (`do_thing(True)` reads opaquely)._
+
+Count: 1003
+
+### `base_exceptions.py` (8)
+
+- `pipelex/base_exceptions.py:12` — `iter_cause_chain` — `def iter_cause_chain(exc: BaseException) -> Iterator[BaseException]`
+- `pipelex/base_exceptions.py:66` — `_redact_provider_metadata_for_strict` — `def _redact_provider_metadata_for_strict(metadata_payload: dict[str, Any]) -> dict[str, Any] | None`
+- `pipelex/base_exceptions.py:178` — `error_domain_to_http_status` — `def error_domain_to_http_status(error_domain: ErrorDomain | str | None) -> int`
+- `pipelex/base_exceptions.py:209` — `error_domain_is_input` — `def error_domain_is_input(error_domain: ErrorDomain | str | None) -> bool`
+- `pipelex/base_exceptions.py:268` — `ErrorReport.to_dict` — `def to_dict(self, disclosure_mode: DisclosureMode=DisclosureMode.VERBOSE) -> dict[str, Any]`
+- `pipelex/base_exceptions.py:360` — `ErrorReport.from_dict` — `def from_dict(cls, data: dict[str, Any]) -> 'ErrorReport'`
+- `pipelex/base_exceptions.py:397` — `_humanize_class_name` — `def _humanize_class_name(class_name: str) -> str`
+- `pipelex/base_exceptions.py:510` — `PipelexError._enrich_error_report_from_cause` — `def _enrich_error_report_from_cause(self, report: ErrorReport) -> ErrorReport`
+
+### `builder` (16)
+
+- `pipelex/builder/concept/concept_spec.py:339` — `ConceptSpec._format_type_display` — `def _format_type_display(self, field_spec: ConceptStructureSpec) -> str`
+- `pipelex/builder/operations/concept_ops.py:14` — `parse_concept_spec` — `def parse_concept_spec(spec_data: Any) -> ConceptSpec`
+- `pipelex/builder/operations/concept_ops.py:95` — `structure_field_to_dict` — `def structure_field_to_dict(field_spec: ConceptStructureSpec) -> dict[str, Any]`
+- `pipelex/builder/operations/concept_ops.py:127` — `concept_spec_to_toml` — `def concept_spec_to_toml(concept_spec: ConceptSpec) -> str`
+- `pipelex/builder/operations/models_ops.py:240` — `format_models_markdown` — `def format_models_markdown(result: dict[str, Any]) -> str`
+- `pipelex/builder/operations/pipe_ops.py:39` — `_normalize_sub_pipe_dict` — `def _normalize_sub_pipe_dict(data: dict[str, Any]) -> None`
+- `pipelex/builder/operations/pipe_ops.py:69` — `_normalize_pipe_code_aliases` — `def _normalize_pipe_code_aliases(data: dict[str, Any]) -> None`
+- `pipelex/builder/operations/pipe_ops.py:79` — `_normalize_prompt_aliases` — `def _normalize_prompt_aliases(data: dict[str, Any]) -> None`
+- `pipelex/builder/operations/pipe_ops.py:303` — `pipe_spec_to_toml` — `def pipe_spec_to_toml(pipe_spec: PipeSpec) -> str`
+- `pipelex/builder/operations/validate_ops.py:22` — `validate_all` — `async def validate_all(library_dirs: list[Path] | None=None) -> dict[str, Any]`
+- `pipelex/builder/operations/validate_ops.py:82` — `validate_bundle_content` — `async def validate_bundle_content(mthds_contents: list[str]) -> dict[str, Any]`
+- `pipelex/builder/pipe/pipe_spec.py:132` — `PipeSpec.validate_pipe_code_syntax` — `def validate_pipe_code_syntax(cls, pipe_code: str) -> str`
+- `pipelex/builder/runner_code.py:48` — `_is_multiple` — `def _is_multiple(multiplicity: VariableMultiplicity | None) -> bool`
+- `pipelex/builder/runner_code.py:86` — `_get_structure_class_import` — `def _get_structure_class_import(class_name: str) -> str | None`
+- `pipelex/builder/runner_code.py:104` — `_collect_concept_info` — `def _collect_concept_info(concept: Concept) -> CustomClassInfo | None`
+- `pipelex/builder/runner_code.py:125` — `_collect_imports_for_inputs` — `def _collect_imports_for_inputs(inputs: InputStuffSpecs) -> tuple[set[str], dict[str, CustomClassInfo]]`
+
+### `cli` (98)
+
+- `pipelex/cli/_cli.py:98` — `version_callback` — `def version_callback(value: bool) -> None`
+- `pipelex/cli/agent_cli/_agent_cli.py:73` — `version_callback` — `def version_callback(value: bool) -> None`
+- `pipelex/cli/agent_cli/commands/agent_output.py:41` — `record_setup_warning` — `def record_setup_warning(warning_payload: dict[str, Any]) -> None`
+- `pipelex/cli/agent_cli/commands/agent_output.py:76` — `set_agent_cli_error_format` — `def set_agent_cli_error_format(error_format: CliOutputFormat) -> None`
+- `pipelex/cli/agent_cli/commands/agent_output.py:187` — `_build_error_source` — `def _build_error_source(exc: BaseException) -> list[str]`
+- `pipelex/cli/agent_cli/commands/agent_output.py:290` — `_render_error_markdown` — `def _render_error_markdown(payload: dict[str, Any]) -> str`
+- `pipelex/cli/agent_cli/commands/agent_output.py:361` — `agent_success` — `def agent_success(result: dict[str, Any]) -> None`
+- `pipelex/cli/agent_cli/commands/agent_output.py:410` — `extract_validation_errors` — `def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]`
+- `pipelex/cli/agent_cli/commands/check_model_cmd.py:21` — `_format_check_markdown` — `def _format_check_markdown(result: dict[str, Any]) -> str`
+- `pipelex/cli/agent_cli/commands/concept_cmd.py:19` — `_concept_spec_to_toml` — `def _concept_spec_to_toml(concept_spec: ConceptSpec) -> str`
+- `pipelex/cli/agent_cli/commands/doctor_cmd.py:27` — `_status_icon` — `def _status_icon(healthy: bool) -> str`
+- `pipelex/cli/agent_cli/commands/doctor_cmd.py:32` — `_format_doctor_markdown` — `def _format_doctor_markdown(result: dict[str, Any]) -> str`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:34` — `_parse_config_arg` — `def _parse_config_arg(config_arg: str | None) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:67` — `_format_init_markdown` — `def _format_init_markdown(result: dict[str, Any]) -> str`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:88` — `_resolve_target_dir` — `def _resolve_target_dir(global_: bool) -> Path`
+- `pipelex/cli/agent_cli/commands/init_cmd.py:110` — `_copy_inference_templates` — `def _copy_inference_templates(target_dir: Path) -> None`
+- `pipelex/cli/agent_cli/commands/pipe_cmd.py:36` — `_pipe_spec_to_toml` — `def _pipe_spec_to_toml(pipe_spec: PipeSpec) -> str`
+- `pipelex/cli/agent_cli/commands/run/_output_helpers.py:52` — `_render_json_payload_lines` — `def _render_json_payload_lines(result_payload: Any) -> list[str]`
+- `pipelex/cli/agent_cli/commands/run/stdin_resolver.py:19` — `_extract_concept_code` — `def _extract_concept_code(concept_data: Any) -> str`
+- `pipelex/cli/agent_cli/commands/run/stdin_resolver.py:37` — `_extract_stuff_entry` — `def _extract_stuff_entry(stuff_data: dict[str, Any]) -> dict[str, Any] | None`
+- `pipelex/cli/agent_cli/commands/run/stdin_resolver.py:57` — `resolve_stdin_inputs` — `def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/cli/agent_cli/commands/run/stdin_resolver.py:155` — `_parse_inputs_arg` — `def _parse_inputs_arg(inputs_arg: str) -> dict[str, Any] | None`
+- `pipelex/cli/agent_cli/commands/validate/_output_helpers.py:8` — `format_validate_markdown` — `def format_validate_markdown(result: dict[str, Any]) -> str`
+- `pipelex/cli/commands/build/structures_cmd.py:34` — `_compute_relative_path_from_output_dir` — `def _compute_relative_path_from_output_dir(output_directory: Path) -> Path | None`
+- `pipelex/cli/commands/doctor_cmd.py:109` — `check_config_files` — `def check_config_files(config_dir: Path | None=None) -> tuple[bool, int, str]`
+- `pipelex/cli/commands/doctor_cmd.py:162` — `check_telemetry_config` — `def check_telemetry_config(config_dir: Path | None=None) -> tuple[bool, str]`
+- `pipelex/cli/commands/doctor_cmd.py:191` — `check_backend_credentials` — `def check_backend_credentials(config_dir: Path | None=None) -> tuple[bool, dict[str, BackendCredentialsReport], str]`
+- `pipelex/cli/commands/doctor_cmd.py:268` — `check_kit_template_exists` — `def check_kit_template_exists(backend_name: str) -> bool`
+- `pipelex/cli/commands/doctor_cmd.py:333` — `check_backend_files` — `def check_backend_files(config_dir: Path | None=None) -> tuple[bool, dict[str, BackendFileReport], str]`
+- `pipelex/cli/commands/doctor_cmd.py:706` — `check_deck_sync` — `def check_deck_sync(config_dir: Path | None=None) -> tuple[bool, DeckSyncReport, str]`
+- `pipelex/cli/commands/doctor_cmd.py:796` — `check_models` — `def check_models(config_dir: Path | None=None) -> tuple[bool, str, dict[str, BackendFileReport]]`
+- `pipelex/cli/commands/doctor_cmd.py:894` — `doctor_cmd` — `def doctor_cmd(fix: bool=False) -> None`
+- `pipelex/cli/commands/doctor_cmd.py:918` — `do_doctor_cmd` — `def do_doctor_cmd(fix: bool=False) -> None`
+- `pipelex/cli/commands/init/backends.py:49` — `get_selected_backend_keys` — `def get_selected_backend_keys(backends_toml_path: Path) -> list[str]`
+- `pipelex/cli/commands/init/backends.py:76` — `disable_gateway_backend` — `def disable_gateway_backend(backends_toml_path: Path) -> None`
+- `pipelex/cli/commands/init/command.py:61` — `attempt_prime_remote_config_cache` — `def attempt_prime_remote_config_cache(target_config_dir: Path | None=None) -> CachePrimingResult`
+- `pipelex/cli/commands/init/command.py:427` — `_init_agreement` — `def _init_agreement(console: Console) -> None`
+- `pipelex/cli/commands/init/credentials.py:23` — `read_env_file` — `def read_env_file(env_path: Path) -> dict[str, str]`
+- `pipelex/cli/commands/init/credentials.py:72` — `get_required_vars_for_enabled_backends` — `def get_required_vars_for_enabled_backends(backends_toml_path: Path) -> dict[str, list[str]]`
+- `pipelex/cli/commands/init/ide_extension.py:26` — `_is_extension_installed` — `def _is_extension_installed(cmd: str) -> bool`
+- `pipelex/cli/commands/init/ide_extension.py:89` — `suggest_extension_install_if_needed` — `def suggest_extension_install_if_needed(console: Console) -> None`
+- `pipelex/cli/commands/init/ui/gateway_ui.py:94` — `prompt_gateway_acceptance` — `def prompt_gateway_acceptance(console: Console) -> bool`
+- `pipelex/cli/commands/init/ui/gateway_ui.py:114` — `display_gateway_declined_message` — `def display_gateway_declined_message(console: Console) -> None`
+- `pipelex/cli/commands/init/ui/gateway_ui.py:136` — `display_gateway_accepted_message` — `def display_gateway_accepted_message(console: Console) -> None`
+- `pipelex/cli/commands/login/command.py:115` — `save_api_key` — `def save_api_key(api_key: str) -> None`
+- `pipelex/cli/commands/run/_inputs_path_resolver.py:19` — `is_relative_local_path` — `def is_relative_local_path(uri: str) -> bool`
+- `pipelex/cli/commands/show_cmd.py:65` — `do_show_pipe` — `def do_show_pipe(pipe_code: str) -> None`
+- `pipelex/cli/commands/show_cmd.py:72` — `do_show_backends` — `def do_show_backends(show_all: bool=False) -> None`
+- `pipelex/cli/commands/update_cmd.py:91` — `_resolve_deck_dir` — `def _resolve_deck_dir(local: bool) -> Path`
+- `pipelex/cli/commands/update_cmd.py:124` — `_action_description` — `def _action_description(status: DeckFileStatus) -> str`
+- `pipelex/cli/commands/validate/_validate_core.py:47` — `_format_signatures_summary_suffix` — `def _format_signatures_summary_suffix(signature_count: int) -> str`
+- `pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py:29` — `_print_report` — `def _print_report(violations: list[Violation]) -> None`
+- `pipelex/cli/dev_cli/commands/check_keyword_only_cmd.py:136` — `_print_violation_lines` — `def _print_violation_lines(violations: list[Violation]) -> None`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:30` — `normalize_for_comparison` — `def normalize_for_comparison(content: str) -> str`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:54` — `extract_reference_data` — `def extract_reference_data(model_specs: BackendModelSpecs) -> dict[str, list[dict[str, Any]]]`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:107` — `generate_pure_markdown_list` — `def generate_pure_markdown_list(models: list[dict[str, Any]]) -> str`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:145` — `generate_markdown_table` — `def generate_markdown_table(models: list[dict[str, Any]]) -> str`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:222` — `generate_reference_markdown` — `def generate_reference_markdown(model_specs: BackendModelSpecs) -> str`
+- `pipelex/cli/dev_cli/commands/gateway_models_generator.py:274` — `generate_reference_pure_markdown` — `def generate_reference_pure_markdown(model_specs: BackendModelSpecs) -> str`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:124` — `_attribute_tail` — `def _attribute_tail(node: ast.expr) -> tuple[str, ...]`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:137` — `_decorator_matches_carveout` — `def _decorator_matches_carveout(decorator: ast.expr) -> bool`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:165` — `_has_carveout_decorator` — `def _has_carveout_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:170` — `_iter_subscript_metadata` — `def _iter_subscript_metadata(annotation: ast.expr) -> Iterator[ast.expr]`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:179` — `_callee_name` — `def _callee_name(func: ast.expr) -> str | None`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:188` — `_annotation_has_typer_metadata` — `def _annotation_has_typer_metadata(annotation: ast.expr | None) -> bool`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:203` — `_has_typer_param_annotation` — `def _has_typer_param_annotation(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:227` — `_is_dunder` — `def _is_dunder(name: str) -> bool`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:298` — `_Collector._visit_function` — `def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:349` — `_module_qname_for` — `def _module_qname_for(path: Path) -> str`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:357` — `iter_source_files` — `def iter_source_files(root: Path) -> Iterator[Path]`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:365` — `collect_all_violations` — `def collect_all_violations(root: Path) -> list[Violation]`
+- `pipelex/cli/dev_cli/commands/keyword_only_guard.py:443` — `main` — `def main(argv: list[str]) -> int`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:42` — `_extract_models_from_backend_toml` — `def _extract_models_from_backend_toml(backend_path: Path) -> dict[str, list[str]]`
+- `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:222` — `_load_test_profile` — `def _load_test_profile(profile_name: str) -> dict[str, Any]`
+- `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:93` — `_validate_sri` — `def _validate_sri(value: str) -> str`
+- `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:116` — `_sha384_sri` — `def _sha384_sri(payload: bytes) -> str`
+- `pipelex/cli/dev_cli/commands/refresh_graph_ui_sri_cmd.py:122` — `_python_string_literal` — `def _python_string_literal(value: str) -> str`
+- `pipelex/cli/dev_cli/commands/sync_main_config_cmd.py:30` — `_format_value` — `def _format_value(value: object) -> str`
+- `pipelex/cli/dev_cli/commands/update_gateway_models_cmd.py:65` — `update_gateway_models_cmd` — `def update_gateway_models_cmd(quiet: bool=False) -> None`
+- `pipelex/cli/error_handlers.py:57` — `set_traceback_requested` — `def set_traceback_requested(value: bool) -> None`
+- `pipelex/cli/error_handlers.py:80` — `print_traceback_if_requested` — `def print_traceback_if_requested(console: Console) -> None`
+- `pipelex/cli/error_handlers.py:370` — `handle_inference_setup_required_error` — `def handle_inference_setup_required_error(exc: InferenceSetupRequiredError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:396` — `handle_telemetry_config_validation_error` — `def handle_telemetry_config_validation_error(exc: TelemetryConfigValidationError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:426` — `handle_gateway_terms_not_accepted_error` — `def handle_gateway_terms_not_accepted_error(exc: GatewayTermsNotAcceptedError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:453` — `handle_gateway_api_key_missing_error` — `def handle_gateway_api_key_missing_error(exc: GatewayApiKeyMissingError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:483` — `handle_gateway_do_not_track_conflict_error` — `def handle_gateway_do_not_track_conflict_error(exc: GatewayDoNotTrackConflictError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:512` — `handle_remote_config_validation_error` — `def handle_remote_config_validation_error(exc: RemoteConfigValidationError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:549` — `handle_remote_config_unavailable_error` — `def handle_remote_config_unavailable_error(exc: RemoteConfigUnavailableError) -> NoReturn`
+- `pipelex/cli/error_handlers.py:582` — `handle_gateway_unknown_model_error` — `def handle_gateway_unknown_model_error(exc: GatewayUnknownModelError) -> NoReturn`
+- `pipelex/cli/installed_methods.py:142` — `discover_methods_from_library_dirs` — `def discover_methods_from_library_dirs(library_dirs: list[str]) -> list[InstalledMethod]`
+- `pipelex/cli/method_resolver.py:22` — `_get_all_exported_pipes` — `def _get_all_exported_pipes(method: InstalledMethod) -> set[str]`
+- `pipelex/cli/method_resolver.py:30` — `_find_method_by_exported_pipe` — `def _find_method_by_exported_pipe(pipe_code: str) -> InstalledMethod`
+- `pipelex/cli/method_resolver.py:63` — `is_github_url` — `def is_github_url(target: str) -> bool`
+- `pipelex/cli/method_resolver.py:68` — `parse_github_url` — `def parse_github_url(url: str) -> tuple[str, str | None]`
+- `pipelex/cli/method_resolver.py:127` — `is_local_path` — `def is_local_path(target: str) -> bool`
+- `pipelex/cli/method_resolver.py:134` — `resolve_method_from_path` — `def resolve_method_from_path(method_path: str) -> InstalledMethod`
+- `pipelex/cli/method_resolver.py:168` — `resolve_method_from_url` — `def resolve_method_from_url(url: str) -> InstalledMethod`
+- `pipelex/cli/method_resolver.py:294` — `resolve_pipe_from_exports` — `def resolve_pipe_from_exports(pipe_code: str) -> list[str] | None`
+
+### `cogt` (172)
+
+- `pipelex/cogt/config_cogt.py:89` — `LLMConfig.get_template` — `def get_template(self, template_name: str) -> str`
+- `pipelex/cogt/content_generation/assignment_models.py:43` — `LLMAssignment.clone_with_new_prompt` — `def clone_with_new_prompt(self, new_prompt: LLMPrompt) -> 'LLMAssignment'`
+- `pipelex/cogt/content_generation/content_generator_protocol.py:26` — `update_job_metadata` — `def update_job_metadata(func: Callable[P, Coroutine[Any, Any, R]]) -> Callable[P, Coroutine[Any, Any, R]]`
+- `pipelex/cogt/content_generation/content_generator_protocol.py:142` — `ContentGeneratorProtocol.make_search_sourced_answer` — `def make_search_sourced_answer(self, search_assignment: SearchAssignment) -> Coroutine[Any, Any, SearchResultContent]`
+- `pipelex/cogt/content_generation/dry_mock.py:167` — `build_mock_object` — `def build_mock_object(model_class: type[BaseModelTypeVar], **field_values: Any) -> BaseModelTypeVar`
+- `pipelex/cogt/content_generation/dry_mock.py:200` — `_reconstruct_object_class` — `def _reconstruct_object_class(object_assignment: ObjectAssignment) -> type[BaseModel]`
+- `pipelex/cogt/content_generation/dry_mock.py:214` — `stamp_mock_main_coordination` — `def stamp_mock_main_coordination(items: Sequence[Any]) -> None`
+- `pipelex/cogt/content_generation/dry_mock.py:229` — `_nb_list_items` — `def _nb_list_items(object_assignment: ObjectAssignment) -> int`
+- `pipelex/cogt/content_generation/dry_mock.py:278` — `_dry_report_func` — `def _dry_report_func(cogt_run_params: CogtRunParams) -> _ReportLLMJobFunc`
+- `pipelex/cogt/content_generation/dry_mock.py:293` — `dry_llm_gen_text` — `def dry_llm_gen_text(llm_assignment: LLMAssignment) -> str`
+- `pipelex/cogt/content_generation/dry_mock.py:303` — `dry_llm_gen_object` — `def dry_llm_gen_object(object_assignment: ObjectAssignment) -> BaseModel`
+- `pipelex/cogt/content_generation/dry_mock.py:309` — `dry_llm_gen_object_list` — `def dry_llm_gen_object_list(object_assignment: ObjectAssignment) -> list[BaseModel]`
+- `pipelex/cogt/content_generation/dry_mock.py:323` — `dry_templating_gen_text` — `def dry_templating_gen_text(templating_assignment: TemplatingAssignment) -> str`
+- `pipelex/cogt/content_generation/dry_mock.py:356` — `dry_img_gen_image_contents` — `def dry_img_gen_image_contents(img_gen_assignment: ImgGenAssignment) -> list[ImageContent]`
+- `pipelex/cogt/content_generation/dry_mock.py:370` — `dry_extract_page_contents` — `def dry_extract_page_contents(extract_assignment: ExtractAssignment) -> list[PageContent]`
+- `pipelex/cogt/content_generation/dry_mock.py:394` — `dry_render_page_views` — `def dry_render_page_views(render_assignment: RenderPageViewsAssignment) -> list[ImageContent]`
+- `pipelex/cogt/content_generation/dry_mock.py:406` — `dry_search_gen_sourced_answer` — `def dry_search_gen_sourced_answer(search_assignment: SearchAssignment) -> SearchResultContent`
+- `pipelex/cogt/content_generation/dry_mock.py:414` — `dry_search_gen_structured` — `def dry_search_gen_structured(search_object_assignment: SearchObjectAssignment) -> dict[str, Any]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:64` — `DryRunFactory.generate_dict_snake_key_pascal_value` — `def generate_dict_snake_key_pascal_value(cls, num_items: int=2) -> dict[str, str]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:97` — `DryRunFactory._get_examples_from_field` — `def _get_examples_from_field(cls, field_info: FieldInfo) -> list[Any] | None`
+- `pipelex/cogt/content_generation/dry_run_factory.py:107` — `DryRunFactory._get_mock_format_from_field` — `def _get_mock_format_from_field(cls, field_info: FieldInfo) -> MockFormat | None`
+- `pipelex/cogt/content_generation/dry_run_factory.py:133` — `DryRunFactory._detect_examples_constraints` — `def _detect_examples_constraints(cls, object_class: type[BaseModelTypeVar]) -> dict[str, list[Any]]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:143` — `DryRunFactory._get_literal_values_from_annotation` — `def _get_literal_values_from_annotation(cls, annotation: Any) -> tuple[Any, ...] | None`
+- `pipelex/cogt/content_generation/dry_run_factory.py:168` — `DryRunFactory._detect_literal_fields` — `def _detect_literal_fields(cls, object_class: type[BaseModel]) -> dict[str, tuple[Any, ...]]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:188` — `DryRunFactory._make_example_picker` — `def _make_example_picker(examples: list[Any]) -> Callable[[], Any]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:238` — `DryRunFactory._extract_types_from_annotation` — `def _extract_types_from_annotation(cls, annotation: Any) -> list[Any]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:258` — `DryRunFactory._create_nested_factory` — `def _create_nested_factory(cls, nested_class: type[BaseModel]) -> type[ModelFactory[Any]]`
+- `pipelex/cogt/content_generation/dry_run_factory.py:318` — `DryRunFactory._detect_format_constraints` — `def _detect_format_constraints(cls, object_class: type[BaseModelTypeVar]) -> dict[MockFormat, set[str]]`
+- `pipelex/cogt/content_generation/exceptions.py:35` — `DryRunObjectFidelityError.for_object_class` — `def for_object_class(cls, object_class_name: str) -> 'DryRunObjectFidelityError'`
+- `pipelex/cogt/content_generation/exceptions.py:63` — `DryRunMockBuildError.for_object_class` — `def for_object_class(cls, object_class_name: str) -> 'DryRunMockBuildError'`
+- `pipelex/cogt/content_generation/extract_generate.py:10` — `extract_gen_pages` — `async def extract_gen_pages(extract_assignment: ExtractAssignment) -> ExtractOutput`
+- `pipelex/cogt/content_generation/generated_content_factory.py:65` — `GeneratedContentFactory._fetch_remote_content` — `async def _fetch_remote_content(self, url: str) -> bytes`
+- `pipelex/cogt/content_generation/img_gen_generate.py:11` — `img_gen_single_image` — `async def img_gen_single_image(img_gen_assignment: ImgGenAssignment) -> GeneratedImageRawDetails`
+- `pipelex/cogt/content_generation/img_gen_generate.py:24` — `img_gen_image_list` — `async def img_gen_image_list(img_gen_assignment: ImgGenAssignment) -> list[GeneratedImageRawDetails]`
+- `pipelex/cogt/content_generation/llm_generate.py:17` — `llm_gen_text` — `async def llm_gen_text(llm_assignment: LLMAssignment) -> str`
+- `pipelex/cogt/content_generation/llm_generate.py:31` — `llm_gen_object` — `async def llm_gen_object(object_assignment: ObjectAssignment) -> BaseModel`
+- `pipelex/cogt/content_generation/llm_generate.py:52` — `llm_gen_object_list` — `async def llm_gen_object_list(object_assignment: ObjectAssignment) -> list[BaseModel]`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:115` — `SchemaToModelFactory._normalize_class_name` — `def _normalize_class_name(cls, title: str) -> str`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:146` — `SchemaToModelFactory._reject_unsafe_schema_extensions` — `def _reject_unsafe_schema_extensions(cls, schema: dict[str, Any]) -> None`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:161` — `SchemaToModelFactory._generate_source_from_schema` — `def _generate_source_from_schema(cls, schema: dict[str, Any]) -> str`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:241` — `SchemaToModelFactory._exec_source_to_types` — `def _exec_source_to_types(cls, source_code: str) -> dict[str, type[Any]]`
+- `pipelex/cogt/content_generation/schema_to_model_factory.py:289` — `SchemaToModelFactory.make_types_from_source` — `def make_types_from_source(cls, source_code: str) -> dict[str, type[Any]]`
+- `pipelex/cogt/content_generation/search_generate.py:25` — `_make_search_worker` — `def _make_search_worker(search_assignment: SearchAssignment) -> SearchWorkerAbstract`
+- `pipelex/cogt/content_generation/search_generate.py:34` — `_make_search_job` — `def _make_search_job(search_assignment: SearchAssignment) -> SearchJob`
+- `pipelex/cogt/content_generation/search_generate.py:46` — `search_gen_sourced_answer` — `async def search_gen_sourced_answer(search_assignment: SearchAssignment) -> SearchResultContent`
+- `pipelex/cogt/content_generation/search_generate.py:54` — `search_gen_structured` — `async def search_gen_structured(search_object_assignment: SearchObjectAssignment) -> dict[str, Any]`
+- `pipelex/cogt/content_generation/templating_generate.py:6` — `templating_gen_text` — `async def templating_gen_text(templating_assignment: TemplatingAssignment) -> str`
+- `pipelex/cogt/document/prompt_document.py:71` — `PromptDocumentUri.get_content_hash` — `def get_content_hash(self, length: int | None=None) -> str`
+- `pipelex/cogt/document/prompt_document.py:112` — `PromptDocumentBase64.get_content_hash` — `def get_content_hash(self, length: int | None=None) -> str`
+- `pipelex/cogt/document/prompt_document.py:145` — `PromptDocumentBinary.get_content_hash` — `def get_content_hash(self, length: int | None=None) -> str`
+- `pipelex/cogt/document/prompt_document_utils.py:114` — `prepare_prompt_document_as_base64` — `async def prepare_prompt_document_as_base64(prompt_document: PromptDocument) -> PreparedFileBase64`
+- `pipelex/cogt/exceptions.py:112` — `find_inference_error_category_in_chain` — `def find_inference_error_category_in_chain(exc: BaseException) -> InferenceErrorCategory | None`
+- `pipelex/cogt/extract/extract_job.py:22` — `ExtractJob.extract_job_before_start` — `def extract_job_before_start(self, inference_model: InferenceModelSpec)`
+- `pipelex/cogt/extract/extract_report.py:25` — `ExtractTokenCostReportField.report_field_for_nb_tokens_by_category` — `def report_field_for_nb_tokens_by_category(token_category: TokenCategory) -> str`
+- `pipelex/cogt/extract/extract_report.py:29` — `ExtractTokenCostReportField.report_field_for_cost_by_category` — `def report_field_for_cost_by_category(token_category: CostCategory) -> str`
+- `pipelex/cogt/extract/extract_worker_abstract.py:53` — `ExtractWorkerAbstract._check_can_perform_job` — `def _check_can_perform_job(self, extract_job: ExtractJob)`
+- `pipelex/cogt/extract/extract_worker_abstract.py:69` — `ExtractWorkerAbstract.extract_pages` — `async def extract_pages(self, extract_job: ExtractJob) -> ExtractOutput`
+- `pipelex/cogt/extract/extract_worker_abstract.py:111` — `ExtractWorkerAbstract._extract_pages` — `async def _extract_pages(self, extract_job: ExtractJob) -> ExtractOutput`
+- `pipelex/cogt/image/prompt_image_utils.py:115` — `prepare_prompt_image_as_base64` — `async def prepare_prompt_image_as_base64(prompt_image: PromptImage) -> PreparedFileBase64`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:231` — `ImgGenArgsFactory.make_args_from_specific` — `def make_args_from_specific(cls, specific_taxonomy: SpecificTaxonomy) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_args_factory.py:509` — `ImgGenArgsFactory.make_args_from_output_compression` — `def make_args_from_output_compression(cls, output_compression_taxonomy: OutputCompressionTaxonomy) -> dict[str, Any]`
+- `pipelex/cogt/img_gen/img_gen_job.py:22` — `ImgGenJob.img_gen_job_before_start` — `def img_gen_job_before_start(self, inference_model: InferenceModelSpec)`
+- `pipelex/cogt/img_gen/img_gen_report.py:25` — `ImgGenTokenCostReportField.report_field_for_nb_tokens_by_category` — `def report_field_for_nb_tokens_by_category(token_category: TokenCategory) -> str`
+- `pipelex/cogt/img_gen/img_gen_report.py:29` — `ImgGenTokenCostReportField.report_field_for_cost_by_category` — `def report_field_for_cost_by_category(token_category: CostCategory) -> str`
+- `pipelex/cogt/img_gen/img_gen_worker_abstract.py:38` — `ImgGenWorkerAbstract._check_can_perform_job` — `def _check_can_perform_job(self, img_gen_job: ImgGenJob)`
+- `pipelex/cogt/img_gen/img_gen_worker_abstract.py:42` — `ImgGenWorkerAbstract.gen_image` — `async def gen_image(self, img_gen_job: ImgGenJob) -> GeneratedImageRawDetails`
+- `pipelex/cogt/img_gen/img_gen_worker_abstract.py:75` — `ImgGenWorkerAbstract._gen_image` — `async def _gen_image(self, img_gen_job: ImgGenJob) -> GeneratedImageRawDetails`
+- `pipelex/cogt/inference/error_classification.py:231` — `_is_quota_exhaustion_openai` — `def _is_quota_exhaustion_openai(error_message: str) -> bool`
+- `pipelex/cogt/inference/error_classification.py:237` — `_is_quota_exhaustion_anthropic` — `def _is_quota_exhaustion_anthropic(error_message: str) -> bool`
+- `pipelex/cogt/inference/error_classification.py:243` — `_is_quota_exhaustion_google` — `def _is_quota_exhaustion_google(error_message: str) -> bool`
+- `pipelex/cogt/inference/error_classification.py:288` — `_is_content_policy_violation` — `def _is_content_policy_violation(error_message: str) -> bool`
+- `pipelex/cogt/inference/error_classification.py:294` — `_stringify_for_scan` — `def _stringify_for_scan(body: Any) -> str`
+- `pipelex/cogt/inference/error_classification.py:308` — `extract_underlying_sdk_exception` — `def extract_underlying_sdk_exception(instructor_exc: Any) -> BaseException | None`
+- `pipelex/cogt/inference/error_classification.py:345` — `_parse_retry_after_seconds` — `def _parse_retry_after_seconds(value: Any) -> float | None`
+- `pipelex/cogt/inference/error_classification.py:370` — `_provider_error_code_from_body` — `def _provider_error_code_from_body(body: Any) -> str | None`
+- `pipelex/cogt/inference/error_classification.py:383` — `extract_openai_metadata` — `def extract_openai_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:430` — `extract_anthropic_metadata` — `def extract_anthropic_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:465` — `_provider_error_code_from_flat_body` — `def _provider_error_code_from_flat_body(body: Any) -> str | None`
+- `pipelex/cogt/inference/error_classification.py:481` — `_parse_response_text_body` — `def _parse_response_text_body(response: Any) -> tuple[Any | None, str | None]`
+- `pipelex/cogt/inference/error_classification.py:510` — `_google_provider_error_code_from_details` — `def _google_provider_error_code_from_details(details: Any) -> str | None`
+- `pipelex/cogt/inference/error_classification.py:533` — `extract_google_metadata` — `def extract_google_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:570` — `extract_azure_metadata` — `def extract_azure_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:623` — `extract_fal_metadata` — `def extract_fal_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:662` — `extract_huggingface_metadata` — `def extract_huggingface_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:695` — `extract_gateway_metadata` — `def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:729` — `extract_mistral_metadata` — `def extract_mistral_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:796` — `extract_bedrock_metadata` — `def extract_bedrock_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classification.py:843` — `extract_linkup_metadata` — `def extract_linkup_metadata(exc: BaseException) -> ProviderErrorMetadata`
+- `pipelex/cogt/inference/error_classify.py:73` — `_classify_statusless` — `def _classify_statusless(metadata: SDKErrorEnvelope) -> ClassificationResult`
+- `pipelex/cogt/inference/error_classify.py:97` — `classify_inference_error` — `def classify_inference_error(metadata: SDKErrorEnvelope) -> ClassificationResult`
+- `pipelex/cogt/inference/inference_constants.py:11` — `InferenceOutputType.is_text` — `def is_text(cls, output_desc: str) -> bool`
+- `pipelex/cogt/inference/inference_manager.py:53` — `InferenceManager._setup_one_internal_llm_worker` — `def _setup_one_internal_llm_worker(self, llm_handle: str) -> LLMWorkerInternalAbstract`
+- `pipelex/cogt/inference/inference_manager.py:88` — `InferenceManager._setup_one_img_gen_worker` — `def _setup_one_img_gen_worker(self, img_gen_handle: str) -> ImgGenWorkerAbstract`
+- `pipelex/cogt/inference/inference_manager.py:109` — `InferenceManager._setup_one_extract_worker` — `def _setup_one_extract_worker(self, extract_handle: str) -> ExtractWorkerAbstract`
+- `pipelex/cogt/inference/inference_manager_protocol.py:19` — `InferenceManagerProtocol.get_llm_worker` — `def get_llm_worker(self, llm_handle: str) -> LLMWorkerAbstract`
+- `pipelex/cogt/inference/inference_manager_protocol.py:33` — `InferenceManagerProtocol.get_img_gen_worker` — `def get_img_gen_worker(self, img_gen_handle: str) -> ImgGenWorkerAbstract`
+- `pipelex/cogt/inference/inference_manager_protocol.py:39` — `InferenceManagerProtocol.get_extract_worker` — `def get_extract_worker(self, extract_handle: str) -> ExtractWorkerAbstract`
+- `pipelex/cogt/inference/transport_retry.py:49` — `_parse_retry_after` — `def _parse_retry_after(raw_value: str | None) -> float | None`
+- `pipelex/cogt/inference/transport_retry.py:69` — `_transport_retry_wait` — `def _transport_retry_wait(retry_state: RetryCallState) -> float`
+- `pipelex/cogt/inference/transport_retry.py:81` — `_make_retry_predicate` — `def _make_retry_predicate(retry_on_ambiguous_failure: bool) -> Callable[[BaseException], bool]`
+- `pipelex/cogt/inference/transport_retry.py:91` — `_make_retry_predicate.should_retry` — `def should_retry(exc: BaseException) -> bool`
+- `pipelex/cogt/llm/instructor_retry.py:7` — `make_instructor_schema_retrying` — `def make_instructor_schema_retrying(max_attempts: int) -> AsyncRetrying`
+- `pipelex/cogt/llm/llm_job.py:28` — `LLMJob.llm_job_before_start` — `def llm_job_before_start(self, inference_model: InferenceModelSpec)`
+- `pipelex/cogt/llm/llm_prompt.py:54` — `LLMPrompt.desc` — `def desc(self, truncate_text_length: int | None=None) -> str`
+- `pipelex/cogt/llm/llm_prompt_template_inputs.py:50` — `LLMPromptTemplateInputs.complemented_by` — `def complemented_by(self, additional_template_inputs: LLMPromptTemplateInputs | None) -> LLMPromptTemplateInputs`
+- `pipelex/cogt/llm/llm_prompt_template_inputs.py:56` — `LLMPromptTemplateInputs.complemented_by_dict` — `def complemented_by_dict(self, additional_inputs_dict: LLMPromptTemplateInputsDict | None) -> LLMPromptTemplateInputs`
+- `pipelex/cogt/llm/llm_report.py:25` — `LLMTokenCostReportField.report_field_for_nb_tokens_by_category` — `def report_field_for_nb_tokens_by_category(token_category: TokenCategory) -> str`
+- `pipelex/cogt/llm/llm_report.py:29` — `LLMTokenCostReportField.report_field_for_cost_by_category` — `def report_field_for_cost_by_category(token_category: CostCategory) -> str`
+- `pipelex/cogt/llm/llm_utils.py:7` — `dump_prompt` — `def dump_prompt(llm_prompt: LLMPrompt) -> None`
+- `pipelex/cogt/llm/llm_utils.py:22` — `dump_response_from_text_gen` — `def dump_response_from_text_gen(response: Any) -> None`
+- `pipelex/cogt/llm/llm_utils.py:30` — `dump_response_from_structured_gen` — `def dump_response_from_structured_gen(response: Any) -> None`
+- `pipelex/cogt/llm/llm_utils.py:34` — `dump_error` — `def dump_error(error: Exception) -> None`
+- `pipelex/cogt/llm/llm_worker_abstract.py:317` — `LLMWorkerAbstract._before_job` — `async def _before_job(self, llm_job: LLMJob)`
+- `pipelex/cogt/llm/llm_worker_abstract.py:357` — `LLMWorkerAbstract._check_can_perform_job` — `def _check_can_perform_job(self, llm_job: LLMJob)`
+- `pipelex/cogt/llm/llm_worker_abstract.py:361` — `LLMWorkerAbstract.gen_text` — `async def gen_text(self, llm_job: LLMJob) -> str`
+- `pipelex/cogt/llm/llm_worker_abstract.py:392` — `LLMWorkerAbstract._gen_text` — `async def _gen_text(self, llm_job: LLMJob) -> str`
+- `pipelex/cogt/llm/llm_worker_internal_abstract.py:88` — `LLMWorkerInternalAbstract._apply_constraints` — `def _apply_constraints(self, llm_job: LLMJob) -> LLMJobParams | None`
+- `pipelex/cogt/llm/llm_worker_internal_abstract.py:152` — `LLMWorkerInternalAbstract._validate_no_reasoning_for_structured_gen` — `def _validate_no_reasoning_for_structured_gen(self, job_params: LLMJobParams)`
+- `pipelex/cogt/llm/llm_worker_internal_abstract.py:157` — `LLMWorkerInternalAbstract._check_vision_support` — `def _check_vision_support(self, llm_job: LLMJob)`
+- `pipelex/cogt/llm/llm_worker_internal_abstract.py:169` — `LLMWorkerInternalAbstract._check_document_support` — `def _check_document_support(self, llm_job: LLMJob)`
+- `pipelex/cogt/model_backends/backend.py:27` — `PipelexBackend.is_gateway_backend` — `def is_gateway_backend(cls, backend_name: str) -> bool`
+- `pipelex/cogt/model_backends/backend.py:54` — `InferenceBackend.get_model_spec` — `def get_model_spec(self, model_name: str) -> InferenceModelSpec | None`
+- `pipelex/cogt/model_backends/backend.py:58` — `InferenceBackend.get_extra_config` — `def get_extra_config(self, key: str) -> Any | None`
+- `pipelex/cogt/model_backends/backend_library.py:392` — `InferenceBackendLibrary.get_inference_backend` — `def get_inference_backend(self, backend_name: str) -> InferenceBackend | None`
+- `pipelex/cogt/models/deck_manifest.py:77` — `DeckSyncReport.files_with_status` — `def files_with_status(self, status: DeckFileStatus) -> list[str]`
+- `pipelex/cogt/models/deck_manifest.py:81` — `compute_sha256` — `def compute_sha256(data: bytes) -> str`
+- `pipelex/cogt/models/deck_manifest.py:85` — `compute_file_sha256` — `def compute_file_sha256(path: Path) -> str`
+- `pipelex/cogt/models/deck_manifest.py:98` — `_is_managed_deck_filename` — `def _is_managed_deck_filename(filename: str) -> bool`
+- `pipelex/cogt/models/deck_manifest.py:119` — `list_managed_installed_files` — `def list_managed_installed_files(deck_dir: Path) -> dict[str, str]`
+- `pipelex/cogt/models/deck_manifest.py:133` — `manifest_path` — `def manifest_path(deck_dir: Path) -> Path`
+- `pipelex/cogt/models/deck_manifest.py:137` — `read_manifest` — `def read_manifest(deck_dir: Path) -> DeckManifest | None`
+- `pipelex/cogt/models/deck_manifest.py:163` — `is_deck_stale_fast` — `def is_deck_stale_fast(deck_dir: Path) -> bool`
+- `pipelex/cogt/models/deck_manifest.py:193` — `_try_parse_version` — `def _try_parse_version(version: str) -> tuple[int, ...] | None`
+- `pipelex/cogt/models/deck_manifest.py:206` — `status_rich_label` — `def status_rich_label(status: DeckFileStatus) -> str`
+- `pipelex/cogt/models/deck_manifest.py:221` — `suggest_x_custom_filename` — `def suggest_x_custom_filename(numbered_filename: str) -> str`
+- `pipelex/cogt/models/deck_manifest.py:233` — `compute_deck_sync_report` — `def compute_deck_sync_report(deck_dir: Path) -> DeckSyncReport`
+- `pipelex/cogt/models/model_deck.py:123` — `ModelDeck.get_aliases_and_waterfalls_for_type` — `def get_aliases_and_waterfalls_for_type(self, model_type: ModelType) -> tuple[dict[str, str], dict[str, list[str]]]`
+- `pipelex/cogt/models/model_deck.py:163` — `ModelDeck._warn_if_ambiguous_llm` — `def _warn_if_ambiguous_llm(self, name: str) -> None`
+- `pipelex/cogt/models/model_deck.py:177` — `ModelDeck._warn_if_ambiguous_extract` — `def _warn_if_ambiguous_extract(self, name: str) -> None`
+- `pipelex/cogt/models/model_deck.py:191` — `ModelDeck._warn_if_ambiguous_img_gen` — `def _warn_if_ambiguous_img_gen(self, name: str) -> None`
+- `pipelex/cogt/models/model_deck.py:205` — `ModelDeck._warn_if_ambiguous_search` — `def _warn_if_ambiguous_search(self, name: str) -> None`
+- `pipelex/cogt/models/model_deck.py:309` — `ModelDeck.get_llm_setting` — `def get_llm_setting(self, llm_choice: LLMModelChoice) -> LLMSetting`
+- `pipelex/cogt/models/model_deck.py:362` — `ModelDeck.get_extract_setting` — `def get_extract_setting(self, extract_choice: ExtractModelChoice) -> ExtractSetting`
+- `pipelex/cogt/models/model_deck.py:411` — `ModelDeck.get_search_setting` — `def get_search_setting(self, search_choice: SearchModelChoice) -> SearchSetting`
+- `pipelex/cogt/models/model_deck.py:460` — `ModelDeck.get_img_gen_setting` — `def get_img_gen_setting(self, img_gen_choice: ImgGenModelChoice) -> ImgGenSetting`
+- `pipelex/cogt/models/model_deck.py:510` — `ModelDeck.final_validate` — `def final_validate(cls, deck: Self)`
+- `pipelex/cogt/models/model_deck_check.py:41` — `check_llm_choice_with_deck` — `def check_llm_choice_with_deck(llm_choice: LLMModelChoice) -> None`
+- `pipelex/cogt/models/model_deck_check.py:103` — `check_extract_choice_with_deck` — `def check_extract_choice_with_deck(extract_choice: ExtractModelChoice) -> None`
+- `pipelex/cogt/models/model_deck_check.py:165` — `check_search_choice_with_deck` — `def check_search_choice_with_deck(search_choice: SearchModelChoice) -> None`
+- `pipelex/cogt/models/model_deck_check.py:227` — `check_img_gen_choice_with_deck` — `def check_img_gen_choice_with_deck(img_gen_choice: ImgGenModelChoice) -> None`
+- `pipelex/cogt/models/model_deck_loader.py:12` — `load_model_deck_blueprint` — `def load_model_deck_blueprint(model_deck_paths: list[str]) -> ModelDeckBlueprint`
+- `pipelex/cogt/models/model_manager.py:44` — `ModelManager.get_model_deck_paths` — `def get_model_deck_paths(cls, deck_dir_path: str) -> list[str]`
+- `pipelex/cogt/models/model_manager.py:143` — `ModelManager._collect_deck_referenced_handles` — `def _collect_deck_referenced_handles(cls, deck: ModelDeck) -> list[tuple[str, ModelType]]`
+- `pipelex/cogt/models/model_manager.py:178` — `ModelManager._extract_choice_handle` — `def _extract_choice_handle(cls, choice: LLMSetting | ExtractSetting | ImgGenSetting | SearchSetting | ModelReference | str | None) -> str | None`
+- `pipelex/cogt/models/model_manager_abstract.py:41` — `ModelManagerAbstract.get_required_inference_backend` — `def get_required_inference_backend(self, backend_name: str) -> InferenceBackend`
+- `pipelex/cogt/models/model_reference.py:63` — `ModelReference.parse` — `def parse(cls, value: str) -> 'ModelReference'`
+- `pipelex/cogt/models/model_reference.py:165` — `ensure_model_reference` — `def ensure_model_reference(value: str | ModelReference) -> ModelReference`
+- `pipelex/cogt/models/model_reference.py:175` — `parse_model_reference` — `def parse_model_reference(value: Any) -> ModelReference | Any`
+- `pipelex/cogt/search/search_job.py:33` — `SearchJob.search_job_before_start` — `def search_job_before_start(self, inference_model: InferenceModelSpec)`
+- `pipelex/cogt/search/search_report.py:25` — `SearchTokenCostReportField.report_field_for_nb_tokens_by_category` — `def report_field_for_nb_tokens_by_category(token_category: TokenCategory) -> str`
+- `pipelex/cogt/search/search_report.py:29` — `SearchTokenCostReportField.report_field_for_cost_by_category` — `def report_field_for_cost_by_category(token_category: CostCategory) -> str`
+- `pipelex/cogt/search/search_worker_abstract.py:31` — `SearchWorkerAbstract.search_sourced_answer` — `async def search_sourced_answer(self, search_job: SearchJob) -> SearchResultContent`
+- `pipelex/cogt/search/search_worker_abstract.py:78` — `SearchWorkerAbstract._search_sourced_answer` — `async def _search_sourced_answer(self, search_job: SearchJob) -> SearchResultContent`
+- `pipelex/cogt/search/search_worker_factory.py:9` — `SearchWorkerFactory.make_search_worker` — `def make_search_worker(cls, inference_model: InferenceModelSpec) -> SearchWorkerAbstract`
+- `pipelex/cogt/templating/template_preprocessor.py:73` — `_replace_at_sigil` — `def _replace_at_sigil(match: Match[str]) -> str`
+- `pipelex/cogt/templating/template_preprocessor.py:86` — `_replace_dollar_sigil` — `def _replace_dollar_sigil(match: Match[str]) -> str`
+- `pipelex/cogt/templating/template_preprocessor.py:139` — `_normalize_and_escape` — `def _normalize_and_escape(template: str) -> str`
+- `pipelex/cogt/templating/template_preprocessor.py:158` — `rewrite_template_sigils` — `def rewrite_template_sigils(template: str) -> str`
+- `pipelex/cogt/usage/cost_registry.py:218` — `CostRegistry.aggregate_costs` — `def aggregate_costs(cls, tokens_usages: Sequence[TokensUsage]) -> AggregatedCosts`
+- `pipelex/cogt/usage/cost_registry.py:283` — `CostRegistry.build_cost_summary` — `def build_cost_summary(cls, tokens_usages: Sequence[TokensUsage]) -> dict[str, Any] | None`
+- `pipelex/cogt/usage/cost_registry.py:314` — `CostRegistry.compute_cost_report` — `def compute_cost_report(cls, tokens_usage: TokensUsage) -> TokenCostReport`
+- `pipelex/cogt/usage/cost_registry.py:360` — `CostRegistry.complete_cost_report` — `def complete_cost_report(cls, tokens_usage: TokensUsage) -> TokenCostReport`
+
+### `core` (118)
+
+- `pipelex/core/bundles/pipe_sorter.py:7` — `sort_pipes_by_dependencies` — `def sort_pipes_by_dependencies(pipes: dict[str, PipeBlueprintUnion]) -> list[tuple[str, PipeBlueprintUnion]]`
+- `pipelex/core/bundles/pipe_sorter.py:48` — `sort_pipes_by_dependencies.visit` — `def visit(pipe_code: str) -> None`
+- `pipelex/core/bundles/pipelex_bundle_blueprint.py:143` — `PipelexBundleBlueprint.get_elaboration_for` — `def get_elaboration_for(self, pipe_code: str) -> ElaborationMetadata | None`
+- `pipelex/core/concepts/concept.py:86` — `Concept.sentence_from_concept` — `def sentence_from_concept(cls, concept: 'Concept') -> str`
+- `pipelex/core/concepts/concept.py:90` — `Concept.is_native_concept` — `def is_native_concept(cls, concept: 'Concept') -> bool`
+- `pipelex/core/concepts/concept.py:167` — `Concept.is_valid_structure_class` — `def is_valid_structure_class(cls, structure_class_name: str) -> bool`
+- `pipelex/core/concepts/concept.py:227` — `Concept._render_schema_representation` — `def _render_schema_representation(self, is_multiple: bool=False) -> tuple[dict[str, Any], set[str]]`
+- `pipelex/core/concepts/concept_factory.py:98` — `ConceptFactory.make_native_concept` — `def make_native_concept(cls, native_concept_code: NativeConceptCode) -> Concept`
+- `pipelex/core/concepts/concept_representation_generator.py:183` — `ConceptRepresentationGenerator._unwrap_optional` — `def _unwrap_optional(self, field_type: Any) -> Any`
+- `pipelex/core/concepts/concept_representation_generator.py:227` — `ConceptRepresentationGenerator._generate_dict_value` — `def _generate_dict_value(self, field_name: str) -> dict[str, str]`
+- `pipelex/core/concepts/concept_representation_generator.py:266` — `ConceptRepresentationGenerator._generate_basemodel_representation` — `def _generate_basemodel_representation(self, model_class: type[BaseModel]) -> dict[str, Any] | str`
+- `pipelex/core/concepts/concept_representation_generator.py:347` — `ConceptRepresentationGenerator._format_python_value` — `def _format_python_value(self, value: Any) -> str`
+- `pipelex/core/concepts/helpers.py:52` — `strip_multiplicity_from_concept_ref_or_code` — `def strip_multiplicity_from_concept_ref_or_code(concept_ref_or_code: str) -> str`
+- `pipelex/core/concepts/helpers.py:66` — `normalize_structure_blueprint` — `def normalize_structure_blueprint(structure_dict: dict[str, str | ConceptStructureBlueprint]) -> dict[str, ConceptStructureBlueprint]`
+- `pipelex/core/concepts/helpers.py:111` — `extract_concept_code_from_concept_ref_or_code` — `def extract_concept_code_from_concept_ref_or_code(concept_ref_or_code: str) -> str`
+- `pipelex/core/concepts/native/concept_native.py:77` — `NativeConceptCode.is_native_structure_class` — `def is_native_structure_class(cls, class_name: str) -> bool`
+- `pipelex/core/concepts/native/concept_native.py:89` — `NativeConceptCode.get_native_structure_class` — `def get_native_structure_class(cls, class_name: str) -> type | None`
+- `pipelex/core/concepts/native/concept_native.py:107` — `NativeConceptCode.is_text_concept` — `def is_text_concept(cls, concept_code: str) -> bool`
+- `pipelex/core/concepts/native/concept_native.py:132` — `NativeConceptCode.is_dynamic_concept` — `def is_dynamic_concept(cls, concept_code: str) -> bool`
+- `pipelex/core/concepts/native/concept_native.py:165` — `NativeConceptCode.is_native_concept_ref_or_code` — `def is_native_concept_ref_or_code(cls, concept_ref_or_code: str) -> bool`
+- `pipelex/core/concepts/native/concept_native.py:176` — `NativeConceptCode.is_valid_native_concept_ref` — `def is_valid_native_concept_ref(cls, concept_ref: str) -> bool`
+- `pipelex/core/concepts/native/concept_native.py:195` — `NativeConceptCode.validate_native_concept_ref_or_code` — `def validate_native_concept_ref_or_code(cls, concept_ref_or_code: str) -> None`
+- `pipelex/core/concepts/native/concept_native.py:201` — `NativeConceptCode.get_validated_native_concept_ref` — `def get_validated_native_concept_ref(cls, concept_ref_or_code: str) -> str`
+- `pipelex/core/concepts/structure_generation/exceptions.py:16` — `SyntaxErrorData.from_syntax_error` — `def from_syntax_error(cls, syntax_error: SyntaxError) -> 'SyntaxErrorData'`
+- `pipelex/core/concepts/structure_generation/generator.py:173` — `StructureGenerator._escape_string_for_python` — `def _escape_string_for_python(self, value: str) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:205` — `StructureGenerator._format_default_value` — `def _format_default_value(self, value: Any) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:227` — `StructureGenerator._format_field_description` — `def _format_field_description(self, description: str) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:351` — `StructureGenerator._get_python_type_from_blueprint` — `def _get_python_type_from_blueprint(self, field_blueprint: ConceptStructureBlueprint) -> str`
+- `pipelex/core/concepts/structure_generation/generator.py:424` — `StructureGenerator._resolve_concept_ref_to_type` — `def _resolve_concept_ref_to_type(self, concept_ref: str | None) -> str`
+- `pipelex/core/concepts/validation.py:6` — `is_concept_code_valid` — `def is_concept_code_valid(concept_code: str) -> bool`
+- `pipelex/core/concepts/validation.py:10` — `validate_concept_code` — `def validate_concept_code(concept_code: str) -> None`
+- `pipelex/core/concepts/validation.py:16` — `is_concept_ref_valid` — `def is_concept_ref_valid(concept_ref: str) -> bool`
+- `pipelex/core/concepts/validation.py:32` — `validate_concept_ref` — `def validate_concept_ref(concept_ref: str) -> None`
+- `pipelex/core/concepts/validation.py:42` — `is_concept_ref_or_code_valid` — `def is_concept_ref_or_code_valid(concept_ref_or_code: str) -> bool`
+- `pipelex/core/concepts/validation.py:59` — `validate_concept_ref_or_code` — `def validate_concept_ref_or_code(concept_ref_or_code: str) -> None`
+- `pipelex/core/domains/domain.py:12` — `SpecialDomain.is_native` — `def is_native(cls, domain_code: str) -> bool`
+- `pipelex/core/domains/domain_factory.py:11` — `DomainFactory.make_from_blueprint` — `def make_from_blueprint(cls, blueprint: DomainBlueprint) -> Domain`
+- `pipelex/core/domains/validation.py:8` — `is_domain_code_valid` — `def is_domain_code_valid(code: Any) -> bool`
+- `pipelex/core/domains/validation.py:26` — `validate_domain_code` — `def validate_domain_code(code: str) -> None`
+- `pipelex/core/interpreter/bundle_elaborator.py:26` — `_is_preliminary_text_pipe` — `def _is_preliminary_text_pipe(pipe_blueprint: PipeBlueprintUnion) -> TypeGuard[PipeLLMBlueprint]`
+- `pipelex/core/interpreter/bundle_elaborator.py:48` — `BundleElaborator.elaborate` — `def elaborate(cls, bundle: PipelexBundleBlueprint) -> PipelexBundleBlueprint`
+- `pipelex/core/interpreter/helpers.py:8` — `is_pipelex_file` — `def is_pipelex_file(file_path: Path) -> bool`
+- `pipelex/core/interpreter/helpers.py:28` — `ValidationErrorScope.is_pipe_scope` — `def is_pipe_scope(cls, scope: str) -> bool`
+- `pipelex/core/interpreter/helpers.py:46` — `get_error_scope` — `def get_error_scope(loc: tuple[int | str, ...]) -> ValidationErrorScope`
+- `pipelex/core/interpreter/validation_error_categorizer.py:17` — `_extract_variable_names_from_message` — `def _extract_variable_names_from_message(message: str) -> list[str] | None`
+- `pipelex/core/interpreter/validation_error_categorizer.py:113` — `_is_pydantic_internal_loc_element` — `def _is_pydantic_internal_loc_element(element: str) -> bool`
+- `pipelex/core/memory/working_memory.py:67` — `WorkingMemory.get_optional_stuff` — `def get_optional_stuff(self, name: str) -> Stuff | None`
+- `pipelex/core/memory/working_memory.py:80` — `WorkingMemory.get_stuff` — `def get_stuff(self, name: str) -> Stuff`
+- `pipelex/core/memory/working_memory.py:96` — `WorkingMemory.get_stuffs` — `def get_stuffs(self, names: set[str]) -> list[Stuff]`
+- `pipelex/core/memory/working_memory.py:102` — `WorkingMemory.get_existing_stuffs` — `def get_existing_stuffs(self, names: set[str]) -> list[Stuff]`
+- `pipelex/core/memory/working_memory.py:109` — `WorkingMemory.is_stuff_code_used` — `def is_stuff_code_used(self, stuff_code: str) -> bool`
+- `pipelex/core/memory/working_memory.py:112` — `WorkingMemory.remove_stuff` — `def remove_stuff(self, name: str)`
+- `pipelex/core/memory/working_memory.py:122` — `WorkingMemory.is_stuff_exists` — `def is_stuff_exists(self, name: str) -> bool`
+- `pipelex/core/memory/working_memory.py:174` — `WorkingMemory.remove_alias` — `def remove_alias(self, alias: str) -> None`
+- `pipelex/core/memory/working_memory.py:183` — `WorkingMemory.get_aliases_for` — `def get_aliases_for(self, target: str) -> list[str]`
+- `pipelex/core/memory/working_memory.py:384` — `WorkingMemory.get_stuff_as_text` — `def get_stuff_as_text(self, name: str) -> TextContent`
+- `pipelex/core/memory/working_memory.py:388` — `WorkingMemory.get_stuff_as_str` — `def get_stuff_as_str(self, name: str) -> str`
+- `pipelex/core/memory/working_memory.py:392` — `WorkingMemory.get_stuff_as_image` — `def get_stuff_as_image(self, name: str) -> ImageContent`
+- `pipelex/core/memory/working_memory.py:396` — `WorkingMemory.get_stuff_as_text_and_image` — `def get_stuff_as_text_and_image(self, name: str) -> TextAndImagesContent`
+- `pipelex/core/memory/working_memory.py:400` — `WorkingMemory.get_stuff_as_document` — `def get_stuff_as_document(self, name: str) -> DocumentContent`
+- `pipelex/core/memory/working_memory.py:404` — `WorkingMemory.get_stuff_as_number` — `def get_stuff_as_number(self, name: str) -> NumberContent`
+- `pipelex/core/memory/working_memory.py:408` — `WorkingMemory.get_stuff_as_html` — `def get_stuff_as_html(self, name: str) -> HtmlContent`
+- `pipelex/core/memory/working_memory.py:412` — `WorkingMemory.get_stuff_as_mermaid` — `def get_stuff_as_mermaid(self, name: str) -> MermaidContent`
+- `pipelex/core/memory/working_memory.py:420` — `WorkingMemory.main_stuff_as` — `def main_stuff_as(self, content_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/memory/working_memory.py:424` — `WorkingMemory.main_stuff_as_list` — `def main_stuff_as_list(self, item_type: type[StuffContentType]) -> ListContent[StuffContentType]`
+- `pipelex/core/memory/working_memory.py:430` — `WorkingMemory.main_list_stuff_first_item_as` — `def main_list_stuff_first_item_as(self, item_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/memory/working_memory_factory.py:31` — `WorkingMemoryFactory.make_from_single_stuff` — `def make_from_single_stuff(cls, stuff: Stuff) -> WorkingMemory`
+- `pipelex/core/memory/working_memory_factory.py:96` — `WorkingMemoryFactory.convert_to_working_memory_format` — `def convert_to_working_memory_format(cls, needed_inputs_spec: InputStuffSpecs) -> list[TypedNamedStuffSpec]`
+- `pipelex/core/memory/working_memory_factory.py:174` — `WorkingMemoryFactory.make_mock_content` — `def make_mock_content(cls, typed_named_stuff_spec: TypedNamedStuffSpec) -> StuffContent`
+- `pipelex/core/memory/working_memory_factory.py:196` — `WorkingMemoryFactory._get_mockable_class` — `def _get_mockable_class(cls, structure_class: type[StuffContent]) -> type[StuffContent]`
+- `pipelex/core/memory/working_memory_factory.py:216` — `WorkingMemoryFactory.make_mock_stuff` — `def make_mock_stuff(cls, typed_named_stuff_spec: TypedNamedStuffSpec) -> Stuff`
+- `pipelex/core/memory/working_memory_factory.py:251` — `WorkingMemoryFactory.make_mock_inputs` — `def make_mock_inputs(cls, needed_inputs: list[TypedNamedStuffSpec]) -> 'WorkingMemory'`
+- `pipelex/core/pipes/handle_pipe_errors.py:18` — `_extract_wrapped_pipe_validation_error` — `def _extract_wrapped_pipe_validation_error(error: ErrorDetails) -> PipeValidationError | None`
+- `pipelex/core/pipes/handle_pipe_errors.py:46` — `categorize_pipe_validation_error` — `def categorize_pipe_validation_error(validation_error: ValidationError) -> list[PipesAndConceptValidationErrorData]`
+- `pipelex/core/pipes/handle_pipe_errors.py:173` — `categorize_pipe_validation_with_libraries_error` — `def categorize_pipe_validation_with_libraries_error(pipe_error: PipeValidationError) -> PipesAndConceptValidationErrorData`
+- `pipelex/core/pipes/handle_pipe_errors.py:202` — `categorize_pipe_factory_error` — `def categorize_pipe_factory_error(factory_error: PipeFactoryError) -> PipeFactoryErrorData`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:67` — `InputStuffSpecs.set_default_domain` — `def set_default_domain(self, domain_code: str)`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:74` — `InputStuffSpecs.get_required_stuff_spec` — `def get_required_stuff_spec(self, variable_name: str) -> StuffSpec`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:81` — `InputStuffSpecs.is_variable_existing` — `def is_variable_existing(self, variable_name: str) -> bool`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:136` — `InputStuffSpecs.format_for_display` — `def format_for_display(self, indent: int=6) -> str`
+- `pipelex/core/pipes/inputs/input_stuff_specs.py:153` — `InputStuffSpecs.render_inputs` — `def render_inputs(self, indent: int=2) -> str`
+- `pipelex/core/pipes/output/output_renderer.py:191` — `_render_python_output` — `def _render_python_output(the_pipe: PipeAbstract) -> str`
+- `pipelex/core/pipes/pipe_abstract.py:121` — `PipeAbstract._make_single_concept_data_for_registry` — `def _make_single_concept_data_for_registry(self, concept: Concept) -> dict[str, Any]`
+- `pipelex/core/pipes/pipe_abstract.py:415` — `PipeAbstract.needed_inputs` — `def needed_inputs(self, visited_pipes: set[str] | None=None) -> InputStuffSpecs`
+- `pipelex/core/pipes/pipe_abstract.py:427` — `PipeAbstract._format_pipe_run_info` — `def _format_pipe_run_info(self, pipe_run_params: PipeRunParams) -> str`
+- `pipelex/core/pipes/pipe_blueprint.py:36` — `PipeCategory.is_controller_by_str` — `def is_controller_by_str(cls, category_str: str) -> bool`
+- `pipelex/core/pipes/pipe_output.py:35` — `PipeOutput.prepare_for_temporal` — `def prepare_for_temporal(self, library_crate: LibraryCrate | None=None) -> 'PipeOutput'`
+- `pipelex/core/pipes/pipe_output.py:66` — `PipeOutput.main_stuff_as_list` — `def main_stuff_as_list(self, item_type: type[StuffContentType]) -> ListContent[StuffContentType]`
+- `pipelex/core/pipes/pipe_output.py:72` — `PipeOutput.main_stuff_as_items` — `def main_stuff_as_items(self, item_type: type[StuffContentType]) -> list[StuffContentType]`
+- `pipelex/core/pipes/pipe_output.py:78` — `PipeOutput.main_stuff_as` — `def main_stuff_as(self, content_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/pipes/stuff_spec/stuff_spec.py:28` — `StuffSpec.render_stuff_spec` — `def render_stuff_spec(self, output_format: ConceptRepresentationFormat) -> dict[str, Any]`
+- `pipelex/core/pipes/validation.py:56` — `is_valid_input_name` — `def is_valid_input_name(input_name: str) -> bool`
+- `pipelex/core/pipes/validation.py:106` — `validate_input_name` — `def validate_input_name(input_name: str) -> None`
+- `pipelex/core/pipes/validation.py:126` — `is_pipe_code_valid` — `def is_pipe_code_valid(pipe_code: str) -> bool`
+- `pipelex/core/pipes/variable_multiplicity.py:58` — `parse_concept_with_multiplicity` — `def parse_concept_with_multiplicity(concept_ref_or_code: str) -> MultiplicityParseResult`
+- `pipelex/core/qualified_ref.py:41` — `QualifiedRef.parse` — `def parse(cls, raw: str) -> 'QualifiedRef'`
+- `pipelex/core/qualified_ref.py:71` — `QualifiedRef.parse_stripping_cross_package` — `def parse_stripping_cross_package(cls, raw: str) -> 'QualifiedRef'`
+- `pipelex/core/qualified_ref.py:82` — `QualifiedRef.parse_concept_ref` — `def parse_concept_ref(cls, raw: str) -> 'QualifiedRef'`
+- `pipelex/core/qualified_ref.py:109` — `QualifiedRef.parse_pipe_ref` — `def parse_pipe_ref(cls, raw: str) -> 'QualifiedRef'`
+- `pipelex/core/qualified_ref.py:148` — `QualifiedRef.is_local_to` — `def is_local_to(self, domain: str) -> bool`
+- `pipelex/core/qualified_ref.py:161` — `QualifiedRef.is_external_to` — `def is_external_to(self, domain: str) -> bool`
+- `pipelex/core/qualified_ref.py:175` — `QualifiedRef.is_address_based_alias` — `def is_address_based_alias(alias: str) -> bool`
+- `pipelex/core/qualified_ref.py:190` — `QualifiedRef.has_cross_package_prefix` — `def has_cross_package_prefix(raw: str) -> bool`
+- `pipelex/core/qualified_ref.py:204` — `QualifiedRef.split_cross_package_ref` — `def split_cross_package_ref(raw: str) -> CrossPackageRef`
+- `pipelex/core/stuffs/image_field_search.py:130` — `check_generic_container_for_images` — `def check_generic_container_for_images(container_type: Any) -> bool`
+- `pipelex/core/stuffs/list_content.py:21` — `ListContent.get_items` — `def get_items(self, item_type: type[StuffContent]) -> list[StuffContent]`
+- `pipelex/core/stuffs/structured_content.py:44` — `StructuredContent._render_value_html` — `def _render_value_html(self, value: Any) -> str`
+- `pipelex/core/stuffs/stuff.py:38` — `Stuff.make_stuff_name` — `def make_stuff_name(cls, concept: Concept) -> str`
+- `pipelex/core/stuffs/stuff.py:95` — `Stuff.content_as` — `def content_as(self, content_type: type[StuffContentType]) -> StuffContentType`
+- `pipelex/core/stuffs/stuff.py:170` — `Stuff.as_list_of_fixed_content_type` — `def as_list_of_fixed_content_type(self, item_type: type[StuffContentType]) -> ListContent[StuffContentType]`
+- `pipelex/core/stuffs/stuff.py:250` — `Stuff.pretty_print_stuff` — `def pretty_print_stuff(self, title: str | None=None) -> None`
+- `pipelex/core/stuffs/stuff_artefact.py:334` — `StuffArtefact.rendered_for_template_async` — `async def rendered_for_template_async(self, text_format: TextFormat) -> str`
+- `pipelex/core/stuffs/stuff_content.py:79` — `StuffContent.rendered_for_prompt` — `def rendered_for_prompt(self, text_format: TextFormat=TextFormat.PLAIN) -> str`
+- `pipelex/core/stuffs/stuff_content.py:95` — `StuffContent.rendered_for_template_async` — `async def rendered_for_template_async(self, text_format: TextFormat=TextFormat.PLAIN) -> str`
+- `pipelex/core/stuffs/stuff_content.py:135` — `StuffContent.pretty_print_content` — `def pretty_print_content(self, title: str | None=None) -> None`
+- `pipelex/core/stuffs/stuff_factory.py:47` — `StuffFactory.make_stuff_name` — `def make_stuff_name(cls, concept: Concept) -> str`
+- `pipelex/core/stuffs/stuff_factory.py:91` — `StuffFactory.make_from_blueprint` — `def make_from_blueprint(cls, blueprint: StuffBlueprint) -> 'Stuff'`
+- `pipelex/core/stuffs/stuff_viewer.py:118` — `_get_html_tab_label` — `def _get_html_tab_label(content_type: str | None) -> str`
+
+### `errors` (12)
+
+- `pipelex/errors/error_pages_generator.py:106` — `_is_production_subclass` — `def _is_production_subclass(cls: type[PipelexError]) -> bool`
+- `pipelex/errors/error_pages_generator.py:195` — `page_slug` — `def page_slug(cls: type[PipelexError]) -> str`
+- `pipelex/errors/error_pages_generator.py:200` — `render_error_page` — `def render_error_page(cls: type[PipelexError]) -> str`
+- `pipelex/errors/error_pages_generator.py:423` — `_subsystem_key` — `def _subsystem_key(cls: type[PipelexError]) -> str`
+- `pipelex/errors/error_pages_generator.py:435` — `_humanize_subsystem` — `def _humanize_subsystem(key: str) -> str`
+- `pipelex/errors/error_pages_generator.py:440` — `_group_by_subsystem` — `def _group_by_subsystem(classes: Iterable[type[PipelexError]]) -> dict[str, list[type[PipelexError]]]`
+- `pipelex/errors/error_pages_generator.py:505` — `render_index_page` — `def render_index_page(by_subsystem: dict[str, list[type[PipelexError]]]) -> str`
+- `pipelex/errors/error_pages_generator.py:550` — `has_authored_marker` — `def has_authored_marker(content: str) -> bool`
+- `pipelex/errors/error_pages_generator.py:560` — `_resolve_class_level_domain` — `def _resolve_class_level_domain(cls: type[PipelexError]) -> str`
+- `pipelex/errors/error_pages_generator.py:570` — `_resolve_class_level_user_action` — `def _resolve_class_level_user_action(cls: type[PipelexError]) -> str | None`
+- `pipelex/errors/error_pages_generator.py:581` — `_parent_link` — `def _parent_link(cls: type[PipelexError]) -> str`
+- `pipelex/errors/error_pages_generator.py:589` — `_short_docstring` — `def _short_docstring(cls: type[PipelexError]) -> str | None`
+
+### `graph` (27)
+
+- `pipelex/graph/graph_analysis.py:87` — `GraphAnalysis.from_graphspec` — `def from_graphspec(cls, graph: GraphSpec) -> 'GraphAnalysis'`
+- `pipelex/graph/graph_analysis.py:169` — `GraphAnalysis.get_children` — `def get_children(self, node_id: str) -> list[str]`
+- `pipelex/graph/graph_analysis.py:180` — `GraphAnalysis.is_controller` — `def is_controller(self, node_id: str) -> bool`
+- `pipelex/graph/graph_analysis.py:191` — `GraphAnalysis.is_root` — `def is_root(self, node_id: str) -> bool`
+- `pipelex/graph/graph_analysis.py:202` — `GraphAnalysis.get_stuff_info` — `def get_stuff_info(self, digest: str) -> StuffInfo | None`
+- `pipelex/graph/graph_analysis.py:213` — `GraphAnalysis.get_producer` — `def get_producer(self, digest: str) -> str | None`
+- `pipelex/graph/graph_analysis.py:224` — `GraphAnalysis.get_consumers` — `def get_consumers(self, digest: str) -> list[str]`
+- `pipelex/graph/graph_rendering.py:19` — `_sanitize_graph_name` — `def _sanitize_graph_name(graph_name: str) -> str`
+- `pipelex/graph/graph_tracer.py:164` — `GraphTracer._emit_event` — `def _emit_event(self, event: TraceEvent) -> None`
+- `pipelex/graph/graph_tracer_manager.py:58` — `GraphTracerManager.get_instance_tracer` — `def get_instance_tracer(cls, lookup_key: str) -> GraphTracerProtocol | None`
+- `pipelex/graph/graph_tracer_manager.py:79` — `GraphTracerManager._get_tracer` — `def _get_tracer(self, graph_id: str) -> GraphTracer | None`
+- `pipelex/graph/graph_tracer_manager.py:174` — `GraphTracerManager.close_tracer` — `def close_tracer(self, tracer_key: str) -> GraphSpec | None`
+- `pipelex/graph/graph_tracer_manager.py:188` — `GraphTracerManager.get_tracer` — `def get_tracer(self, graph_id: str) -> GraphTracer | None`
+- `pipelex/graph/mermaidflow/mermaidflow_factory.py:333` — `MermaidflowFactory._get_node_label` — `def _get_node_label(cls, node: NodeSpec) -> str`
+- `pipelex/graph/mermaidflow/mermaidflow_utils.py:9` — `make_stuff_id` — `def make_stuff_id(digest: str) -> str`
+- `pipelex/graph/mermaidflow/stuff_collector.py:63` — `collect_stuff_data` — `def collect_stuff_data(graph: GraphSpec) -> dict[str, Any]`
+- `pipelex/graph/mermaidflow/stuff_collector.py:76` — `collect_stuff_data_text` — `def collect_stuff_data_text(graph: GraphSpec) -> dict[str, str]`
+- `pipelex/graph/mermaidflow/stuff_collector.py:89` — `collect_stuff_data_html` — `def collect_stuff_data_html(graph: GraphSpec) -> dict[str, str]`
+- `pipelex/graph/mermaidflow/stuff_collector.py:102` — `collect_stuff_content_type` — `def collect_stuff_content_type(graph: GraphSpec) -> dict[str, str]`
+- `pipelex/graph/mermaidflow/stuff_collector.py:117` — `collect_stuff_metadata` — `def collect_stuff_metadata(graph: GraphSpec) -> dict[str, dict[str, str]]`
+- `pipelex/graph/mermaidflow/stuff_collector.py:127` — `collect_stuff_metadata.extract_metadata` — `def extract_metadata(io_spec: IOSpec) -> dict[str, str]`
+- `pipelex/graph/reactflow/reactflow_html.py:20` — `_build_viewer_config` — `def _build_viewer_config(config: ReactFlowRenderingConfig) -> dict[str, object]`
+- `pipelex/graph/validation.py:10` — `validate_graphspec` — `def validate_graphspec(graph: GraphSpec) -> None`
+- `pipelex/graph/validation.py:32` — `_validate_unique_node_ids` — `def _validate_unique_node_ids(graph: GraphSpec) -> None`
+- `pipelex/graph/validation.py:42` — `_validate_unique_edge_ids` — `def _validate_unique_edge_ids(graph: GraphSpec) -> None`
+- `pipelex/graph/validation.py:52` — `_validate_edge_references` — `def _validate_edge_references(graph: GraphSpec) -> None`
+- `pipelex/graph/validation.py:65` — `_validate_failed_nodes_have_errors` — `def _validate_failed_nodes_have_errors(graph: GraphSpec) -> None`
+
+### `hub.py` (44)
+
+- `pipelex/hub.py:112` — `PipelexHub.set_instance` — `def set_instance(cls, pipelex_hub: 'PipelexHub') -> None`
+- `pipelex/hub.py:137` — `PipelexHub.set_config` — `def set_config(self, config: ConfigRoot)`
+- `pipelex/hub.py:148` — `PipelexHub.set_console_print_target` — `def set_console_print_target(self, target: ConsoleTarget)`
+- `pipelex/hub.py:158` — `PipelexHub.set_console` — `def set_console(self, console: Console)`
+- `pipelex/hub.py:161` — `PipelexHub.set_secrets_provider` — `def set_secrets_provider(self, secrets_provider: SecretsProviderAbstract)`
+- `pipelex/hub.py:164` — `PipelexHub.set_storage_provider` — `def set_storage_provider(self, storage_provider: StorageProviderAbstract | None)`
+- `pipelex/hub.py:167` — `PipelexHub.set_class_registry` — `def set_class_registry(self, class_registry: ClassRegistryAbstract)`
+- `pipelex/hub.py:170` — `PipelexHub.set_telemetry_manager` — `def set_telemetry_manager(self, telemetry_manager: TelemetryManagerAbstract)`
+- `pipelex/hub.py:175` — `PipelexHub.set_models_manager` — `def set_models_manager(self, models_manager: ModelManagerAbstract)`
+- `pipelex/hub.py:178` — `PipelexHub.set_plugin_manager` — `def set_plugin_manager(self, plugin_manager: PluginManager)`
+- `pipelex/hub.py:181` — `PipelexHub.set_inference_manager` — `def set_inference_manager(self, inference_manager: InferenceManagerProtocol)`
+- `pipelex/hub.py:184` — `PipelexHub.set_report_delegate` — `def set_report_delegate(self, reporting_delegate: ReportingProtocol)`
+- `pipelex/hub.py:187` — `PipelexHub.set_content_generator` — `def set_content_generator(self, content_generator: ContentGeneratorProtocol)`
+- `pipelex/hub.py:190` — `PipelexHub.set_dry_run_forced` — `def set_dry_run_forced(self, is_forced: bool) -> None`
+- `pipelex/hub.py:198` — `PipelexHub.set_domain_library` — `def set_domain_library(self, domain_library: DomainLibraryAbstract)`
+- `pipelex/hub.py:201` — `PipelexHub.set_concept_library` — `def set_concept_library(self, concept_library: ConceptLibraryAbstract)`
+- `pipelex/hub.py:204` — `PipelexHub.set_pipe_library` — `def set_pipe_library(self, pipe_library: PipeLibraryAbstract)`
+- `pipelex/hub.py:207` — `PipelexHub.set_pipe_router` — `def set_pipe_router(self, pipe_router: 'PipeRouterProtocol')`
+- `pipelex/hub.py:210` — `PipelexHub.set_pipe_run` — `def set_pipe_run(self, pipe_run: 'PipeRunProtocol') -> None`
+- `pipelex/hub.py:213` — `PipelexHub.set_pipeline_manager` — `def set_pipeline_manager(self, pipeline_manager: PipelineManagerAbstract)`
+- `pipelex/hub.py:216` — `PipelexHub.set_observer` — `def set_observer(self, observer: ObserverProtocol)`
+- `pipelex/hub.py:357` — `PipelexHub.set_library_manager` — `def set_library_manager(self, library_manager: LibraryManagerAbstract)`
+- `pipelex/hub.py:360` — `PipelexHub.set_default_library_dirs` — `def set_default_library_dirs(self, library_dirs: list[Path] | None) -> None`
+- `pipelex/hub.py:378` — `PipelexHub.set_func_registry` — `def set_func_registry(self, func_registry: FuncRegistry)`
+- `pipelex/hub.py:389` — `set_pipelex_hub` — `def set_pipelex_hub(pipelex_hub: PipelexHub)`
+- `pipelex/hub.py:455` — `get_llm_worker` — `def get_llm_worker(llm_handle: str) -> LLMWorkerAbstract`
+- `pipelex/hub.py:461` — `get_img_gen_worker` — `def get_img_gen_worker(img_gen_handle: str) -> ImgGenWorkerAbstract`
+- `pipelex/hub.py:467` — `get_extract_worker` — `def get_extract_worker(extract_handle: str) -> ExtractWorkerAbstract`
+- `pipelex/hub.py:481` — `scoped_content_generator` — `def scoped_content_generator(content_generator: ContentGeneratorProtocol) -> Generator[None, None, None]`
+- `pipelex/hub.py:515` — `get_secret` — `def get_secret(secret_id: str) -> str`
+- `pipelex/hub.py:525` — `set_current_library` — `def set_current_library(library_id: str) -> None`
+- `pipelex/hub.py:561` — `scoped_current_library` — `def scoped_current_library(library_id: str) -> Generator[None, None, None]`
+- `pipelex/hub.py:578` — `resolve_library_dirs` — `def resolve_library_dirs(library_dirs: Sequence[str | Path] | None=None) -> tuple[list[Path], str]`
+- `pipelex/hub.py:612` — `get_required_domain` — `def get_required_domain(domain_code: str) -> Domain`
+- `pipelex/hub.py:616` — `get_optional_domain` — `def get_optional_domain(domain_code: str) -> Domain | None`
+- `pipelex/hub.py:628` — `get_required_pipe` — `def get_required_pipe(pipe_code: str) -> PipeAbstract`
+- `pipelex/hub.py:632` — `get_optional_pipe` — `def get_optional_pipe(pipe_code: str) -> PipeAbstract | None`
+- `pipelex/hub.py:636` — `get_pipe_source` — `def get_pipe_source(pipe_code: str) -> Path | None`
+- `pipelex/hub.py:652` — `get_required_concept` — `def get_required_concept(concept_ref: str) -> Concept`
+- `pipelex/hub.py:659` — `set_pipe_router` — `def set_pipe_router(pipe_router: 'PipeRouterProtocol') -> None`
+- `pipelex/hub.py:678` — `scoped_pipe_router` — `def scoped_pipe_router(pipe_router: 'PipeRouterProtocol') -> Generator[None, None, None]`
+- `pipelex/hub.py:712` — `scoped_event_log` — `def scoped_event_log(event_log: 'EventLogProtocol') -> Generator[None, None, None]`
+- `pipelex/hub.py:751` — `get_pipeline` — `def get_pipeline(pipeline_run_id: str) -> Pipeline`
+- `pipelex/hub.py:763` — `get_native_concept` — `def get_native_concept(native_concept: NativeConceptCode) -> Concept`
+
+### `kit` (3)
+
+- `pipelex/kit/cursor_rules.py:20` — `_iter_agent_files` — `def _iter_agent_files(agents_dir: Traversable) -> Iterable[tuple[str, str]]`
+- `pipelex/kit/cursor_rules.py:55` — `_is_pipelex_managed` — `def _is_pipelex_managed(mdc_path: Path) -> bool`
+- `pipelex/kit/single_file_agent_rules.py:39` — `_demote_headings.demote_match` — `def demote_match(match: re.Match[str]) -> str`
+
+### `language` (16)
+
+- `pipelex/language/mthds_factory.py:36` — `MthdsFactory.format_tomlkit_string` — `def format_tomlkit_string(cls, text: str) -> Any`
+- `pipelex/language/mthds_factory.py:163` — `MthdsFactory.add_spaces_to_inline_tables` — `def add_spaces_to_inline_tables(cls, toml_string: str) -> str`
+- `pipelex/language/mthds_factory.py:171` — `MthdsFactory.add_spaces_to_inline_tables.find_and_replace_inline_tables` — `def find_and_replace_inline_tables(text: str) -> str`
+- `pipelex/language/mthds_factory.py:228` — `MthdsFactory.make_template_table` — `def make_template_table(cls, template_value: Mapping[str, Any]) -> Any`
+- `pipelex/language/mthds_factory.py:238` — `MthdsFactory.make_construct_table` — `def make_construct_table(cls, construct_value: Mapping[str, Any]) -> Any`
+- `pipelex/language/mthds_factory.py:250` — `MthdsFactory.make_table_obj_for_pipe` — `def make_table_obj_for_pipe(cls, section_value: Mapping[str, Any]) -> Any`
+- `pipelex/language/mthds_factory.py:267` — `MthdsFactory.make_table_obj_for_concept` — `def make_table_obj_for_concept(cls, section_value: Mapping[str, Any]) -> Any`
+- `pipelex/language/mthds_factory.py:324` — `MthdsFactory.dict_to_mthds_styled_toml` — `def dict_to_mthds_styled_toml(cls, data: Mapping[str, Any]) -> str`
+- `pipelex/language/mthds_factory.py:358` — `MthdsFactory.make_mthds_content` — `def make_mthds_content(cls, blueprint: PipelexBundleBlueprint) -> str`
+- `pipelex/language/mthds_schema_generator.py:57` — `_remove_internal_fields` — `def _remove_internal_fields(schema: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/language/mthds_schema_generator.py:98` — `_promote_schema_required_fields` — `def _promote_schema_required_fields(schema: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/language/mthds_schema_generator.py:125` — `_require_type_on_pipe_definitions` — `def _require_type_on_pipe_definitions(schema: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/language/mthds_schema_generator.py:152` — `_convert_to_draft4` — `def _convert_to_draft4(schema: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/language/mthds_schema_generator.py:173` — `_draft4_visitor` — `def _draft4_visitor(node: dict[str, Any]) -> None`
+- `pipelex/language/mthds_schema_generator.py:198` — `_patch_construct_schema` — `def _patch_construct_schema(schema: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/language/mthds_schema_generator.py:287` — `_add_taplo_metadata` — `def _add_taplo_metadata(schema: dict[str, Any]) -> dict[str, Any]`
+
+### `libraries` (46)
+
+- `pipelex/libraries/concept/concept_library.py:27` — `ConceptLibrary.set_concept_resolver` — `def set_concept_resolver(self, resolver: Callable[[str], Concept | None]) -> None`
+- `pipelex/libraries/concept/concept_library.py:107` — `ConceptLibrary.get_optional_concept` — `def get_optional_concept(self, concept_ref: str) -> Concept | None`
+- `pipelex/libraries/concept/concept_library.py:204` — `ConceptLibrary.is_concept_exists` — `def is_concept_exists(self, concept_ref: str) -> bool`
+- `pipelex/libraries/concept/concept_library_abstract.py:9` — `ConceptLibraryAbstract.add_new_concept` — `def add_new_concept(self, concept: Concept) -> None`
+- `pipelex/libraries/concept/concept_library_abstract.py:13` — `ConceptLibraryAbstract.add_concepts` — `def add_concepts(self, concepts: list[Concept]) -> None`
+- `pipelex/libraries/concept/concept_library_abstract.py:17` — `ConceptLibraryAbstract.remove_concepts_by_concept_refs` — `def remove_concepts_by_concept_refs(self, concept_refs: list[str]) -> None`
+- `pipelex/libraries/concept/concept_library_abstract.py:21` — `ConceptLibraryAbstract.list_concepts_by_domain` — `def list_concepts_by_domain(self, domain_code: str) -> list[Concept]`
+- `pipelex/libraries/concept/concept_library_abstract.py:29` — `ConceptLibraryAbstract.get_required_concept` — `def get_required_concept(self, concept_ref: str) -> Concept`
+- `pipelex/libraries/concept/concept_library_abstract.py:49` — `ConceptLibraryAbstract.get_native_concept` — `def get_native_concept(self, native_concept: NativeConceptCode) -> Concept`
+- `pipelex/libraries/domain/domain_library.py:33` — `DomainLibrary.add_domain` — `def add_domain(self, domain: Domain)`
+- `pipelex/libraries/domain/domain_library.py:59` — `DomainLibrary.add_domains` — `def add_domains(self, domains: list[Domain])`
+- `pipelex/libraries/domain/domain_library.py:63` — `DomainLibrary.remove_domain_by_code` — `def remove_domain_by_code(self, domain_code: str) -> None`
+- `pipelex/libraries/domain/domain_library_abstract.py:8` — `DomainLibraryAbstract.get_domain` — `def get_domain(self, domain_code: str) -> Domain | None`
+- `pipelex/libraries/domain/domain_library_abstract.py:12` — `DomainLibraryAbstract.get_required_domain` — `def get_required_domain(self, domain_code: str) -> Domain`
+- `pipelex/libraries/library.py:44` — `Library.set_class_registry` — `def set_class_registry(self, class_registry: ClassRegistry) -> None`
+- `pipelex/libraries/library.py:56` — `Library.get_dependency_library` — `def get_dependency_library(self, alias: str) -> 'Library | None'`
+- `pipelex/libraries/library.py:67` — `Library.resolve_concept` — `def resolve_concept(self, concept_ref: str) -> 'Concept | None'`
+- `pipelex/libraries/library.py:148` — `Library._has_unresolved_cross_package_deps` — `def _has_unresolved_cross_package_deps(self, pipe: PipeController) -> bool`
+- `pipelex/libraries/library_crate_factory.py:33` — `LibraryCrateFactory.make_from_blueprints` — `def make_from_blueprints(cls, blueprints: list[PipelexBundleBlueprint]) -> LibraryCrate`
+- `pipelex/libraries/library_crate_factory.py:199` — `LibraryCrateFactory._declaration_sort_key` — `def _declaration_sort_key(declaration: PipeDeclaration) -> tuple[str, str]`
+- `pipelex/libraries/library_manager.py:62` — `_find_methods_dirs_from_blueprints` — `def _find_methods_dirs_from_blueprints(blueprints: list[PipelexBundleBlueprint]) -> list[Path]`
+- `pipelex/libraries/library_manager.py:116` — `LibraryManager._pop_and_teardown_library` — `def _pop_and_teardown_library(self, library_id: str) -> bool`
+- `pipelex/libraries/library_manager.py:621` — `LibraryManager._load_concepts_from_blueprints` — `def _load_concepts_from_blueprints(self, blueprints: list[PipelexBundleBlueprint]) -> list['Concept']`
+- `pipelex/libraries/library_manager.py:670` — `LibraryManager._load_concepts_from_crate` — `def _load_concepts_from_crate(self, concepts: dict[str, ConceptBlueprint | str]) -> list['Concept']`
+- `pipelex/libraries/library_manager.py:700` — `LibraryManager._topological_load_concepts` — `def _topological_load_concepts(self, ref_to_entry: 'Mapping[str, tuple[str, str, ConceptBlueprint | str]]') -> list['Concept']`
+- `pipelex/libraries/library_manager.py:916` — `LibraryManager._find_package_root` — `def _find_package_root(self, mthds_paths: list[Path]) -> Path | None`
+- `pipelex/libraries/library_manager.py:1237` — `LibraryManager._remove_pipes_from_blueprint` — `def _remove_pipes_from_blueprint(self, blueprint: PipelexBundleBlueprint) -> None`
+- `pipelex/libraries/library_manager.py:1245` — `LibraryManager._remove_concepts_from_blueprint` — `def _remove_concepts_from_blueprint(self, blueprint: PipelexBundleBlueprint) -> None`
+- `pipelex/libraries/library_manager.py:1264` — `LibraryManager._rebuild_models_with_forward_refs` — `def _rebuild_models_with_forward_refs(self, concepts: list['Concept']) -> None`
+- `pipelex/libraries/library_manager.py:1295` — `LibraryManager._detect_concept_cycles` — `def _detect_concept_cycles(self, concepts: list['Concept']) -> None`
+- `pipelex/libraries/library_manager.py:1316` — `LibraryManager._detect_concept_cycles.get_referenced_concepts` — `def get_referenced_concepts(concept: 'Concept') -> list[str]`
+- `pipelex/libraries/library_manager.py:1323` — `LibraryManager._detect_concept_cycles.get_referenced_concepts.extract_type_names` — `def extract_type_names(annotation: type) -> list[str]`
+- `pipelex/libraries/library_manager_abstract.py:22` — `LibraryManagerAbstract.teardown` — `def teardown(self, library_id: str | None=None) -> None`
+- `pipelex/libraries/library_manager_abstract.py:30` — `LibraryManagerAbstract.open_library` — `def open_library(self, library_id: str | None=None) -> tuple[str, 'Library']`
+- `pipelex/libraries/library_manager_abstract.py:34` — `LibraryManagerAbstract.open_fresh_library` — `def open_fresh_library(self, library_id: str) -> 'Library'`
+- `pipelex/libraries/library_manager_abstract.py:45` — `LibraryManagerAbstract.get_library` — `def get_library(self, library_id: str) -> 'Library'`
+- `pipelex/libraries/library_manager_abstract.py:52` — `LibraryManagerAbstract.get_library_class_registry` — `def get_library_class_registry(self, library_id: str) -> ClassRegistry | None`
+- `pipelex/libraries/library_manager_abstract.py:59` — `LibraryManagerAbstract.get_pipe_source` — `def get_pipe_source(self, pipe_code: str) -> Path | None`
+- `pipelex/libraries/library_manager_abstract.py:71` — `LibraryManagerAbstract.get_crate` — `def get_crate(self, library_id: str) -> LibraryCrate | None`
+- `pipelex/libraries/library_utils.py:65` — `get_pipelex_mthds_files_from_dirs` — `def get_pipelex_mthds_files_from_dirs(dirs: set[Path]) -> list[Path]`
+- `pipelex/libraries/pipe/pipe_library_abstract.py:21` — `PipeLibraryAbstract.get_required_pipe` — `def get_required_pipe(self, pipe_code: str) -> PipeAbstract`
+- `pipelex/libraries/pipe/pipe_library_abstract.py:25` — `PipeLibraryAbstract.get_optional_pipe` — `def get_optional_pipe(self, pipe_code: str) -> PipeAbstract | None`
+- `pipelex/libraries/pipe/pipe_library_abstract.py:36` — `PipeLibraryAbstract.remove_pipes_by_refs` — `def remove_pipes_by_refs(self, pipe_refs: list[str]) -> None`
+- `pipelex/libraries/pipe/pipe_library_abstract.py:44` — `PipeLibraryAbstract.add_new_pipe` — `def add_new_pipe(self, pipe: PipeAbstract) -> None`
+- `pipelex/libraries/pipe/pipe_library_abstract.py:48` — `PipeLibraryAbstract.add_pipes` — `def add_pipes(self, pipes: list[PipeAbstract]) -> None`
+- `pipelex/libraries/visibility_utils.py:14` — `_blueprint_to_metadata` — `def _blueprint_to_metadata(blueprint: PipelexBundleBlueprint) -> BundleMetadata`
+
+### `observer` (4)
+
+- `pipelex/observer/multi_observer.py:14` — `MultiObserver.remove_observer` — `def remove_observer(self, name: str) -> None`
+- `pipelex/observer/observer_protocol.py:18` — `ObserverProtocol.observe_before_run` — `async def observe_before_run(self, payload: PayloadType) -> None`
+- `pipelex/observer/observer_protocol.py:25` — `ObserverProtocol.observe_after_successful_run` — `async def observe_after_successful_run(self, payload: PayloadType) -> None`
+- `pipelex/observer/observer_protocol.py:32` — `ObserverProtocol.observe_after_failing_run` — `async def observe_after_failing_run(self, payload: PayloadType) -> None`
+
+### `pipe_controllers` (5)
+
+- `pipelex/pipe_controllers/batch/pipe_batch.py:35` — `resolve_batch_max_concurrency` — `def resolve_batch_max_concurrency(max_concurrency_setting: int | str) -> int | None`
+- `pipelex/pipe_controllers/condition/pipe_condition.py:197` — `PipeCondition._evaluate_expression` — `async def _evaluate_expression(self, working_memory: WorkingMemory) -> str`
+- `pipelex/pipe_controllers/condition/special_outcome.py:15` — `SpecialOutcome.is_continue` — `def is_continue(cls, outcome: str) -> bool`
+- `pipelex/pipe_controllers/condition/special_outcome.py:30` — `SpecialOutcome.is_fail` — `def is_fail(cls, outcome: str) -> bool`
+- `pipelex/pipe_controllers/sub_pipe_factory.py:13` — `SubPipeFactory.make_from_blueprint` — `def make_from_blueprint(cls, blueprint: SubPipeBlueprint) -> SubPipe`
+
+### `pipe_operators` (13)
+
+- `pipelex/pipe_operators/compose/construct_blueprint.py:108` — `ConstructFieldBlueprint.make_from_raw` — `def make_from_raw(cls, raw: Any) -> ConstructFieldBlueprint`
+- `pipelex/pipe_operators/compose/construct_blueprint.py:294` — `ConstructBlueprint.make_from_raw` — `def make_from_raw(cls, raw: dict[str, Any]) -> ConstructBlueprint`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:78` — `StructuredContentComposer._build_field_type_summary` — `def _build_field_type_summary(self, field_values: dict[str, Any]) -> str`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:377` — `StructuredContentComposer._get_field_expected_type` — `def _get_field_expected_type(self, field_name: str) -> type[Any] | None`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:451` — `StructuredContentComposer._expects_list_content_type` — `def _expects_list_content_type(self, expected_type: type[Any]) -> bool`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:474` — `StructuredContentComposer._expects_list_type` — `def _expects_list_type(self, expected_type: type[Any]) -> bool`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:486` — `StructuredContentComposer._get_list_item_type` — `def _get_list_item_type(self, expected_type: type[Any]) -> type[Any] | None`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:624` — `StructuredContentComposer._resolve_template` — `async def _resolve_template(self, field_blueprint: ConstructFieldBlueprint) -> str`
+- `pipelex/pipe_operators/compose/structured_content_composer.py:691` — `StructuredContentComposer._get_nested_field_class` — `def _get_nested_field_class(self, field_name: str) -> type[StuffContent]`
+- `pipelex/pipe_operators/llm/helpers.py:12` — `get_output_structure_prompt` — `async def get_output_structure_prompt(concept_ref: str) -> str | None`
+- `pipelex/pipe_operators/llm/pipe_llm.py:141` — `PipeLLM.resolve_dynamic_output_stuff_spec` — `def resolve_dynamic_output_stuff_spec(self, pipe_run_params: PipeRunParams) -> StuffSpec`
+- `pipelex/pipe_operators/llm/pipe_llm.py:383` — `PipeLLM._format_error_location` — `def _format_error_location(self, pipe_run_params: PipeRunParams) -> str`
+- `pipelex/pipe_operators/structure/pipe_structure.py:204` — `PipeStructure._format_error_location` — `def _format_error_location(self, pipe_run_params: PipeRunParams) -> str`
+
+### `pipe_run` (9)
+
+- `pipelex/pipe_run/delivery_executor.py:77` — `DeliveryExecutor.generate_result_files` — `async def generate_result_files(self, pipe_output: PipeOutput) -> dict[str, ResultFile]`
+- `pipelex/pipe_run/delivery_executor.py:121` — `DeliveryExecutor._get_raw_main_stuff_dict` — `def _get_raw_main_stuff_dict(cls, working_memory_raw: dict[str, Any]) -> dict[str, Any] | None`
+- `pipelex/pipe_run/delivery_executor.py:132` — `DeliveryExecutor.try_local_hydrate_stuff` — `def try_local_hydrate_stuff(cls, stuff_raw: dict[str, Any]) -> Stuff | None`
+- `pipelex/pipe_run/pipe_router_protocol.py:14` — `PipeRouterProtocol._before_run` — `async def _before_run(self, pipe_job: PipeJob) -> None`
+- `pipelex/pipe_run/pipe_router_protocol.py:50` — `PipeRouterProtocol.run` — `async def run(self, pipe_job: PipeJob) -> PipeOutput`
+- `pipelex/pipe_run/pipe_router_protocol.py:81` — `PipeRouterProtocol._run_pipe_job` — `async def _run_pipe_job(self, pipe_job: PipeJob) -> PipeOutput`
+- `pipelex/pipe_run/pipe_run_params.py:229` — `PipeRunParams.push_pipe_to_stack` — `def push_pipe_to_stack(self, pipe_code: str) -> None`
+- `pipelex/pipe_run/pipe_run_params.py:239` — `PipeRunParams.pop_pipe_from_stack` — `def pop_pipe_from_stack(self, pipe_code: str) -> None`
+- `pipelex/pipe_run/pipe_run_params.py:249` — `PipeRunParams.push_pipe_layer` — `def push_pipe_layer(self, pipe_code: str) -> None`
+
+### `pipelex.py` (1)
+
+- `pipelex/pipelex.py:140` — `Pipelex._get_config_file_not_found_error_msg` — `def _get_config_file_not_found_error_msg(component_name: str) -> str`
+
+### `pipeline` (13)
+
+- `pipelex/pipeline/blueprint_selection.py:26` — `select_primary_blueprint` — `def select_primary_blueprint(blueprints: Sequence[PipelexBundleBlueprint]) -> PrimaryBlueprintSelection`
+- `pipelex/pipeline/bundle_validator.py:270` — `BundleValidator._signature_pre_pass` — `def _signature_pre_pass(cls, pipes: list[PipeAbstract]) -> None`
+- `pipelex/pipeline/execution_seams.py:132` — `load_libraries_and_activate` — `def load_libraries_and_activate(library_dirs: Sequence[str | Path] | None=None) -> str`
+- `pipelex/pipeline/input_normalizer.py:32` — `normalize_data_urls_to_storage` — `async def normalize_data_urls_to_storage(working_memory: WorkingMemory) -> WorkingMemory`
+- `pipelex/pipeline/pipe_io_contracts.py:63` — `build_pipe_io_contracts` — `def build_pipe_io_contracts(pipes: Sequence[PipeAbstract]) -> dict[str, PipeIOContract]`
+- `pipelex/pipeline/pipeline_factory.py:9` — `PipelineFactory.make_pipeline` — `def make_pipeline(cls, pipeline_run_id: str | None=None) -> Pipeline`
+- `pipelex/pipeline/pipeline_manager_abstract.py:16` — `PipelineManagerAbstract.get_optional_pipeline` — `def get_optional_pipeline(self, pipeline_run_id: str) -> Pipeline | None`
+- `pipelex/pipeline/pipeline_manager_abstract.py:20` — `PipelineManagerAbstract.get_pipeline` — `def get_pipeline(self, pipeline_run_id: str) -> Pipeline`
+- `pipelex/pipeline/pipeline_manager_abstract.py:28` — `PipelineManagerAbstract.remove_pipeline` — `def remove_pipeline(self, pipeline_run_id: str) -> None`
+- `pipelex/pipeline/validate_bundle.py:68` — `build_validated_pipes` — `def build_validated_pipes(dry_run_result: dict[str, DryRunOutput]) -> list[ValidatedPipeEntry]`
+- `pipelex/pipeline/validate_bundle.py:79` — `build_pending_signatures` — `def build_pending_signatures(pipes_by_ref: dict[str, PipeAbstract]) -> list[str]`
+- `pipelex/pipeline/validate_bundle.py:95` — `_translate_to_validate_bundle_error` — `def _translate_to_validate_bundle_error(category: Literal['pipe', 'concept']) -> Generator[None, None, None]`
+- `pipelex/pipeline/validate_bundle.py:463` — `load_concepts_only_from_directory` — `def load_concepts_only_from_directory(directory: Path) -> LoadConceptsOnlyResult`
+
+### `plugins` (83)
+
+- `pipelex/plugins/anthropic/anthropic_config.py:26` — `AnthropicConfig.get_reasoning_level` — `def get_reasoning_level(self, effort: ReasoningEffort) -> AnthropicEffortLevel | None`
+- `pipelex/plugins/anthropic/anthropic_factory.py:78` — `AnthropicFactory._make_image_block_param` — `def _make_image_block_param(prepped_image: PreparedFile) -> ImageBlockParam`
+- `pipelex/plugins/anthropic/anthropic_factory.py:137` — `AnthropicFactory.make_user_message` — `async def make_user_message(cls, llm_job: LLMJob) -> MessageParam`
+- `pipelex/plugins/anthropic/anthropic_factory.py:199` — `AnthropicFactory.make_simple_messages` — `async def make_simple_messages(cls, llm_job: LLMJob) -> 'list["ChatCompletionMessageParam"]'`
+- `pipelex/plugins/anthropic/anthropic_factory.py:236` — `AnthropicFactory.make_nb_tokens_by_category` — `def make_nb_tokens_by_category(usage: Usage) -> NbTokensByCategoryDict`
+- `pipelex/plugins/anthropic/anthropic_factory.py:252` — `AnthropicFactory.calculate_safe_max_tokens_for_timeout` — `def calculate_safe_max_tokens_for_timeout(timeout_seconds: int) -> int`
+- `pipelex/plugins/azure_rest/azure_img_gen_worker.py:65` — `AzureImgGenWorker._raise_categorized_azure_status_error` — `def _raise_categorized_azure_status_error(self, exc: httpx.HTTPStatusError) -> None`
+- `pipelex/plugins/bedrock/bedrock_factory.py:62` — `BedrockFactory.make_simple_message` — `def make_simple_message(cls, llm_job: LLMJob) -> BedrockMessage`
+- `pipelex/plugins/bedrock/bedrock_llm_worker.py:46` — `BedrockLLMWorker._validate_no_reasoning_params` — `def _validate_no_reasoning_params(self, job_params: LLMJobParams) -> None`
+- `pipelex/plugins/docling/docling_extract_worker.py:63` — `DoclingExtractWorker._extract_from_source` — `async def _extract_from_source(self, source_uri: str) -> ExtractOutput`
+- `pipelex/plugins/docling/docling_factory.py:17` — `DoclingFactory.make_extract_output_from_docling_document` — `def make_extract_output_from_docling_document(cls, doc: 'DoclingDocument') -> ExtractOutput`
+- `pipelex/plugins/fal/fal_factory.py:13` — `FalFactory.make_generated_image` — `def make_generated_image(cls, fal_result: dict[str, Any]) -> GeneratedImageRawDetails`
+- `pipelex/plugins/fal/fal_factory.py:29` — `FalFactory.make_generated_image_list` — `def make_generated_image_list(cls, fal_result: dict[str, Any]) -> list[GeneratedImageRawDetails]`
+- `pipelex/plugins/fal/fal_poller.py:19` — `FalPoller._is_transient_http` — `def _is_transient_http(self, exc: BaseException) -> bool`
+- `pipelex/plugins/fal/fal_poller.py:25` — `FalPoller.poll_queue_until_complete` — `async def poll_queue_until_complete(self, response_dict: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:156` — `GatewayCompletionsFactory._extract_pages_from_choices_content` — `def _extract_pages_from_choices_content(cls, response: GenericResponse) -> list[dict[str, Any]] | None`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:187` — `GatewayCompletionsFactory._make_extract_output_from_response_azure` — `def _make_extract_output_from_response_azure(cls, response: GenericResponse) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:226` — `GatewayCompletionsFactory._make_extract_output_from_response_mistral` — `def _make_extract_output_from_response_mistral(cls, response: GenericResponse) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:276` — `GatewayCompletionsFactory._make_extract_output_from_response_deepseek` — `def _make_extract_output_from_response_deepseek(cls, response: GenericResponse) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:311` — `GatewayCompletionsFactory._make_extract_output_from_response_linkup_fetch` — `def _make_extract_output_from_response_linkup_fetch(cls, response: GenericResponse) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_completions_factory.py:345` — `GatewayCompletionsFactory._extract_content_string_from_response` — `def _extract_content_string_from_response(cls, response: GenericResponse) -> str | None`
+- `pipelex/plugins/gateway/gateway_constants.py:9` — `GatewayOpenAISdkVariant.is_completions` — `def is_completions(cls, sdk: str) -> bool`
+- `pipelex/plugins/gateway/gateway_constants.py:21` — `GatewayOpenAISdkVariant.is_responses` — `def is_responses(cls, sdk: str) -> bool`
+- `pipelex/plugins/gateway/gateway_deck.py:9` — `GatewayDeck.get_config_id` — `def get_config_id(cls, headers: dict[str, str]) -> str`
+- `pipelex/plugins/gateway/gateway_extract_worker.py:94` — `GatewayExtractWorker._extract_document` — `async def _extract_document(self, extract_job: ExtractJob) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_extract_worker.py:128` — `GatewayExtractWorker._extract_web_fetch` — `async def _extract_web_fetch(self, extract_job: ExtractJob) -> ExtractOutput`
+- `pipelex/plugins/gateway/gateway_factory.py:32` — `GatewayFactory.is_debug_enabled` — `def is_debug_enabled(cls, backend: InferenceBackend) -> bool`
+- `pipelex/plugins/gateway/gateway_factory.py:37` — `GatewayFactory.get_endpoint` — `def get_endpoint(cls, backend: InferenceBackend) -> str`
+- `pipelex/plugins/gateway/gateway_factory.py:41` — `GatewayFactory.get_api_key` — `def get_api_key(cls, backend: InferenceBackend) -> str`
+- `pipelex/plugins/gateway/gateway_factory.py:48` — `GatewayFactory.make_portkey_client` — `def make_portkey_client(cls, backend: InferenceBackend) -> AsyncPortkey`
+- `pipelex/plugins/gateway/gateway_protocols.py:13` — `GatewayExtractProtocol.make_from_model_handle` — `def make_from_model_handle(cls, model_handle: str) -> GatewayExtractProtocol`
+- `pipelex/plugins/gateway/gateway_search_worker.py:178` — `GatewaySearchWorker._extract_content` — `def _extract_content(self, response: GenericResponse) -> str`
+- `pipelex/plugins/google/google_config.py:32` — `GoogleConfig.get_reasoning_level` — `def get_reasoning_level(self, effort: ReasoningEffort) -> genai_types.ThinkingLevel | None`
+- `pipelex/plugins/google/google_factory.py:21` — `GoogleFactory.make_google_client` — `def make_google_client(cls, backend: InferenceBackend) -> GoogleGenAiClient`
+- `pipelex/plugins/google/google_factory.py:31` — `GoogleFactory.prepare_image_part` — `async def prepare_image_part(cls, prompt_image: PromptImage) -> genai_types.Part`
+- `pipelex/plugins/google/google_factory.py:42` — `GoogleFactory.prepare_document_part` — `async def prepare_document_part(cls, prompt_document: PromptDocument) -> genai_types.Part`
+- `pipelex/plugins/google/google_factory.py:53` — `GoogleFactory.prepare_user_contents` — `async def prepare_user_contents(cls, llm_prompt: LLMPrompt) -> genai_types.ContentListUnion`
+- `pipelex/plugins/google/google_factory.py:139` — `GoogleFactory.extract_token_usage` — `def extract_token_usage(cls, usage_metadata: genai_types.GenerateContentResponseUsageMetadata | None) -> NbTokensByCategoryDict`
+- `pipelex/plugins/google/google_img_gen_factory.py:82` — `GoogleImgGenFactory.aspect_ratio_literal` — `def aspect_ratio_literal(cls, aspect_ratio: AspectRatio) -> GoogleAspectRatioType`
+- `pipelex/plugins/huggingface/huggingface_factory.py:6` — `HuggingFaceFactory.make_huggingface_inference_provider` — `def make_huggingface_inference_provider(cls, provider_str: str) -> PROVIDER_OR_POLICY_T`
+- `pipelex/plugins/huggingface/huggingface_img_gen_worker.py:37` — `HuggingFaceImgGenWorker._generate_single_image` — `async def _generate_single_image(self, img_gen_job: ImgGenJob) -> Image.Image`
+- `pipelex/plugins/linkup/linkup_search_worker.py:42` — `LinkupSearchWorker._parse_date` — `def _parse_date(self, date_str: str | None) -> date | None`
+- `pipelex/plugins/mistral/mistral_config.py:29` — `MistralConfig.get_reasoning_level` — `def get_reasoning_level(self, effort: ReasoningEffort) -> MistralPromptMode | None`
+- `pipelex/plugins/mistral/mistral_extract_worker.py:62` — `MistralExtractWorker._extract_page_from_image` — `async def _extract_page_from_image(self, image_uri: str) -> ExtractOutput`
+- `pipelex/plugins/mistral/mistral_factory.py:50` — `MistralFactory.make_mistral_client` — `def make_mistral_client(cls, backend: InferenceBackend) -> Mistral`
+- `pipelex/plugins/mistral/mistral_factory.py:73` — `MistralFactory.make_simple_messages` — `async def make_simple_messages(self, llm_job: LLMJob) -> list[Messages]`
+- `pipelex/plugins/mistral/mistral_factory.py:93` — `MistralFactory.make_mistral_image_url` — `async def make_mistral_image_url(self, prompt_image: PromptImage) -> ImageURLChunk`
+- `pipelex/plugins/mistral/mistral_factory.py:114` — `MistralFactory.make_mistral_document_url` — `async def make_mistral_document_url(self, prompt_document: PromptDocument) -> DocumentURLChunk`
+- `pipelex/plugins/mistral/mistral_factory.py:136` — `MistralFactory.make_simple_messages_openai_typed` — `async def make_simple_messages_openai_typed(self, llm_job: LLMJob) -> 'list["ChatCompletionMessageParam"]'`
+- `pipelex/plugins/mistral/mistral_factory.py:189` — `MistralFactory.make_nb_tokens_by_category` — `def make_nb_tokens_by_category(self, usage: UsageInfo) -> NbTokensByCategoryDict`
+- `pipelex/plugins/mistral/mistral_factory.py:197` — `MistralFactory.make_extract_output_from_mistral_response` — `async def make_extract_output_from_mistral_response(cls, mistral_extract_response: mistralai.OCRResponse) -> ExtractOutput`
+- `pipelex/plugins/mistral/mistral_factory.py:222` — `MistralFactory._clean_mistral_image_base64` — `def _clean_mistral_image_base64(cls, base64_str: str) -> str`
+- `pipelex/plugins/mistral/mistral_factory.py:278` — `MistralFactory.make_extracted_image_from_page_from_mistral_ocr_image_obj` — `def make_extracted_image_from_page_from_mistral_ocr_image_obj(cls, mistral_ocr_image_obj: mistralai.OCRImageObject) -> ExtractedImageFromPage`
+- `pipelex/plugins/mistral/mistral_factory.py:326` — `MistralFactory.make_mistral_image_url_chunk_from_uri` — `async def make_mistral_image_url_chunk_from_uri(cls, uri: str) -> ImageURLChunkTypedDict`
+- `pipelex/plugins/mistral/mistral_llm_worker.py:68` — `MistralLLMWorker._resolve_prompt_mode` — `def _resolve_prompt_mode(self, job_params: LLMJobParams) -> 'OptionalNullable[MistralPromptMode]'`
+- `pipelex/plugins/openai/openai_completions_factory.py:27` — `OpenAICompletionsFactory.make_simple_messages` — `async def make_simple_messages(self, llm_job: LLMJob) -> 'list["ChatCompletionMessageParam"]'`
+- `pipelex/plugins/openai/openai_completions_factory.py:94` — `OpenAICompletionsFactory._get_document_filename` — `def _get_document_filename(prompt_document: PromptDocument) -> str`
+- `pipelex/plugins/openai/openai_completions_factory.py:99` — `OpenAICompletionsFactory.make_nb_tokens_by_category` — `def make_nb_tokens_by_category(self, usage: 'CompletionUsage') -> NbTokensByCategoryDict`
+- `pipelex/plugins/openai/openai_completions_img_gen_worker.py:177` — `OpenAICompletionsImgGenWorker._build_messages_with_images` — `async def _build_messages_with_images(self, img_gen_job: ImgGenJob) -> 'list[ChatCompletionMessageParam]'`
+- `pipelex/plugins/openai/openai_completions_llm_worker.py:87` — `OpenAICompletionsLLMWorker._resolve_reasoning_effort` — `def _resolve_reasoning_effort(self, job_params: LLMJobParams) -> ChatCompletionReasoningEffort | None`
+- `pipelex/plugins/openai/openai_config.py:32` — `OpenAIConfig.get_reasoning_level` — `def get_reasoning_level(self, effort: ReasoningEffort) -> 'ChatCompletionReasoningEffort | None'`
+- `pipelex/plugins/openai/openai_func.py:12` — `create_pydantic_model_from_function` — `def create_pydantic_model_from_function(func: Callable[..., Any]) -> type[BaseModel]`
+- `pipelex/plugins/openai/openai_func.py:33` — `create_openai_schema_from_function` — `def create_openai_schema_from_function(func: Callable[..., Any]) -> dict[str, Any]`
+- `pipelex/plugins/openai/openai_func.py:63` — `list_openai_tools` — `def list_openai_tools(openai_message: ChatCompletionMessage) -> list[str]`
+- `pipelex/plugins/openai/openai_img_gen_factory.py:121` — `OpenAIImgGenFactory.moderation_for_openai_image` — `def moderation_for_openai_image(cls, is_moderated: bool | None) -> OpenAIImageModerationType`
+- `pipelex/plugins/openai/openai_img_gen_factory.py:130` — `OpenAIImgGenFactory.input_fidelity_for_openai_image` — `def input_fidelity_for_openai_image(cls, input_fidelity: InputFidelity) -> OpenAIImageInputFidelityType`
+- `pipelex/plugins/openai/openai_img_gen_factory.py:138` — `OpenAIImgGenFactory._size_to_string` — `def _size_to_string(size: ImageSize) -> str`
+- `pipelex/plugins/openai/openai_img_gen_worker.py:186` — `OpenAIImgGenWorker._convert_image_data_urls_for_openai_sdk` — `def _convert_image_data_urls_for_openai_sdk(image_arg: Any) -> list[tuple[str, bytes, str]]`
+- `pipelex/plugins/openai/openai_img_gen_worker.py:209` — `OpenAIImgGenWorker._get_requested_size` — `def _get_requested_size(args_dict: dict[str, Any]) -> str | None`
+- `pipelex/plugins/openai/openai_responses_factory.py:36` — `OpenAIResponsesFactory.make_input_items` — `async def make_input_items(self, llm_job: LLMJob) -> list[ResponseInputItemParam]`
+- `pipelex/plugins/openai/openai_responses_factory.py:93` — `OpenAIResponsesFactory._get_document_filename` — `def _get_document_filename(prompt_document: PromptDocument) -> str`
+- `pipelex/plugins/openai/openai_responses_factory.py:98` — `OpenAIResponsesFactory.make_nb_tokens_by_category` — `def make_nb_tokens_by_category(self, usage: ResponseUsage) -> NbTokensByCategoryDict`
+- `pipelex/plugins/openai/openai_responses_llm_worker.py:90` — `OpenAIResponsesLLMWorker._resolve_reasoning` — `def _resolve_reasoning(self, job_params: LLMJobParams) -> Reasoning | None`
+- `pipelex/plugins/openai/vertexai_factory.py:20` — `VertexAIFactory.make_endpoint_and_api_key` — `def make_endpoint_and_api_key(cls, extra_config: dict[str, Any]) -> tuple[str, str]`
+- `pipelex/plugins/openai/vertexai_factory.py:51` — `VertexAIFactory._make_api_key` — `def _make_api_key(cls, gcp_credentials_file_path: str) -> str`
+- `pipelex/plugins/plugin.py:19` — `Plugin.make_for_inference_model` — `def make_for_inference_model(cls, inference_model: InferenceModelSpec) -> 'Plugin'`
+- `pipelex/plugins/plugin_sdk_registry.py:19` — `PluginSdkRegistry.get_sdk_instance` — `def get_sdk_instance(self, plugin: Plugin) -> Any | None`
+- `pipelex/plugins/portkey/portkey_constants.py:17` — `PortkeyOpenAISdkVariant.is_completions` — `def is_completions(cls, sdk: str) -> bool`
+- `pipelex/plugins/portkey/portkey_constants.py:29` — `PortkeyOpenAISdkVariant.is_responses` — `def is_responses(cls, sdk: str) -> bool`
+- `pipelex/plugins/portkey/portkey_factory.py:24` — `PortkeyFactory.is_debug_enabled` — `def is_debug_enabled(cls, backend: InferenceBackend) -> bool`
+- `pipelex/plugins/portkey/portkey_factory.py:29` — `PortkeyFactory.get_endpoint` — `def get_endpoint(cls, backend: InferenceBackend) -> str`
+- `pipelex/plugins/portkey/portkey_factory.py:33` — `PortkeyFactory.get_api_key` — `def get_api_key(cls, backend: InferenceBackend) -> str`
+- `pipelex/plugins/pypdfium2/pypdfium2_worker.py:38` — `Pypdfium2Worker._resolve_pdf_uri` — `async def _resolve_pdf_uri(self, pdf_uri: str) -> PdfInput`
+
+### `reporting` (7)
+
+- `pipelex/reporting/cost_report_renderer.py:86` — `render_cost_report_for_output` — `def render_cost_report_for_output(pipe_output: PipeOutput) -> None`
+- `pipelex/reporting/reporting_manager.py:143` — `ReportingManager._report_llm_job` — `def _report_llm_job(self, llm_job: LLMJob)`
+- `pipelex/reporting/reporting_manager.py:152` — `ReportingManager._report_img_gen_job` — `def _report_img_gen_job(self, img_gen_job: ImgGenJob)`
+- `pipelex/reporting/reporting_manager.py:161` — `ReportingManager._report_extract_job` — `def _report_extract_job(self, extract_job: ExtractJob)`
+- `pipelex/reporting/reporting_manager.py:170` — `ReportingManager._report_search_job` — `def _report_search_job(self, search_job: SearchJob)`
+- `pipelex/reporting/reporting_protocol.py:10` — `ReportingProtocol.report_inference_job` — `def report_inference_job(self, inference_job: InferenceJobAbstract)`
+- `pipelex/reporting/reporting_protocol.py:25` — `ReportingProtocol.clear_event_log` — `def clear_event_log(self, context_key: str) -> None`
+
+### `runtime_bridge` (10)
+
+- `pipelex/runtime_bridge/bootstrap.py:24` — `ensure_pipelex_booted` — `def ensure_pipelex_booted(config_overrides: dict[str, Any] | None=None) -> None`
+- `pipelex/runtime_bridge/bridge.py:225` — `serialize_pipe_output` — `def serialize_pipe_output(pipe_output: PipeOutput) -> dict[str, Any]`
+- `pipelex/runtime_bridge/bridge.py:250` — `_decode_library_crate` — `def _decode_library_crate(library_crate_dump: dict[str, Any] | None) -> LibraryCrate | None`
+- `pipelex/runtime_bridge/bridge.py:260` — `_decode_delivery_assignment` — `def _decode_delivery_assignment(delivery_assignment_dump: dict[str, Any] | None) -> DeliveryAssignment | None`
+- `pipelex/runtime_bridge/bridge.py:383` — `_resolve_main_stuff_root_key` — `def _resolve_main_stuff_root_key(pipe_output: PipeOutput) -> str | None`
+- `pipelex/runtime_bridge/primitives/hydration.py:39` — `_hydrate_list_item` — `def _hydrate_list_item(raw_item: dict[str, Any] | str | StuffContent) -> StuffContent`
+- `pipelex/runtime_bridge/primitives/hydration.py:109` — `hydrate_working_memory` — `def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory`
+- `pipelex/runtime_bridge/primitives/pipe_classification.py:17` — `is_controller_pipe` — `def is_controller_pipe(pipe: PipeAbstract) -> bool`
+- `pipelex/runtime_bridge/primitives/pipe_classification.py:29` — `is_leaf_pipe` — `def is_leaf_pipe(pipe: PipeAbstract) -> bool`
+- `pipelex/runtime_bridge/primitives/trace_flush.py:14` — `flush_trace_events_to_backend` — `async def flush_trace_events_to_backend(events: list[TraceEvent]) -> None`
+
+### `system` (61)
+
+- `pipelex/system/configuration/config_check.py:12` — `check_is_initialized` — `def check_is_initialized(print_warning_if_not: bool=True) -> bool`
+- `pipelex/system/configuration/config_loader.py:32` — `ConfigLoader.find_project_root` — `def find_project_root(start_dir: Path) -> Path | None`
+- `pipelex/system/configuration/configs.py:83` — `PromptingConfig.get_prompting_style` — `def get_prompting_style(self, prompting_target: PromptingTarget | None=None) -> TemplatingStyle | None`
+- `pipelex/system/environment.py:21` — `get_required_env` — `def get_required_env(key: str) -> str`
+- `pipelex/system/environment.py:29` — `get_optional_env` — `def get_optional_env(key: str) -> str | None`
+- `pipelex/system/environment.py:33` — `is_env_var_set` — `def is_env_var_set(key: str) -> bool`
+- `pipelex/system/environment.py:37` — `all_env_vars_are_set` — `def all_env_vars_are_set(keys: list[str]) -> bool`
+- `pipelex/system/environment.py:41` — `any_env_var_is_placeholder` — `def any_env_var_is_placeholder(keys: list[str]) -> bool`
+- `pipelex/system/environment.py:53` — `is_env_var_truthy` — `def is_env_var_truthy(key: str) -> bool`
+- `pipelex/system/pipelex_service/pipelex_details.py:22` — `PipelexDetails.make_distinct_id` — `def make_distinct_id(cls, gateway_api_key: str) -> str`
+- `pipelex/system/pipelex_service/pipelex_service_config.py:24` — `load_pipelex_service_config_if_exists` — `def load_pipelex_service_config_if_exists(config_dir: Path) -> PipelexServiceConfig | None`
+- `pipelex/system/pipelex_service/pipelex_service_config.py:45` — `is_pipelex_gateway_enabled` — `def is_pipelex_gateway_enabled(backends_file_path: Path | None=None) -> bool`
+- `pipelex/system/pipelex_service/remote_config_cache.py:99` — `RemoteConfigCache.store` — `def store(cls, remote_config_payload: dict[str, Any]) -> None`
+- `pipelex/system/pipelex_service/remote_config_fetcher.py:79` — `RemoteConfigFetcher._log_retry_attempt` — `def _log_retry_attempt(cls, retry_state: RetryCallState) -> None`
+- `pipelex/system/pipelex_service/remote_config_fetcher.py:85` — `RemoteConfigFetcher._fetch_remote_config_with_retry` — `def _fetch_remote_config_with_retry(cls, url: str) -> httpx.Response`
+- `pipelex/system/pipelex_service/remote_config_fetcher.py:107` — `RemoteConfigFetcher._fetch_remote_config_with_retry._fetch_with_retry` — `def _fetch_with_retry(url: str) -> httpx.Response`
+- `pipelex/system/pipelex_service/remote_config_fetcher.py:133` — `RemoteConfigFetcher._fetch_fresh` — `def _fetch_fresh(cls, url: str) -> tuple[dict[str, Any], RemoteConfig]`
+- `pipelex/system/pipelex_service/remote_config_fetcher.py:201` — `RemoteConfigFetcher.fetch_remote_config` — `def fetch_remote_config(cls, require_fresh: bool=False) -> RemoteConfigResult`
+- `pipelex/system/registries/class_registry_utils.py:135` — `ClassRegistryUtils.auto_register_all_subclasses` — `def auto_register_all_subclasses(cls, base_class: type[Any]) -> int`
+- `pipelex/system/registries/func_registry.py:22` — `pipe_func` — `def pipe_func(name: str | None=None) -> Callable[[T], T]`
+- `pipelex/system/registries/func_registry.py:48` — `pipe_func.decorator` — `def decorator(func: T) -> T`
+- `pipelex/system/registries/func_registry.py:88` — `FuncRegistry.log` — `def log(self, message: str) -> None`
+- `pipelex/system/registries/func_registry.py:91` — `FuncRegistry.set_logger` — `def set_logger(self, logger: logging.Logger) -> None`
+- `pipelex/system/registries/func_registry.py:116` — `FuncRegistry.unregister_function` — `def unregister_function(self, func: Callable[..., Any]) -> None`
+- `pipelex/system/registries/func_registry.py:125` — `FuncRegistry.unregister_function_by_name` — `def unregister_function_by_name(self, name: str) -> None`
+- `pipelex/system/registries/func_registry.py:132` — `FuncRegistry.register_functions_dict` — `def register_functions_dict(self, functions: dict[str, Callable[..., Any]]) -> None`
+- `pipelex/system/registries/func_registry.py:137` — `FuncRegistry.register_functions` — `def register_functions(self, functions: list[Callable[..., Any]]) -> None`
+- `pipelex/system/registries/func_registry.py:142` — `FuncRegistry.get_function` — `def get_function(self, name: str) -> Callable[..., Any] | None`
+- `pipelex/system/registries/func_registry.py:146` — `FuncRegistry.get_required_function` — `def get_required_function(self, name: str) -> Callable[..., Any]`
+- `pipelex/system/registries/func_registry.py:167` — `FuncRegistry.get_required_function_with_signature` — `def get_required_function_with_signature(self, name: str) -> Callable[..., object]`
+- `pipelex/system/registries/func_registry.py:183` — `FuncRegistry.has_function` — `def has_function(self, name: str) -> bool`
+- `pipelex/system/registries/func_registry.py:187` — `FuncRegistry.is_marked_pipe_func` — `def is_marked_pipe_func(self, func: Any) -> bool`
+- `pipelex/system/registries/func_registry.py:273` — `FuncRegistry.check_function_eligibility` — `def check_function_eligibility(self, func: Any) -> str | None`
+- `pipelex/system/registries/func_registry.py:368` — `FuncRegistry.get_ineligible_function_info` — `def get_ineligible_function_info(self, name: str) -> IneligibleFunctionInfo | None`
+- `pipelex/system/registries/func_registry_utils.py:113` — `FuncRegistryUtils._register_funcs_in_file` — `def _register_funcs_in_file(cls, file_path: Path) -> None`
+- `pipelex/system/registries/func_registry_utils.py:176` — `FuncRegistryUtils._find_functions_in_module` — `def _find_functions_in_module(cls, module: Any) -> list[Callable[..., Any]]`
+- `pipelex/system/registries/func_registry_utils.py:211` — `FuncRegistryUtils._get_function_registration_name` — `def _get_function_registration_name(cls, func: Callable[..., Any]) -> str`
+- `pipelex/system/registries/singleton.py:21` — `MetaSingleton.clear_subclass_instances` — `def clear_subclass_instances(cls, base_cls: type[Any]) -> None`
+- `pipelex/system/registries/singleton.py:28` — `MetaSingleton.get_subclass_instance` — `def get_subclass_instance(cls, base_cls: type[T]) -> T | None`
+- `pipelex/system/runtime.py:100` — `RuntimeManager.set_run_mode` — `def set_run_mode(self, run_mode: RunMode)`
+- `pipelex/system/runtime.py:103` — `RuntimeManager.set_worker_mode` — `def set_worker_mode(self, worker_mode: WorkerMode)`
+- `pipelex/system/telemetry/exception_capture.py:56` — `DualClientExceptionCapture._thread_exception_handler` — `def _thread_exception_handler(self, args: threading.ExceptHookArgs) -> None`
+- `pipelex/system/telemetry/exception_capture.py:62` — `DualClientExceptionCapture._capture_exception` — `def _capture_exception(self, exc_info: tuple[type[BaseException], BaseException | None, TracebackType | None]) -> None`
+- `pipelex/system/telemetry/otel_constants.py:93` — `make_otel_gen_ai_output_type` — `def make_otel_gen_ai_output_type(output_type: str) -> otel_gen_ai_attributes.GenAiOutputTypeValues`
+- `pipelex/system/telemetry/otel_factory.py:48` — `OtelFactory.stringify_json` — `def stringify_json(cls, json_conent: JsonContent) -> str`
+- `pipelex/system/telemetry/otel_factory.py:118` — `OtelFactory.make_trace_id` — `def make_trace_id(cls, pipeline_run_id: str) -> int`
+- `pipelex/system/telemetry/otel_factory.py:151` — `OtelFactory._is_unresolved_placeholder` — `def _is_unresolved_placeholder(cls, value: str | None) -> bool`
+- `pipelex/system/telemetry/otel_factory.py:156` — `OtelFactory.make_langfuse_exporter` — `def make_langfuse_exporter(cls, langfuse_config: LangfuseConfig) -> 'OTLPSpanExporter'`
+- `pipelex/system/telemetry/posthog_span_exporter.py:64` — `PostHogSpanExporter._truncate_content` — `def _truncate_content(self, content: str) -> str`
+- `pipelex/system/telemetry/posthog_span_exporter.py:80` — `PostHogSpanExporter._apply_content_redaction` — `def _apply_content_redaction(self, properties: dict[str, Any]) -> None`
+- `pipelex/system/telemetry/posthog_span_exporter.py:172` — `PostHogSpanExporter._get_redacted_pipe_code` — `def _get_redacted_pipe_code(self, pipe_code: str | None) -> str | None`
+- `pipelex/system/telemetry/posthog_span_exporter.py:185` — `PostHogSpanExporter._get_redacted_output_class_name` — `def _get_redacted_output_class_name(self, output_class_name: str | None) -> str | None`
+- `pipelex/system/telemetry/posthog_span_exporter.py:337` — `PostHogSpanExporter._do_export` — `def _do_export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult`
+- `pipelex/system/telemetry/telemetry_config.py:182` — `TelemetryConfig.is_custom_telemetry_allowed_for_mode` — `def is_custom_telemetry_allowed_for_mode(self, mode: str) -> bool`
+- `pipelex/system/telemetry/telemetry_config.py:214` — `TelemetryRedactionConfig.make_from_posthog_config` — `def make_from_posthog_config(cls, posthog_config: PostHogConfig | None) -> Self`
+- `pipelex/system/telemetry/telemetry_config.py:239` — `load_telemetry_config` — `def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> TelemetryConfig`
+- `pipelex/system/telemetry/telemetry_manager.py:155` — `TelemetryManager._wrap_capture_exception` — `def _wrap_capture_exception(self, client: Posthog) -> None`
+- `pipelex/system/telemetry/telemetry_manager.py:163` — `TelemetryManager._wrap_capture_exception.sanitized_capture_exception` — `def sanitized_capture_exception(exception: ExceptionArg | None=None, **kwargs: Unpack[OptionalCaptureArgs]) -> Any`
+- `pipelex/system/telemetry/telemetry_manager_abstract.py:89` — `TelemetryManagerAbstract.setup` — `def setup(self, integration_mode: IntegrationMode)`
+- `pipelex/system/telemetry/telemetry_manager_abstract.py:106` — `TelemetryManagerAbstract.is_custom_portkey_logging_enabled` — `def is_custom_portkey_logging_enabled(self, is_debug_configured: bool) -> bool`
+- `pipelex/system/telemetry/telemetry_manager_abstract.py:114` — `TelemetryManagerAbstract.is_pipelex_gateway_portkey_logging_enabled` — `def is_pipelex_gateway_portkey_logging_enabled(self, is_debug_configured: bool) -> bool`
+
+### `temporal` (48)
+
+- `pipelex/temporal/codec/codec_server.py:39` — `_make_cors_handler` — `def _make_cors_handler(cors_origins: list[str]) -> Callable[[web.Request], Awaitable[web.Response]]`
+- `pipelex/temporal/codec/codec_server.py:42` — `_make_cors_handler.cors_options` — `async def cors_options(request: web.Request) -> web.Response`
+- `pipelex/temporal/codec/storage_payload_codec.py:49` — `StoragePayloadCodec._extract_job_routing` — `def _extract_job_routing(payload: Payload) -> tuple[str, str] | None`
+- `pipelex/temporal/codec/storage_payload_codec.py:75` — `StoragePayloadCodec._sanitize_path_segment` — `def _sanitize_path_segment(segment: str) -> str`
+- `pipelex/temporal/config_temporal.py:192` — `RetryPolicyConfigBase.make_retry_policy` — `def make_retry_policy(self, merged_non_retryable_types: list[str]) -> 'RetryPolicy'`
+- `pipelex/temporal/config_temporal.py:445` — `WorkerConfig.all_non_retryable_error_types` — `def all_non_retryable_error_types(self, queue_options_by_queue: dict[str, 'QueueOptions']) -> set[str]`
+- `pipelex/temporal/config_temporal.py:731` — `Temporal.validate_task_queue_known` — `def validate_task_queue_known(self, task_queue: str) -> None`
+- `pipelex/temporal/log_temporal.py:64` — `_RequestIdLog.verbose` — `def verbose(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/log_temporal.py:67` — `_RequestIdLog.debug` — `def debug(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/log_temporal.py:70` — `_RequestIdLog.dev` — `def dev(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/log_temporal.py:73` — `_RequestIdLog.info` — `def info(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/log_temporal.py:76` — `_RequestIdLog.warning` — `def warning(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/log_temporal.py:79` — `_RequestIdLog.error` — `def error(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/log_temporal.py:82` — `_RequestIdLog.critical` — `def critical(self, content: Union[str, Any]) -> None`
+- `pipelex/temporal/sandbox_manager.py:9` — `SandboxManager.set_sandbox_callable` — `def set_sandbox_callable(self, sandbox_callable: Callable[[], bool])`
+- `pipelex/temporal/temporal_connect.py:83` — `connect_to_temporal_selected_server` — `async def connect_to_temporal_selected_server(selected_server_config: str) -> TemporalClient`
+- `pipelex/temporal/temporal_data_converter.py:57` — `BaseModelPayloadConverter._is_kajson_wire_value` — `def _is_kajson_wire_value(cls, value: object) -> bool`
+- `pipelex/temporal/temporal_data_converter.py:79` — `BaseModelPayloadConverter._first_kajson_list_element` — `def _first_kajson_list_element(cls, value: object) -> object | None`
+- `pipelex/temporal/temporal_data_converter.py:101` — `BaseModelPayloadConverter._kajson_deserialize_from_payload` — `def _kajson_deserialize_from_payload(self, payload: Payload) -> Any`
+- `pipelex/temporal/temporal_data_converter.py:133` — `BaseModelPayloadConverter._is_kajson_type` — `def _is_kajson_type(cls, type_hint: Any) -> bool`
+- `pipelex/temporal/temporal_data_converter.py:145` — `BaseModelPayloadConverter._unwrap_optional_kajson_type` — `def _unwrap_optional_kajson_type(cls, type_hint: type[Any] | None) -> bool`
+- `pipelex/temporal/temporal_data_converter.py:200` — `make_data_converter` — `def make_data_converter(payload_codec: PayloadCodec | None=None) -> DataConverter`
+- `pipelex/temporal/temporal_hub.py:20` — `TemporalHub.set_task_manager` — `def set_task_manager(self, task_manager: TaskManager)`
+- `pipelex/temporal/temporal_manager.py:37` — `TemporalManager.setup` — `def setup(cls, session_id: str) -> None`
+- `pipelex/temporal/temporal_manager.py:86` — `TemporalManager.get_temporal_client` — `async def get_temporal_client(self, should_auto_connect: bool) -> TemporalClient`
+- `pipelex/temporal/temporal_manager.py:95` — `TemporalManager.make_top_workflow_id` — `def make_top_workflow_id(self, pipeline_run_id: str) -> str`
+- `pipelex/temporal/temporal_manager.py:115` — `get_temporal_client` — `async def get_temporal_client(should_auto_connect: bool) -> TemporalClient`
+- `pipelex/temporal/temporal_task_manager.py:236` — `TemporalTaskManager._resolve_scope_by_name` — `def _resolve_scope_by_name(scope_name: str | None) -> WorkerScope`
+- `pipelex/temporal/temporal_task_manager.py:245` — `TemporalTaskManager._resolve_runtime_profile_by_name` — `def _resolve_runtime_profile_by_name(profile_name: str | None) -> WorkerRuntimeProfile`
+- `pipelex/temporal/test_extras/wf_test_structured_output_cross_process.py:65` — `_assert_invoice_round_trip` — `def _assert_invoice_round_trip(invoice: FixtureInvoice) -> None`
+- `pipelex/temporal/test_extras/wf_test_structured_output_cross_process.py:101` — `_assert_invoice_list_round_trip` — `def _assert_invoice_list_round_trip(invoices: list[FixtureInvoice]) -> None`
+- `pipelex/temporal/test_helpers/temporal_pytest_plugins.py:11` — `pytest_addoption` — `def pytest_addoption(parser: Parser)`
+- `pipelex/temporal/tprl/activity_error_boundary.py:25` — `convert_pipelex_errors` — `def convert_pipelex_errors(func: Callable[_ActivityParams, Awaitable[_ActivityReturn]]) -> Callable[_ActivityParams, Awaitable[_ActivityReturn]]`
+- `pipelex/temporal/tprl/conditional_worker.py:17` — `with_conditional_worker` — `def with_conditional_worker(execute_workflow: FuncExecuteWorkflow) -> FuncExecuteWorkflow`
+- `pipelex/temporal/tprl/observability.py:64` — `stamp_submitter_session_id` — `def stamp_submitter_session_id(pipe_job: PipeJob) -> PipeJob`
+- `pipelex/temporal/tprl/observability.py:85` — `build_search_attributes` — `def build_search_attributes(pipe_job: PipeJob) -> TypedSearchAttributes`
+- `pipelex/temporal/tprl/observability.py:124` — `build_static_summary` — `def build_static_summary(pipe: PipeAbstract) -> str`
+- `pipelex/temporal/tprl/observability.py:137` — `build_static_details` — `def build_static_details(pipe_job: PipeJob) -> str`
+- `pipelex/temporal/tprl/temporal_error.py:25` — `error_report_dict_from_details` — `def error_report_dict_from_details(details: Sequence[Any]) -> dict[str, Any] | None`
+- `pipelex/temporal/tprl/temporal_error.py:41` — `_find_error_report_dict` — `def _find_error_report_dict(exc: BaseException) -> dict[str, Any] | None`
+- `pipelex/temporal/tprl/temporal_error.py:64` — `_message_from_exc` — `def _message_from_exc(exc: BaseException) -> str`
+- `pipelex/temporal/tprl/temporal_error.py:85` — `recover_error_report` — `def recover_error_report(exc: BaseException) -> ErrorReport`
+- `pipelex/temporal/tprl/temporal_error.py:168` — `TemporalError._log_critical` — `def _log_critical(cls, message: str) -> None`
+- `pipelex/temporal/tprl/temporal_error.py:181` — `TemporalError._log_error` — `def _log_error(cls, message: str) -> None`
+- `pipelex/temporal/tprl/temporal_error.py:192` — `TemporalError._error_type_in_name_list` — `def _error_type_in_name_list(cls, error_type: str | None) -> bool`
+- `pipelex/temporal/tprl/temporal_error.py:205` — `TemporalError.from_app_error` — `def from_app_error(cls, exc: ApplicationError) -> Self`
+- `pipelex/temporal/tprl/workflow_caller.py:86` — `WorkflowExecutor.make_workflow_id` — `def make_workflow_id(self, pipeline_run_id: str) -> str`
+- `pipelex/temporal/tprl_pipe/wf_pipe_router.py:25` — `_carries_temporal_failure` — `def _carries_temporal_failure(exc: BaseException) -> bool`
+
+### `test_extras` (6)
+
+- `pipelex/test_extras/shared_pytest_plugins.py:69` — `pytest_addoption` — `def pytest_addoption(parser: Parser)`
+- `pipelex/test_extras/shared_pytest_plugins.py:93` — `pytest_configure` — `def pytest_configure(config: Config) -> None`
+- `pipelex/test_extras/shared_pytest_plugins.py:151` — `_setup_env_var_placeholders` — `def _setup_env_var_placeholders(env_var_keys: list[str]) -> None`
+- `pipelex/test_extras/shared_pytest_plugins.py:174` — `_cleanup_placeholder_env_vars` — `def _cleanup_placeholder_env_vars(env_var_keys: list[str]) -> None`
+- `pipelex/test_extras/shared_pytest_plugins.py:230` — `needs_inference_in_pipelex` — `def needs_inference_in_pipelex(request: FixtureRequest) -> bool`
+- `pipelex/test_extras/shared_pytest_plugins.py:256` — `is_inference_disabled_in_pipelex` — `def is_inference_disabled_in_pipelex(request: FixtureRequest) -> bool`
+
+### `tools` (165)
+
+- `pipelex/tools/aws/aws_config.py:37` — `AwsConfig.get_aws_access_keys_with_method` — `def get_aws_access_keys_with_method(self, api_key_method: AwsKeyMethod) -> tuple[str, str, str]`
+- `pipelex/tools/jinja2/image_registry.py:27` — `ImageRegistry.register_image` — `def register_image(self, image: Any) -> int`
+- `pipelex/tools/jinja2/image_registry.py:48` — `ImageRegistry.get_image_placeholder` — `def get_image_placeholder(self, image: Any) -> str | None`
+- `pipelex/tools/jinja2/image_registry.py:74` — `ImageRegistry.make_finalize.finalize` — `def finalize(value: Any) -> Any`
+- `pipelex/tools/jinja2/jinja2_filters.py:139` — `escape_script_tag` — `def escape_script_tag(value: Any) -> Any`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:32` — `_build_full_path` — `def _build_full_path(node: nodes.Node) -> str | None`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:50` — `_collect_declarations_from_body` — `def _collect_declarations_from_body(body: list[nodes.Node]) -> set[str]`
+- `pipelex/tools/jinja2/jinja2_required_variables.py:163` — `_extract_filters_and_variable` — `def _extract_filters_and_variable(node: nodes.Node) -> tuple[list[str], nodes.Node | None]`
+- `pipelex/tools/jinja2/jinja2_template_loader.py:117` — `TemplateLoader.load` — `def load(cls, name: str) -> None`
+- `pipelex/tools/jinja2/jinja2_template_loader.py:157` — `TemplateLoader.reload` — `def reload(cls, name: str | None=None) -> None`
+- `pipelex/tools/jinja2/jinja2_template_loader.py:173` — `TemplateLoader.is_loaded` — `def is_loaded(cls, name: str) -> bool`
+- `pipelex/tools/jinja2/jinja2_template_registry.py:47` — `TemplateRegistry.get` — `def get(cls, key: str) -> str`
+- `pipelex/tools/jinja2/jinja2_template_registry.py:77` — `TemplateRegistry.is_registered` — `def is_registered(cls, key: str) -> bool`
+- `pipelex/tools/jinja2/text_format_renderable.py:32` — `TextFormatRenderable.rendered_for_template_async` — `async def rendered_for_template_async(self, text_format: TextFormat) -> str`
+- `pipelex/tools/log/log.py:28` — `Log.set_log_mode` — `def set_log_mode(self, mode: LogMode)`
+- `pipelex/tools/log/log.py:73` — `Log.configure_if_unset` — `def configure_if_unset(self, log_config: LogConfig) -> bool`
+- `pipelex/tools/log/log.py:92` — `Log.configure` — `def configure(self, log_config: LogConfig)`
+- `pipelex/tools/log/log.py:131` — `Log.set_poor_log_formatter` — `def set_poor_log_formatter(self, formatter: logging.Formatter)`
+- `pipelex/tools/log/log.py:143` — `Log._should_ignore` — `def _should_ignore(self, problem_id: str | None=None) -> bool`
+- `pipelex/tools/log/log.py:170` — `Log.set_level_by_int` — `def set_level_by_int(self, level_int: int)`
+- `pipelex/tools/log/log.py:179` — `Log.set_level_by_name` — `def set_level_by_name(self, level_name: str)`
+- `pipelex/tools/log/log.py:194` — `Log.set_level` — `def set_level(self, level: LogLevel)`
+- `pipelex/tools/log/log.py:214` — `Log.set_levels_for_packages` — `def set_levels_for_packages(self, package_log_levels: dict[str, LogLevel])`
+- `pipelex/tools/log/log_config.py:41` — `CallerInfoTemplate.for_template_key` — `def for_template_key(cls, key: CallerInfoTemplate) -> str`
+- `pipelex/tools/log/log_config.py:71` — `RichLogConfig.make_rich_handler` — `def make_rich_handler(self, target: ConsoleTarget) -> RichHandler`
+- `pipelex/tools/log/log_dispatch.py:23` — `LogDispatch.set_log_mode` — `def set_log_mode(self, mode: LogMode)`
+- `pipelex/tools/log/log_dispatch.py:46` — `LogDispatch.configure` — `def configure(self, log_config: LogConfig)`
+- `pipelex/tools/log/log_formatter.py:10` — `emoji_for_channel` — `def emoji_for_channel(channel_name: str) -> str | None`
+- `pipelex/tools/log/log_levels.py:47` — `LogLevel.from_int` — `def from_int(logging_level: int) -> 'LogLevel'`
+- `pipelex/tools/mermaid/mermaid_utils.py:32` — `encode_pako_from_bytes` — `def encode_pako_from_bytes(state_bytes: bytes) -> str`
+- `pipelex/tools/mermaid/mermaid_utils.py:39` — `encode_pako_from_string` — `def encode_pako_from_string(state: str) -> str`
+- `pipelex/tools/mermaid/mermaid_utils.py:45` — `make_mermaid_url` — `def make_mermaid_url(mermaid_code: str) -> str`
+- `pipelex/tools/mermaid/mermaid_utils.py:80` — `clean_str_for_mermaid_node_title` — `def clean_str_for_mermaid_node_title(text: str) -> str`
+- `pipelex/tools/mermaid/mermaid_utils.py:97` — `sanitize_mermaid_id` — `def sanitize_mermaid_id(node_id: str) -> str`
+- `pipelex/tools/mermaid/mermaid_utils.py:114` — `escape_mermaid_label` — `def escape_mermaid_label(label: str) -> str`
+- `pipelex/tools/misc/async_utils.py:8` — `_invoke` — `async def _invoke(factory: Callable[[], Awaitable[_T]]) -> _T`
+- `pipelex/tools/misc/attribute_utils.py:26` — `AttributePolisher.should_truncate` — `def should_truncate(cls, value: Any) -> bool`
+- `pipelex/tools/misc/attribute_utils.py:39` — `AttributePolisher.get_truncated_value` — `def get_truncated_value(cls, value: Any) -> Any`
+- `pipelex/tools/misc/attribute_utils.py:53` — `AttributePolisher._looks_like_base64` — `def _looks_like_base64(cls, value: str) -> bool`
+- `pipelex/tools/misc/base64_utils.py:9` — `load_binary_as_base64` — `async def load_binary_as_base64(path: Path) -> str`
+- `pipelex/tools/misc/base64_utils.py:15` — `make_base64_url_from_path` — `async def make_base64_url_from_path(path: Path) -> str`
+- `pipelex/tools/misc/base64_utils.py:23` — `make_base64_url_from_http_url` — `async def make_base64_url_from_http_url(url: str) -> str`
+- `pipelex/tools/misc/base64_utils.py:31` — `make_base64_url_from_bytes` — `def make_base64_url_from_bytes(raw_bytes: bytes) -> str`
+- `pipelex/tools/misc/base64_utils.py:47` — `is_prefixed_base64_url` — `def is_prefixed_base64_url(possibly_base64_url: str) -> bool`
+- `pipelex/tools/misc/base64_utils.py:51` — `strip_base64_str_if_needed` — `def strip_base64_str_if_needed(base64_str: str) -> str`
+- `pipelex/tools/misc/base64_utils.py:59` — `extract_base64_str_from_base64_url_if_possible` — `def extract_base64_str_from_base64_url_if_possible(possibly_base64_url: str) -> tuple[str, str] | None`
+- `pipelex/tools/misc/dict_utils.py:173` — `extract_vars_from_strings_recursive` — `def extract_vars_from_strings_recursive(data: Any) -> set[str]`
+- `pipelex/tools/misc/dict_utils.py:194` — `extract_vars_from_strings_recursive.extract_from_string` — `def extract_from_string(text: str) -> None`
+- `pipelex/tools/misc/dict_utils.py:221` — `extract_vars_from_strings_recursive.traverse` — `def traverse(value: Any) -> None`
+- `pipelex/tools/misc/diff.py:44` — `has_diff_dirs._filter_excluded_files` — `def _filter_excluded_files(file_list: list[str]) -> list[str]`
+- `pipelex/tools/misc/diff.py:47` — `has_diff_dirs._has_diff` — `def _has_diff(dir_comparison: filecmp.dircmp[str]) -> bool`
+- `pipelex/tools/misc/diff.py:238` — `make_diff_dirs_pretty._filter_excluded_files` — `def _filter_excluded_files(file_list: list[str]) -> list[str]`
+- `pipelex/tools/misc/document_utils.py:59` — `DocumentFormat.is_supported_mime_type` — `def is_supported_mime_type(cls, mime_type: str) -> bool`
+- `pipelex/tools/misc/document_utils.py:64` — `DocumentFormat.raise_if_unsupported_mime_type` — `def raise_if_unsupported_mime_type(cls, mime_type: str) -> None`
+- `pipelex/tools/misc/document_utils.py:79` — `DocumentFormat.from_mime_type` — `def from_mime_type(cls, mime_type: str) -> 'DocumentFormat'`
+- `pipelex/tools/misc/exceptions.py:36` — `TomlError.from_tomli_error` — `def from_tomli_error(cls, exc: tomli.TOMLDecodeError) -> Self`
+- `pipelex/tools/misc/file_utils.py:82` — `load_text_from_path` — `def load_text_from_path(path: Path) -> str`
+- `pipelex/tools/misc/file_utils.py:101` — `failable_load_text_from_path` — `def failable_load_text_from_path(path: Path) -> str | None`
+- `pipelex/tools/misc/file_utils.py:119` — `load_binary` — `def load_binary(path: Path) -> bytes`
+- `pipelex/tools/misc/file_utils.py:123` — `load_binary_async` — `async def load_binary_async(path: Path) -> bytes`
+- `pipelex/tools/misc/file_utils.py:217` — `remove_file` — `def remove_file(file_path: Path)`
+- `pipelex/tools/misc/file_utils.py:234` — `remove_folder` — `def remove_folder(folder_path: Path) -> None`
+- `pipelex/tools/misc/file_utils.py:273` — `_reraise_walk_error` — `def _reraise_walk_error(walk_error: OSError) -> None`
+- `pipelex/tools/misc/file_utils.py:406` — `ensure_directory_exists` — `def ensure_directory_exists(directory_path: Path) -> None`
+- `pipelex/tools/misc/file_utils.py:416` — `ensure_path` — `def ensure_path(path: Path) -> bool`
+- `pipelex/tools/misc/file_utils.py:435` — `ensure_directory_for_file_path` — `def ensure_directory_for_file_path(file_path: Path) -> None`
+- `pipelex/tools/misc/file_utils.py:444` — `path_exists` — `def path_exists(path_str: str | Path) -> bool`
+- `pipelex/tools/misc/filetype_utils.py:38` — `detect_file_type_from_path` — `def detect_file_type_from_path(path: Path) -> FileType`
+- `pipelex/tools/misc/filetype_utils.py:60` — `detect_file_type_from_bytes` — `def detect_file_type_from_bytes(raw_bytes: bytes) -> FileType`
+- `pipelex/tools/misc/filetype_utils.py:82` — `detect_file_type_from_base64` — `def detect_file_type_from_base64(base64_data: str | bytes) -> FileType`
+- `pipelex/tools/misc/filetype_utils.py:115` — `mime_type_to_extension` — `def mime_type_to_extension(mime_type: str) -> str`
+- `pipelex/tools/misc/hash_utils.py:24` — `hash_md5_to_int` — `def hash_md5_to_int(string: str) -> int`
+- `pipelex/tools/misc/http_utils.py:24` — `validate_url_resource_exists` — `def validate_url_resource_exists(url: str) -> None`
+- `pipelex/tools/misc/http_utils.py:50` — `_validate_http_url` — `def _validate_http_url(url: str) -> None`
+- `pipelex/tools/misc/http_utils.py:80` — `_validate_local_path` — `def _validate_local_path(url: str) -> None`
+- `pipelex/tools/misc/image_utils.py:58` — `ImageFormat.from_mime_type` — `def from_mime_type(cls, mime_type: str) -> 'ImageFormat'`
+- `pipelex/tools/misc/image_utils.py:72` — `ImageFormat.is_supported_mime_type` — `def is_supported_mime_type(cls, mime_type: str) -> bool`
+- `pipelex/tools/misc/image_utils.py:77` — `ImageFormat.raise_if_unsupported_mime_type` — `def raise_if_unsupported_mime_type(cls, mime_type: str) -> None`
+- `pipelex/tools/misc/json_utils.py:23` — `clean_json_content` — `def clean_json_content(content: Any) -> Any`
+- `pipelex/tools/misc/json_utils.py:156` — `load_json_from_path` — `def load_json_from_path(path: Path) -> JsonContent`
+- `pipelex/tools/misc/json_utils.py:177` — `load_json_dict_from_path` — `def load_json_dict_from_path(path: Path) -> dict[str, Any]`
+- `pipelex/tools/misc/json_utils.py:202` — `load_json_list_from_path` — `def load_json_list_from_path(path: Path) -> list[Any]`
+- `pipelex/tools/misc/json_utils.py:262` — `remove_none_values` — `def remove_none_values(json_content: JsonContent | Any) -> JsonContent | Any`
+- `pipelex/tools/misc/json_utils.py:307` — `remove_none_values_from_dict` — `def remove_none_values_from_dict(data: Mapping[str, Any]) -> dict[str, Any]`
+- `pipelex/tools/misc/placeholder.py:4` — `make_placeholder_value` — `def make_placeholder_value(key: str) -> str`
+- `pipelex/tools/misc/placeholder.py:17` — `value_is_placeholder` — `def value_is_placeholder(value: str | None) -> bool`
+- `pipelex/tools/misc/semver.py:18` — `parse_version` — `def parse_version(version_str: str) -> Version`
+- `pipelex/tools/misc/semver.py:40` — `parse_constraint` — `def parse_constraint(constraint_str: str) -> SimpleSpec`
+- `pipelex/tools/misc/semver.py:119` — `parse_version_tag` — `def parse_version_tag(tag: str) -> Version | None`
+- `pipelex/tools/misc/string_utils.py:6` — `has_text` — `def has_text(text: str) -> bool`
+- `pipelex/tools/misc/string_utils.py:22` — `is_none_or_has_text` — `def is_none_or_has_text(text: str | None) -> bool`
+- `pipelex/tools/misc/string_utils.py:39` — `can_inject_text` — `def can_inject_text(value: Any | None) -> bool`
+- `pipelex/tools/misc/string_utils.py:63` — `is_not_none_and_has_text` — `def is_not_none_and_has_text(text: str | None) -> bool`
+- `pipelex/tools/misc/string_utils.py:80` — `camel_to_snake_case` — `def camel_to_snake_case(name: str) -> str`
+- `pipelex/tools/misc/string_utils.py:101` — `pascal_case_to_snake_case` — `def pascal_case_to_snake_case(name: str) -> str`
+- `pipelex/tools/misc/string_utils.py:121` — `pascal_case_to_kebab` — `def pascal_case_to_kebab(name: str) -> str`
+- `pipelex/tools/misc/string_utils.py:158` — `pascal_case_to_sentence` — `def pascal_case_to_sentence(name: str) -> str`
+- `pipelex/tools/misc/string_utils.py:199` — `snake_to_pascal_case` — `def snake_to_pascal_case(snake_str: str) -> str`
+- `pipelex/tools/misc/string_utils.py:220` — `snake_to_capitalize_first_letter` — `def snake_to_capitalize_first_letter(snake_str: str) -> str`
+- `pipelex/tools/misc/string_utils.py:242` — `snake_to_title_case` — `def snake_to_title_case(snake_str: str) -> str`
+- `pipelex/tools/misc/string_utils.py:262` — `is_snake_case` — `def is_snake_case(word: str) -> bool`
+- `pipelex/tools/misc/string_utils.py:266` — `is_pascal_case` — `def is_pascal_case(word: str) -> bool`
+- `pipelex/tools/misc/string_utils.py:270` — `normalize_to_ascii` — `def normalize_to_ascii(text: str) -> str`
+- `pipelex/tools/misc/string_utils.py:309` — `get_root_from_dotted_path` — `def get_root_from_dotted_path(dotted_path: str) -> str`
+- `pipelex/tools/misc/tenacity_utils.py:6` — `log_retry` — `def log_retry(retry_state: RetryCallState) -> None`
+- `pipelex/tools/misc/toml_utils.py:17` — `load_toml_from_content` — `def load_toml_from_content(content: str) -> dict[str, Any]`
+- `pipelex/tools/misc/toml_utils.py:25` — `load_toml_from_path` — `def load_toml_from_path(path: str | Path) -> dict[str, Any]`
+- `pipelex/tools/misc/toml_utils.py:46` — `load_toml_from_path_if_exists` — `def load_toml_from_path_if_exists(path: str | Path) -> dict[str, Any] | None`
+- `pipelex/tools/misc/toml_utils.py:53` — `load_toml_with_tomlkit` — `def load_toml_with_tomlkit(path: str | Path) -> tomlkit.TOMLDocument`
+- `pipelex/tools/misc/toml_utils.py:79` — `load_toml_from_path_and_merge_with_overrides` — `def load_toml_from_path_and_merge_with_overrides(paths: Sequence[str | Path]) -> dict[str, Any]`
+- `pipelex/tools/network/host_rules.py:19` — `is_disallowed_ip` — `def is_disallowed_ip(host: str) -> bool`
+- `pipelex/tools/network/host_rules.py:43` — `is_disallowed_host` — `def is_disallowed_host(host: str) -> bool`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:41` — `_resolve_pdf_uri_to_input` — `async def _resolve_pdf_uri_to_input(pdf_uri: str) -> PdfInput`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:178` — `PyPdfium2Renderer._extract_text_from_pdf_pages_sync` — `def _extract_text_from_pdf_pages_sync(pdf_input: PdfInput) -> list[str]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:273` — `PyPdfium2Renderer.extract_text_from_pdf_pages` — `async def extract_text_from_pdf_pages(self, pdf_input: PdfInput) -> list[str]`
+- `pipelex/tools/pdf/pypdfium2_renderer.py:282` — `PyPdfium2Renderer.extract_text_from_pdf_pages_from_uri` — `async def extract_text_from_pdf_pages_from_uri(self, pdf_uri: str) -> list[str]`
+- `pipelex/tools/secrets/secrets_provider_abstract.py:8` — `SecretsProviderAbstract.get_required_secret` — `def get_required_secret(self, secret_id: str) -> str`
+- `pipelex/tools/secrets/secrets_provider_abstract.py:11` — `SecretsProviderAbstract.get_optional_secret` — `def get_optional_secret(self, secret_id: str) -> str | None`
+- `pipelex/tools/secrets/secrets_provider_abstract.py:22` — `SecretsProviderAbstract.get_secret` — `def get_secret(self, secret_id: str) -> str`
+- `pipelex/tools/secrets/secrets_utils.py:51` — `substitute_vars.replace_var` — `def replace_var(match: re.Match[str]) -> str`
+- `pipelex/tools/secrets/secrets_utils.py:130` — `_get_env_var` — `def _get_env_var(var_name: str) -> str`
+- `pipelex/tools/storage/gcp_storage_provider.py:84` — `GcpStorageProvider._load_with_metadata_sync` — `def _load_with_metadata_sync(self, key: str) -> StoredData`
+- `pipelex/tools/storage/gcp_storage_provider.py:170` — `GcpStorageProvider._make_public_url` — `def _make_public_url(self, key: str) -> str`
+- `pipelex/tools/storage/gcp_storage_provider.py:181` — `GcpStorageProvider._generate_signed_url_sync` — `def _generate_signed_url_sync(self, key: str) -> str | None`
+- `pipelex/tools/storage/local_storage_provider.py:26` — `LocalStorageProvider._validate_key` — `def _validate_key(self, key: str) -> Path`
+- `pipelex/tools/storage/s3_storage_provider.py:176` — `S3StorageProvider._make_public_url` — `def _make_public_url(self, key: str) -> str`
+- `pipelex/tools/storage/storage_provider_abstract.py:28` — `StorageProviderAbstract._strip_scheme` — `def _strip_scheme(self, uri: str) -> str`
+- `pipelex/tools/storage/storage_provider_abstract.py:45` — `StorageProviderAbstract._add_scheme` — `def _add_scheme(self, key: str) -> str`
+- `pipelex/tools/storage/storage_provider_abstract.py:62` — `StorageProviderAbstract.load` — `async def load(self, uri: str) -> bytes`
+- `pipelex/tools/storage/storage_provider_abstract.py:74` — `StorageProviderAbstract.load_with_metadata` — `async def load_with_metadata(self, uri: str) -> StoredData`
+- `pipelex/tools/storage/storage_provider_abstract.py:87` — `StorageProviderAbstract._load_with_metadata` — `async def _load_with_metadata(self, key: str) -> StoredData`
+- `pipelex/tools/storage/storage_provider_abstract.py:123` — `StorageProviderAbstract.public_url` — `async def public_url(self, uri: str) -> str | None`
+- `pipelex/tools/storage/storage_provider_factory.py:14` — `make_storage_provider_from_config` — `def make_storage_provider_from_config(storage_provider_config: StorageProviderConfig) -> StorageProviderAbstract`
+- `pipelex/tools/tabular/csv_codec.py:60` — `_is_flat_annotation` — `def _is_flat_annotation(annotation: Any) -> bool`
+- `pipelex/tools/tabular/csv_codec.py:86` — `_annotation_allows_none` — `def _annotation_allows_none(annotation: Any) -> bool`
+- `pipelex/tools/tabular/csv_codec.py:93` — `flat_field_names` — `def flat_field_names(row_model: type[StuffContent]) -> list[str]`
+- `pipelex/tools/tabular/csv_codec.py:120` — `_assert_single_char_delimiter` — `def _assert_single_char_delimiter(delimiter: str) -> None`
+- `pipelex/tools/tabular/csv_codec.py:275` — `is_tabular_path` — `def is_tabular_path(path: Path) -> bool`
+- `pipelex/tools/tabular/csv_codec.py:287` — `assert_supported_table_suffix` — `def assert_supported_table_suffix(path: Path) -> None`
+- `pipelex/tools/tabular/csv_codec.py:407` — `_validation_error_label` — `def _validation_error_label(error: 'ErrorDetails') -> str`
+- `pipelex/tools/tabular/csv_codec.py:419` — `_to_cell` — `def _to_cell(value: Any) -> str`
+- `pipelex/tools/typing/class_utils.py:14` — `normalize_property_for_comparison` — `def normalize_property_for_comparison(prop: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/tools/typing/class_utils.py:46` — `normalize_properties_for_comparison` — `def normalize_properties_for_comparison(properties: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/tools/typing/class_utils.py:129` — `has_compatible_field._is_compatible` — `def _is_compatible(type_param: Any) -> bool`
+- `pipelex/tools/typing/module_inspector.py:11` — `import_module_from_file` — `def import_module_from_file(file_path: Path) -> Any`
+- `pipelex/tools/typing/module_inspector.py:58` — `convert_file_path_to_module_path` — `def convert_file_path_to_module_path(file_path: Path) -> str`
+- `pipelex/tools/typing/pydantic_utils.py:24` — `empty_list_factory_of` — `def empty_list_factory_of(_: type[T]) -> Callable[[], list[T]]`
+- `pipelex/tools/typing/pydantic_utils.py:62` — `analyze_pydantic_validation_error` — `def analyze_pydantic_validation_error(exc: ValidationError) -> PydanticValidationErrorAnalysis`
+- `pipelex/tools/typing/pydantic_utils.py:145` — `format_pydantic_validation_error` — `def format_pydantic_validation_error(exc: ValidationError) -> str`
+- `pipelex/tools/typing/pydantic_utils.py:158` — `_serialize_input_value` — `def _serialize_input_value(value: Any) -> Any`
+- `pipelex/tools/typing/pydantic_utils.py:180` — `_serialize_context` — `def _serialize_context(ctx: dict[str, Any]) -> dict[str, Any]`
+- `pipelex/tools/typing/pydantic_utils.py:196` — `format_pydantic_validation_error_for_agent` — `def format_pydantic_validation_error_for_agent(exc: ValidationError) -> tuple[str, dict[str, Any]]`
+- `pipelex/tools/typing/pydantic_utils.py:277` — `convert_strenum_to_str` — `def convert_strenum_to_str(obj: dict[str, Any] | list[Any] | StrEnum | Any) -> dict[str, Any] | list[Any] | str | Any`
+- `pipelex/tools/typing/pydantic_utils.py:305` — `clean_model_to_dict` — `def clean_model_to_dict(obj: BaseModel) -> dict[str, Any]`
+- `pipelex/tools/typing/pydantic_utils.py:409` — `_truncated_rich_repr_from_items` — `def _truncated_rich_repr_from_items(rich_repr_items: RichReprResult) -> RichReprResult`
+- `pipelex/tools/typing/pydantic_utils.py:431` — `make_truncated_wrapper` — `def make_truncated_wrapper(model: BaseModel) -> Any`
+- `pipelex/tools/typing/pydantic_utils.py:440` — `make_truncated_wrapper.rich_repr_method` — `def rich_repr_method(_self: Any) -> RichReprResult`
+- `pipelex/tools/typing/structure_printer.py:32` — `StructurePrinter.pretty_type` — `def pretty_type(self, tp: object) -> str`
+- `pipelex/tools/typing/structure_printer.py:95` — `StructurePrinter.get_type_structure.format_type` — `def format_type(tp: Any) -> str`
+- `pipelex/tools/typing/structure_printer.py:137` — `StructurePrinter.get_type_structure.collect_types` — `def collect_types(tp: type[Any]) -> None`
+- `pipelex/tools/uri/uri_resolver.py:23` — `extract_filename_from_uri` — `def extract_filename_from_uri(uri: str) -> str | None`
+- `pipelex/tools/uri/uri_resolver.py:45` — `describe_uri` — `def describe_uri(uri: str) -> str`
+- `pipelex/tools/uri/uri_resolver.py:58` — `resolve_uri` — `def resolve_uri(uri: str) -> ResolvedUri`
+- `pipelex/tools/uri/uri_resolver.py:118` — `_resolve_file_uri` — `def _resolve_file_uri(uri: str) -> ResolvedLocalPath`
+- `pipelex/tools/uri/uri_resolver.py:135` — `_resolve_base64_data_url` — `def _resolve_base64_data_url(uri: str) -> ResolvedBase64DataUrl`
+
+### `tracing` (18)
+
+- `pipelex/tracing/activity_event_log.py:44` — `ActivityEventLogCache.get_or_create` — `def get_or_create(cls, tracing_config: TracingConfig) -> EventLogProtocol | None`
+- `pipelex/tracing/dynamodb_event_log.py:95` — `DynamoDBEventLog._make_pk` — `def _make_pk(pipeline_run_id: str) -> str`
+- `pipelex/tracing/dynamodb_event_log.py:102` — `DynamoDBEventLog._key_condition` — `def _key_condition(self, pipeline_run_id: str) -> Any`
+- `pipelex/tracing/event_log_protocol.py:54` — `EventLogProtocol.emit` — `def emit(self, event: TraceEvent) -> None`
+- `pipelex/tracing/event_log_protocol.py:63` — `EventLogProtocol.read_events` — `def read_events(self, pipeline_run_id: str) -> list[TraceEvent]`
+- `pipelex/tracing/event_log_protocol.py:79` — `EventLogProtocol.cleanup` — `def cleanup(self, pipeline_run_id: str) -> None`
+- `pipelex/tracing/graphspec_assembler.py:163` — `_AssemblerState.pass_one` — `def pass_one(self, events: Sequence[TraceEvent]) -> None`
+- `pipelex/tracing/graphspec_assembler.py:220` — `_AssemblerState._track_earliest_timestamp` — `def _track_earliest_timestamp(self, event: TraceEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:224` — `_AssemblerState._handle_pipe_start` — `def _handle_pipe_start(self, event: PipeStartEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:248` — `_AssemblerState._handle_pipe_end_success` — `def _handle_pipe_end_success(self, event: PipeEndSuccessEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:276` — `_AssemblerState._handle_pipe_end_error` — `def _handle_pipe_end_error(self, event: PipeEndErrorEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:286` — `_AssemblerState._handle_edge_event` — `def _handle_edge_event(self, event: EdgeEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:304` — `_AssemblerState._handle_controller_output` — `def _handle_controller_output(self, event: ControllerOutputEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:314` — `_AssemblerState._handle_execution_data` — `def _handle_execution_data(self, event: ExecutionDataEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:321` — `_AssemblerState._handle_batch_item` — `def _handle_batch_item(self, event: BatchItemEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:327` — `_AssemblerState._handle_batch_aggregate` — `def _handle_batch_aggregate(self, event: BatchAggregateEvent) -> None`
+- `pipelex/tracing/graphspec_assembler.py:333` — `_AssemblerState._handle_parallel_combine` — `def _handle_parallel_combine(self, event: ParallelCombineEvent) -> None`
+- `pipelex/tracing/usage_aggregator.py:13` — `UsageAggregator.aggregate` — `def aggregate(events: Sequence[TraceEvent]) -> list[AnyTokensUsage]`
+
+## C. `SYMMETRIC_ALLOWLIST` — Exception 2
+
+_Exception 2 — the curated symmetric-tuple allowlist (multiple positionals that read better ordered, e.g. `set_env(key, value)`)._
+
+Count: 5
+
+- `pipelex/kit/single_file_agent_rules.py:86` — `unified_diff` — `def unified_diff(before: str, after: str, path: str) -> str`
+- `pipelex/system/environment.py:49` — `set_env` — `def set_env(key: str, value: str) -> None`
+- `pipelex/tools/misc/diff.py:79` — `diff_files` — `def diff_files(path1: str | Path, path2: str | Path) -> str`
+- `pipelex/tools/misc/diff.py:356` — `diff_dirs` — `def diff_dirs(dir1: str | Path, dir2: str | Path) -> None`
+- `pipelex/tools/typing/class_utils.py:69` — `are_classes_equivalent` — `def are_classes_equivalent(class_1: type[Any], class_2: type[Any]) -> bool`
+
+## D. `MULTI_POSITIONAL` — variadic wrapper
+
+_Survives the guard with 2+ positionals or a `*args` — i.e. a variadic wrapper/closure, not a deliberate subject choice._
+
+Count: 1
+
+- `pipelex/temporal/tprl/conditional_worker.py:36` — `with_conditional_worker.wrapper` — `async def wrapper(self: WorkflowExecutor[WorkflowInput, WorkflowOutput], *args: Any, **kwargs: Any) -> Any`
+
diff --git a/wip/keyword-only-arguments/audit/review-prompt.md b/wip/keyword-only-arguments/audit/review-prompt.md
new file mode 100644
index 000000000..7f4e3cdc0
--- /dev/null
+++ b/wip/keyword-only-arguments/audit/review-prompt.md
@@ -0,0 +1,31 @@
+# Cold-start prompt — audit the positional-subject decisions
+
+Paste the block below into a fresh session to run the review. It points the session at the audit file, fans out Sonnet 4.6 sub-agents per package, and produces a consolidated suspect list without touching any source.
+
+---
+
+We just finished a keyword-only-arguments refactor of the pipelex/ runtime. Exception 1 of the convention lets the first true parameter (the "subject") stay positional. I want to audit whether that exception was ever ABUSED — i.e. a first arg made positional just to satisfy the rule, when it isn't really the semantic object of the function and would read better keyworded.
+
+The full population is enumerated in:
+ wip/keyword-only-subject-positional-audit.md
+
+Start by reading that file's "## Review strategy" section — it's the playbook. The headline points, so you don't re-derive them:
+
+- This is a naming/API-taste call, not a reasoning task. Run the per-line judgments with SONNET 4.6 sub-agents (model: sonnet), fanned out one per package. Don't use Opus for the sweep.
+- The bottleneck is CONTEXT, not model grade. Each sub-agent MUST have Read + Grep and is expected to open the function body (and a call site or two) whenever the signature alone is ambiguous. Do NOT just hand it the text line.
+- Calibration matters: instruct each sub-agent to DEFAULT TO "fine" and emit ONLY the suspects, each as: file:line — function — current signature — why the positional reads wrong — suggested fix (usually "move the * before this arg too"). Cite the rubric in docs/contribute/keyword-only-arguments.md.
+
+Triage (don't review all 1806 lines):
+
+1. Section B (LONE_SUBJECT, ~1003) is mostly noise — one positional param means there was no subject choice to abuse. From it, keep ONLY primitive-typed lone subjects (bool/int/str/float, e.g. do_thing(True)); filter the rest mechanically. No LLM needed for the filter.
+2. Fan out Sonnet 4.6 over Section A (SUBJECT_THEN_KEYWORDS, 797) + the primitive lone-subjects, one agent per package (the audit groups entries by package with counts).
+3. Each sub-agent WRITES its package's shortlist to its own file:
+ wip/keyword-only-audit-findings/<package>.md
+ (disjoint paths, so parallel writes are safe; this preserves exact file:line citations that a returned chat message might truncate). Each entry:
+ file:line — function — current signature — why the positional reads wrong — suggested fix
+ An agent that finds nothing writes a file stating "no suspects".
+4. After the fan-out, YOU (orchestrator) merge those into one consolidated report:
+ wip/keyword-only-subject-positional-suspects.md
+ grouped by package, ordered by confidence, with a top summary count. Then stop and show me — I'll adjudicate (or we point Opus at just that shortlist).
+
+Scope of "don't change code": do NOT edit any pipelex/ source or tests in this pass — this is review only. Writing the findings/ files and the consolidated suspects report IS the deliverable, not a code change.
diff --git a/wip/keyword-only-arguments/autofix-review-followups.md b/wip/keyword-only-arguments/autofix-review-followups.md
new file mode 100644
index 000000000..19ac4ba13
--- /dev/null
+++ b/wip/keyword-only-arguments/autofix-review-followups.md
@@ -0,0 +1,67 @@
+# Keyword-only auto-fix — review follow-ups
+
+Follow-up items from the code review of the **`--fix` auto-fix** addition to the keyword-only guard (branch `feature/Tweaks-for-validation-api`, 2026-06-17). This is a follow-on to the landed keyword-only refactor tracked in this folder's [README](README.md).
+
+## What the auto-fix change added
+
+- `pipelex-dev check-keyword-only --fix` — inserts a bare `*` as far left as possible (right after `self`/`cls`, and after any `/`) so **every** non-`self`/`cls` parameter becomes keyword-only, for every *mechanically-fixable* violation, and reports the rest for a manual fix. Core lives in the stdlib-only `keyword_only_guard.py` (`fix_source` / `fix_all_violations` / `_fix_insertion_point`); reporting in `check_keyword_only_cmd.py` (`_run_fix`).
+- `make fix-keyword-only` / `fko` Makefile target.
+- `make agent-check` now runs `fix-keyword-only` early (after `fix-unused-imports`, before `format`), replacing the old check-only `check-keyword-only` step that ran last. `make check` / `c` / `cc` keep the **check-only** variant (read-only, CI-equivalent).
+- Tests in `tests/unit/pipelex/cli/dev/test_keyword_only_guard_fix.py`; docs "Auto-fix" section in `docs/contribute/keyword-only-arguments.md`.
+
+The review (3 independent finder angles + verification, conventions/markdown clean) surfaced the items below. Ranked; each tagged **bug** (fix) or **tradeoff** (decide).
+
+## Placement change (2026-06-17)
+
+Per user direction, the auto-fixer places the bare `*` **as far left as possible** so all args become keyword-only — `def f(a, b)` → `def f(*, a, b)`, `def m(self, a, b)` → `def m(self, *, a, b)`, `def make(cls, source, target)` → `def make(cls, *, source, target)` — rather than the original after-subject form (`def f(a, *, b)`). The subject-stays-positional exception is a *permission*, not a requirement, and the convention explicitly calls the all-keyword-only form "always allowed and often preferable", so the fixer now takes it. `_fix_insertion_point` targets the first positional-or-keyword param that is not `self`/`cls`; a single positional-only subject is still fixable (the `*` goes after the `/`), and only two-or-more positional-only params remain unfixable. The unfixable shapes (`*args`, an existing keyword-only section) are unchanged. Tests in `test_keyword_only_guard_fix.py` and docs Auto-fix section updated to match.
+
+## Findings
+
+### F1 — `fix_source` can silently corrupt a file: `str.splitlines()` ≠ `ast.lineno` on exotic whitespace — **bug** — ✅ FIXED (2026-06-17)
+
+`keyword_only_guard.py:424` — `lines = source.splitlines(keepends=True)`, indexed by `lineno - 1`.
+
+`ast`/CPython count line breaks as only `\n`, `\r`, `\r\n`. `str.splitlines()` *also* splits on form-feed `\x0c`, `
`/`
`, NEL `\x85`, VT `\x0b`, `\x1c–\x1e`. When any such character appears **before** a violation in the same file — most realistically a form-feed page-break inside a docstring — `lines[lineno-1]` points at the **wrong physical line** and the `b"*, "` insert lands there.
+
+Verified end-to-end: when the wrong line is inside a string literal the result **still re-parses**, so the re-parse guard at `keyword_only_guard.py:431-434` does NOT catch it → corrupted file is **written to disk**, and the real violation is reported as "fixed" (it isn't). When the misplaced insert instead breaks syntax, a genuinely-fixable violation is wrongly reported "unfixable" (non-destructive but wrong).
+
+Latent today: `grep -rlP '[\x0b\x0c\x85\x{2028}\x{2029}\x1c\x1d\x1e]' pipelex/ --include='*.py'` finds nothing. High impact when triggered. Landmine for any future file with such a char.
+
+### F2 — pre-existing: same divergence breaks `# kw-only: ignore` detection — **bug** — ✅ FIXED (2026-06-17)
+
+`keyword_only_guard.py` — `_def_line_has_escape_hatch` reads `source_lines[node.lineno-1]`, where `source_lines = source.splitlines()` (built in `find_violations_in_source` at `:387` and `_find_fix_records_in_source` at `:400`). Same root cause: with an exotic-whitespace char earlier in the file, the escape-hatch marker on a def line is read off the wrong line → **false-positive violation**, and the `PostToolUse` hook would wrongly block the edit. Not introduced by the `--fix` PR, but same module/mechanism, and one fix covers both (`CLAUDE.md`: "Flag and fix existing bugs").
+
+**Proposed fix for F1+F2 (single change):** stop using `str.splitlines()` for `ast`-line indexing. Add a shared helper that splits on the tokenizer's newline set only — e.g. `re.split(r'(\r\n|\r|\n)', source)` (capturing group), take the content elements (even indices) for `source_lines`, and in `fix_source` edit the content element in place and reconstruct with `"".join(...)`. `re` is already imported in the module. Add a regression test: a form-feed-in-docstring file followed by a violation, asserting the violation (not the docstring) is what gets the `*` and the docstring is byte-for-byte intact.
+
+**Resolution (2026-06-17):** Implemented as proposed. Added `_LINE_BREAK_RE = re.compile(r"(\r\n|\r|\n)")` and a shared `_split_source_lines(source)` helper (`_LINE_BREAK_RE.split(source)[::2]` — content lines are the even indices). The two detection paths (`find_violations_in_source`, `_find_fix_records_in_source`) now build `source_lines` via the helper, and `fix_source` splits with the capturing group (`parts = _LINE_BREAK_RE.split(source)`), edits the content element at `(lineno - 1) * 2` in place, and rejoins — reconstructing the file byte-for-byte. Two regression tests added (both verified red before the fix): `test_form_feed_in_string_neither_corrupts_nor_misreports` (F1 — exercises the *silent-corruption* path where the misplaced `*` lands inside a triple-quoted string and still re-parses) and `test_escape_hatch_survives_form_feed_earlier_in_file` (F2 — false-positive on a `# kw-only: ignore`d def). `make agent-check` green; full guard suite green.
+
+### F3 — standalone `make fko` / `--fix` leaves the tree NOT `ruff format`-clean — **tradeoff (lean fix)** — ✅ FIXED (2026-06-17)
+
+`Makefile:328` (`fix-keyword-only`) runs `check-keyword-only --fix --quiet` with no following `format`. The insert is correct but un-normalized: `def f(a,b)` → `def f(a,*, b)`; a multiline signature yields `*, b` on one line. Inside `agent-check` it's masked because `format` runs next — but the docs now tell a developer to run `make fko` on its own ("auto-insert the bare `*`"), and committing that output fails CI's `ruff-format --check`.
+
+**Options:** (a) chain `format` (or `ruff-format`) into the `fix-keyword-only` target so the standalone path is self-consistent; (b) leave the target raw and add a one-line note in the docs that `fko` should be followed by `make format` (or run inside `agent-check`). (a) is the more solid fix.
+
+**Resolution (2026-06-17):** Took option (a). The `fix-keyword-only` target (`Makefile`) now runs `$(VENV_RUFF) format . --config pyproject.toml` immediately after `check-keyword-only --fix --quiet`, so `make fix-keyword-only` / `make fko` leaves a `ruff format`-clean tree. `ruff format` (not `format`) is sufficient — the fixer only edits `.py` files, never the TOML/MTHDS that `plxt fmt` owns. Inside `agent-check` the later `format` step re-runs `ruff format`, but that is a near-instant no-op on the already-formatted tree. Docs Auto-fix section updated to match. Verified with a throwaway `pipelex/` violation: raw insert `def probe(a,*, b):` → after `make fko` → `def probe(a, *, b):`, `ruff format --check` exit 0.
+
+### F4 — an unfixable violation now halts `agent-check` before pyright/mypy, possibly mid-mutation — **tradeoff** — ✅ FIXED (2026-06-17, Option B)
+
+`check_keyword_only_cmd.py:127` (`_run_fix` `sys.exit(1)` on `unfixable`) + `Makefile:1168` (`agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy`, fail-fast make).
+
+Previously `check-keyword-only` ran **last** in `agent-check`, so pyright/mypy always ran. Now a single non-mechanically-fixable violation (`*args` present, an existing keyword-only section, a positional-only-only def) short-circuits the whole type-check pass. And if `fixed` was non-empty alongside `unfixable`, files were already written but `format` is skipped → partially-mutated, un-formatted tree (compounds F3).
+
+This is partly by design (the goal was to surface keyword-only issues early). The decision: accept the fail-fast tradeoff, or run the keyword-only autofix in a way that doesn't gate the type-check phase (e.g. keep the fixer early but defer the non-zero exit on *unfixable* until after the rest, or split "fix" from "gate").
+
+**Resolution (2026-06-17) — split fix from gate (Option B).** The `--fix` path is now **non-gating**: `_run_fix` reports both fixed and unfixable violations but no longer `sys.exit(1)`s on the unfixable ones (the `if not fixed:` "nothing to fix" branch was tightened to `if not fixed and not unfixable:` so an unfixable run never prints the empty-happy-path message). `agent-check` gained the read-only `check-keyword-only` as its **last** prerequisite (`... pyright mypy check-keyword-only`), which is what now gates. Net effect: the fixer runs early (fix → `ruff format`, both always run since `--fix` exits 0), so `format`/`lint`/`pyright`/`mypy` always run and the tree is never left half-mutated-and-unformatted (also fully closes the F3-compounded wart); the read-only check enforces last. `make check` / `c` / CI were already read-only-gating and are unchanged. Standalone `make fko` is now fix+report (exit 0); `make cko` / `make check-keyword-only` is the gate. Verified end-to-end with a fixable+unfixable probe: `fko` fixed + formatted + reported + exited 0 (`ruff format --check` clean), `cko` FAILED on the remaining unfixable, full `agent-check` runs pyright/mypy then gates last. F5 tests updated to the non-gating contract (unfixable → exit 0 + report). Docs Auto-fix section + gate list updated.
+
+### F5 — `_run_fix` exit-code / reporting logic is untested — **tradeoff (add tests)** — ✅ FIXED (2026-06-17)
+
+`test_keyword_only_guard_fix.py` covers `fix_source` / `fix_all_violations` well, but the command-layer control flow in `check_keyword_only_cmd.py:98-134` (`_run_fix`) has no coverage: fix-only → exit 0; unfixable → exit 1; the fixed-and-unfixable path (files written *and* exit 1); `fix` precedence over `report`; quiet vs verbose "nothing to fix" branch. `test_check_keyword_only_cmd.py` was not updated.
+
+**Resolution (2026-06-17):** Added `tests/unit/pipelex/cli/dev/test_check_keyword_only_cmd_fix.py` (`TestCheckKeywordOnlyCmdFix`), driving the public `check_keyword_only_cmd(fix=...)` so the real `_run_fix` control flow runs. `fix_all_violations` / `collect_all_violations` are mocked (pytest-mock) to drive each branch; `get_console` is routed to a `StringIO`-backed `Console` and `SOURCE_ROOT` to a real temp dir, so assertions are deterministic and touch no real files. Pins the enumerated cases: fix-only → exit 0 + "Auto-fixed"; quiet "nothing to fix" one-liner vs verbose success panel; and `fix` precedence (`collect_all_violations` / `_print_report` asserted not called). A new module (not the existing `test_check_keyword_only_cmd.py`, which holds the guard-core `TestCheckKeywordOnly` class) — one TestClass per module. `make agent-check` green; CLI unit suite green. (Note: the unfixable cases were updated by F4 below — they now assert non-gating exit 0 + a printed manual-fix report, not `SystemExit(1)`.)
+
+## Recommended order
+
+1. ~~**F1 + F2** — real silent-correctness bugs; fix together with the tokenizer-accurate line split + regression test.~~ ✅ Done 2026-06-17.
+2. ~~**F3** — small, worthwhile; chain `format` into `fko` (option a).~~ ✅ Done 2026-06-17.
+3. ~~**F4** — decide consciously; current behavior is defensible but is a regression in feedback completeness vs the old ordering.~~ ✅ Done 2026-06-17 (Option B: split fix from gate).
+4. ~~**F5** — add command-layer tests if the exit-code contract is worth pinning (it gates CI/`agent-check`, so likely yes).~~ ✅ Done 2026-06-17.
diff --git a/wip/keyword-only-arguments/downstream-consumer-breakage.md b/wip/keyword-only-arguments/downstream-consumer-breakage.md
new file mode 100644
index 000000000..3a359bf43
--- /dev/null
+++ b/wip/keyword-only-arguments/downstream-consumer-breakage.md
@@ -0,0 +1,76 @@
+# Downstream consumer breakage — keyword-only refactor follow-up
+
+> **Status (2026-06-15):** lockstep PRs opened against each consumer's `dev`, each pinning `pipelex` to the keyword-only branch git rev (`529b9082`, branch `refactor/Function-calling-4`) and carrying the call-site fixes. All four pass local `make agent-check` + `make agent-test`:
+>
+> - **pipelex-api** → [PR #19](https://github.com/Pipelex/pipelex-api/pull/19) — keyword-only delta only (it already tracked pipelex `dev`): one `parse_pipe_spec(pipe_type, spec_data=...)` fix.
+> - **pipelex-starter-python** → [PR #55](https://github.com/Pipelex/pipelex-starter-python/pull/55)
+> - **cocode** → [PR #75](https://github.com/Pipelex/cocode/pull/75)
+> - **pipelex-cookbook** → [PR #153](https://github.com/Pipelex/pipelex-cookbook/pull/153)
+>
+> **Key finding:** cookbook/cocode/starter-python were pinned to **PyPI `pipelex` 0.32.x**, so pinning them to the branch (which tracks pipelex `dev`) surfaced the **whole accumulated dev delta**, dominated by a *non*-keyword-only change — the **`PipelexRunner` → `PipelexMTHDSProtocol`** runner rename (MTHDS Protocol surface alignment: `execute_pipeline()` → `execute()`, `response.pipe_output` unchanged). Those three PRs therefore carry that runtime-runner migration **in addition to** the keyword-only fixes. Keyword-only-specific fixes were tiny: cookbook's `save_text_to_path` + its `get_stuff_as`/`get_stuff_as_list` (`content_type=`/`item_type=`) calls; nothing extra in cocode/starter. The git-rev pins are **temporary** — swap each back to a released `pipelex` version once the refactor lands on PyPI.
+>
+> **Follow-up (2026-06-15b):** `parse_pipe_spec` arg order was **reversed** in pipelex — `parse_pipe_spec(pipe_type, *, spec_data)` → `parse_pipe_spec(spec_data, *, pipe_type)` — so the subject is now the thing being parsed (the data), matching its sibling `parse_concept_spec(spec_data)`. This re-breaks the **single** call site PR #19 had already fixed: `pipelex-api/api/routes/pipelex/agent/pipe_spec.py:48` must change from `parse_pipe_spec(request_data.pipe_type, spec_data=request_data.spec)` to `parse_pipe_spec(request_data.spec, pipe_type=request_data.pipe_type)`. **Sequence (don't desync the pin):** (1) commit the pipelex reversal → new SHA; (2) bump pipelex-api's `[tool.uv.sources]` rev from `529b908255…` to the new SHA on PR #19's branch `chore/keyword-only-pipelex-rev`; (3) apply the call-site fix; (4) `make agent-check` + `make agent-test` in pipelex-api. No other consumer calls `parse_pipe_spec`, so #55 / #75 / #153 are unaffected by the reversal (only a rev bump if we want them on the newest SHA).
+>
+> **Follow-up (2026-06-15c) — DONE (push pending):** pipelex HEAD `755b82117fd4c26ba090455cfd571099cf05708b` is pushed to `refactor/Function-calling-4`. That commit turned out **broader** than just the `parse_pipe_spec` reversal — it also flips the subject/keyword order of several other signatures (`save_bytes_to_binary_file`, `hydrate_content`, `load_template`, `load_config`, `build_deck`, `write_manifest`, `text_in_renaming_keys`/`text_in_renaming_values`, `_row_to_dict`, plus the `init` CLI helpers `customize_backends_config`/`setup_telemetry`/`display_selected_backends`/`prompt_primary_backend`). Re-audited every consumer for those names: **none** call them positionally (each site already passes by keyword), so `parse_pipe_spec` in pipelex-api stayed the *only* real call-site break. All four consumer PR branches (`chore/keyword-only-pipelex-rev`) had their pin bumped `529b9082…` → `755b8211…` in **both** `pyproject.toml` and `uv.lock`, re-synced, and verified green on `make agent-check` + `make agent-test`; pipelex-api additionally carries the `pipe_spec.py` call-site fix + CHANGELOG entry. Each branch has a fresh commit on top — **not yet pushed** (push was left to the user / blocked by auto-mode). When pushing, the open PRs #19 / #55 / #75 / #153 update in place.
+>
+> **Follow-up (2026-06-15d) — recheck after the positional-subject consolidation:** pipelex HEAD moved again to `0e32c8c02` ("Consolidate keyword-only refactor for positional-subject abuse suspects", pushed to `refactor/Function-calling-4`). That commit turned all 59 positional-subject suspects **fully** keyword-only by relocating the bare `*` to immediately after `self`/`cls` — **no reordering, no renames** (see [`positional-subject-suspects.md`](positional-subject-suspects.md)). So the only way it can break a consumer is a now-keyword-only *subject* still passed **positionally**. Re-audited every consumer (`pipelex-api`, `cocode`, `pipelex-cookbook`, `pipelex-starter-python`, `pipelex-mistralai-workflows`, `pipelex-worker`) for call sites of all 59 changed functions. **Exactly one new break:** `pipelex-api/tests/unit/conftest.py:12` calls `Pipelex.make(IntegrationMode.PYTEST, needs_inference=..., temporal_enabled=False)` — `integration_mode` positional. This was *compliant* under `755b82117` (Wave 5 left the subject positional-allowed) but `0e32c8c02` made `Pipelex.make` fully keyword-only (`make(cls, *, integration_mode=..., ...)`), so it now raises `TypeError`. Fix: `Pipelex.make(integration_mode=IntegrationMode.PYTEST, needs_inference=..., temporal_enabled=False)`. Every other consumer is clean: `cocode` passes `integration_mode=IntegrationMode.CI` by keyword and `make_pipelex_for_cli(context=...)` by keyword; cookbook/starter-python omit `integration_mode`; the `pipe_job.pipe.run_pipe(job_metadata=..., ...)` site in `pipelex-mistralai-workflows` is all-keyword; `make_temporal_pipe_run()`/`make_temporal_pipe_router()`/`check_is_initialized()` are no-arg. `mistralai-workflows` is on `feature/Mistral-native` (mistralai-2x HOLD pin, not the keyword-only branch) and `pipelex-worker` is on `dev` (PyPI version pin) — both out of scope. **Pin staleness:** the four `chore/keyword-only-pipelex-rev` branches (pipelex-api / cocode / cookbook / starter-python) are still pinned to `755b82117`, now one commit behind HEAD `0e32c8c02`. To restore true lockstep, bump `755b82117…` → `0e32c8c02…` in `pyproject.toml` **and** `uv.lock` on each; only **pipelex-api** additionally needs the conftest call-site fix above. **DONE (push pending):** all four `chore/keyword-only-pipelex-rev` branches re-pinned `755b82117…` → `0e32c8c02600e17bbe146331f9b701ccc03a1ca1` (pyproject + uv.lock), reinstalled via `uv sync --all-extras`, and verified green on `make agent-check` + `make agent-test` — pipelex-api (commit `24c91c4`, also carries the `tests/unit/conftest.py` `integration_mode=` fix + CHANGELOG line), cocode (`b82d26c`), pipelex-starter-python (`fbf69be`), pipelex-cookbook (`7d48804`). **Pushed** to the existing PR branches (#19 / #75 / #55 / #153), which update in place. The only remaining open item is the at-release pin swap (see checklist).
+>
+> **Follow-up (2026-06-15e) — pipelex-worker brought into scope:** previously marked out of scope only because it pinned `pipelex` via a PyPI version (`pipelex[dynamodb,s3,temporal]==0.33.0`), not a git rev. Now aligned with the others on a new `chore/keyword-only-pipelex-rev` branch off `dev`: the PyPI pin is overridden with the `0e32c8c0` git rev via `[tool.uv.sources]` and relocked (`uv lock`: registry → git source). The worker has **no `pipelex` imports in its own source** (it just runs the installed `pipelex worker` process), so there is **no keyword-only call-site break**. Its `pipelex doctor` config-health smoke tests then failed on a *pre-existing* brittleness, not a config regression: `pipelex doctor` renders through rich and emits ANSI style/reset codes even when piped (`NO_COLOR` only drops colors, not the bold/reset), and a `\x1b[0m` between `Configuration Files` and the `✓` defeated the section regex — fixed by stripping ANSI before matching. The merged config is valid against 0.33.0 (no `ConfigValidationError`); the only residual is the expected soft `Model Deck installed for 0.32.1, current 0.33.0` warning, which the test ignores by design and does not break the worker. All three env smoke tests green. Commit `af8572a`, pushed, **[PR #23](https://github.com/Pipelex/pipelex-worker/pull/23)** opened against `dev`. `pipelex-mistralai-workflows` remains genuinely out of scope — its own mistralai-2x hold track, editable-pinned to the `../_workflows` pipelex worktree, gated until instructor #2298.
+
+> Original release-time checklist below (the pipelex-internal keyword-only refactor is **complete** — all waves landed, guard hard-blocks; see [`../../TODOS.md`](../../TODOS.md)). Companion to the convention itself at [`../../docs/contribute/keyword-only-arguments.md`](../../docs/contribute/keyword-only-arguments.md).
+
+The keyword-only refactor intentionally turns multi-arg public helpers keyword-only (e.g. `save_text_to_path(text, *, path, create_directory=False)`, and on the public surface `Pipelex.make()` / `Pipelex.setup()` / `PipelexHub.setup_config()` — every argument after the first is now keyword-only). This is a deliberate breaking change, documented in the runtime `CHANGELOG.md`. Breaking changes are allowed in this workspace, but consumers must be updated in lockstep — otherwise the official examples ship broken.
+
+## Confirmed breakage (Wave 1 — `tools/`)
+
+- **`pipelex-cookbook/utils/results_utils.py:42`** — `save_text_to_path(content, result_file_path)` passes `path` positionally, but `path` is now keyword-only. Fix: `save_text_to_path(text=content, path=result_file_path)`. (The third param `create_directory` defaults to `False` and is unchanged.)
+
+That is the only positional break found across the consumer repos for the Wave 1 public surface. The later waves (`core/` … the public `pipelex.py` / `hub.py` surface) have **not** yet been re-audited across the consumer repos — do that at release (recipe below).
+
+## Repos audited and clean (Wave 1)
+
+- **`cocode`** — already calls `save_text_to_path` in keyword form (`text=…, path=…`) at every site (`repox/repox_cmd.py`, `swe/swe_utils.py`, `swe/swe_cmd.py`). Its other pipelex-tools imports (`load_text_from_path`, `failable_load_text_from_path`, `ensure_path`, `path_exists`, `load_json_list_from_path`, `pascal_case_to_kebab`, `pascal_case_to_sentence`, `empty_list_factory_of`) are all single-arg or already keyword — no break.
+- **`pipelex-starter-python`** — only uses `pretty_print` (single positional `content`), no break.
+- **`pipelex-api`, `pipelex-worker`, `pipelex-mistralai-workflows`** — no positional calls to keyword-only Wave 1 helpers. (Re-check `Pipelex.make` / `setup` call sites — the public-surface change landed in Wave 5.)
+- **`pretty_print` / `pretty_print_md` / `pretty_print_url`** (the only `pipelex/__init__.py` `__all__` exports) — now keyword-only on everything after `content`; no consumer passes `title` (or any later arg) positionally, so nothing breaks today. Worth keeping an eye on since these are the headline public API.
+
+## Public surface converted in Wave 5 (re-audit before release)
+
+The final wave made the top-level entry points keyword-only after their first parameter. A consumer passing a second-or-later argument positionally breaks:
+
+- `Pipelex.make(integration_mode, *, ...)` — e.g. `Pipelex.make(IntegrationMode.PYTHON, False)` → `Pipelex.make(IntegrationMode.PYTHON, needs_inference=False)`.
+- `Pipelex.setup(...)` and `PipelexHub.setup_config(config_cls, *, ...)` — same shape.
+
+The common no-arg / all-keyword calls (`Pipelex.make()`, `Pipelex.make(needs_inference=False)`) are unaffected. Consumers to check: `pipelex-api`, `pipelex-worker`, `n8n-nodes-pipelex`, `pipelex-cookbook`, `pipelex-starter-python`, `pipelex-mistralai-workflows`.
+
+## How to re-run the audit
+
+From the workspace root (`/Users/lchoquel/repos/Pipelex`):
+
+```bash
+# 1. positional second-arg calls to the file/bytes writers
+rg -n -g '*.py' -e 'save_text_to_path\(' -e 'save_bytes_to_path\(' \
+ cocode pipelex-cookbook pipelex-starter-python pipelex-mistralai-workflows pipelex-api pipelex-worker \
+ | grep -vE 'text=|path=|content='
+
+# 2. pretty_print* called with a positional non-content arg
+rg -n -g '*.py' 'pretty_print(_md|_url)?\([^)]*,[^=)]' \
+ cocode pipelex-cookbook pipelex-starter-python | grep -vE 'title=|subtitle='
+
+# 3. public bootstrap entry points with a positional second arg
+rg -n -g '*.py' -e 'Pipelex\.make\(' -e 'Pipelex\.setup\(' -e 'setup_config\(' \
+ cocode pipelex-cookbook pipelex-starter-python pipelex-mistralai-workflows pipelex-api pipelex-worker n8n-nodes-pipelex \
+ | grep -E '\([^)]+,[^=)]'
+```
+
+Generalise the helper list per wave: take the functions a wave converted (the `### Changed` keyword-only entries in `CHANGELOG.md` name the packages and the headline signatures), keep only those imported by a consumer repo and exposing a second positional arg, then grep for positional call sites.
+
+## Checklist
+
+- [x] `pipelex-cookbook/utils/results_utils.py:42` → keyword form (PR #153, with its unit-test assertion updated to keyword form).
+- [x] Re-run the audit greps for the full converted surface (Waves 1–5). Only positional keyword-only break found across consumers: cookbook's `save_text_to_path` + `get_stuff_as*`, and pipelex-api's `parse_pipe_spec`. All `Pipelex.make` call sites already pass the subject positionally + the rest by keyword (compliant).
+- [x] Open lockstep PRs pinning each consumer to the branch git rev, all green on local `make agent-check` + `make agent-test` (PRs #19 / #55 / #75 / #153).
+- [x] **`parse_pipe_spec` reversal (2026-06-15b) — pipelex-api lockstep:** done. pipelex reversal pushed (SHA `755b82117`); PR #19's pin bumped (pyproject + uv.lock), `pipe_spec.py:48` changed to `parse_pipe_spec(request_data.spec, pipe_type=request_data.pipe_type)`, CHANGELOG updated. `make agent-check` + `make agent-test` green. Committed on `chore/keyword-only-pipelex-rev`; push pending. The 2026-06-15c note widens this to all four consumers (the same SHA also reordered other signatures, none of which any consumer calls positionally).
+- [x] **Positional-subject consolidation (2026-06-15d) — re-audit + fix DONE (push pending):** pipelex HEAD `0e32c8c02` made all 59 suspects fully keyword-only (no reorder). Re-audited all consumers → only new break was `pipelex-api/tests/unit/conftest.py:12` (`Pipelex.make(IntegrationMode.PYTEST, …)` positional → now `integration_mode=...`). Bumped the four `chore/keyword-only-pipelex-rev` pins `755b82117…` → `0e32c8c02…` (pyproject + uv.lock), applied the conftest fix to pipelex-api, reinstalled, and verified `make agent-check` + `make agent-test` green on all four. Commits: pipelex-api `24c91c4`, cocode `b82d26c`, starter-python `fbf69be`, cookbook `7d48804` — **pushed** to the PR branches (#19 / #75 / #55 / #153), which update in place.
+- [x] **pipelex-worker (2026-06-15e) — brought into scope:** PyPI `==0.33.0` pin → `0e32c8c0` git rev (`[tool.uv.sources]` + `uv lock` relock, registry→git). No call-site break (no `pipelex` imports). Fixed a brittle ANSI assertion in the `pipelex doctor` smoke test (strip ANSI before matching); 3/3 env tests green. Commit `af8572a`, [PR #23](https://github.com/Pipelex/pipelex-worker/pull/23) vs `dev`. (`pipelex-mistralai-workflows` stays out of scope — own mistralai-2x hold track.)
+- [ ] **At pipelex release:** swap each consumer's temporary `[tool.uv.sources]` git pin back to the released `pipelex` version (`==`/`>=`), and confirm CI stays green. Remember the release also ships the `PipelexRunner → PipelexMTHDSProtocol` rename — already handled in these PRs.
diff --git a/wip/keyword-only-arguments/keyword-only-arguments.html b/wip/keyword-only-arguments/keyword-only-arguments.html
new file mode 100644
index 000000000..62be01a66
--- /dev/null
+++ b/wip/keyword-only-arguments/keyword-only-arguments.html
@@ -0,0 +1,392 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Keyword-only arguments — what we built</title>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+<style>
+ :root {
+ --bg: #0f1117; --panel: #171a23; --panel2: #1d212c; --ink: #e6e9ef; --muted: #9aa3b2;
+ --line: #2a2f3a; --accent: #6ea8fe; --good: #4ec98a; --bad: #f0768b; --warn: #e7b964;
+ --add-bg: #11271b; --add-ink: #7fe0a8; --del-bg: #2a1620; --del-ink: #f3899d; --code: #cdd6e6;
+ --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+ }
+ * { box-sizing: border-box; }
+ body {
+ margin: 0; background: var(--bg); color: var(--ink);
+ font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+ }
+ .wrap { max-width: 980px; margin: 0 auto; padding: 40px 24px 96px; }
+ header.hero { border-bottom: 1px solid var(--line); padding-bottom: 22px; margin-bottom: 28px; }
+ .eyebrow { color: var(--accent); font-weight: 700; letter-spacing: .14em; text-transform: uppercase; font-size: 12px; }
+ h1 { font-size: 33px; line-height: 1.15; margin: 8px 0 6px; }
+ h2 { font-size: 23px; margin: 44px 0 12px; padding-top: 10px; border-top: 1px solid var(--line); }
+ h3 { font-size: 17px; margin: 26px 0 8px; color: #cfd6e4; }
+ p, li { color: #d3d8e2; }
+ a { color: var(--accent); }
+ code { font-family: var(--mono); background: #11141c; border: 1px solid var(--line); border-radius: 5px; padding: .08em .36em; font-size: .9em; color: var(--code); }
+ .sub { color: var(--muted); font-size: 15px; }
+ .tldr {
+ background: linear-gradient(180deg, #1a2030, #161b28);
+ border: 1px solid #2c3650; border-left: 4px solid var(--accent);
+ border-radius: 12px; padding: 18px 22px; margin: 4px 0 8px;
+ }
+ .tldr h2 { border: 0; margin: 0 0 8px; padding: 0; font-size: 18px; color: var(--accent); }
+ .tldr ul { margin: 8px 0 0; padding-left: 20px; }
+ .tldr li { margin: 5px 0; }
+ .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; margin: 16px 0; }
+ @media (max-width: 720px){ .grid { grid-template-columns: 1fr; } }
+ .card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; }
+ .card h3 { margin-top: 0; }
+ .pill { display: inline-block; font-size: 12px; font-weight: 600; padding: 2px 9px; border-radius: 999px; border: 1px solid var(--line); color: var(--muted); }
+ .pill.good { color: var(--good); border-color: #275; } .pill.warn { color: var(--warn); border-color: #654; }
+ figure { margin: 18px 0; background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 14px; }
+ figure figcaption { color: var(--muted); font-size: 13px; margin-top: 8px; text-align: center; }
+ .mermaid { background: transparent; text-align: center; }
+ details { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 8px 16px; margin: 12px 0; }
+ details[open] { padding-bottom: 14px; }
+ summary { cursor: pointer; font-weight: 650; color: #d8def0; padding: 6px 0; }
+ summary::marker { color: var(--accent); }
+ table { width: 100%; border-collapse: collapse; margin: 14px 0; font-size: 14.5px; }
+ th, td { border: 1px solid var(--line); padding: 8px 11px; text-align: left; vertical-align: top; }
+ th { background: var(--panel2); color: #cfd6e4; }
+ td code { font-size: .86em; }
+ /* tabs */
+ .tabs { margin: 16px 0; border: 1px solid var(--line); border-radius: 12px; overflow: hidden; background: var(--panel); }
+ .tabbar { display: flex; flex-wrap: wrap; gap: 0; background: var(--panel2); border-bottom: 1px solid var(--line); }
+ .tabbar button {
+ appearance: none; background: transparent; border: 0; border-right: 1px solid var(--line);
+ color: var(--muted); padding: 10px 15px; cursor: pointer; font: 600 13.5px var(--mono); letter-spacing: .02em;
+ }
+ .tabbar button:hover { color: var(--ink); }
+ .tabbar button.active { color: var(--ink); background: var(--panel); box-shadow: inset 0 -2px 0 var(--accent); }
+ .tabpanel { display: none; padding: 0; }
+ .tabpanel.active { display: block; }
+ pre { margin: 0; padding: 16px 18px; overflow-x: auto; font-family: var(--mono); font-size: 13px; line-height: 1.55; color: var(--code); background: #0c0e14; }
+ pre.plain { border: 1px solid var(--line); border-radius: 10px; }
+ .diff .ln { display: block; white-space: pre; }
+ .diff .add { background: var(--add-bg); color: var(--add-ink); }
+ .diff .del { background: var(--del-bg); color: var(--del-ink); }
+ .diff .ctx { color: #8b93a4; }
+ .diff .hdr { color: #6f7891; }
+ .filechip { font: 600 12px var(--mono); color: var(--muted); padding: 8px 18px; background: var(--panel2); border-bottom: 1px solid var(--line); }
+ .note { font-size: 14px; color: var(--muted); }
+ .kbd { font-family: var(--mono); background:#11141c; border:1px solid var(--line); border-bottom-width:2px; border-radius:5px; padding:.03em .4em; }
+ .legend { display:flex; gap:16px; flex-wrap:wrap; font-size:12.5px; color:var(--muted); margin: 6px 2px 0;}
+ .legend span { display:inline-flex; align-items:center; gap:6px;}
+ .sw { width:14px; height:14px; border-radius:3px; display:inline-block; border:1px solid var(--line);}
+ footer { margin-top: 50px; border-top: 1px solid var(--line); padding-top: 18px; color: var(--muted); font-size: 13.5px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<header class="hero">
+ <div class="eyebrow">Pipelex runtime · refactor/Function-calling-4</div>
+ <h1>Keyword-only arguments, everywhere — and a guard that keeps it that way</h1>
+ <p class="sub">A codebase-wide refactor + a mechanical enforcement guard, plus the lockstep update of every downstream consumer. Written for the people who'll write the next function.</p>
+</header>
+
+<div class="tldr">
+ <h2>TL;DR</h2>
+ <ul>
+ <li><b>What changed:</b> across all of <code>pipelex/</code>, every <i>non-subject</i> function parameter is now <b>keyword-only</b>. A function may keep its first real argument (the "subject") positional; everything after it must be passed by name. So <code>do_thing(retries=3, timeout=30)</code> — never the opaque <code>do_thing(3, 30)</code>.</li>
+ <li><b>Why:</b> call sites become self-documenting, and you can reorder / insert parameters without silently rebinding a caller's positional args.</li>
+ <li><b>How it stays true:</b> a stdlib-only AST guard (<code>check-keyword-only</code>) runs in <code>make agent-check</code>, in the <code>make check</code> aggregate, and in CI — it <b>hard-blocks on any violation</b>. A <code>PostToolUse</code> hook runs the same guard on each edited file in ~40&nbsp;ms, so agents get blocked in-loop, not at CI.</li>
+ <li><b>The sweep:</b> ~1,800 functions audited (one Sonnet sub-agent per package); <b>59</b> "kept-positional-out-of-habit" suspects were found and all made <i>fully</i> keyword-only — by relocating the bare <code>*</code> only, <b>no reordering, no renames</b>.</li>
+ <li><b>Breaking &amp; downstream:</b> the public surface (<code>Pipelex.make()</code> / <code>setup()</code> / <code>PipelexHub.setup_config()</code>) is now keyword-only after the subject. All four consumer repos (pipelex-api, cocode, cookbook, starter-python) were re-pinned to the branch and fixed in lockstep — exactly <b>one</b> real call-site break across all of them. Green on <code>agent-check</code> + <code>agent-test</code>; PRs pushed.</li>
+ <li><b>One open item:</b> at pipelex release, swap each consumer's temporary git pin back to a released version.</li>
+ </ul>
+</div>
+
+<h2>The rule, in one picture</h2>
+<p>The compliant shape places a bare <code>*</code> right after the subject. The subject — the first non-<code>self</code>/<code>cls</code> parameter — <i>may</i> stay positional; making it keyword-only too is always allowed and often nicer.</p>
+
+<figure>
+<svg viewBox="0 0 900 220" width="100%" role="img" aria-label="Anatomy of a compliant signature">
+ <style>
+ .mono{font-family:var(--mono);font-size:18px;fill:#e6e9ef}
+ .lbl{font-family:var(--mono);font-size:12.5px}
+ .box{fill:none;stroke-width:2;rx:8}
+ </style>
+ <rect x="0" y="0" width="900" height="220" fill="#12151d" rx="14"/>
+ <text x="40" y="74" class="mono">def <tspan fill="#6ea8fe">handle</tspan>(<tspan fill="#9aa3b2">self</tspan>, <tspan fill="#4ec98a">request</tspan>, <tspan fill="#e7b964">*</tspan>, <tspan fill="#cdd6e6">retries</tspan>=3, <tspan fill="#cdd6e6">timeout</tspan>=30):</text>
+
+ <!-- subject brace -->
+ <rect x="148" y="48" width="86" height="34" class="box" stroke="#4ec98a"/>
+ <text x="191" y="120" text-anchor="middle" class="lbl" fill="#4ec98a">subject</text>
+ <text x="191" y="138" text-anchor="middle" class="lbl" fill="#7f9">may stay positional</text>
+
+ <!-- star -->
+ <rect x="245" y="48" width="22" height="34" class="box" stroke="#e7b964"/>
+ <text x="256" y="120" text-anchor="middle" class="lbl" fill="#e7b964">bare *</text>
+ <text x="256" y="138" text-anchor="middle" class="lbl" fill="#caa">the boundary</text>
+
+ <!-- keywords -->
+ <rect x="278" y="48" width="300" height="34" class="box" stroke="#6ea8fe"/>
+ <text x="428" y="120" text-anchor="middle" class="lbl" fill="#6ea8fe">keyword-only</text>
+ <text x="428" y="138" text-anchor="middle" class="lbl" fill="#9bf">must be passed by name</text>
+
+ <text x="40" y="190" class="lbl" fill="#9aa3b2">Call site &#8594; <tspan fill="#4ec98a">handle(request)</tspan> or <tspan fill="#4ec98a">handle(request=req, retries=5, timeout=10)</tspan> — never <tspan fill="#f0768b">handle(req, 5, 10)</tspan></text>
+</svg>
+<figcaption>A lone subject (<code>def render(node)</code>) is compliant. A second bare positional (<code>def f(a, b)</code>, <code>def truncate(text, max_length=80)</code>) is a violation.</figcaption>
+</figure>
+
+<div class="tabs" id="rule-tabs">
+ <div class="tabbar">
+ <button class="active" data-tab="ok">✓ compliant</button>
+ <button data-tab="bad">✗ violations</button>
+ <button data-tab="hatch"># kw-only: ignore</button>
+ </div>
+ <div class="tabpanel active" data-panel="ok">
+<pre class="plain">def render(node): ... # lone subject — fine
+def f(subject, *, opt1, opt2): ... # subject positional, rest keyword
+def f(*, a, b): ... # fully keyword-only — always allowed
+def make(cls, *, integration_mode=...): ... # classmethod, fully keyword-only</pre>
+ </div>
+ <div class="tabpanel" data-panel="bad">
+<pre class="plain">def f(a, b): ... # second bare positional
+def truncate(text, max_length=80): ... # max_length must be keyword-only
+def make(cls, integration_mode, *, ...): .. # subject kept positional "by habit"
+ # when every call site already
+ # passes integration_mode=...</pre>
+ </div>
+ <div class="tabpanel" data-panel="hatch">
+<pre class="plain"># A genuinely justified one-off — placed right after the open paren so
+# `ruff format` keeps it on the def header line:
+def legacy_cb(a, b): # kw-only: ignore
+ ...
+
+# Carve-outs are automatic (no marker needed): dunders, pydantic
+# validators/serializers, Typer/Temporal/pytest/Jinja2 entrypoints,
+# @override impls, and a curated symmetric-tuple allowlist.</pre>
+ </div>
+</div>
+
+<h2>How it stays true: three layers of enforcement</h2>
+<p>One rule, one AST core, three places it fires. The guard is <b>stdlib-only</b> (<code>ast</code>/<code>re</code>/<code>pathlib</code>) so the single-file path can run without importing the <code>pipelex</code> package chain — that's what keeps the editor hook at a few tens of milliseconds.</p>
+
+<figure>
+<div class="mermaid">
+flowchart LR
+ subgraph DEV["In-loop (per edit)"]
+ E["Edit/Write a *.py file"] --> H{{"PostToolUse hook<br/>check-keyword-only.sh"}}
+ H -->|"by file path,<br/>no -m import"| G1["guard.main()<br/>single file, ~40ms"]
+ G1 -->|violation| B1["exit 2 → blocks the agent<br/>prints offending signatures"]
+ G1 -->|clean| P1["exit 0"]
+ end
+ subgraph CI["Gate (pre-merge)"]
+ C["make agent-check / make check / CI"] --> G2["pipelex-dev check-keyword-only<br/>full pipelex/ tree"]
+ G2 -->|any violation| B2["non-zero → hard-block"]
+ G2 -->|clean| P2["pass"]
+ end
+ G1 -. "same AST core<br/>(find_violations_in_source)" .- G2
+</div>
+<figcaption>The single-file hook result is an exact subset of the full-tree scan — <code>relative_path</code>/<code>module_qname</code> are computed identically, so the carve-out allowlist matches either way.</figcaption>
+</figure>
+
+<details>
+ <summary>The carve-outs (skipped automatically) and the escape hatch</summary>
+ <ul>
+ <li><b>Dunders</b> — <code>__init__</code>, <code>__call__</code>, … (interpreter calls them positionally).</li>
+ <li><b>pydantic</b> — <code>@field_validator</code>, <code>@model_validator</code>, <code>@field_serializer</code>, <code>@model_serializer</code>, <code>@validator</code>, <code>@root_validator</code>.</li>
+ <li><b>Framework entrypoints invoked positionally</b> — Typer <code>@app.command</code>/<code>@app.callback</code> (and the decorator-less <code>Argument(...)</code>/<code>Option(...)</code> annotation form), Temporal <code>@activity.defn</code> / <code>@workflow.run|signal|query|update</code>, <code>@pytest.fixture</code>, and Jinja2 <code>@pass_context</code>/<code>@pass_environment</code>/<code>@pass_eval_context</code>.</li>
+ <li><b><code>@override</code> impls</b> — they track the base signature.</li>
+ <li><b>Curated symmetric-tuple allowlist</b> — a handful of <code>(qualified_name, path)</code> pairs where both operands are genuinely peers (e.g. <code>diff_files(a, b)</code>). No pattern guessing; both name and path must match exactly.</li>
+ <li><b>Escape hatch</b> — an inline <code># kw-only: ignore</code> on the <code>def</code> line, for a justified one-off.</li>
+ </ul>
+ <p class="note">The type checker can't see framework-positional callbacks (route handlers, <code>__import__</code> hooks), so <code>make agent-test</code> is the safety net — and it caught real cases during the rollout.</p>
+</details>
+
+<h2>Rolling it out: audit → consolidation → enforce</h2>
+<p>The tree was made compliant wave by wave (execution path, then the framework-sensitive &amp; public API last). Then a dedicated pass hunted the subtler problem: signatures that satisfied the rule on a technicality — they kept <i>a</i> subject positional — but where that "subject" was really a lookup table, a mode flag, or a trace-context carrier, while the actual operand sat in the keyword args.</p>
+
+<figure>
+<div class="mermaid">
+flowchart TD
+ A["Waves 1–5: make pipelex/ compliant<br/>(bare * after the subject)"] --> B["Guard built + CI-gated<br/>(hard-block, baseline scaffolding removed)"]
+ B --> C["Positional-subject audit<br/>~1,800 functions · 1 Sonnet sub-agent per package"]
+ C --> D{"Is the positional<br/>arg really the subject?"}
+ D -->|"yes — fine"| E["leave it"]
+ D -->|"no — abuse"| F["59 suspects<br/>(lookup tables, mode flags,<br/>trace carriers, symmetric pairs)"]
+ F --> G["Consolidate: all 59 made FULLY keyword-only<br/>move * before the subject · no reorder · no rename"]
+ G --> H["agent-check + agent-test green"]
+ H --> I["Downstream consumers re-pinned + fixed in lockstep"]
+</div>
+<figcaption>"No reordering, no renames" is the load-bearing property: it means the only way the consolidation can break a caller is if that caller passed a now-keyword-only subject <i>positionally</i>.</figcaption>
+</figure>
+
+<details>
+ <summary>The recurring shapes the 59 suspects collapsed into</summary>
+ <ul>
+ <li><b>Lookup-table / registry carried positional</b> while the real query is keyworded — e.g. <code>model_cost_per_token(costs, *, cost_category)</code>, <code>get_reasoning_level_str(effort_to_level_map, *, effort)</code>.</li>
+ <li><b><code>*_for_pipe</code> / <code>*_from_response</code> / <code>*_from_uri</code></b> — the name advertises the operand, but a <i>different</i> arg was positional.</li>
+ <li><b>Mode flag / bare bool positional</b> — <code>f(True)</code> reveals nothing, and every call site already keyworded it.</li>
+ <li><b>Trace/provenance carrier positional</b> (<code>job_metadata</code>, <code>lookup_key</code>, <code>calling_pipe_code</code>) while the function acts on the keyword args.</li>
+ <li><b>Accumulator/sink dict positional</b> while the content being added is keyworded.</li>
+ <li><b>Symmetric pair split across the <code>*</code></b> — neither operand is "the subject", so the split was just noise.</li>
+ <li><b>Public-API surface</b> — <code>Pipelex.make</code>/<code>setup</code>, a deliberate keyword-only break.</li>
+ </ul>
+ <p class="note">A near-universal tell: the existing call sites already passed the "positional" arg by keyword — the positional permission was buying nothing.</p>
+</details>
+
+<h2>Downstream: one branch SHA, five consumers, exactly one real break</h2>
+<p>The consumers were pinned to the pipelex branch git rev and walked forward as the branch moved. The headache wasn't the keyword-only changes — it was that bumping off PyPI&nbsp;0.32.x surfaced the whole accumulated <code>dev</code> delta (notably the unrelated <code>PipelexRunner → PipelexMTHDSProtocol</code> runner rename). The keyword-only-specific call-site fixes were tiny.</p>
+
+<table>
+ <thead><tr><th>Consumer</th><th>Branch</th><th>Keyword-only break?</th><th>Result</th></tr></thead>
+ <tbody>
+ <tr><td>pipelex-api</td><td><code>chore/keyword-only-pipelex-rev</code> · <a href="https://github.com/Pipelex/pipelex-api/pull/19">PR&nbsp;#19</a></td><td><b>Yes (1)</b> — <code>tests/unit/conftest.py</code></td><td class="pill good">green · pushed</td></tr>
+ <tr><td>cocode</td><td><code>chore/keyword-only-pipelex-rev</code> · <a href="https://github.com/Pipelex/cocode/pull/75">PR&nbsp;#75</a></td><td>No (all keyword already)</td><td class="pill good">green · pushed</td></tr>
+ <tr><td>pipelex-cookbook</td><td><code>chore/keyword-only-pipelex-rev</code> · <a href="https://github.com/Pipelex/pipelex-cookbook/pull/153">PR&nbsp;#153</a></td><td>No (earlier waves only)</td><td class="pill good">green · pushed</td></tr>
+ <tr><td>pipelex-starter-python</td><td><code>chore/keyword-only-pipelex-rev</code> · <a href="https://github.com/Pipelex/pipelex-starter-python/pull/55">PR&nbsp;#55</a></td><td>No</td><td class="pill good">green · pushed</td></tr>
+ <tr><td>pipelex-worker</td><td><code>chore/keyword-only-pipelex-rev</code> · <a href="https://github.com/Pipelex/pipelex-worker/pull/23">PR&nbsp;#23</a></td><td>No — no <code>pipelex</code> imports (thin worker); fixed a brittle ANSI assertion in the doctor smoke test</td><td class="pill good">green · pushed</td></tr>
+ <tr><td>pipelex-mistralai-workflows</td><td><code>feature/Mistral-native</code> (mistralai-2x hold pin)</td><td>Out of scope (own hold track)</td><td class="pill">n/a</td></tr>
+ </tbody>
+</table>
+
+<figure>
+<div class="mermaid">
+sequenceDiagram
+ participant PX as pipelex branch
+ participant API as pipelex-api
+ participant REST as cocode, cookbook, starter
+ Note over PX: 529b9082 -- initial keyword-only waves
+ PX->>API: pin to 529b9082, one parse_pipe_spec fix
+ PX->>REST: pin to 529b9082
+ Note over PX: 755b8211 -- parse_pipe_spec arg order reversed
+ PX->>API: re-pin to 755b8211, pipe_spec.py call-site fix
+ PX->>REST: re-pin to 755b8211, no positional call sites
+ Note over PX: 0e32c8c0 -- positional-subject consolidation
+ PX->>API: re-pin to 0e32c8c0, conftest integration_mode fix
+ PX->>REST: re-pin to 0e32c8c0, no-op bump, call sites already keyword
+</div>
+<figcaption>Each re-pin touched <code>pyproject.toml</code> <b>and</b> <code>uv.lock</code>, then <code>uv sync --all-extras</code> + <code>make agent-check</code> + <code>make agent-test</code> before committing.</figcaption>
+</figure>
+
+<h2>Minimal diffs for the critical changes</h2>
+<div class="legend">
+ <span><i class="sw" style="background:var(--add-bg)"></i> added</span>
+ <span><i class="sw" style="background:var(--del-bg)"></i> removed</span>
+ <span><i class="sw" style="background:#0c0e14"></i> context / new file</span>
+</div>
+
+<div class="tabs" id="diff-tabs">
+ <div class="tabbar">
+ <button class="active" data-tab="d-make">Pipelex.make</button>
+ <button data-tab="d-flips">representative flips</button>
+ <button data-tab="d-guard">the guard (core)</button>
+ <button data-tab="d-hook">PostToolUse hook</button>
+ <button data-tab="d-down">downstream fix</button>
+ </div>
+
+ <div class="tabpanel active" data-panel="d-make">
+ <div class="filechip">pipelex/pipelex.py — the public-API change that drove the one consumer break</div>
+ <pre class="diff"><span class="ln ctx"> def make(</span><span class="ln ctx"> cls,</span><span class="ln del">- integration_mode: IntegrationMode = IntegrationMode.PYTHON,</span><span class="ln ctx"> *,</span><span class="ln add">+ integration_mode: IntegrationMode = IntegrationMode.PYTHON,</span><span class="ln ctx"> needs_inference: bool = True,</span><span class="ln ctx"> temporal_enabled: bool | None = None,</span><span class="ln ctx"> ...</span></pre>
+ <p class="note">The <code>*</code> moved up one line — that's the whole change. <code>Pipelex.make(IntegrationMode.PYTHON)</code> no longer type-checks; <code>Pipelex.make(integration_mode=...)</code> does. Same shape applied to <code>Pipelex.setup()</code> and <code>PipelexHub.setup_config()</code>.</p>
+ </div>
+
+ <div class="tabpanel" data-panel="d-flips">
+ <div class="filechip">representative one-line flips — move <code>*</code> before the subject, nothing else</div>
+ <pre class="diff"><span class="ln hdr"># pipelex/cogt/usage/costs_per_token.py — lookup table was positional</span><span class="ln del">-def model_cost_per_token(costs: CostsByCategoryDict, *, cost_category: CostCategory) -> float:</span><span class="ln add">+def model_cost_per_token(*, costs: CostsByCategoryDict, cost_category: CostCategory) -> float:</span><span class="ln ctx"> </span><span class="ln hdr"># pipelex/core/stuffs/stuff_content.py — both args are render options, self is the subject</span><span class="ln del">- def rendered_markdown(self, level: int = 1, *, is_pretty: bool = False) -> str:</span><span class="ln add">+ def rendered_markdown(self, *, level: int = 1, is_pretty: bool = False) -> str:</span><span class="ln ctx"> </span><span class="ln hdr"># pipelex/libraries/concept/concept_library.py — alias is a namespacing key, concept is what's added</span><span class="ln del">- def add_dependency_concept(self, alias: str, *, concept: Concept) -> None:</span><span class="ln add">+ def add_dependency_concept(self, *, alias: str, concept: Concept) -> None:</span></pre>
+ <p class="note">All 59 suspects were resolved exactly like this — relocate the bare <code>*</code>, no reorder, no rename. Internal call sites that passed the subject positionally were converted to keyword in the same commit.</p>
+ </div>
+
+ <div class="tabpanel" data-panel="d-guard">
+ <div class="filechip">pipelex/cli/dev_cli/commands/keyword_only_guard.py (new · stdlib-only) — the rule</div>
+ <pre class="plain">def _positional_or_keyword_count(node, *, is_method: bool) -> int:
+ """Count positional-or-keyword params after dropping self/cls and the allowed subject."""
+ params = [*node.args.posonlyargs, *node.args.args]
+ if is_method and params and params[0].arg in {"self", "cls"}:
+ params = params[1:]
+ params = params[1:] # drop the single allowed subject (Exception 1)
+ return len(params) # *args/**kwargs and kw-only params are not counted
+
+def _evaluate_def(node, *, module_qname, relative_path, class_stack,
+ func_stack, is_method, source_lines) -> Violation | None:
+ # carve-outs first — any match => skip entirely
+ if _is_dunder(node.name): return None
+ if _def_line_has_escape_hatch(node, source_lines=source_lines): return None
+ if _has_carveout_decorator(node): return None # pydantic / Typer / Temporal / pytest / Jinja2 / @override
+ if _has_typer_param_annotation(node): return None # decorator-less Typer entrypoints
+ if (dotted_qname, relative_path) in SYMMETRIC_ALLOWLIST: return None
+
+ # the rule: a bare * is required once any non-subject positional-or-keyword param remains
+ if _positional_or_keyword_count(node, is_method=is_method) >= 1:
+ return Violation(relative_path=relative_path, qualified_name=local_qname, lineno=node.lineno)
+ return None</pre>
+ <p class="note">A <code>_Collector(ast.NodeVisitor)</code> walks the module tracking the class/function scope; <code>find_violations_in_source()</code> is the shared core both entrypoints call. A mid-edit <code>SyntaxError</code> is skipped, never reported — the hook must not block on a transient parse error.</p>
+ </div>
+
+ <div class="tabpanel" data-panel="d-hook">
+ <div class="filechip">.claude/hooks/check-keyword-only.sh (new) — the in-loop gate</div>
+ <pre class="plain"># PostToolUse hook: run the stdlib-only AST guard on the just-edited file (~40ms).
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+GUARD="$PROJECT_DIR/pipelex/cli/dev_cli/commands/keyword_only_guard.py"
+PYTHON="$PROJECT_DIR/.venv/bin/python"
+
+input=$(cat) # tool-call JSON on stdin (pure bash, no jq — house style)
+file_path=$(echo "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
+ | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)
+
+[ -z "$file_path" ] && exit 0 # fast, silent pass-through ...
+case "$file_path" in *.py) ;; *) exit 0 ;; esac # ... non-.py rejected in bash, no Python launch
+[ -x "$PYTHON" ] || exit 0
+[ -f "$GUARD" ] || exit 0
+
+cd "$PROJECT_DIR" # invoked by FILE PATH (not -m) → skips the pipelex import chain
+exec "$PYTHON" "$GUARD" "$file_path" # exit 2 + stderr → Claude Code surfaces it as blocking feedback</pre>
+ <p class="note">Running by file path instead of <code>python -m</code> is deliberate: <code>-m</code> would import <code>pipelex/__init__.py → rich</code> and blow the cold-start budget.</p>
+ </div>
+
+ <div class="tabpanel" data-panel="d-down">
+ <div class="filechip">pipelex-api — the only real downstream call-site break + the lockstep pin bump</div>
+ <pre class="diff"><span class="ln hdr"># tests/unit/conftest.py — integration_mode was passed positionally</span><span class="ln ctx"> pipelex_instance = Pipelex.make(</span><span class="ln del">- IntegrationMode.PYTEST,</span><span class="ln add">+ integration_mode=IntegrationMode.PYTEST,</span><span class="ln ctx"> needs_inference=needs_inference_in_pipelex(request),</span><span class="ln ctx"> temporal_enabled=False,</span><span class="ln ctx"> )</span><span class="ln ctx"> </span><span class="ln hdr"># pyproject.toml (mirrored in uv.lock) — re-pin to the consolidation SHA</span><span class="ln ctx"> [tool.uv.sources]</span><span class="ln del">-pipelex = { git = "...pipelex.git", rev = "755b82117fd4c26ba090455cfd571099cf05708b" }</span><span class="ln add">+pipelex = { git = "...pipelex.git", rev = "0e32c8c02600e17bbe146331f9b701ccc03a1ca1" }</span></pre>
+ <p class="note">This call was <i>compliant</i> under the earlier SHA (the subject was positional-allowed) and only broke once the consolidation made <code>Pipelex.make</code> fully keyword-only — a textbook example of why the rule pays off: insert/reorder safety. cocode / cookbook / starter-python needed only the rev bump.</p>
+ </div>
+</div>
+
+<h2>Status &amp; the one open thread</h2>
+<div class="grid">
+ <div class="card">
+ <h3>Done <span class="pill good">landed on branch</span></h3>
+ <p>Tree fully compliant; guard hard-blocks in <code>agent-check</code> + CI; convention promoted to the contributor docs (in the mkdocs nav); a standing rule lives in the kit source that regenerates <code>CLAUDE.md</code>/<code>AGENTS.md</code>. All four consumer PRs pushed and green.</p>
+ </div>
+ <div class="card">
+ <h3>Open <span class="pill warn">at release</span></h3>
+ <p>When the refactor lands on PyPI, swap each consumer's temporary <code>[tool.uv.sources]</code> git pin back to the released <code>pipelex</code> version (<code>==</code>/<code>&gt;=</code>) and confirm CI stays green. Tracked in the downstream-consumer-breakage record's checklist.</p>
+ </div>
+</div>
+
+<footer>
+ Branch <code>refactor/Function-calling-4</code>. Consumer PRs: pipelex-api&nbsp;#19, cocode&nbsp;#75, pipelex-cookbook&nbsp;#153, pipelex-starter-python&nbsp;#55, pipelex-worker&nbsp;#23. The full convention spec, the resolved suspects list, and the raw audit live alongside this file in the <code>keyword-only-arguments/</code> track.
+</footer>
+
+</div>
+
+<script>
+ mermaid.initialize({
+ startOnLoad: true,
+ theme: "dark",
+ themeVariables: {
+ background: "#171a23", primaryColor: "#1d212c", primaryBorderColor: "#2c3650",
+ primaryTextColor: "#e6e9ef", lineColor: "#6ea8fe", fontSize: "14px"
+ },
+ flowchart: { curve: "basis" }
+ });
+ // lightweight tabs
+ document.querySelectorAll(".tabs").forEach(function (tabs) {
+ var buttons = tabs.querySelectorAll(".tabbar button");
+ var panels = tabs.querySelectorAll(".tabpanel");
+ buttons.forEach(function (btn) {
+ btn.addEventListener("click", function () {
+ var key = btn.getAttribute("data-tab");
+ buttons.forEach(function (b) { b.classList.toggle("active", b === btn); });
+ panels.forEach(function (p) { p.classList.toggle("active", p.getAttribute("data-panel") === key); });
+ });
+ });
+ });
+</script>
+</body>
+</html>
diff --git a/wip/keyword-only-arguments/positional-subject-suspects.md b/wip/keyword-only-arguments/positional-subject-suspects.md
new file mode 100644
index 000000000..ffd5d87f0
--- /dev/null
+++ b/wip/keyword-only-arguments/positional-subject-suspects.md
@@ -0,0 +1,280 @@
+# Keyword-only refactor — positional-subject ABUSE suspects (consolidated)
+
+> **RESOLVED (2026-06-15).** All 59 suspects — high-confidence, med/low, the public-API pair (`Pipelex.make`/`setup`), and the "decide as a family" clusters (`pipe_controllers` `_*_controller_pipe` family, the eight `graph` `GraphTracerManager` `lookup_key` dispatch methods) — were applied as **fully keyword-only** by relocating the bare `*` to immediately after `self`/`cls` (no reordering). Sibling/override sets were flipped consistently (e.g. `StuffContent.rendered_markdown` base + all subclass overrides; `PipeController._*_controller_pipe` base + overrides). Two convention boundaries were deliberately **left untouched** as out-of-scope: the broader `PipeAbstract._live_run_pipe`/`_dry_run_pipe` `job_metadata`-first convention (not among the suspects), and `GraphTracerProtocol`/`GraphTracer` (`node_id`-first, a different class). Positional call sites — production (`plugins/*_config.py` → `get_reasoning_level_str`, `check_rules_sync_cmd.py` → `build_merged_rules`) and tests — were converted to keyword; temporal `test_worker_cli.py` mock assertions were rewritten from `.call_args.args[0]` to `.call_args.kwargs[...]`. `make agent-check` (ruff, pyright 0 errors, mypy clean, `check-keyword-only` PASSED) and `make agent-test` both green. Public-API break (`Pipelex.make`/`setup` now keyword-only after the subject) is folded into the already-breaking refactor branch; downstream impact tracked in [`downstream-consumer-breakage.md`](downstream-consumer-breakage.md).
+
+Consolidated shortlist from the positional-subject audit ([`audit/positional-subject-audit.md`](audit/positional-subject-audit.md)). The question for every entry: *was the first arg genuinely the semantic object of the call, or was it kept positional merely to satisfy Exception 1 ("the subject may stay positional"), when the call would actually read better with that arg keyworded too?*
+
+## How this was produced
+
+- **Population reviewed:** 1140 of the 1806 audited functions — the 797 `SUBJECT_THEN_KEYWORDS` entries (`def f(subject, *, …)`, where the subject choice was actually made) plus 343 **primitive-typed** lone subjects (`def f(x: bool/int/str/float)`, which read opaquely at the call site). The remaining ~660 non-primitive lone subjects and the symmetric-allowlist/variadic entries were filtered out mechanically (no LLM) — a single positional param with a domain type offers no subject to abuse.
+- **Method:** one **Sonnet 4.6** sub-agent per package (25 agents), each with Read+Grep, instructed to open the function body and a call site or two whenever the signature alone was ambiguous, to **default to "fine" and emit only suspects**, and to cite the rubric in `docs/contribute/keyword-only-arguments.md`. Per-package shortlists live in [`audit/findings/<package>.md`](audit/findings/).
+- **Calibration was healthy:** every package came back with a short list (0–5 suspects); no agent rubber-stamped or over-flagged.
+
+## Summary
+
+- **Total reviewed:** 1140 entries (797 Section A + 343 primitive lone-subjects).
+- **Total suspects: 59** — **31 high-confidence**, 28 medium/low.
+- **Zero-suspect packages:** `base_exceptions`, `errors`, `hub`, `language`, `pipe_signature`, `tracing`.
+- The suggested fix is **almost always the same**: move the `*` before the subject too (make the signature *fully* keyword-only). A handful suggest *reordering* so a different arg becomes the positional subject.
+
+| Package | High | Med/Low | Total |
+| --- | ---: | ---: | ---: |
+| `temporal` | 4 | 1 | 5 |
+| `pipe_controllers` | 3 | 2 | 5 |
+| `builder` | 3 | 1 | 4 |
+| `cli` | 3 | 1 | 4 |
+| `tools` | 3 | 1 | 4 |
+| `pipe_operators` | 2 | 2 | 4 |
+| `plugins` | 1 | 3 | 4 |
+| `system` | 1 | 3 | 4 |
+| `libraries` | 1 | 3 | 4 |
+| `cogt` | 2 | 1 | 3 |
+| `core` | 2 | 1 | 3 |
+| `pipe_run` | 2 | 1 | 3 |
+| `pipelex` | 1 | 2 | 3 |
+| `observer` | 2 | 0 | 2 |
+| `kit` | 1 | 1 | 2 |
+| `graph` | 0 | 1 | 1 |
+| `pipeline` | 0 | 1 | 1 |
+| `reporting` | 0 | 1 | 1 |
+| `runtime_bridge` | 0 | 1 | 1 |
+| **Total** | **31** | **28** | **59** |
+
+## Cross-cutting patterns (for adjudication)
+
+The 59 suspects collapse into a small number of recurring shapes. A near-universal tell: **the existing call sites already pass the "positional" arg by keyword**, which means the positional permission is buying nothing today — exactly the signal that Exception 1 was leaned on mechanically.
+
+1. **Lookup-table / registry / config carried positional while the real query is keyworded.** The strongest cluster. The positional arg is a deck/map/dict you read *out of*, and the keyword arg is what you're looking up.
+ - `builder` `_resolve_preset_backend(model_deck, *, model_handle, …)` · `cogt` `model_cost_per_token(costs, *, cost_category)` · `cogt` `get_reasoning_level_str(effort_to_level_map, *, effort)` · `tools` `apply_tag_style(context, *, value, …)` · `kit` `_read_agent_file(agents_dir, *, name)`.
+
+2. **`*_for_pipe` / `*_from_response` / `*_from_uri` — the name advertises the operand, but a *different* arg is positional.** The function name itself says which arg is the object, and it isn't the positional one.
+ - `builder` `build_output_for_pipe(mthds_contents, *, pipe_code, …)` · `builder` `build_runner_code_for_pipe(mthds_contents, *, pipe_code)` · `plugins` `make_extract_output_from_response(inference_model, *, response)` · `plugins` `make_mistral_document_url_chunk_from_uri(mistral_client, *, uri)` · `tools` `detect_jinja2_required_variables(template_category, *, template_source)` (+ `detect_jinja2_variable_references`).
+
+3. **Mode flag / bare bool carried positional** — `f(True)` reveals nothing, and every call site already keywords it.
+ - `cli` `build_run_output(with_memory, *, …)` · `cli` `determine_needs(reset, *, …)` · `temporal` `run_worker(is_not_sandboxed, *, …)` · `system` `update_service_terms_acceptance(accepted, …)` · `system` `update_inference_setup_completed(completed, …)` · `system` `check_is_initialized(print_warning_if_not=…)` · `core` `rendered_markdown(level=1, *, is_pretty=…)` (+ async twin).
+
+4. **`task_queue` positional on Temporal factories** — a defaulted config option, not "the thing being made". Three parallel sites.
+ - `temporal` `create_executor` · `make_temporal_pipe_router` · `make_temporal_pipe_run`.
+
+5. **Trace/provenance context carrier positional** (`job_metadata`, `lookup_key`, `calling_pipe_code`) while the function acts on the stuffs/outputs in the keyword args.
+ - `pipe_controllers` `_register_branch_outputs_with_graph_tracer`, `_register_parallel_combine_with_graph_tracer`, `sub_pipe.run_pipe(calling_pipe_code, …)` · `graph` `on_pipe_end_success(lookup_key, …)` and 7 sibling dispatch methods.
+
+6. **Accumulator/sink dict carried positional** while the content being added is keyworded.
+ - `pipe_run` `_try_add_rendered_file(files, *, filename, …)` · `_add_optional_text_file(files, *, …)`.
+
+7. **Symmetric / directional pair arbitrarily split across the `*`** — neither operand is "the subject", so a positional+keyword split is just noise.
+ - `pipe_operators` `_expects_type(expected_type, *, target_type)` · `plugins` `make_nb_tokens_by_category_from_nb(nb_input, *, nb_output)` · `libraries` `compute_fingerprint_from_content(concepts, *, pipes)` · `pipe_run` `output_multiplicity_to_apply(base, *, override)` · `pipeline` `copy_with_update(otel_context, *, trace_context, …)`.
+
+8. **Public-API surface** — already known to be keyword-breaking from the refactor; worth a deliberate call.
+ - `pipelex` `Pipelex.make(integration_mode=…, *, …)` and `Pipelex.setup(integration_mode, *, …)`.
+
+**Note on conventions:** several med/low entries are deliberate codebase-wide conventions (e.g. `job_metadata` as the first param on the whole run-pipe family in `pipe_controllers`; the `lookup_key` dispatch discriminant across the eight `GraphTracerManager` methods). Those should be decided *as a family* — fix the base/convention or leave it, don't pick off one site.
+
+---
+
+## Suspects by package (ordered by confidence)
+
+### `temporal` (4 high · 1 med/low)
+
+**High**
+
+- `pipelex/temporal/task_manager.py:36` — `TaskManager.run_worker` — `async def run_worker(self, is_not_sandboxed: bool, *, is_unit_testing: bool, ...)` — `is_not_sandboxed` is a boolean flag that reads opaquely positionally: `run_worker(True)` reveals nothing. It's not the semantic object the method acts on; the worker it launches is. Both real call sites already pass it as `is_not_sandboxed=...`. The `temporal_task_manager.py` override (which carries `@override` and is thus skip-exempt) would track automatically once the Protocol base is fixed. Suggested fix: make the signature fully keyword-only — `async def run_worker(self, *, is_not_sandboxed: bool, is_unit_testing: bool, ...)`.
+- `pipelex/temporal/tprl/workflow_caller.py:298` — `WorkflowExecutorFactory.create_executor` — `def create_executor(cls, task_queue: str | None = None, *, workflow_execution_timeout, retry_policy, ...)` — `task_queue` is one of many configuration options for the executor being created; `create_executor` doesn't designate it as the subject (no "for this queue" semantic). All four existing call sites pass it as `task_queue=...`. Suggested fix: move `task_queue` after `*`.
+- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:127` — `make_temporal_pipe_router` — `def make_temporal_pipe_router(task_queue: str | None = None, *, workflow_execution_timeout, retry_policy, ...)` — same pattern as `create_executor`: `task_queue` is a config option defaulting to `None`, not the semantic object of a "make router" call. Suggested fix: `def make_temporal_pipe_router(*, task_queue: str | None = None, ...)`.
+- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:131` — `make_temporal_pipe_run` — `def make_temporal_pipe_run(task_queue: str | None = None, *, workflow_execution_timeout, retry_policy, ...)` — same pattern as `make_temporal_pipe_router`. Suggested fix: `def make_temporal_pipe_run(*, task_queue: str | None = None, ...)`.
+
+**Medium / low**
+
+- `pipelex/temporal/worker_cli.py:25` — `run_worker` — `async def run_worker(project: str | None = None, *, is_not_sandboxed: bool, is_unit_testing: bool, ...)` — `project` defaults to `None` and is looked up from pyproject.toml when absent; its role is closer to a context/config override than the semantic subject of "run a worker". The one real call site passes it positionally from the Typer command, but a fully keyword-only form would be equally natural. Medium confidence — `project` does describe which project's worker to run, so the positional reading is defensible.
+
+### `pipe_controllers` (3 high · 2 med/low)
+
+**High**
+
+- `pipelex/pipe_controllers/parallel/pipe_parallel.py:326` — `PipeParallel._register_branch_outputs_with_graph_tracer` — `def _register_branch_outputs_with_graph_tracer(self, job_metadata: JobMetadata, *, output_stuffs: dict[str, 'Stuff']) -> None` — `job_metadata` is a trace-context carrier / lookup key, not the semantic object; the function acts on `output_stuffs`. Both call sites (210, 309) already pass `job_metadata=job_metadata`. Suggested fix: make fully keyword-only.
+- `pipelex/pipe_controllers/parallel/pipe_parallel.py:369` — `PipeParallel._register_parallel_combine_with_graph_tracer` — `def _register_parallel_combine_with_graph_tracer(self, job_metadata: JobMetadata, *, combined_stuff: 'Stuff', branch_stuffs: dict[str, 'Stuff']) -> None` — same pattern: `job_metadata` is a context/trace carrier; the function acts on `combined_stuff` and `branch_stuffs`. Both call sites (203, 302) use `job_metadata=job_metadata`. Suggested fix: move `*` before `job_metadata`.
+- `pipelex/pipe_controllers/sub_pipe.py:34` — `SubPipe.run_pipe` — `async def run_pipe(self, calling_pipe_code: str, *, working_memory: WorkingMemory, job_metadata: JobMetadata, sub_pipe_run_params: PipeRunParams, library_crate: 'LibraryCrate | None'=None) -> PipeOutput` — `calling_pipe_code` is caller provenance/context, not the semantic object; `self` (the SubPipe) is the object being run. Call sites (pipe_parallel.py:152, pipe_sequence.py:195, pipe_condition.py:328) already pass `calling_pipe_code=self.code`. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/pipe_controllers/pipe_controller.py:71` — `PipeController._live_run_controller_pipe` — `async def _live_run_controller_pipe(self, job_metadata: JobMetadata, *, ...)` — `job_metadata` positional follows the codebase-wide `_live_run_pipe(self, job_metadata, *, ...)` convention on `PipeAbstract`. The single call site uses keyword form. Medium confidence only — changing the controller without changing the base class would create inconsistency. **Decide as a family** with the base run-pipe signatures.
+- `pipelex/pipe_controllers/pipe_controller.py:83` — `PipeController._dry_run_controller_pipe` — same reasoning as `_live_run_controller_pipe`; treat as a pair.
+
+### `builder` (3 high · 1 med/low)
+
+**High**
+
+- `pipelex/builder/operations/models_ops.py:36` — `_resolve_preset_backend` — `def _resolve_preset_backend(model_deck: ModelDeck, *, model_handle: str, model_type: ModelType) -> InferenceModelSpec | None` — Docstring: "Resolve a preset's model handle to an InferenceModelSpec" — the thing resolved is `model_handle`; `model_deck` is a lookup registry. Call sites confirm: `_resolve_preset_backend(model_deck, model_handle=setting.model, model_type=model_type)` — the deck reads as an unlabeled blob while the real target is buried in keyword args. Suggested fix: make fully keyword-only.
+- `pipelex/builder/operations/output_ops.py:14` — `build_output_for_pipe` — `async def build_output_for_pipe(mthds_contents: list[str], *, pipe_code: str, output_format: ...) -> dict[str, Any]` — the name says "for_pipe", so the pipe is the subject; `mthds_contents` is raw bundle source material (context/input). `build_output_for_pipe(some_list, pipe_code="my.pipe")` makes the caller think twice about the first list. Suggested fix: make fully keyword-only, or reorder so `pipe_code` is the positional subject.
+- `pipelex/builder/operations/runner_code_ops.py:17` — `build_runner_code_for_pipe` — `async def build_runner_code_for_pipe(mthds_contents: list[str], *, pipe_code: str) -> str` — same pattern as `build_output_for_pipe`: name says "for_pipe", the pipe is the object, but `mthds_contents` was made positional. Suggested fix: make fully keyword-only, or promote `pipe_code`.
+
+**Medium / low**
+
+- `pipelex/builder/operations/models_ops.py:101` — `_build_presets_for_category` (+ parallels `_build_aliases_for_category` :135, `_build_waterfalls_for_category` :160) — `def _build_presets_for_category(model_deck: ModelDeck, *, category: ModelCategory, backend: str | None)` — name says "for_category"; `category` drives behavior, `model_deck` is the data source. At call sites the deck reads as an unnamed blob. Lower confidence than `_resolve_preset_backend` because the deck is a richer object with a plausible claim to being the queried subject. Suggested fix: make fully keyword-only (all three).
+
+### `cli` (3 high · 1 med/low)
+
+**High**
+
+- `pipelex/cli/cli_factory.py:31` — `make_pipelex_for_cli` — `def make_pipelex_for_cli(context: ErrorContext, *, library_dirs: ..., needs_inference: bool, ...) -> Pipelex` — `context` is error-reporting metadata (an `ErrorContext` enum that shapes error messages), not the object being created. The function builds a `Pipelex`; `context` is a side-channel tag. Every call site uses `context=...`. Suggested fix: make fully keyword-only.
+- `pipelex/cli/agent_cli/commands/run/_output_helpers.py:14` — `build_run_output` — `def build_run_output(with_memory: bool, *, main_stuff_json: dict, working_memory_dump: dict, compact_result: ..., extra_metadata: ...) -> dict` — `with_memory: bool` is a mode flag, not the object being assembled; `main_stuff_json` is the more central data. Both call sites pass `with_memory=with_memory`. Suggested fix: move `*` before `with_memory`.
+- `pipelex/cli/commands/init/command.py:182` — `determine_needs` — `def determine_needs(reset: bool, *, check_config: bool, check_inference: bool, ...) -> tuple[bool, bool, bool, bool]` — `reset: bool` is one mode flag among several others; not more "the subject" than `check_config`/`check_inference`. The single call site passes `reset=reset`. Suggested fix: move `*` before `reset` (consistent with the other flags).
+
+**Medium / low**
+
+- `pipelex/cli/agent_cli/commands/init_cmd.py:173` — `_configure_backends` — `def _configure_backends(config: dict[str, Any], *, backends_toml_path: Path, template_backends_path: Path) -> list[str]` — the primary action modifies `backends_toml_path`; `config: dict` is read-only context. The call site passes `config` positionally, so there's no immediate caller-side benefit. Private helper, contained impact, and `config` as "data being acted upon" is defensible. Low confidence.
+
+### `tools` (3 high · 1 med/low)
+
+**High**
+
+- `pipelex/tools/jinja2/jinja2_required_variables.py:121` — `detect_jinja2_required_variables` — `def detect_jinja2_required_variables(template_category: TemplateCategory, *, template_source: str) -> set[str]` — `template_source` is the object analyzed; `template_category` is a configuration/mode parameter. All call sites pass `template_category=` as keyword, so the positional exemption buries the real subject keyword-only. Suggested fix: swap order — `detect_jinja2_required_variables(template_source: str, *, template_category: TemplateCategory)`.
+- `pipelex/tools/jinja2/jinja2_required_variables.py:255` — `detect_jinja2_variable_references` — `def detect_jinja2_variable_references(template_category: TemplateCategory, *, template_source: str) -> list[VariableReference]` — same pattern: source is the object, category is config; all call sites keyword the category. Suggested fix: swap order so `template_source` is the positional subject.
+- `pipelex/tools/jinja2/jinja2_filters.py:110` — `apply_tag_style` — `def apply_tag_style(context: Context, *, value: str, tag_name: str | None=None) -> str` — `context` is a Jinja2 `Context` used only to retrieve `TAG_STYLE`; `value` is the string being wrapped. Single call site passes `context` positionally (framework-driven), but conceptually the positional arg is a lookup registry, not the acted-on object. Suggested fix: fully keyword-only. *(Caveat: confirm the Jinja2 invocation path — if a `@pass_context` filter calls it positionally, the framework owns the convention.)*
+
+**Medium / low**
+
+- `pipelex/tools/jinja2/jinja2_environment.py:9` — `make_jinja2_env_from_loader` — `def make_jinja2_env_from_loader(template_category: TemplateCategory, *, loader: BaseLoader, enable_async: bool=True) -> Environment` — the name says "from loader", pointing to `loader` as the operative arg; `template_category` is config. Minor — `template_category` plausibly drives env construction. Suggested fix: reorder to `loader` positional, or fully keyword-only.
+
+### `pipe_operators` (2 high · 2 med/low)
+
+**High**
+
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:269` — `ImgGenPromptBlueprint._render_text` — `async def _render_text(self, context_provider: ContextProviderAbstract, *, template_blueprint: TemplateBlueprint, ...)` — `context_provider` is a lookup environment/registry, not the thing rendered; `template_blueprint` is the real subject. Call sites always pass `context_provider=`. Suggested fix: make fully keyword-only.
+- `pipelex/pipe_operators/llm/llm_prompt_blueprint.py:350` — `LLMPromptBlueprint._unravel_text` — `async def _unravel_text(self, context_provider: ContextProviderAbstract, *, jinja2_blueprint: TemplateBlueprint, ...)` — identical to `_render_text`: `context_provider` is the resolution environment, `jinja2_blueprint` is what gets unraveled. Call sites use `context_provider=`. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/pipe_operators/compose/structured_content_composer.py:392` — `StructuredContentComposer._expects_type` — `def _expects_type(self, expected_type: type[Any], *, target_type: type)` — symmetric type-comparison pair (`issubclass(expected_type, target_type)`); neither arg is more "subject". Call sites pass `expected_type=` as keyword. Suggested fix: make fully keyword-only.
+- `pipelex/pipe_operators/img_gen/img_gen_prompt_blueprint.py:65` — `ImgGenPromptBlueprint.make_img_gen_prompt` — `async def make_img_gen_prompt(self, context_provider: ContextProviderAbstract, *, extra_params, max_prompt_images)` — `context_provider` is a resolution environment, not what's generated (the prompt is built from `self`). Lower confidence because "context to use for building" is a defensible subject role. Suggested fix: make fully keyword-only.
+
+### `plugins` (1 high · 3 med/low)
+
+**High**
+
+- `pipelex/plugins/gateway/gateway_completions_factory.py:138` — `GatewayCompletionsFactory.make_extract_output_from_response` — `def make_extract_output_from_response(cls, inference_model: InferenceModelSpec, *, response: GenericResponse) -> ExtractOutput` — name is "from_response", so `response` is the primary operand; `inference_model` is only a lookup key selecting the extraction sub-method (`GatewayExtractProtocol.make_from_model_handle`). Suggested fix: make fully keyword-only (or reorder so `response` is the subject).
+
+**Medium / low**
+
+- `pipelex/plugins/anthropic/anthropic_factory.py:244` — `AnthropicFactory.make_nb_tokens_by_category_from_nb` — `def make_nb_tokens_by_category_from_nb(nb_input: int, *, nb_output: int) -> NbTokensByCategoryDict` — symmetric directional pair (`nb_input`/`nb_output`); splitting across `*` is arbitrary. No external call sites found, so risk is low. Suggested fix: make fully keyword-only.
+- `pipelex/plugins/mistral/mistral_factory.py:365` — `MistralFactory.make_mistral_document_url_chunk_from_uri` — `async def make_mistral_document_url_chunk_from_uri(cls, mistral_client: Mistral, *, uri: str) -> DocumentURLChunkTypedDict` — name ends "from_uri", so `uri` is the operand; `mistral_client` is a dependency (the docstring calls it "required for local file uploads"). Suggested fix: make fully keyword-only.
+- `pipelex/plugins/plugin_sdk_registry.py:22` — `PluginSdkRegistry.set_sdk_instance` — `def set_sdk_instance(self, plugin: Plugin, *, sdk_instance: Any) -> Any` — registry keyed by `plugin.sdk_handle`; `plugin` acts as an index, `sdk_instance` is what's stored. "Set X instance" implies `sdk_instance` is the subject. Call sites already keyword both. Suggested fix: make fully keyword-only.
+
+### `system` (1 high · 3 med/low)
+
+**High**
+
+- `pipelex/system/pipelex_service/gateway_config_merger.py:69` — `GatewayConfigMerger._apply_overrides_to_model` — `def _apply_overrides_to_model(cls, model_name: str, *, gateway_model_specs: BackendModelSpecs, local_model_config: BackendModelSpecs) -> None` — `model_name` is a string used only in log/warning messages; the real operands are the two keyword specs. The sole call site passes `model_name=model_name`. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/system/pipelex_service/pipelex_service_agreement.py:29` — `update_service_terms_acceptance` — `def update_service_terms_acceptance(accepted: bool, *, config_dir: Path | None=None) -> None` — bare `bool` positional; `update_service_terms_acceptance(True)` is opaque. All call sites use `accepted=...`. Suggested fix: make fully keyword-only.
+- `pipelex/system/pipelex_service/pipelex_service_agreement.py:53` — `update_inference_setup_completed` — `def update_inference_setup_completed(completed: bool, *, config_dir: Path | None=None) -> None` — same pattern; always called as `completed=True`. Suggested fix: make fully keyword-only.
+- `pipelex/system/configuration/config_check.py:12` — `check_is_initialized` — `def check_is_initialized(print_warning_if_not: bool=True) -> bool` — (primitive lone-subject) single `bool` with a descriptive name; `check_is_initialized(False)` would be opaque. Callers always keyword it or use the default. Low priority. Suggested fix: `def check_is_initialized(*, print_warning_if_not: bool=True)`.
+
+### `libraries` (1 high · 3 med/low)
+
+**High**
+
+- `pipelex/libraries/libraries/library_crate.py:39` — `LibraryCrate.compute_fingerprint_from_content` — `def compute_fingerprint_from_content(concepts: dict[str, 'ConceptBlueprint | str'], *, pipes: dict[str, PipeBlueprintUnion]) -> str` — `concepts` and `pipes` are co-equal operands (both dict inputs to a hash); neither is the object. Call sites keyword both. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/libraries/concept/concept_library.py:191` — `ConceptLibrary.add_dependency_concept` — `def add_dependency_concept(self, alias: str, *, concept: Concept) -> None` — `alias` is a namespace/prefix used to build a composite key; `concept` is what's actually added. Call sites use `alias=alias`. Suggested fix: make `alias` keyword-only too, or reorder to `(self, concept, *, alias)`.
+- `pipelex/libraries/pipe/pipe_library.py:97` — `PipeLibrary.add_dependency_pipe` — `def add_dependency_pipe(self, alias: str, *, pipe: PipeAbstract) -> None` — identical pattern to `add_dependency_concept`: `alias` is the namespacing key, `pipe` is the subject. Suggested fix: same.
+- `pipelex/libraries/visibility_utils.py:35` — `make_visibility_checker` (+ `check_visibility_for_blueprints` :53) — `def make_visibility_checker(manifest: MethodsManifest | None, *, blueprints: list[PipelexBundleBlueprint]) -> PackageVisibilityChecker` — `manifest` is nullable config/filter (often `None`); `blueprints` is the primary data inspected. Call sites pass `manifest=manifest`. Low confidence — `manifest` could be argued as the filter subject. Suggested fix: make both keyword-only (both functions).
+
+### `cogt` (2 high · 1 med/low)
+
+**High**
+
+- `pipelex/cogt/usage/costs_per_token.py:4` — `model_cost_per_token` — `def model_cost_per_token(costs: CostsByCategoryDict, *, cost_category: CostCategory) -> float` — `costs` is a dict used purely as a lookup table; the function dispatches on `cost_category` (`costs.get(cost_category) / 1_000_000`). The real subject is `cost_category`. All three call sites use `costs=...`. Suggested fix: make fully keyword-only, or reorder with `cost_category` first.
+- `pipelex/cogt/llm/reasoning_config_base.py:40` — `get_reasoning_level_str` — `def get_reasoning_level_str(effort_to_level_map: EffortToLevelMap, *, effort: ReasoningEffort) -> str | None` — body is `effort_to_level_map.get(effort)`; the map is a lookup table, `effort` is the query. All four call sites pass the map positionally as `self.effort_to_level_map`, reading opaquely. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/cogt/model_backends/backend_credentials.py:26` — `BackendCredentialsErrorMsgFactory.make_one_variable_missing_error_msg` — `def make_one_variable_missing_error_msg(cls, secrets_provider: SecretsProviderAbstract, *, backend_name: str | None, var_name: str) -> str` — `secrets_provider` is a dispatch context (`isinstance`-branches to pick wording); `backend_name`/`var_name` are the real domain objects. Sole call site uses `secrets_provider=`. Lower confidence because the provider does control branching. Low urgency.
+
+### `core` (2 high · 1 med/low)
+
+**High**
+
+- `pipelex/core/stuffs/stuff_content.py:64` — `StuffContent.rendered_markdown` — `def rendered_markdown(self, level: int=1, *, is_pretty: bool=False) -> str` — `level` and `is_pretty` are both optional rendering options; neither is the subject (`self` is). All call sites use keyword form or the no-arg default. `rendered_markdown(2)` is opaque. Suggested fix: move `*` before `level`.
+- `pipelex/core/stuffs/stuff_content.py:113` — `StuffContent.rendered_markdown_async` — `async def rendered_markdown_async(self, level: int=1, *, is_pretty: bool=False) -> str` — same issue as `rendered_markdown`; parallel async signature. Suggested fix: move `*` before `level`.
+
+**Medium / low**
+
+- `pipelex/core/concepts/concept.py:194` — `Concept.render_concept_representation` — `def render_concept_representation(self, output_format: ConceptRepresentationFormat, *, is_multiple: bool=False) -> tuple[dict[str, Any], set[str]]` — `self` (Concept) is the real subject; `output_format` and `is_multiple` are equal-standing rendering options. All call sites keyword both. Suggested fix: move `*` before `output_format`.
+
+### `pipe_run` (2 high · 1 med/low)
+
+**High**
+
+- `pipelex/pipe_run/delivery_executor.py:201` — `DeliveryExecutor._try_add_rendered_file` — `async def _try_add_rendered_file(cls, files: dict[str, ResultFile], *, filename: str, render: Awaitable[str], content_type: str) -> None` — `files` is a mutable accumulator/sink, not the object; the real subjects of the "add" are `filename`/`render`/`content_type`. Call site: `self._try_add_rendered_file(files, filename="main_stuff.json", ...)`. Suggested fix: make fully keyword-only.
+- `pipelex/pipe_run/delivery_executor.py:219` — `DeliveryExecutor._add_optional_text_file` — `def _add_optional_text_file(cls, files: dict[str, ResultFile], *, filename: str, text: str | None, content_type: str) -> None` — same pattern: `files` is the accumulator carried positionally, `filename`/`text`/`content_type` are the content added. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/pipe_run/pipe_run_params.py:28` — `output_multiplicity_to_apply` — `def output_multiplicity_to_apply(base_multiplicity: VariableMultiplicity | None, *, override_multiplicity: VariableMultiplicity | None) -> VariableMultiplicityResolution` — two-operand priority merge; neither input is clearly "the object". Docstring examples (`output_multiplicity_to_apply(None, None)`) show opaque positional calling. Suggested fix: make fully keyword-only.
+
+### `pipelex` (1 high · 2 med/low)
+
+**High**
+
+- `pipelex/pipelex.py:512` — `Pipelex.make` — `def make(cls, integration_mode: IntegrationMode = IntegrationMode.PYTHON, *, ...)` — `integration_mode` is a mode/config option, not the subject of the factory (the subject is the instance created). All call sites omit it or pass `integration_mode=...`. `Pipelex.make(IntegrationMode.CLI)` reads opaquely. **Primary public API entry point** — keyword-only is the right default. Suggested fix: `def make(cls, *, integration_mode: IntegrationMode = IntegrationMode.PYTHON, ...)`.
+
+**Medium / low**
+
+- `pipelex/pipelex.py:165` — `Pipelex.setup` — `def setup(self, integration_mode: IntegrationMode, *, ...)` — same logic as `make`: `integration_mode` is a mode flag, not the subject (`self` is). The sole internal call site uses `integration_mode=integration_mode`. Public API surface (though `make` is the primary entry). Suggested fix: `def setup(self, *, integration_mode: IntegrationMode, ...)`.
+- `pipelex/pipelex.py:145` — `Pipelex._get_validation_error_msg` — `def _get_validation_error_msg(component_name: str, *, validation_exc: Exception) -> str` — `component_name` is a descriptive label ("routing profile library", …), behaving like context alongside `validation_exc`. Call sites: `self._get_validation_error_msg("routing profile library", validation_exc=exc)` — the bare positional string reads opaquely. Private, low call-count, but inconsistent (`validation_exc` already keyword-only). Suggested fix: make fully keyword-only.
+
+### `observer` (2 high · 0 med/low)
+
+**High**
+
+- `pipelex/observer/multi_observer.py:14` — `MultiObserver.remove_observer` — `def remove_observer(self, name: str) -> None` — asymmetric with `add_observer(*, name, observer)` which is fully keyword-only; `remove_observer("some_name")` passes a bare string with no call-site context. Convention consistency + readability → `def remove_observer(self, *, name: str)`. *(Primitive lone-subject — flagged for the asymmetry, not opacity alone.)*
+- `pipelex/observer/local_observer.py:22` — `LocalObserver._write_to_jsonl` — `def _write_to_jsonl(self, event_type: str, *, payload: PayloadType) -> None` — `event_type` is a routing/selector string (picks the file + injects a key), not the object written; the payload is the real subject. Call sites pass a named constant so readability is acceptable, but the positional/keyword split is inconsistent (both are equally descriptive). Suggested fix: `def _write_to_jsonl(self, *, event_type, payload)`.
+
+### `kit` (1 high · 1 med/low)
+
+**High**
+
+- `pipelex/kit/single_file_agent_rules.py:12` — `_read_agent_file` — `def _read_agent_file(agents_dir: Traversable, *, name: str) -> str` — `agents_dir` is a lookup-context directory; `name` is the file read — the real object. "read [name] from [agents_dir]" has the subject keyworded and the context positional. Call site (:79): `_read_agent_file(agents_dir, name=name)`. Suggested fix: make fully keyword-only.
+
+**Medium / low**
+
+- `pipelex/kit/single_file_agent_rules.py:49` — `build_merged_rules` — `def build_merged_rules(kit_index: KitIndex, *, agent_set: str | None=None, file_list: list[str] | None=None) -> str` — `kit_index` is a config/registry data source + lookup table, reading more like context than subject. Lower confidence — a `KitIndex` could reasonably be "the thing being merged from". Suggested fix: make fully keyword-only.
+
+### `graph` (0 high · 1 med/low)
+
+**Medium / low**
+
+- `pipelex/graph/graph_tracer_manager.py:266` — `GraphTracerManager.on_pipe_end_success` (+ siblings `on_pipe_end_error` :325, `register_execution_data` :304, `add_edge` :360, `register_controller_output` :389, `register_batch_item_extraction` :411, `register_batch_aggregation` :440, `register_parallel_combine` :469) — `lookup_key` is a registry dispatch key routing to the right `GraphTracer` via `self._get_tracer(lookup_key)`; the semantic subject is `node_id` (in the keyword args). All call sites already pass `lookup_key=` as keyword, so no opacity exists today. The case for keyword-only: `lookup_key` is a dispatch concern, not the object, and the naming asymmetry with `GraphTracerProtocol` (which takes `node_id` positionally) is mildly confusing. Low confidence — `lookup_key` as first-positional is a coherent "which tracer" discriminant. **Decide as a family** across all eight manager dispatch methods.
+
+### `pipeline` (0 high · 1 med/low)
+
+**Medium / low**
+
+- `pipelex/pipeline/job_metadata.py:89` — `JobMetadata.copy_with_update` — `def copy_with_update(self, otel_context: OtelContext | None, *, trace_context: TraceContext | None = None, **updates: Any)` — `otel_context` is not the subject (`self` is); it's one of two context fields being updated, asymmetrically split from `trace_context` across `*`. Call sites pass `otel_context=...`, and the docstring justifies the asymmetry semantically (different inheritance semantics), but from a signature-readability standpoint both context args are peers. Suggested fix: make fully keyword-only.
+
+### `reporting` (0 high · 1 med/low)
+
+**Medium / low**
+
+- `pipelex/reporting/reporting_manager.py:251` — `ReportingManager._emit_best_effort` — `def _emit_best_effort(event_log: EventLogProtocol, *, event: UsageReportEvent) -> None` — `event` is the object emitted; `event_log` is the target/sink (`event_log.emit(event)`). Both call sites pass `event_log=`. "emit best effort" names the action, not the receiver, so neither arg has a clear subject claim. Suggested fix: make fully keyword-only.
+
+### `runtime_bridge` (0 high · 1 med/low)
+
+**Medium / low**
+
+- `pipelex/runtime_bridge/primitives/hydration.py:17` — `_validate_as_known_class` — `def _validate_as_known_class(item_class: type[StuffContent], *, raw_item: StuffContent | dict[str, Any]) -> StuffContent` — `item_class` is a type/schema used to validate, not the data acted on; `raw_item` is the actual object. "validate raw_item into item_class" → `raw_item` is arguably the subject. Call sites: `_validate_as_known_class(item_class_or_none, raw_item=raw_item)` — a type as positional subject is unusual. Suggested fix: make fully keyword-only, or reorder to `(raw_item, *, item_class)`.
+
+---
+
+## Zero-suspect packages
+
+`base_exceptions` (1 reviewed), `errors` (7), `hub` (15), `language` (8), `pipe_signature` (2), `tracing` (9) — reviewed, no positional-subject abuse found.
+
+## Suggested next step
+
+Reserve adjudication for the **31 high-confidence** entries first — they cluster tightly into patterns 1–6 above and most already have call sites that keyword the "positional" arg, so the fix is low-risk and mechanical (`move *` / reorder). The `pipelex.make`/`setup` pair (pattern 8) is a deliberate public-API call. The med/low entries flagged "decide as a family" (`pipe_controllers` run-pipe convention, `graph` dispatch methods) should be settled at the base/convention level, not site-by-site. Point Opus at this shortlist, or hand-pick — happy to drive either.
diff --git a/wip/validate-parse-level-source-attribution.md b/wip/validate-parse-level-source-attribution.md
new file mode 100644
index 000000000..60e472744
--- /dev/null
+++ b/wip/validate-parse-level-source-attribution.md
@@ -0,0 +1,32 @@
+# Deferred: thread `mthds_source` through parse-level validate failures
+
+Code-review follow-up (greptile P1) on pipelex PR #992 (`feature/Tweaks-for-validation-api`). **Deferred** — recorded here for scoping rather than fixed in this PR, because it is a non-trivial runtime parse-path change, not a clear/small win.
+
+## The gap
+
+In `pipelex/pipeline/validate_bundle.py` (~line 286–291), the multi-file load builds blueprints per content with the source threaded in:
+
+```python
+content_sources = list(mthds_sources) if mthds_sources is not None else [None] * len(mthds_contents)
+loaded_blueprints = [
+ PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=content, mthds_source=source)
+ for content, source in zip(mthds_contents, content_sources, strict=True)
+]
+```
+
+When one content has **malformed TOML**, `make_pipelex_bundle_blueprint()` raises *before* it seeds `mthds_source` into the blueprint data. The exception propagates out of the comprehension to the enclosing `_translate_to_validate_bundle_error(category="pipe")` context manager, which (with the structured-info GATE) yields a last-resort `blueprint_validation` residual **with no `source`**. So `validate_bundle(mthds_contents=[good, bad], mthds_sources=["a.mthds","bad.mthds"])` returns a structured error that cannot be attributed to `bad.mthds`.
+
+## Why it matters
+
+The vscode cross-file diagnostics path routes each `validation_errors[].source` to the owning editor file. A source-less parse error is unroutable (it also has no `pipe_code`/`concept_code` to fall back on), so a syntax error in a multi-file API request lands nowhere useful in the editor. (The PR #50 path-boundary fix in `crossFileDiagnostics.ts` only helps once a `source` exists.)
+
+## Why it's deferred (not a quick patch)
+
+- It needs the comprehension restructured into a per-item loop with a `try`/`except` around `make_pipelex_bundle_blueprint`, catching the **specific** interpreter parse exception (must be identified — no speculative `except`), so the current `source` can be attached.
+- The residual category is currently `pipe` for this block (the `with _translate_to_validate_bundle_error(category="pipe")` scope); a parse-level failure is arguably `blueprint_validation`. Fixing attribution may also mean correcting the category — a second judgment call.
+- The source must be plumbed into the residual item built by `build_validation_error_items` (`pipeline/validation_errors.py`) — i.e. convert the per-content parse failure into a `blueprint_validation` item carrying that source, rather than the generic translated residual.
+- All of this sits on top of the Phase-2 + GATE logic; it carries regression risk against the just-landed structured-info invariant and deserves its own focused change + tests.
+
+## Suggested shape (when picked up)
+
+Loop per (content, source); on the specific parse exception, raise/emit a `blueprint_validation` `ValidationErrorItem` with `source=<this source>` and the parse message, so the GATE residual is no longer source-less. Add a unit test: two contents, the second malformed, assert the returned `validation_errors[]` has one item whose `source` is the second source. Then the conformance HTTP arm can assert parse-level source attribution on the real wire.