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.
feat(config): personal override files for backends.toml and routing_profiles.toml (#1189)
Louis Choquel67a2a6f182f4
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 3e05f290f..275d6f775 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:0ff100013089b0a003f5e016377c4394e27d7efa5aad76c4cc34fdb288941ab8"+digest = "sha256:9537c65f6feb9ee29c70d74fd8419797288448e0627d106c7931002163d012ff"reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-02T23:04:48Z"-rationale = "Pre-landing review round on fix/Doctor-backend-file-check-leniency. The trigger is again pipelex/cli/commands/doctor_cmd.py: check_models now attributes an InferenceBackendLibraryError with the same _is_error_about_backend helper the Backend Files row uses, instead of marking every report whose backend name appears in the message text -- which falsely condemned portkey, whose name rides in the loader's own advice as the example header x-portkey-provider. No command, flag, output key, exit code or message shape moved; the doctor's summary line for that failure is unchanged. Re-read docs/tools/cli/ and pipelex/cli/agent_cli/CLAUDE.md: the doctor is described at the row level (config, credentials, model health) and only the telemetry and pending_migrations findings are detailed; neither page states which backend a models-row failure is charged to, so nothing there is stale."+reviewed_at = "2026-09-03T12:14:14Z"+rationale = "Review round: doctor catches RoutingProfileLibraryError and a broken override at the gateway gate; init gates the terms prompt on the merged document and warns when an override still pins the gateway on after the base disabled it. No command, flag, output key or exit code moved. show.md names the overrides; init and doctor pages describe steps and rows without naming the file read; the warning is documented in under-the-hood/init-cli-flows.md and inference-backend-config.md."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -82,7 +82,7 @@ rationale = "Pre-landing review round on fix/Doctor-backend-file-check-leniency."pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:20738a9e42f0e5ef7ffc489093348af3cb4643a0""pipelex/cli/commands/codegen/types_cmd.py" = "blob:b7c9c7a3664c9fbe66f9b4c3c5ebf9ea1322445c""pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"-"pipelex/cli/commands/doctor_cmd.py" = "blob:69b83439f17b9ffa533b82e37f0906bba39c34ca"+"pipelex/cli/commands/doctor_cmd.py" = "blob:73ac79646eee18d68df2f22d24c9fa3b9937c310""pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:5ce264f5b0ab4ff4172f4d8789450916947f5c0e""pipelex/cli/commands/fix/_fix_core.py" = "blob:8f6a187a0fb42c498629b177753d81620800b0da"@@ -90,8 +90,8 @@ rationale = "Pre-landing review round on fix/Doctor-backend-file-check-leniency."pipelex/cli/commands/fix/bundle_cmd.py" = "blob:427364cc453957dfe0cec879f019050329c13b3c""pipelex/cli/commands/graph_cmd.py" = "blob:aa3649ca4ee3d4c9084236f0c3f6b1072803df46""pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/commands/init/backends.py" = "blob:24d61a06f613c0f460c6330ce5fb8dd965b27d79"-"pipelex/cli/commands/init/command.py" = "blob:1bc09139f8c2635b0f8af34c9644fd61dbf90da9"+"pipelex/cli/commands/init/backends.py" = "blob:c22b74b29f0ff4d7f90072c8068247dfb4109e36"+"pipelex/cli/commands/init/command.py" = "blob:2aafd4493c7f94da0a320dac06465e88a761d858""pipelex/cli/commands/init/config_files.py" = "blob:c13be6b8d2a8b211ce9ef0f4889ee131ffc3d2d8""pipelex/cli/commands/init/credentials.py" = "blob:7475c3082b8ee7530a76a52a8ab8bf18a7e21209""pipelex/cli/commands/init/ide_extension.py" = "blob:9f0ec1494c07062246ecc906bc55b7f2cf95c715"@@ -117,7 +117,7 @@ rationale = "Pre-landing review round on fix/Doctor-backend-file-check-leniency."pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472""pipelex/cli/commands/run/method_cmd.py" = "blob:9f5c7b6ad8f7fc7d086a9e6253049c6e2ec3e7d8""pipelex/cli/commands/run/pipe_cmd.py" = "blob:f92fcb94e3ad55cf5aeec366a59fa7a74bcc9667"-"pipelex/cli/commands/show_cmd.py" = "blob:7974d91404ea93f05b16b05b9aef3c1a540b965d"+"pipelex/cli/commands/show_cmd.py" = "blob:9492c9af966877f694ca61f7b1db3d151a1ddf56""pipelex/cli/commands/update_cmd.py" = "blob:06100ec3b9d6c66ca89a8c1536aa27983ae409ca""pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/validate/_validate_core.py" = "blob:3294c9c716ac616a89213c7356d38a8eff62da40"diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex eca205d35..fd43f4c1b 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -1,16 +1,16 @@contract = "config-docs"-digest = "sha256:da6430dd97584b9c51121406bc427b52d2bd26de47dc23e81ebfa851c635d6f7"+digest = "sha256:82d1d53686fa9f2add43b6900301972a2e177ebabeb80e14c4be07db45de9c6e"reviewed_by = "Louis Choquel"-reviewed_at = "2026-08-29T01:23:56Z"-rationale = "Added the [interpreter.methods] section with fetch_on_miss (new MethodsConfig model on InterpreterConfig, default true in pipelex.toml and the kit template). Documented in the new docs/configuration/config-practical/methods-config.md (added to both mkdocs nav sites) and cross-linked from packages.md and run-by-address.md. No existing key was removed, renamed or narrowed and none of the four named validator sites was touched, so no migration-ledger entry is owed: old override files without the new section keep booting on the shipped default."+reviewed_at = "2026-09-03T12:14:13Z"+rationale = "Review round: the path sequence now takes its base from the backends_file_path / routing_profiles_file_path property so a fixture patching that property is honoured. No config model field or validator site moved, so no ledger entry is owed. inference-backend-config.md already documents the override log line, the parse-error refusal and the scalar-over-table refusal added in the same round."[trigger_files]"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b""pipelex/cogt/img_gen/img_gen_job_components.py" = "blob:084985080413fd8d6c3b1b9b0747020cb0161858""pipelex/pipelex.toml" = "blob:37e48515b6d69d39cefb46ba1cda5c1cbb323a30""pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"-"pipelex/system/configuration/config_check.py" = "blob:efa78599c08e5e003d975cc54978ea5d267214a0"-"pipelex/system/configuration/config_loader.py" = "blob:86856b64aeff095a77f0c038fded2ee4dd948d00"+"pipelex/system/configuration/config_check.py" = "blob:88e15a92b186088a5ea1c7c4ebcedac830707d3a"+"pipelex/system/configuration/config_loader.py" = "blob:cbd3c9a54d5f9410c65b08702d19560a06f83086""pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339""pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160""pipelex/system/configuration/config_surface.py" = "blob:96f685656a3f4355e8a073e8bf6184e020fea8f5"diff --git a/.gitignore b/.gitignoreindex b345b78e2..0eb6f5dc6 100644--- a/.gitignore+++ b/.gitignore@@ -48,6 +48,8 @@ pipelex_super.tomlpipelex_override.tomlpipelex_temporary_override.tomltelemetry_override.toml+backends_override.toml+routing_profiles_override.toml# local pipelex service configuration.pipelex/pipelex_service.tomldiff --git a/.worktreeinclude b/.worktreeincludeindex 080b6ba52..ecaf0b08e 100644--- a/.worktreeinclude+++ b/.worktreeinclude@@ -3,5 +3,7 @@.env.pipelex/pipelex_override.toml.pipelex/telemetry_override.toml+.pipelex/inference/backends_override.toml+.pipelex/inference/routing_profiles_override.toml.pipelex/pipelex_service.toml.pipelex-dev/test_profiles_override.tomldiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1ead49c39..c3b53a130 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,9 +4,11 @@### Added+- **`backends_override.toml` and `routing_profiles_override.toml`**: a personal override layer for the two inference documents, the one `pipelex.toml` and `telemetry.toml` already had. Each sits beside its base file under `.pipelex/inference/`, is git-ignored and never shipped by the kit, and carries only the keys it sets: `[pipelex_gateway] enabled = false` in one and `active = "all_anthropic"` in the other is a complete pair. The base resolves as before — the project's file if it has one, otherwise the global one — and the overrides deep-merge over it, the global `~/.pipelex/inference/` one first and the project's one last, so a single edit under the home directory moves every project on the machine onto another backend, a project override still wins where one project must differ, and deleting the two files restores the shipped default. That order is deliberately not `pipelex.toml`'s, where a project base beats a global override: every project carries a tracked `backends.toml`, so a project base that won would defeat the file's purpose. Every reader sees the merged document — the boot, the gate that decides whether to fetch gateway model specs, `pipelex show backends`, and the doctor's file, credentials and models rows, including under `--global`, where the sequence is pinned to that directory and its own override. `pipelex init` keeps reading and writing the base file, because its checkboxes must pre-fill from the file they will write. The two names are in `GIT_IGNORED_CONFIG_FILES`, so the kit mirror, `make check-config-sync` and the global bootstrap copy look past them, and the migration ledger never touches them. See [Personal overrides](configuration/config-technical/inference-backend-config.md#personal-overrides).+- **`make test-ts-gates`** (alias `make ttg`): the TypeScript emission gates, provisioned and made mandatory. The `ts-zod` target promises its bytes are already what prettier would write — a codegen stamp is a hash over those bytes, so anything less has a consumer's first `prettier --write` report an untouched artifact as hand-edited. Two tests actually read the emission rather than measuring its lines: `prettier --check` over it, which is also the only thing that parses it, and running the emitted schema under a real zod against the runtime's own payload. Both were written to skip when node was absent, which in a Python repo meant they skipped in CI and on every developer machine, so the emitter's whole content contract was guarded by nothing. This target installs a pinned prettier and zod into the gitignored `.ts-toolchain/` and runs the codegen suite with `PIPELEX_REQUIRE_TS_GATES=1`, under which a missing binary is a failure instead of a skip; the new `Tests (ts emission gates)` CI job runs the same target behind a node step and blocks through the `Tests (all)` aggregate. An ordinary run on a machine with no node still skips, and now says which command would provision the toolchain. Moving the pinned prettier version is an emitter change rather than a dependency bump: the emitter models that formatter's exact break, quote and object-literal behaviour, so the gate is expected to red and the emitter to be taught what moved. See [TypeScript Emission Gates](contribute/typescript-emission-gates.md).-- **`.worktreeinclude`**: the gitignored files a fresh worktree of this repo needs — `.env`, the three `.pipelex/*.toml` overrides and `.pipelex-dev/test_profiles_override.toml` — are now declared in a tracked file at the repo root instead of living in one contributor's shell script. Claude Code reads it when it creates a worktree with git, and the workspace's `wt` tool reads it for the durable ones, so a fresh worktree of `pipelex` arrives configured either way. The file holds only the names of untracked files this repo's `.gitignore` already discloses, never their contents; it was previously gitignored here, which made the mechanism personal and untracked before anyone had used it.+- **`.worktreeinclude`**: the gitignored files a fresh worktree of this repo needs — `.env`, the personal `.pipelex/` overrides (including the two inference ones) and `.pipelex-dev/test_profiles_override.toml` — are now declared in a tracked file at the repo root instead of living in one contributor's shell script. Claude Code reads it when it creates a worktree with git, and the workspace's `wt` tool reads it for the durable ones, so a fresh worktree of `pipelex` arrives configured either way. The file holds only the names of untracked files this repo's `.gitignore` already discloses, never their contents; it was previously gitignored here, which made the mechanism personal and untracked before anyone had used it.- **`build_output_form` — the output-form descriptor, and a payload schema on the output contract.** The validate report now carries a third artifact, `output_form`, beside `pipe_io_contracts` and `input_form`, and the output contract carries a `json_schema` where it carried none. Both are the MTHDS change the standard landed in the same version, and both close the one real asymmetry between a pipe's two halves: an input had a presentation view and a payload schema; an output had neither, so a tool registry had no return type and a result renderer had to infer a payload's shape by inspecting it.@@ -26,12 +28,18 @@### Changed+- **The inference loaders take a path sequence, and the routing loader raises what the boot catches** (breaking). `InferenceBackendLibrary.load` takes `backends_library_paths`, `load_active_routing_profile` takes `routing_profile_library_paths`, and `ModelManager.setup` takes both, each a sequence whose first path is the base file and whose rest are the override files in merge order — built by the new `ConfigLoader.backends_file_paths()` / `routing_profiles_file_paths()` and read by the new `load_toml_from_base_and_overrides`. `is_pipelex_gateway_enabled` takes a `config_dir` instead of a file path, so a caller pins a directory rather than building a path by hand. The routing loader used to raise `ModelManagerError` for a missing file and `RoutingProfileLibraryError` for a profile naming a disabled backend, while the boot caught `RoutingProfileLibraryNotFoundError` and `RoutingProfileDisabledBackendError` — two clauses that were never reached, so a profile activated before its backend was enabled surfaced as a raw internal error. The loader now raises those two classes, keeps `RoutingProfileLibraryError` for an invalid document, a file that does not parse or an `active` naming no profile, and the boot turns all three into a `PipelexSetupError` that keeps the loader's account of what to fix; the doctor's Models row reports that third class too, where it used to surface as an unexpected error. The backend library refuses a file that does not parse and a backend whose value is not a table (`acme = false` where `[acme] enabled = false` was meant) as `InferenceBackendLibraryValidationError`, and `is_pipelex_gateway_enabled` — which the boot reads before the library loads — raises that same class for a parse error, so the boot's own clause names the file instead of a raw `TomlError` escaping before any clause is reached. When an override was merged, both loaders log which files the document was read from. `pipelex init` decides whether the gateway is enabled on the merged document, so a gateway switched on only by an override gets the terms prompt, and when declining the terms disables the gateway in the base while an override still pins it on, it warns and names the file. `ConfigLoader.backends_file_paths()` / `routing_profiles_file_paths()` take their base from the `backends_file_path` / `routing_profiles_file_path` properties, so a fixture that patches a property still redirects every reader; the integration fixtures that pin a routing profile now patch the sequence method instead, which also keeps a developer's personal override from re-routing the backend under test.++- **The `.pipelex/.gitignore` pipelex writes lists the personal overrides.** Beside the migration-backup rule, a fresh configuration directory now gets one line per personal override file — `pipelex_override.toml`, `pipelex_temporary_override.toml`, `telemetry_override.toml`, `inference/backends_override.toml` and `inference/routing_profiles_override.toml` — so a developer's own choices never reach a new project's `git status`. The file is still written only when absent and never rewritten; a project set up earlier adds the names to its own `.gitignore`.+- **Inference errors now declare an `error_domain`, derived from the category the worker already assigned** (breaking): the whole `CogtError` family used to report no domain at all, so every inference failure — a content-policy refusal included — was rendered as HTTP 500 by any consumer reading `ErrorReport.http_status`. `InferenceErrorCategory` gains an `error_domain` property and `CogtError.to_error_report()` derives from it, which means a **content-classified failure now answers 422 instead of 500**: a provider content-policy refusal, a malformed prompt image, a bad prompt parameter and their siblings are all properties of material the caller submitted. The widest reach of that mapping is worth stating plainly, because it goes past the classes that declare `CONTENT` on themselves: **every provider HTTP 400 classifies as `CONTENT`**, as does a builtin `ValueError` / `RuntimeError` / `FileNotFoundError` out of a local file extractor, so a context-length overflow, a parameter a model rejects, and an engine-side request-construction fault all answer 422 now and leave the 5xx rate. The `UserAction` on those was already `CHANGE_INPUT`, so the status is only catching up with the advice the report was already giving. The other mappings change no status and only make the report truthful about why — `CONFIGURATION` is `config`, `TRANSIENT` / `CAPACITY` / `AMBIGUOUS` are `runtime`, and `UNKNOWN` deliberately asserts no domain, since classification itself failed there and an absent domain already renders 500. Deriving rather than declaring per class is what keeps `error_domain` and `error_category` from contradicting each other on the wire; a leaf that declares its own domain still wins, and the provider-429 passthrough is still checked before the domain. The effect reaches the HTTP boundary through every wrapping layer: `PipelineExecutionError`'s generic `RUNTIME` was documented as a floor applied only when the cause chain surfaced no domain, and until now the cause chain surfaced none for any inference failure, so the floor fired every time. Consumers that route on the domain rather than the status see the same correction — a validate hook classifying `config` / `runtime` as a warning and everything else as a block now warns on a genuine backend or model-deck misconfiguration surfacing through dry-run inference, where before an undomained error fell through to the default block and told the agent to edit a `.mthds` file that was not at fault. On the agent CLI this makes three `AGENT_ERROR_DOMAINS` entries unreachable, since a report that carries its own domain is read before that fallback lookup: `ModelDeckPresetValidatonError` and `GatewayUnknownModelError` derive the `config` the dict already stated and are simply removed, while `ModelChoiceNotFoundError` now declares `error_domain = input` on the class itself — a mistyped model reference is the caller's to fix, on the hosted API as much as in a local file, even though its category is `CONFIGURATION` from the provider call's point of view, and an operator-side deck fault surfaces as `ModelDeckPresetValidatonError` instead. The drift test that bars a self-describing class from those dicts gained the arm that covers derivation, so the next such entry cannot go dead unnoticed. See [Error Model](under-the-hood/error-model.md).- **The shared projection corpus covers the open-shaped natives the two engine fixes unblocked**: `scaffold_bundle.mthds` gains a `scaffold_anything_slot` pipe carrying `native.Anything` and a `scaffold_dynamic_prompt` pipe putting a `native.Dynamic` slot at an LLM prompt position under both markers — the latter a bundle that did not validate at all while the prompt analyzers read a dynamic concept's universal compatibility as identity. The `Anything` slot is captured knowing the runtime refuses it: its template is the empty object every `unknown` node renders, and at an `Anything` position the input shaper accepts a bare string alone and returns it as a `native.Text` stuff, so both shapes of its pipe are declared in `EXPECTED_UNSHAPEABLE` against the item tracking the shaper fix rather than left to fail the round-trip gate. That is the gap being stated, not widened — the descriptor states `Anything` as `unknown` exactly as it states `Dynamic` and `Composite`, so a projection reading only the descriptor has nothing else to render there, and closing it deletes those entries and regenerates. It gets a pipe to itself deliberately: an `EXPECTED_UNSHAPEABLE` key is a whole template and the shaper stops at the first slot it refuses, so declaring it inside `scaffold_open_natives` would have suspended the round-trip check for the pinned and structureless natives beside it — including the only site where `unknown-empty-object` is measured. **`output_bundle.mthds` also joins the documented bundle list**, in the command block, in the CI corpus list and in the agent rules: it has been part of the committed capture since the output-form descriptor landed, but every regeneration recipe still named three bundles, so following one would have dropped its pipes from the capture. Re-committing the capture byte-identically in `mthds-js` and `mthds-python` is tracked separately, since a capture has to come from a merged `dev` and the two mirrors must land together. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **`kajson` version**: The pin moves to `kajson==0.7.1`, the release making `ClassRegistry.register_classes_dict({})` a no-op instead of raising `IndexError` — its logging branch for the single-class case indexed into an empty collection. This engine seeds a fresh per-run or per-library registry from a snapshot of the process-global one, so a snapshot that happens to be empty used to crash the seeding rather than register nothing; both seeding sites (distributed-run rehydration and the scoped-registry test fixture) are now safe unconditionally. The release changes nothing in the encoder or decoder, so the serialized wire format is untouched in both directions. Everyone downstream inherits that exact version.### Removed+- **`InferenceBackendLibrary.check_backend_credentials` and `CredentialsValidationReport`.** The method had no caller, and it read the base `backends.toml` alone — a reader that would have quietly ignored the new override files. The doctor's credentials row, which does the same job over the merged document, is the one that remains.+- **`DocumentFormat`**: the `pipelex/tools/misc/document_utils.py` module and the `DocumentFormat` enum it held are gone. Nothing in the engine ever imported them — the only reference outside the module was its own unit test — and the MIME-type and file-extension knowledge they duplicated already lives in `pipelex/tools/misc/filetype_utils.py`, which is what the runtime actually calls. (Breaking for anyone importing the symbol from outside: use `filetype_utils` instead.)### Fixeddiff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.mdindex 1dbb819f3..8411186f7 100644--- a/docs/configuration/config-technical/inference-backend-config.md+++ b/docs/configuration/config-technical/inference-backend-config.md@@ -61,7 +61,9 @@ All inference backend configurations are stored in the `.pipelex/inference/` dir.pipelex/└── inference/├── backends.toml # Backend provider configurations+ ├── backends_override.toml # Personal overrides of backends.toml (git-ignored, optional)├── routing_profiles.toml # Model routing rules+ ├── routing_profiles_override.toml # Personal overrides of routing_profiles.toml (git-ignored, optional)├── backends/ # Individual backend model specifications│ ├── openai.toml # OpenAI models (LLMs, image generation)│ ├── anthropic.toml # Anthropic models (LLMs)@@ -599,7 +601,43 @@ Note the sigil prefixes: `@` for aliases and `$` for presets.## Customization-### Local Overrides+### Personal overrides++`backends.toml` and `routing_profiles.toml` are tracked files: the project ships them, and `pipelex init` writes them. To run on a different backend without editing them — to try a backend the project keeps off, or to move every project on your machine onto one provider — write the change in a personal override file beside them:++- `backends_override.toml` layers over `backends.toml`+- `routing_profiles_override.toml` layers over `routing_profiles.toml`++An override carries only the keys it sets. Tables merge into the base's tables, so `[anthropic]` with a single `enabled = true` flips that one flag and leaves the backend's other keys alone; scalars and lists replace the base's value whole, so a `fallback_order` in an override is the whole list, not an addition to it. The merge happens before validation, which is why `active = "all_anthropic"` on its own is a complete routing override.++Both files are optional and git-ignored: `pipelex init` writes the rule into `.pipelex/.gitignore` for a fresh project (a project set up earlier adds the two names to its own `.gitignore`), the kit never ships them, and `pipelex migrate` never touches them.++Where a file lives decides its reach. The base file resolves as before — the project's copy if it has one, otherwise the global one — and the overrides merge over it in this order:++1. the base `backends.toml` / `routing_profiles.toml`+2. `~/.pipelex/inference/<file>_override.toml` — the global override, applied in every project on the machine+3. `{project}/.pipelex/inference/<file>_override.toml` — the project override, which wins++The global override reaches a project that carries its own tracked base, which is the point: one edit under `~/.pipelex/inference/` and every project follows. Deleting the override files restores the shipped default.++A developer who wants a whole machine off the gateway and on Anthropic writes two files once:++```toml+# ~/.pipelex/inference/backends_override.toml+[pipelex_gateway]+enabled = false+```++```toml+# ~/.pipelex/inference/routing_profiles_override.toml+active = "all_anthropic"+```++Enabling a backend and activating a profile that needs it go together: a profile whose default or routes name a backend that is not enabled is refused at boot, and the error names the backend to enable. `pipelex show backends` and `pipelex doctor` report the merged view, so what they print is what runs.++An override leaves a trace. When one was merged, the boot logs which files each document was read from, so a run on an unexpected backend says why in its own log. A file that does not parse is refused the way an invalid document is — as a setup error naming the file, in the boot, in `pipelex init` and in the doctor's Models row — and so is a value where a table was meant, such as `anthropic = false` where `[anthropic]` with `enabled = false` was intended. `pipelex init` keeps writing the base file, but it decides whether the gateway is enabled on the merged document, so a gateway switched on only by an override still gets the terms prompt; and when declining the terms disables the gateway in the base while an override still pins it on, the command says so and names the file to edit.++### Custom deck filesUse custom deck files (prefixed with `x_`) for project-specific customizations:@@ -643,9 +681,9 @@ To add a new backend:The system loads configurations in this order:-1. **Load Backends**: Read `backends.toml` to get enabled backends+1. **Load Backends**: Read `backends.toml`, with any `backends_override.toml` merged over it (see [Personal overrides](#personal-overrides)), to get enabled backends2. **Load Model Specs**: For each backend, load model specifications (LLMs, OCR models, image generation models)-3. **Load Routing Profiles**: Read routing rules and identify active profile+3. **Load Routing Profiles**: Read `routing_profiles.toml`, with any `routing_profiles_override.toml` merged over it, and identify the active profile4. **Build Model Deck**:- Apply routing rules to determine backend for each model across all AI capabilities- Load aliases and presets from deck files for LLMs, OCR, and image generationdiff --git a/docs/configuration/index.md b/docs/configuration/index.mdindex 295607369..3075c9603 100644--- a/docs/configuration/index.md+++ b/docs/configuration/index.md@@ -79,6 +79,7 @@ Notes on the override sequence:- `pipelex_{environment}.toml` (example: `pipelex_dev.toml`) is selected by the `PIPELEX_ENV` environment variable (see [Selecting the environment](#selecting-the-environment))- `pipelex_{run_mode}.toml` — example run modes: normal, unit_test; under unit testing the run-mode overlay is sourced exclusively from `./tests/pipelex_{run_mode}.toml`- Each subsequent configuration file in this sequence can override settings from the previous ones, and project-level files override the global `~/.pipelex/` layer+- The two inference documents, `inference/backends.toml` and `inference/routing_profiles.toml`, are not part of this merge. Each has a single personal override file beside it, `backends_override.toml` and `routing_profiles_override.toml`, merged over the resolved base — global tier first, then project tier. See [Personal overrides](config-technical/inference-backend-config.md#personal-overrides)### Override File Namingdiff --git a/docs/contribute/configuration-defaults-and-overrides.md b/docs/contribute/configuration-defaults-and-overrides.mdindex 05e785fa0..71fc23042 100644--- a/docs/contribute/configuration-defaults-and-overrides.md+++ b/docs/contribute/configuration-defaults-and-overrides.md@@ -45,6 +45,16 @@ Load order:!!! note "Unit-test special case"When `runtime_manager.is_unit_testing` is true, the `pipelex_{run_mode}.toml` entry is sourced exclusively from `./tests/pipelex_{run_mode}.toml` (e.g. `tests/pipelex_unit_test.toml`). Global and project run_mode files are not loaded, keeping test runs hermetic from machine-wide overrides.+### The inference documents++`.pipelex/inference/backends.toml` and `.pipelex/inference/routing_profiles.toml` are not part of the `pipelex.toml` merge. Each is its own document with a shorter sequence, built by `ConfigLoader.backends_file_paths()` / `routing_profiles_file_paths()` and read by `load_toml_from_base_and_overrides`:++1. **The base** — the project's file if the project `.pipelex/inference/` has one, otherwise the global one. One file, winner takes all; a personal override cannot stand in for it.+2. **Global override** — `~/.pipelex/inference/backends_override.toml` (respectively `routing_profiles_override.toml`), if present.+3. **Project override** — the same file under the project's `.pipelex/inference/`, if present and distinct from the global one.++The order differs from `pipelex.toml`'s on purpose: there the project base beats the global override, here the global override beats the project base. A global inference override exists so one machine-wide choice ("run on this backend") reaches every project, and every project carries a tracked `backends.toml`, so a project base that won would defeat the file. The project override still wins over the global one. With an explicit `config_dir` (the doctor's `--global`, an init targeting one directory), the sequence is that directory's base and its own override, nothing layered.+## Where to change things in code- **Config merge logic**: `pipelex/system/configuration/config_loader.py`diff --git a/docs/features/configuration.md b/docs/features/configuration.mdindex 7d0754158..529cef2d6 100644--- a/docs/features/configuration.md+++ b/docs/features/configuration.md@@ -27,6 +27,8 @@ Within each tier, the base `pipelex.toml` is followed by an override sequence, mThe entire global tier merges before the project tier, so any project-tier file — including the plain project `pipelex.toml` — overrides every global-tier file.+The two inference documents, `.pipelex/inference/backends.toml` and `.pipelex/inference/routing_profiles.toml`, have an override layer of their own: a `backends_override.toml` and a `routing_profiles_override.toml` beside them, git-ignored, each carrying only the keys it sets. The base file resolves as before (the project's copy if it has one, otherwise the global one) and the overrides merge over it, global tier first, then project tier — so one `~/.pipelex/inference/` override reaches every project on the machine, and deleting it restores the shipped default. See [Inference Backend Configuration](../configuration/config-technical/inference-backend-config.md#personal-overrides) for the files and the merge order.+## Environment VariablesTwo configuration areas support `${...}` variable substitution in their TOML files: the inference backend configuration (`.pipelex/inference/backends.toml` and the per-backend TOML files under `.pipelex/inference/backends/`) and the telemetry configuration (`.pipelex/telemetry.toml`). In those files, use `${env:VAR}` for environment variables, `${secret:VAR}` for the secrets provider, and fallback chains like `${env:VAR|secret:VAR}`. The `pipelex.toml` layering described above does not perform substitution — a `${env:VAR}` there stays a literal string.diff --git a/docs/get-started/configure-ai-providers.md b/docs/get-started/configure-ai-providers.mdindex 542fe4da4..5285ad248 100644--- a/docs/get-started/configure-ai-providers.md+++ b/docs/get-started/configure-ai-providers.md@@ -94,7 +94,7 @@ When using your own keys, enable the corresponding backends:pipelex init```-2. Edit `~/.pipelex/inference/backends.toml` (or `.pipelex/inference/backends.toml` in your project root if you have a project-local config — the project file fully overrides the global one):+2. Edit `~/.pipelex/inference/backends.toml` (or `.pipelex/inference/backends.toml` in your project root if you have a project-local config — the project file fully overrides the global one). To run on a backend of your own choosing without touching a tracked file, write the same keys in a git-ignored `backends_override.toml` beside it instead: see [Personal overrides](../configuration/config-technical/inference-backend-config.md#personal-overrides).```toml[google]diff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex c8b1f9746..bedcc8b6d 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -673,7 +673,7 @@ Always back up, before writing. Exactly one backup per file — a successful runThe name is the source file's whole name, extension included, followed by `.bak.` and a compact UTC stamp: `pipelex.toml` backs up to `pipelex.toml.bak.20260815T120000Z`. Extension-included so a backup never shadows a real `.toml`, and separator-free so no filesystem objects to it. Pruning matches that whole shape, stamp included — a copy the user made by hand under a name that merely starts the same way (`pipelex.toml.bak.notes`) is theirs, and is never touched.-**A backup does not belong in the user's `git status`, and pipelex writes the rule that keeps it out.** A project's `.pipelex/` is normally inside a git repository, so one run would otherwise put a dozen untracked `.bak.<stamp>` files in front of the user and leave them to work out which are ours. Pipelex therefore keeps a `.gitignore` *inside* the configuration directory, carrying one rule — `*.bak.` followed by the exact stamp shape, spelled out digit class by digit class, built from the same infix the namer uses so renaming it cannot leave a rule that matches nothing. The stamp is spelled out in full rather than abbreviated to a `[0-9]*` run, because a run would also swallow a copy the user named themselves along the lines of `pipelex.toml.bak.1-notesZ` — one pruning explicitly refuses to touch, and hiding a file we decline to manage is the worse half of both answers. In-directory rather than in the repository root because the walk is `~/.pipelex/` and the project `.pipelex/` and nothing else, so a local file needs no idea where the root is and never edits a file the user maintains for their whole project.+**A backup does not belong in the user's `git status`, and pipelex writes the rule that keeps it out.** A project's `.pipelex/` is normally inside a git repository, so one run would otherwise put a dozen untracked `.bak.<stamp>` files in front of the user and leave them to work out which are ours. Pipelex therefore keeps a `.gitignore` *inside* the configuration directory, carrying one line per personal override file — `pipelex_override.toml` and its siblings, `inference/backends_override.toml` and `inference/routing_profiles_override.toml`, files that hold only a developer's own choices and have no business in a project's commits either — and the backup rule — `*.bak.` followed by the exact stamp shape, spelled out digit class by digit class, built from the same infix the namer uses so renaming it cannot leave a rule that matches nothing. The stamp is spelled out in full rather than abbreviated to a `[0-9]*` run, because a run would also swallow a copy the user named themselves along the lines of `pipelex.toml.bak.1-notesZ` — one pruning explicitly refuses to touch, and hiding a file we decline to manage is the worse half of both answers. In-directory rather than in the repository root because the walk is `~/.pipelex/` and the project `.pipelex/` and nothing else, so a local file needs no idea where the root is and never edits a file the user maintains for their whole project.One backup is deliberately out of reach of this rule. A configuration file that is a symlink is migrated through to the file it names, so its backup lands beside *that* file — in a dotfiles directory, which is the user's and not ours. Pipelex does not follow it there: writing into the `.gitignore` of somebody's whole dotfiles repository is a larger liberty than the single untracked copy it would hide.diff --git a/docs/tools/cli/show.md b/docs/tools/cli/show.mdindex b0440eff8..6799e5fa6 100644--- a/docs/tools/cli/show.md+++ b/docs/tools/cli/show.md@@ -126,6 +126,6 @@ pipelex show backends --all## Related Configuration- [Inference Backend Configuration](../../configuration/config-technical/inference-backend-config.md)-- Backend configuration files: `.pipelex/inference/backends.toml`-- Routing configuration: `.pipelex/inference/routing_profiles.toml`+- Backend configuration files: `.pipelex/inference/backends.toml`, with a personal `backends_override.toml` merged over it when present+- Routing configuration: `.pipelex/inference/routing_profiles.toml`, with a personal `routing_profiles_override.toml` merged over it when presentdiff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.mdindex 5e4f15675..083a1c5f6 100644--- a/docs/under-the-hood/init-cli-flows.md+++ b/docs/under-the-hood/init-cli-flows.md@@ -190,7 +190,7 @@ This handles two scenarios:| `not backends_existed_before` | First-time setup (no inference yet) | Force inference step regardless of focus || `check_inference and backends_exists_now` | Inference in focus + existing config | Re-run inference (reset) |-When inference is **not** forced and backends already exist, gateway terms are still checked:+When inference is **not** forced and backends already exist, gateway terms are still checked. "Enabled" is read off the merged backends document pinned to the target directory (`is_pipelex_gateway_enabled(config_dir=…)`), so a gateway switched on only by that directory's `backends_override.toml` is prompted for terms too; declining writes `enabled = false` into the base, and `warn_if_gateway_pinned_by_override` says so when an override still keeps it on:```pythonif not needs_inference and backends_existed_before:@@ -270,7 +270,7 @@ Copies a telemetry template and prints instructions. No interactive prompts. Whi| Constant | Contents | Reason ||----------|----------|--------|-| `INIT_SKIP_FILES` | All `GIT_IGNORED_CONFIG_FILES` (`pipelex_service.toml`, `pipelex_override.toml`, `telemetry_override.toml`, `telemetry.project.toml`, `pipelex_gateway_models.md`, `pipelex_gateway_models_plain.md`, `x_custom_llm_deck.toml`, `x_custom_extract_deck.toml`) plus `telemetry.toml` and `.DS_Store` | Git-ignored, auto-generated, or managed by other steps |+| `INIT_SKIP_FILES` | Every name in `GIT_IGNORED_CONFIG_FILES` (`pipelex/kit/paths.py` is the list: the personal overrides, the service file, the generated gateway model pages, the custom deck files) plus `telemetry.toml` and `.DS_Store` | Git-ignored, auto-generated, or managed by other steps || `INIT_SKIP_DIRS` | `inference` | Managed independently by inference step |### Source Modules@@ -451,8 +451,8 @@ flowchart TD|-------|-------------------|---------|| `check_config_files()` | `resolve_config_file()` | Layered resolution (project > global) || `check_telemetry_config()` | `resolve_config_file()` | Layered resolution (project > global) |-| `check_backend_credentials()` | `resolve_config_file()` | Finds `backends.toml` wherever it lives |-| `check_backend_files()` | `resolve_config_file()` | Finds `inference/backends/` wherever it lives |+| `check_backend_credentials()` | `backends_file_paths()` | Reads the merged backends document: the base `backends.toml` wherever it lives, plus the personal `backends_override.toml` at each tier |+| `check_backend_files()` | `resolve_config_file()` for `inference/backends/`, `backends_file_paths()` for the enabled-backend list | Finds `inference/backends/` wherever it lives, and reads the merged backends document to decide which backends to probe || `check_models()` gateway terms | `global_config_dir` | **Always global** — reads from `~/.pipelex/` || `check_pending_migrations()` | none | **Both directories, always** — see below |diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex 69b83439f..73ac79646 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -33,10 +33,11 @@ from pipelex.cogt.exceptions import (ModelDeckNotFoundError,ModelDeckValidationError,RoutingProfileDisabledBackendError,+ RoutingProfileLibraryError,RoutingProfileLibraryNotFoundError,)-from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsErrorMsgFactory-from pipelex.cogt.model_backends.backend_library import BackendCredentialsReport, InferenceBackendLibrary+from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsErrorMsgFactory, BackendCredentialsReport+from pipelex.cogt.model_backends.backend_library import InferenceBackendLibraryfrom pipelex.cogt.model_backends.gateway_config import GatewayConfigfrom pipelex.cogt.models.deck_manifest import DeckFileStatus, DeckSyncReport, compute_deck_sync_report, status_rich_labelfrom pipelex.cogt.models.model_manager import ModelManager@@ -65,7 +66,7 @@ from pipelex.tools.misc.dict_utils import extract_vars_from_strings_recursivefrom pipelex.tools.misc.exceptions import TomlErrorfrom pipelex.tools.misc.json_utils import deep_updatefrom pipelex.tools.misc.placeholder import value_is_placeholder-from pipelex.tools.misc.toml_utils import load_toml_from_path+from pipelex.tools.misc.toml_utils import load_toml_from_base_and_overrides, load_toml_from_pathfrom pipelex.tools.secrets.env_secrets_provider import EnvSecretsProviderif TYPE_CHECKING:@@ -404,13 +405,13 @@ def check_backend_credentials(*, config_dir: Path | None = None) -> tuple[bool,Returns:Tuple of (is_healthy, backend_reports_dict, summary_message)"""- backends_toml_path = config_manager.resolve_config_file("inference/backends.toml", config_dir=config_dir)+ backends_file_paths = config_manager.backends_file_paths(config_dir=config_dir)- if not backends_toml_path.exists():+ if not backends_file_paths[0].exists():return False, {}, "Backend configuration file not found"try:- backends_dict = load_toml_from_path(backends_toml_path)+ backends_dict = load_toml_from_base_and_overrides(paths=backends_file_paths)backend_reports: dict[str, BackendCredentialsReport] = {}all_backends_valid = True@@ -563,13 +564,13 @@ def check_backend_files(*, config_dir: Path | None = None) -> tuple[bool, dict[sif not backends_dir_path.exists():return True, {}, "No backend files to check"- # Get list of enabled backends from backends.toml- backends_toml_path = config_manager.resolve_config_file("inference/backends.toml", config_dir=config_dir)- if not backends_toml_path.exists():+ # Get list of enabled backends from the backends document (base plus the personal overrides)+ backends_file_paths = config_manager.backends_file_paths(config_dir=config_dir)+ if not backends_file_paths[0].exists():return True, {}, "No backends.toml to check"try:- backends_dict = load_toml_from_path(backends_toml_path)+ backends_dict = load_toml_from_base_and_overrides(paths=backends_file_paths)except (TomlError, OSError) as exc:return False, {}, f"Error loading backends.toml: {exc}"@@ -616,7 +617,7 @@ def check_backend_files(*, config_dir: Path | None = None) -> tuple[bool, dict[s# in lenient mode, which is what this probe exists to catch.temp_library.load(secrets_provider=secrets_provider,- backends_library_path=str(backends_toml_path),+ backends_library_paths=backends_file_paths,backends_dir_path=str(backends_dir_path),include_disabled=False,lenient=True,@@ -1091,16 +1092,19 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strreturn False, msg, backend_file_reports# Fetch gateway model specs if Gateway is enabled.- # Probe the same backends.toml / pipelex_service.toml the doctor is reporting on+ # Probe the same backends document / pipelex_service.toml the doctor is reporting on# (project-vs-global) instead of always defaulting to the global path — otherwise# --global on a machine with a project-local backends.toml would mis-report gateway- # state because the layered `config_manager.backends_file_path` would still resolve- # to the project file.- backends_file_path = config_dir / "inference" / "backends.toml" if config_dir is not None else None+ # state because the layered `config_manager.backends_file_paths()` would still resolve+ # its base to the project file.service_config_dir = config_dir if config_dir is not None else config_manager.global_config_dirgateway_config: GatewayConfig | None = Nonegateway_config_source: RemoteConfigSource | None = None- if is_pipelex_gateway_enabled(backends_file_path=backends_file_path):+ try:+ gateway_enabled = is_pipelex_gateway_enabled(config_dir=config_dir)+ except InferenceBackendLibraryValidationError as exc:+ return False, f"Error checking models: {exc}", backend_file_reports+ if gateway_enabled:pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=service_config_dir)if pipelex_service_config is None:return False, "Pipelex Gateway is enabled but service configuration is missing", backend_file_reports@@ -1118,10 +1122,11 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strreturn False, f"Failed to fetch Pipelex Gateway remote configuration: {exc}", backend_file_reports# When --global (config_dir set), pin every path so layered config_manager.X- # resolution doesn't silently fall back to the project-local files.- backends_library_override = str(config_dir / "inference" / "backends.toml") if config_dir is not None else None+ # resolution doesn't silently fall back to the project-local files. The two documents+ # are pinned as sequences: that directory's base file and its own override.+ backends_library_override = config_manager.backends_file_paths(config_dir=config_dir) if config_dir is not None else Nonebackends_dir_override = str(config_dir / "inference" / "backends") if config_dir is not None else None- routing_profile_override = str(config_dir / "inference" / "routing_profiles.toml") if config_dir is not None else None+ routing_profile_override = config_manager.routing_profiles_file_paths(config_dir=config_dir) if config_dir is not None else Nonedeck_dir_override = str(config_dir / "inference" / "deck") if config_dir is not None else Nonemodels_manager = ModelManager()@@ -1131,9 +1136,9 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strsecrets_provider=secrets_provider,gateway_config=gateway_config,gateway_config_source=gateway_config_source,- backends_library_path=backends_library_override,+ backends_library_paths=backends_library_override,backends_dir_path=backends_dir_override,- routing_profile_library_path=routing_profile_override,+ routing_profile_library_paths=routing_profile_override,deck_dir_path=deck_dir_override,)models_manager.validate_model_deck()@@ -1152,6 +1157,7 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strInferenceBackendLibraryNotFoundError,ModelDeckNotFoundError,RoutingProfileDisabledBackendError,+ RoutingProfileLibraryError, # an invalid document, or an `active` naming no profile: the likeliest override typoInferenceBackendLibraryValidationError,ModelDeckValidationError,InferenceBackendCredentialsError,diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.pyindex 24d61a06f..c22b74b29 100644--- a/pipelex/cli/commands/init/backends.py+++ b/pipelex/cli/commands/init/backends.py@@ -1,8 +1,14 @@-"""Backend configuration logic for the init command."""+"""Backend configuration logic for the init command.++Everything here reads and writes the base `backends.toml` — never a `backends_override.toml`. The+checkboxes must pre-fill from the file they will write, or a personal override would be copied into+the tracked file on save; the merged view is the runtime's and the doctor's, not the editor's.+"""from pathlib import Pathfrom typing import Any+from rich.console import Consolefrom rich.markup import escapefrom tomlkit.exceptions import TOMLKitError@@ -25,7 +31,8 @@ from pipelex.kit.paths import get_kit_configs_dirfrom pipelex.runtime_hub import get_consolefrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.pipelex_service.pipelex_service_agreement import update_service_terms_acceptance-from pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_with_tomlkit, save_toml_to_path+from pipelex.system.pipelex_service.pipelex_service_config import is_pipelex_gateway_enabled+from pipelex.tools.misc.toml_utils import describe_toml_base_and_overrides, load_toml_from_path, load_toml_with_tomlkit, save_toml_to_pathdef update_backends_in_toml(toml_doc: Any, *, selected_indices: list[int], backend_options: list[tuple[str, str]]) -> None:@@ -73,6 +80,33 @@ def get_selected_backend_keys(backends_toml_path: Path) -> list[str]:return selected_backends+def warn_if_gateway_pinned_by_override(*, console: Console, backends_toml_path: Path) -> bool:+ """After a disabling write to the base: say so when an override still enables the gateway.++ Every writer here edits the base ``backends.toml``, while the runtime reads that file with the+ personal ``backends_override.toml`` files merged over it. Disabling the gateway in the base after+ the terms were declined is therefore a no-op when an override pins ``enabled = true``, and the+ next boot refuses for the declined terms with nothing to say about why the flip did not take.+ This names the files that were read so the user edits the right one.++ Args:+ console: Where the warning goes.+ backends_toml_path: The base file that was just written, ``<config dir>/inference/backends.toml``.++ Returns:+ True when the gateway is still enabled by the merged document, False otherwise.+ """+ config_dir = backends_toml_path.parent.parent+ if not is_pipelex_gateway_enabled(config_dir=config_dir):+ return False+ description = describe_toml_base_and_overrides(paths=config_manager.backends_file_paths(config_dir=config_dir))+ console.print(+ f"[yellow]⚠ Pipelex Gateway is still enabled by a personal override: {escape(description)}. "+ "Disable it there too, or the next boot will refuse because the terms were declined.[/yellow]"+ )+ return True++def disable_gateway_backend(backends_toml_path: Path) -> None:"""Disable the pipelex_gateway backend in backends.toml.@@ -176,6 +210,7 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confitry:disable_gateway_backend(backends_toml_path)console.print("[yellow]⚠ Could not save gateway terms. Gateway has been disabled to prevent errors.[/yellow]")+ warn_if_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path)except (OSError, TOMLKitError, TypeError) as disable_exc:log.warning(f"Could not disable gateway backend: {disable_exc}")console.print(diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.pyindex 1bc09139f..2aafd4493 100644--- a/pipelex/cli/commands/init/command.py+++ b/pipelex/cli/commands/init/command.py@@ -13,6 +13,7 @@ from pipelex.cli.commands.init.backends import (customize_backends_config,disable_gateway_backend,get_selected_backend_keys,+ warn_if_gateway_pinned_by_override,)from pipelex.cli.commands.init.config_files import init_configfrom pipelex.cli.commands.init.credentials import prompt_credentials@@ -26,11 +27,10 @@ from pipelex.cli.commands.init.ui.gateway_ui import ()from pipelex.cli.commands.init.ui.general_ui import build_initialization_panelfrom pipelex.cli.commands.init.ui.types import InitFocus-from pipelex.cogt.model_backends.backend import PipelexBackendfrom pipelex.cogt.models.deck_manifest import compute_kit_manifest, write_manifestfrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.runtime_hub import get_console-from pipelex.system.configuration.config_loader import BACKENDS_FILE_NAME, INFERENCE_DIR_NAME, config_manager+from pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableErrorfrom pipelex.system.pipelex_service.pipelex_service_agreement import update_service_terms_acceptancefrom pipelex.system.pipelex_service.pipelex_service_config import (@@ -80,18 +80,14 @@ def attempt_prime_remote_config_cache(*, target_config_dir: Path | None = None)priming step.Args:- target_config_dir: When set, read the ``backends.toml`` *at that directory* to decide- whether the gateway is enabled. ``pipelex init`` and ``pipelex init --local``- target different ``.pipelex/`` directories — using the layered/project-preferred- config here would let priming branch on the wrong file. ``None`` (default) falls- back to the layered path. The terms-acceptance check always reads the *global*- ``pipelex_service.toml`` by design.+ target_config_dir: When set, read the backends document *at that directory* (its+ ``backends.toml`` and its own ``backends_override.toml``) to decide whether the gateway+ is enabled. ``pipelex init`` and ``pipelex init --local`` target different ``.pipelex/``+ directories — using the layered/project-preferred config here would let priming branch+ on the wrong file. ``None`` (default) falls back to the layered document. The+ terms-acceptance check always reads the *global* ``pipelex_service.toml`` by design."""- if target_config_dir is not None:- backends_file_path = target_config_dir / INFERENCE_DIR_NAME / BACKENDS_FILE_NAME- else:- backends_file_path = None- if not is_pipelex_gateway_enabled(backends_file_path=backends_file_path):+ if not is_pipelex_gateway_enabled(config_dir=target_config_dir):return CachePrimingResult(primed=False)service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)@@ -152,12 +148,13 @@ def _check_gateway_terms_if_needed(*, console: Console, backends_toml_path: Pathconsole: Rich Console instance for user interaction.backends_toml_path: Path to backends.toml file."""- # Check if backends.toml exists and gateway is enabled+ # Check if backends.toml exists and gateway is enabled. Enabled means enabled in the merged+ # document pinned to this directory — a gateway switched on only by that directory's+ # `backends_override.toml` needs the terms as much as one switched on in the base.if not backends_toml_path.exists():return- selected_backend_keys = get_selected_backend_keys(backends_toml_path)- if PipelexBackend.GATEWAY not in selected_backend_keys:+ if not is_pipelex_gateway_enabled(config_dir=backends_toml_path.parent.parent):return# Gateway is enabled - check if terms are already accepted (always global)@@ -175,8 +172,9 @@ def _check_gateway_terms_if_needed(*, console: Console, backends_toml_path: Pathelse:display_gateway_declined_message(console=console)update_service_terms_acceptance(accepted=False, config_dir=config_manager.global_config_dir)- # Actually disable the gateway in backends.toml+ # Actually disable the gateway in backends.toml — and say so if an override still pins it ondisable_gateway_backend(backends_toml_path)+ warn_if_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path)def determine_needs(@@ -471,6 +469,7 @@ def _init_agreement(*, console: Console) -> None:backends_toml_path = config_manager.pipelex_config_dir / "inference" / "backends.toml"if backends_toml_path.exists():disable_gateway_backend(backends_toml_path)+ warn_if_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path)console.print()diff --git a/pipelex/cli/commands/show_cmd.py b/pipelex/cli/commands/show_cmd.pyindex 7974d9140..9492c9af9 100644--- a/pipelex/cli/commands/show_cmd.py+++ b/pipelex/cli/commands/show_cmd.py@@ -72,7 +72,7 @@ def do_show_backends(*, show_all: bool = False) -> None:backend_library = InferenceBackendLibrary()backend_library.load(secrets_provider=secrets_provider,- backends_library_path=str(config_manager.backends_file_path),+ backends_library_paths=config_manager.backends_file_paths(),backends_dir_path=str(config_manager.backends_dir_path),include_disabled=True,lenient=True,diff --git a/pipelex/cogt/model_backends/backend_credentials.py b/pipelex/cogt/model_backends/backend_credentials.pyindex edd0aeb5f..a5cf35436 100644--- a/pipelex/cogt/model_backends/backend_credentials.py+++ b/pipelex/cogt/model_backends/backend_credentials.py@@ -14,13 +14,6 @@ class BackendCredentialsReport(ConfigModel):all_credentials_valid: bool-class CredentialsValidationReport(ConfigModel):- """Complete report of credentials validation across all backends."""-- backend_reports: dict[str, BackendCredentialsReport]- all_backends_valid: bool--class BackendCredentialsErrorMsgFactory:@classmethoddef make_one_variable_missing_error_msg(diff --git a/pipelex/cogt/model_backends/backend_library.py b/pipelex/cogt/model_backends/backend_library.pyindex 249bfb290..acce4b348 100644--- a/pipelex/cogt/model_backends/backend_library.py+++ b/pipelex/cogt/model_backends/backend_library.py@@ -1,3 +1,4 @@+from collections.abc import Sequencefrom functools import partialfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, NamedTuple, Self, cast@@ -14,7 +15,6 @@ from pipelex.cogt.exceptions import (InferenceModelSpecError,)from pipelex.cogt.model_backends.backend import InferenceBackend, PipelexBackend-from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsReport, CredentialsValidationReportfrom pipelex.cogt.model_backends.backend_factory import (InferenceBackendBlueprint,InferenceBackendFactory,@@ -34,15 +34,19 @@ from pipelex.system.configuration.config_surface import (replay_surface_files_in_memory,stale_configuration_warning,)-from pipelex.system.environment import get_optional_envfrom pipelex.system.pipelex_service.gateway_config_merger import GatewayConfigMergerfrom pipelex.system.runtime import runtime_managerfrom pipelex.tools.misc.dict_utils import (apply_to_strings_recursive,- extract_vars_from_strings_recursive,)-from pipelex.tools.misc.placeholder import value_is_placeholder-from pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_from_path_if_exists+from pipelex.tools.misc.exceptions import TomlError+from pipelex.tools.misc.toml_utils import (+ describe_toml_base_and_overrides,+ load_toml_from_base_and_overrides,+ load_toml_from_path,+ load_toml_from_path_if_exists,+ present_toml_override_paths,+)from pipelex.tools.secrets.exceptions import UnknownVarPrefixError, VarFallbackPatternError, VarNotFoundErrorfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstractfrom pipelex.tools.secrets.secrets_utils import substitute_vars@@ -103,7 +107,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):self,*,secrets_provider: SecretsProviderAbstract,- backends_library_path: str,+ backends_library_paths: Sequence[Path],backends_dir_path: str,include_disabled: bool = False,gateway_config: GatewayConfig | None = None,@@ -125,9 +129,14 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):would repair: `backends_dir_path` picks one directory (a project's `.pipelex/` wins the wholedirectory over the global one), while `pipelex migrate` walks every configuration root.+ The index itself is one document read from several files: the base `backends.toml` first,+ then each `backends_override.toml` that exists, deep-merged in order so a personal file+ carrying only `[<backend>] enabled = true` flips that one flag and leaves the table's other+ keys to the base. `config_manager.backends_file_paths()` is the sequence every reader passes.+Args:secrets_provider: Provider for secrets/credentials.- backends_library_path: Path to backends.toml.+ backends_library_paths: The base `backends.toml` first, then the override files in merge order.backends_dir_path: Path to directory containing per-backend TOML files.include_disabled: Whether to include disabled backends.gateway_config: Gateway configuration for Pipelex Gateway backend.@@ -142,11 +151,20 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):is carried forward in both modes, or fatal in both, according to the ledger alone."""stale_plans: list[MigrationPlan] = []+ library_paths_description = describe_toml_base_and_overrides(paths=backends_library_paths)try:- backends_dict = load_toml_from_path(path=backends_library_path)+ backends_dict = load_toml_from_base_and_overrides(paths=backends_library_paths)except FileNotFoundError as file_not_found_exc:- msg = f"Could not find inference backend library at '{backends_library_path}': {file_not_found_exc}"+ msg = f"Could not find inference backend library at '{backends_library_paths[0]}': {file_not_found_exc}"raise InferenceBackendLibraryNotFoundError(msg) from file_not_found_exc+ except TomlError as toml_exc:+ # A hand-edited override with a stray quote is a document the library cannot load, and+ # the boot's own clause for that names the file; a raw parse error would not reach it.+ msg = f"Invalid inference backend library {library_paths_description}: {toml_exc}"+ raise InferenceBackendLibraryValidationError(msg) from toml_exc+ if present_toml_override_paths(paths=backends_library_paths):+ # The one trace a machine-wide override leaves: which files this boot actually merged.+ log.info(f"Inference backends read from {library_paths_description}")# Create a partial function with the secrets provider boundsubstitute_vars_with_provider = partial(substitute_vars, secrets_provider=secrets_provider)@@ -154,8 +172,19 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):# We'll split the read settings into standard fields and extra configbackend_blueprint_standard_fields = InferenceBackendBlueprint.model_fields.keys()for backend_name, backend_dict in backends_dict.items():+ if not isinstance(backend_dict, dict):+ # The likeliest half-written override: `acme = false` where `[acme] enabled = false`+ # was meant. `deep_update` replaces a table by a scalar whole, so this is the first+ # place that can name the file rather than crash on `.copy()`. Fatal in both modes:+ # leniency is for what this machine cannot load, not for a document that is wrong.+ msg = (+ f"Invalid inference backend '{backend_name}' in {library_paths_description}: "+ f"expected a table, got {type(backend_dict).__name__} ({backend_dict!r})"+ )+ raise InferenceBackendLibraryValidationError(msg, backend_name=backend_name)+ backend_table = cast("dict[str, Any]", backend_dict)extra_config: dict[str, Any] = {}- inference_backend_blueprint_dict_raw = backend_dict.copy()+ inference_backend_blueprint_dict_raw = backend_table.copy()enabled = inference_backend_blueprint_dict_raw.get("enabled", True)if not enabled and not include_disabled:continue@@ -169,7 +198,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):if lenient:log.verbose(f"Skipping backend '{backend_name}': variable fallback pattern error")continue- msg = f"Variable substitution failed due to a pattern error in file '{backends_library_path}':\n{var_fallback_pattern_exc}"+ msg = f"Variable substitution failed due to a pattern error in {library_paths_description}:\n{var_fallback_pattern_exc}"key_name = "unknown"raise InferenceBackendCredentialsError(credentials_error_type=InferenceBackendCredentialsErrorType.VAR_FALLBACK_PATTERN,@@ -182,7 +211,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):log.verbose(f"Skipping backend '{backend_name}': missing credential variable '{var_not_found_exc.var_name}'")continuemsg = (- f"Variable substitution failed due to a 'variable not found' error in file '{backends_library_path}':\n"+ f"Variable substitution failed due to a 'variable not found' error in {library_paths_description}:\n"f"Backend name: '{backend_name}', Variable name: '{var_not_found_exc.var_name}'\n"f"{var_not_found_exc}\nRun mode: '{runtime_manager.run_mode}'")@@ -201,13 +230,13 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):backend_name=backend_name,message=(f"Variable substitution failed due to an unknown variable prefix error "- f"in file '{backends_library_path}':\n{unknown_var_prefix_exc}"+ f"in {library_paths_description}:\n{unknown_var_prefix_exc}"),key_name=unknown_var_prefix_exc.var_name,) from unknown_var_prefix_exctry:- for backend_blueprint_key in backend_dict:+ for backend_blueprint_key in backend_table:if backend_blueprint_key not in backend_blueprint_standard_fields:extra_config[backend_blueprint_key] = inference_backend_blueprint_dict.pop(backend_blueprint_key)try:@@ -217,7 +246,7 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):# analysis: pydantic's error alone names a field, and every table of this file has# that field.validation_error_msg = format_pydantic_validation_error(validation_error)- msg = f"Invalid inference backend '{backend_name}' in '{backends_library_path}': {validation_error_msg}"+ msg = f"Invalid inference backend '{backend_name}' in {library_paths_description}: {validation_error_msg}"raise InferenceBackendLibraryValidationError(msg, backend_name=backend_name) from validation_error# Handle pipelex_gateway specially - use remote config@@ -229,11 +258,12 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):log.verbose(f"Skipping backend '{backend_name}': gateway model specs not available")continue# A caller's omission rather than a user's: the boot fetches the gateway's- # specs whenever `is_pipelex_gateway_enabled` reads this same file as enabled,- # and that reader and this loop agree on what "enabled" means. Reachable only- # by loading the library directly without a gateway config.+ # specs whenever `is_pipelex_gateway_enabled` reads this same document (base+ # plus overrides) as enabled, and that reader and this loop agree on what+ # "enabled" means. Reachable only by loading the library directly without a+ # gateway config.msg = (- f"Backend '{backend_name}' is enabled in '{backends_library_path}' but no Pipelex Gateway model specs "+ f"Backend '{backend_name}' is enabled in {library_paths_description} but no Pipelex Gateway model specs ""were given to the loader: pass `gateway_config`, or disable the backend")raise InferenceBackendLibraryError(msg, backend_name=backend_name)@@ -540,78 +570,6 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):key_name=unknown_var_prefix_exc.var_name,) from unknown_var_prefix_exc- 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- without performing actual substitution or loading model specs.-- Args:- path: Path to the backend library TOML file- include_disabled: If True, check disabled backends too-- Returns:- CredentialsValidationReport with detailed status per backend-- """- try:- backends_dict = load_toml_from_path(path=path)- except FileNotFoundError as file_not_found_exc:- msg = f"Could not find inference backend library at '{path}': {file_not_found_exc}"- raise InferenceBackendLibraryNotFoundError(msg) from file_not_found_exc-- backend_reports: dict[str, BackendCredentialsReport] = {}- all_backends_valid = True-- for backend_name, backend_dict in backends_dict.items():- enabled = backend_dict.get("enabled", True)- if not enabled and not include_disabled:- continue-- # Skip internal backend- if backend_name == "internal":- continue-- # Skip vertexai in CI testing- if runtime_manager.is_ci_testing and backend_name == "vertexai":- continue-- # Extract all variable placeholders from the backend config- required_vars_set = extract_vars_from_strings_recursive(backend_dict)- required_vars = sorted(required_vars_set)-- # Check status of each variable- missing_vars: list[str] = []- placeholder_vars: list[str] = []-- for var_name in required_vars:- var_value = get_optional_env(var_name)- if var_value is None:- missing_vars.append(var_name)- elif value_is_placeholder(var_value):- placeholder_vars.append(var_name)-- # Determine if all credentials are valid for this backend- backend_valid = len(missing_vars) == 0 and len(placeholder_vars) == 0-- # Create report for this backend- backend_report = BackendCredentialsReport(- backend_name=backend_name,- required_vars=required_vars,- missing_vars=missing_vars,- placeholder_vars=placeholder_vars,- all_credentials_valid=backend_valid,- )- backend_reports[backend_name] = backend_report-- if not backend_valid:- all_backends_valid = False-- return CredentialsValidationReport(- backend_reports=backend_reports,- all_backends_valid=all_backends_valid,- )-def list_backend_names(self) -> list[str]:return list(self.root.keys())diff --git a/pipelex/cogt/model_routing/routing_profile_loader.py b/pipelex/cogt/model_routing/routing_profile_loader.pyindex edb1c4a24..58fa9cc46 100644--- a/pipelex/cogt/model_routing/routing_profile_loader.py+++ b/pipelex/cogt/model_routing/routing_profile_loader.py@@ -1,48 +1,72 @@+from collections.abc import Sequence+from pathlib import Path+from pydantic import ValidationErrorfrom pipelex import log-from pipelex.cogt.exceptions import ModelManagerError, RoutingProfileLibraryError+from pipelex.cogt.exceptions import RoutingProfileDisabledBackendError, RoutingProfileLibraryError, RoutingProfileLibraryNotFoundErrorfrom pipelex.cogt.model_routing.routing_profile import RoutingProfilefrom pipelex.cogt.model_routing.routing_profile_factory import RoutingProfileFactory, RoutingProfileLibraryBlueprint-from pipelex.tools.misc.toml_utils import load_toml_from_path+from pipelex.tools.misc.exceptions import TomlError+from pipelex.tools.misc.toml_utils import describe_toml_base_and_overrides, load_toml_from_base_and_overrides, present_toml_override_pathsfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_errordef load_active_routing_profile(- routing_profile_library_path: str,*,+ routing_profile_library_paths: Sequence[Path],enabled_backends: list[str],lenient: bool = False,) -> RoutingProfile:- """Load the active routing profile from the routing profile library from TOML file.+ """Load the active routing profile from the routing profile library.++ The library is one document read from several files: the base ``routing_profiles.toml``+ first, then each ``routing_profiles_override.toml`` that exists, deep-merged in order. An+ override carries only the keys it sets — ``active = "…"`` alone is a complete one — which is+ why the merge happens before validation: ``active`` is a required field of the blueprint.++ What this raises is what ``RuntimeBoot`` catches, and the classes are the contract: a missing+ base is ``RoutingProfileLibraryNotFoundError``, a file that does not parse, a document the+ blueprint refuses or an ``active`` naming no profile is ``RoutingProfileLibraryError``, and a profile whose default or+ routes name a backend that is not enabled is ``RoutingProfileDisabledBackendError``. That last+ one is the half-written override — ``active`` flipped, the backend still off — and the boot+ turns it into a setup error that says so.Args:- routing_profile_library_path: Path to the routing profiles TOML file.+ routing_profile_library_paths: The base file first, then the override files in merge order.enabled_backends: List of currently enabled backend names.lenient: When True, warn instead of raising when the profile referencesbackends that are not enabled (e.g. because credentials are missing)."""- # Load the routing profile library from TOML file+ library_description = describe_toml_base_and_overrides(paths=routing_profile_library_paths)try:- catalog_dict = load_toml_from_path(path=routing_profile_library_path)+ catalog_dict = load_toml_from_base_and_overrides(paths=routing_profile_library_paths)except FileNotFoundError as not_found_exc:- msg = f"Could not find routing profile library at '{routing_profile_library_path}': {not_found_exc}"- raise ModelManagerError(msg) from not_found_exc+ msg = f"Could not find routing profile library at '{routing_profile_library_paths[0]}': {not_found_exc}"+ raise RoutingProfileLibraryNotFoundError(msg) from not_found_exc+ except TomlError as toml_exc:+ msg = f"Invalid routing profile library {library_description}: {toml_exc}"+ raise RoutingProfileLibraryError(msg) from toml_exc+ if present_toml_override_paths(paths=routing_profile_library_paths):+ log.info(f"Routing profiles read from {library_description}")# Validate the routing profile library configurationtry:routing_profile_library_blueprint = RoutingProfileLibraryBlueprint.model_validate(catalog_dict)except ValidationError as exc:valiation_error_msg = format_pydantic_validation_error(exc)- msg = f"Invalid routing profile library configuration in '{routing_profile_library_path}': {valiation_error_msg}"- raise ModelManagerError(msg) from exc+ msg = f"Invalid routing profile library configuration in {library_description}: {valiation_error_msg}"+ raise RoutingProfileLibraryError(msg) from exc# Validate that the active profile existsprofile_names_str = ", ".join(routing_profile_library_blueprint.profiles.keys())active_profile_name = routing_profile_library_blueprint.activeif active_profile_name not in routing_profile_library_blueprint.profiles:- msg = f"Active profile '{active_profile_name}' not found in profile routing library. Available profiles: {profile_names_str}"- raise ModelManagerError(msg)+ msg = (+ f"Active profile '{active_profile_name}' not found in the routing profile library {library_description}. "+ f"Available profiles: {profile_names_str}"+ )+ raise RoutingProfileLibraryError(msg)# Load all profilesactive_profile_blueprint = routing_profile_library_blueprint.profiles[active_profile_name]@@ -59,7 +83,7 @@ def load_active_routing_profile(f"You must either enable backend '{active_profile.default}' or set a different default backend for profile '{active_profile_name}', ""or select a different routing profile.")- raise RoutingProfileLibraryError(msg)+ raise RoutingProfileDisabledBackendError(msg)# Check routes that use disabled backendsseen_disabled_backends: set[str] = set()@@ -69,7 +93,7 @@ def load_active_routing_profile(log.verbose(f"Backend '{backend_name}' for profile '{active_profile_name}' is not enabled (lenient mode)")else:msg = f"Backend '{backend_name}', required for profile '{active_profile_name}' is not enabled"- raise RoutingProfileLibraryError(msg)+ raise RoutingProfileDisabledBackendError(msg)seen_disabled_backends.add(backend_name)return active_profilediff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.pyindex 05ea0d70e..13e287d0b 100644--- a/pipelex/cogt/models/model_manager.py+++ b/pipelex/cogt/models/model_manager.py@@ -1,3 +1,4 @@+from collections.abc import Sequencefrom pathlib import Pathfrom typing_extensions import override@@ -69,16 +70,18 @@ class ModelManager(ModelManagerAbstract):gateway_config: GatewayConfig | None,gateway_config_source: RemoteConfigSource | None,needs_inference: bool = True,- backends_library_path: str | None = None,+ backends_library_paths: Sequence[Path] | None = None,backends_dir_path: str | None = None,- routing_profile_library_path: str | None = None,+ routing_profile_library_paths: Sequence[Path] | None = None,deck_dir_path: str | None = None,) -> None:# Override paths let the doctor scope --global properly; default None falls- # back to layered config_manager paths for all other callers.+ # back to layered config_manager paths for all other callers. The two documents are+ # sequences — the base file, then the personal override files — see+ # `ConfigLoader.backends_file_paths`.self.inference_backend_library.load(secrets_provider=secrets_provider,- backends_library_path=backends_library_path or str(config_manager.backends_file_path),+ backends_library_paths=backends_library_paths or config_manager.backends_file_paths(),backends_dir_path=backends_dir_path or str(config_manager.backends_dir_path),gateway_config=gateway_config,lenient=not needs_inference,@@ -91,7 +94,7 @@ class ModelManager(ModelManagerAbstract):log.warning(stale_warning)enabled_backends = self.inference_backend_library.all_enabled_backends()self._routing_profile = load_active_routing_profile(- routing_profile_library_path=routing_profile_library_path or str(config_manager.routing_profiles_file_path),+ routing_profile_library_paths=routing_profile_library_paths or config_manager.routing_profiles_file_paths(),enabled_backends=enabled_backends,lenient=not needs_inference,)diff --git a/pipelex/kit/paths.py b/pipelex/kit/paths.pyindex e459054c8..f87b4e75a 100644--- a/pipelex/kit/paths.py+++ b/pipelex/kit/paths.py@@ -6,6 +6,9 @@ from importlib.resources.abc import Traversable# - pipelex_service.toml: Contains terms_accepted (False for new users, True for devs)# - pipelex_override.toml: Personal config overrides# - telemetry_override.toml: Personal telemetry settings+# - inference/backends_override.toml, inference/routing_profiles_override.toml: personal+# overrides of the two inference documents, so a developer runs on another backend without+# editing the tracked files (matched by bare name, like everything here)# - telemetry.project.toml: Kit-internal commented-out template used by project init# only; must never be propagated into ~/.pipelex/ or a project's .pipelex/ as-is# The config-sync check and the kit mirror extend this set with the files that intentionally@@ -18,6 +21,8 @@ GIT_IGNORED_CONFIG_FILES: frozenset[str] = frozenset("pipelex_service.toml","pipelex_override.toml","telemetry_override.toml",+ "backends_override.toml",+ "routing_profiles_override.toml","telemetry.project.toml","pipelex_gateway_models.md", # Auto-generated from remote config"pipelex_gateway_models_plain.md", # Auto-generated from remote configdiff --git a/pipelex/migration/gitignore.py b/pipelex/migration/gitignore.pyindex 989e2bc3c..9ee5247d8 100644--- a/pipelex/migration/gitignore.py+++ b/pipelex/migration/gitignore.py@@ -1,11 +1,22 @@"""The `.gitignore` pipelex keeps inside the configuration directory it owns.-A migration copies every file before it rewrites it, and that copy lands beside the original —-inside `.pipelex/`, which in a real project is inside a git repository. Without a rule, one-`pipelex migrate` puts a dozen untracked `.bak.<stamp>` files into the user's `git status`, and-the user is left to work out which of them are ours and write the pattern themselves. Each of-them writes a slightly different one, or forgets, and a tool that dirties a repository every time-it runs stops getting run.+Two kinds of file in that directory are not the project's to commit, and the file carries a rule+for each.++The first is a personal override: `pipelex_override.toml` and its siblings, and the two inference+overrides `inference/backends_override.toml` and `inference/routing_profiles_override.toml`. Each+is read on top of a tracked file and carries only the keys it sets, so a developer runs on the+backend of their choice, or reports telemetry where they like, without editing the file the project+ships — provided the override never reaches the commit. Listing them here is what makes a fresh+`pipelex init` project safe by default; a project set up before a rule existed keeps its own file+and adds the line itself, because this file is never rewritten (see below).++The second is a backup. A migration copies every file before it rewrites it, and that copy lands+beside the original — inside `.pipelex/`, which in a real project is inside a git repository.+Without a rule, one `pipelex migrate` puts a dozen untracked `.bak.<stamp>` files into the user's+`git status`, and the user is left to work out which of them are ours and write the pattern+themselves. Each of them writes a slightly different one, or forgets, and a tool that dirties a+repository every time it runs stops getting run.**Why the rule lives here and not in the user's root `.gitignore`.** The walk is the global`~/.pipelex/` and the project `.pipelex/`, and nothing else (see `run.py`), so a backup written@@ -44,16 +55,37 @@ CONFIG_DIR_GITIGNORE_NAME = ".gitignore""""What the file is called inside `~/.pipelex/` or a project's `.pipelex/`."""BACKUP_IGNORE_PATTERN = f"*{BACKUP_INFIX}{BACKUP_STAMP_GLOB}"-"""The one rule the file carries: any name ending in the infix followed by exactly the stamp.+"""The backup rule: any name ending in the infix followed by exactly the stamp.Exactly the stamp, rather than something stamp-shaped, is what keeps `pipelex.toml.bak.notes` — andevery other copy the user named themselves — visible in their own `git status`."""+PERSONAL_OVERRIDE_IGNORE_PATTERNS: tuple[str, ...] = (+ "pipelex_override.toml",+ "pipelex_temporary_override.toml",+ "telemetry_override.toml",+ "inference/backends_override.toml",+ "inference/routing_profiles_override.toml",+)+"""The personal override files pipelex layers over the tracked ones, one rule each.++Each carries only the keys it sets, on top of a file the project tracks — which is the whole point+of it: a developer's own choices (their observability, the backend they run on) stay theirs, and a+project's defaults ship as the project wrote them. The two inference overrides are named with their+subdirectory, because a rule with a slash in it is anchored to this directory rather than matched at+any depth. What is *not* here: `pipelex_local.toml` and the `pipelex_{{environment}}.toml` tier, which+are part of a project's tracked configuration, and `pipelex_service.toml`, which is not an override.+"""+_GITIGNORE_CONTENT = f"""\# Written by pipelex when it set this directory up. Yours from here on — pipelex reads this file# never, and rewrites it never. Delete a line and it stays deleted.#+# The personal override files pipelex layers over the tracked ones. Each carries only the keys it+# sets, so what a machine chooses for itself stays out of what the project commits.+{chr(10).join(PERSONAL_OVERRIDE_IGNORE_PATTERNS)}+## The timestamped copy `pipelex migrate` takes of every file before it rewrites it. It is our own# transient artifact; the durable history of these files is your commits.#diff --git a/pipelex/migration/surfaces.py b/pipelex/migration/surfaces.pyindex 706d60fdc..b77363060 100644--- a/pipelex/migration/surfaces.py+++ b/pipelex/migration/surfaces.py@@ -594,6 +594,9 @@ def build_config_surface_registry() -> SurfaceRegistry:# ledger over the same files would be two tools writing one directory. Not# `inference/routing_profiles.toml` either: it has neither mechanism, but it also has no# break to repair, and a surface is claimed when there is something to carry forward.+ # The personal `backends_override.toml` and `routing_profiles_override.toml` beside those+ # two are outside every surface for the same reason, and for one more: an override+ # carries only the keys it sets, and a ledger replays over a whole document.## What *is* in scope is the schema of a backend file — which keys a model table may carry# — and not its content: which models a machine defines is the machine's business.diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex ab627afd3..52c17d027 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -60,6 +60,7 @@ from pipelex.cogt.exceptions import (ModelDeckNotFoundError,ModelDeckValidationError,RoutingProfileDisabledBackendError,+ RoutingProfileLibraryError,RoutingProfileLibraryNotFoundError,)from pipelex.cogt.inference.inference_manager import InferenceManager@@ -377,8 +378,14 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# --- Pipelex Service and Telemetry --------------------------------------------------# Check if Pipelex Gateway is enabled- # for now the only servic is the Pipelex Gateway- is_pipelex_service_enabled = is_pipelex_gateway_enabled()+ # for now the only service is the Pipelex Gateway+ try:+ is_pipelex_service_enabled = is_pipelex_gateway_enabled()+ except BACKEND_LIBRARY_REFUSED as backends_document_exc:+ # The document is read here before the library loads it: a file that does not parse+ # is the library's refusal, and it gets the library's message.+ msg = self._get_validation_error_msg(component=BootComponent.INFERENCE_BACKEND_LIBRARY, validation_exc=backends_document_exc)+ raise PipelexSetupError(msg) from backends_document_exceffective_needs_model_specs = needs_model_specs if needs_model_specs is not None else needs_inference@@ -583,6 +590,9 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.except RoutingProfileDisabledBackendError as routing_profile_exc:msg = f"Some backend(s) required for a routing profile is not enabled: {routing_profile_exc}"raise PipelexSetupError(msg) from routing_profile_exc+ except RoutingProfileLibraryError as routing_validation_exc:+ msg = self._get_validation_error_msg(component=BootComponent.ROUTING_PROFILE_LIBRARY, validation_exc=routing_validation_exc)+ raise PipelexSetupError(msg) from routing_validation_excexcept BACKEND_LIBRARY_REFUSED as backend_validation_exc:msg = self._get_validation_error_msg(component=BootComponent.INFERENCE_BACKEND_LIBRARY, validation_exc=backend_validation_exc)diff --git a/pipelex/system/configuration/config_check.py b/pipelex/system/configuration/config_check.pyindex efa78599c..88e15a92b 100644--- a/pipelex/system/configuration/config_check.py+++ b/pipelex/system/configuration/config_check.py@@ -10,7 +10,9 @@ PLXT_CONFIG_NAME = "plxt.toml"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+ # Use resolve_config_file for all checks — consistent with how backends and routing are resolved.+ # The two inference documents are checked by their base file on purpose: a personal+ # `*_override.toml` carries only the keys it sets and cannot stand in for the file it overrides.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)routing_exists = path_exists(config_manager.routing_profiles_file_path)diff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.pyindex 86856b64a..cbd3c9a54 100644--- a/pipelex/system/configuration/config_loader.py+++ b/pipelex/system/configuration/config_loader.py@@ -50,8 +50,10 @@ PROJECT_ROOT_MARKERS: frozenset[str] = frozenset({CONFIG_DIR_NAME, ".git", "pyprINFERENCE_DIR_NAME = "inference"BACKENDS_FILE_NAME = "backends.toml"+BACKENDS_OVERRIDE_FILE_NAME = "backends_override.toml"BACKENDS_DIR_NAME = "backends"ROUTING_PROFILES_FILE_NAME = "routing_profiles.toml"+ROUTING_PROFILES_OVERRIDE_FILE_NAME = "routing_profiles_override.toml"MODEL_DECKS_DIR_NAME = "deck"@@ -192,7 +194,11 @@ class ConfigLoader:@propertydef backends_file_path(self) -> Path:- """Resolve backends.toml from project dir or global dir."""+ """The base ``backends.toml``, from the project dir or else the global dir.++ The base is the file that must exist and the one ``pipelex init`` writes. A reader wants+ ``backends_file_paths`` instead: the same base followed by the personal override files.+ """return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{BACKENDS_FILE_NAME}")@property@@ -202,9 +208,76 @@ class ConfigLoader:@propertydef routing_profiles_file_path(self) -> Path:- """Resolve routing_profiles.toml from project dir or global dir."""+ """The base ``routing_profiles.toml``, from the project dir or else the global dir.++ The base is the file that must exist and the one ``pipelex init`` writes. A reader wants+ ``routing_profiles_file_paths`` instead: the same base followed by the personal override files.+ """return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{ROUTING_PROFILES_FILE_NAME}")+ def backends_file_paths(self, *, config_dir: Path | None = None) -> list[Path]:+ """The ``backends.toml`` merge sequence: the resolved base, then the override at each tier.++ See ``_inference_file_paths`` for the order and why it is what it is.+ """+ return self._inference_file_paths(+ resolved_base=self.backends_file_path,+ file_name=BACKENDS_FILE_NAME,+ override_file_name=BACKENDS_OVERRIDE_FILE_NAME,+ config_dir=config_dir,+ )++ def routing_profiles_file_paths(self, *, config_dir: Path | None = None) -> list[Path]:+ """The ``routing_profiles.toml`` merge sequence: the resolved base, then the override at each tier.++ See ``_inference_file_paths`` for the order and why it is what it is.+ """+ return self._inference_file_paths(+ resolved_base=self.routing_profiles_file_path,+ file_name=ROUTING_PROFILES_FILE_NAME,+ override_file_name=ROUTING_PROFILES_OVERRIDE_FILE_NAME,+ config_dir=config_dir,+ )++ def _inference_file_paths(self, *, resolved_base: Path, file_name: str, override_file_name: str, config_dir: Path | None) -> list[Path]:+ """The paths a reader of one inference document merges, base first.++ The first path is the base and must exist; the rest are the personal override files, each+ carrying only the keys it sets, merged in order so the last wins per leaf key+ (``load_toml_from_base_and_overrides`` is the loader that honours this contract).++ Without ``config_dir`` the sequence is::++ [resolved base, ~/.pipelex/inference/<override>, <project>/.pipelex/inference/<override>]++ The base keeps today's winner-takes-all resolution — a project's file if it has one, else+ the global one — and the overrides layer over whichever was picked, global then project.+ That order is deliberately not ``pipelex.toml``'s, where a project base beats a global+ override: a global inference override exists so that one machine-wide choice ("run on this+ backend") reaches every project on the machine, and every project carries a tracked+ ``backends.toml`` of its own, so a project base that beat it would defeat the file's purpose.+ A project override still wins over the global one, for the one project that needs to differ.++ With ``config_dir`` (the doctor's ``--global``, an init targeting one directory) the+ sequence is pinned to that directory and its own override, mirroring ``load_config``.++ ``resolved_base`` is the public ``backends_file_path`` / ``routing_profiles_file_path``+ property, read rather than recomputed here on purpose: that property is a seam a test+ fixture may patch to boot on a document of its own, and a sequence that resolved the base+ itself would read past the patch and boot every such test on the real file. A fixture that+ must also keep the personal override tiers out patches this repository's sequence methods+ instead. A property patched with a ``str`` is what the ``Path(...)`` below is for.+ """+ relative_base = f"{INFERENCE_DIR_NAME}/{file_name}"+ relative_override = f"{INFERENCE_DIR_NAME}/{override_file_name}"+ if config_dir is not None:+ return [config_dir / relative_base, config_dir / relative_override]+ paths = [Path(resolved_base), self.global_config_dir / relative_override]+ project_dir = self.project_config_dir+ if project_dir is not None and project_dir != self.global_config_dir:+ paths.append(project_dir / relative_override)+ return paths+@propertydef model_decks_dir_path(self) -> Path:"""Resolve model decks directory from project dir or global dir."""@@ -247,6 +320,11 @@ class ConfigLoader:Order matters: later files win on key collisions during deep-merge.+ This is the widest of the three override families a ``.pipelex/`` directory carries. The+ other two are narrower on purpose: a plugin config takes ``{name}_{environment}.toml`` and+ ``{name}_override.toml`` (``_plugin_override_files_for_dir``), and the two inference+ documents take a single ``*_override.toml`` each (``_inference_file_paths``).+Args:config_dir: The .pipelex directory to look in.include_run_mode: When False, omit the `pipelex_{run_mode}.toml` entry.diff --git a/pipelex/system/pipelex_service/pipelex_service_config.py b/pipelex/system/pipelex_service/pipelex_service_config.pyindex 8ede1a6c3..72e6415e2 100644--- a/pipelex/system/pipelex_service/pipelex_service_config.py+++ b/pipelex/system/pipelex_service/pipelex_service_config.py@@ -4,6 +4,7 @@ from typing import Any, castfrom pydantic import Field, ValidationErrorfrom pipelex import log+from pipelex.cogt.exceptions import InferenceBackendLibraryValidationErrorfrom pipelex.cogt.model_backends.backend import PipelexBackendfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.configuration.config_model import ConfigModel@@ -19,7 +20,8 @@ from pipelex.system.pipelex_service.pipelex_service_agreement import (PipelexServiceAgreement,PipelexServiceOnboarding,)-from pipelex.tools.misc.toml_utils import load_toml_from_path, load_toml_from_path_if_exists+from pipelex.tools.misc.exceptions import TomlError+from pipelex.tools.misc.toml_utils import describe_toml_base_and_overrides, load_toml_from_base_and_overrides, load_toml_from_pathfrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error@@ -75,33 +77,45 @@ def _service_config_the_ledger_can_explain(*, config_path: Path) -> PipelexServireturn service_config-def is_pipelex_gateway_enabled(backends_file_path: Path | None = None) -> bool:+def is_pipelex_gateway_enabled(*, config_dir: Path | None = None) -> bool:"""Check if pipelex_gateway is enabled in the backends configuration.- This reads the backends.toml file directly without loading the full backend library.+ This reads the backends document directly without loading the full backend library — the+ same document the loader reads: the base ``backends.toml`` with every ``backends_override.toml``+ merged over it, from ``config_manager.backends_file_paths``.**It must read `enabled` exactly as the library loader does** — the raw value's truthiness, and- enabled when the key is absent — because the two are read over the same file and the boot acts- on the answer here: it fetches the gateway's model specs only when this says enabled, then hands- them to a loader that decides for itself which backends are enabled. Reading the literal `true`- here while the loader read truthiness left `enabled = 1` in a state neither could name: no specs+ enabled when the key is absent, over the same merged document — because the boot acts on the+ answer here: it fetches the gateway's model specs only when this says enabled, then hands them+ to a loader that decides for itself which backends are enabled. Reading the literal `true` here+ while the loader read truthiness left `enabled = 1` in a state neither could name: no specsfetched, backend loaded — refused as *"model specs were not provided"* on a strict boot, silently- dropped from the deck on a lenient one.+ dropped from the deck on a lenient one. An override the loader saw and this did not would be the+ same split.Args:- backends_file_path: Explicit path to the ``backends.toml`` file to inspect. When- ``None`` (default), uses the layered/project-preferred path from- ``config_manager.backends_file_path``. Callers that act on a specific target- directory (e.g. ``pipelex init`` / ``pipelex init --local``) should pass the- target's ``backends.toml`` so they don't accidentally branch on a sibling config.+ config_dir: Read the document at that directory — its ``backends.toml`` and its own+ ``backends_override.toml`` — as ``pipelex init`` targeting one ``.pipelex/`` and the+ doctor's ``--global`` do, so they never branch on a sibling configuration. ``None``+ (default) reads the layered document: the resolved base, then the global override, then+ the project override.Returns:- True if pipelex_gateway is enabled, False otherwise.+ True if pipelex_gateway is enabled, False otherwise — including when there is no base file.++ Raises:+ InferenceBackendLibraryValidationError: a file in the document does not parse. The same+ class the library loader raises for it, so the boot's clause for an unloadable backend+ library names the file, rather than a parse error surfacing before any clause is reached."""- resolved_path = backends_file_path if backends_file_path is not None else config_manager.backends_file_path- backends_toml = load_toml_from_path_if_exists(resolved_path)- if backends_toml is None:+ backends_file_paths = config_manager.backends_file_paths(config_dir=config_dir)+ try:+ backends_toml = load_toml_from_base_and_overrides(paths=backends_file_paths)+ except FileNotFoundError:return False+ except TomlError as toml_exc:+ msg = f"Invalid inference backend library {describe_toml_base_and_overrides(paths=backends_file_paths)}: {toml_exc}"+ raise InferenceBackendLibraryValidationError(msg) from toml_excgateway_config = backends_toml.get(PipelexBackend.GATEWAY)if gateway_config is None or not isinstance(gateway_config, dict):diff --git a/pipelex/tools/misc/toml_utils.py b/pipelex/tools/misc/toml_utils.pyindex 64628679a..d37dd7ed3 100644--- a/pipelex/tools/misc/toml_utils.py+++ b/pipelex/tools/misc/toml_utils.py@@ -89,3 +89,50 @@ def load_toml_from_path_and_merge_with_overrides(paths: Sequence[str | Path]) ->deep_update(merged_dict, updates=one_dict)return merged_dict+++def load_toml_from_base_and_overrides(paths: Sequence[str | Path]) -> dict[str, Any]:+ """The document at the first path, with each later path that exists deep-merged over it in order.++ The first path is the document and must exist — a missing one raises ``FileNotFoundError``+ exactly as ``load_toml_from_path`` would. The rest are overrides: each carries only the keys it+ sets, so an absent one is simply skipped, and a later one wins over an earlier one per leaf key.+ Tables merge; scalars and lists are replaced whole (``deep_update`` semantics).++ This is what distinguishes it from ``load_toml_from_path_and_merge_with_overrides``, where every+ path is optional and an empty sequence of files is an empty document: here the base's absence is+ the caller's error to report, because an override cannot stand in for the file it overrides.++ Args:+ paths: The base file first, then the override files in merge order.++ Returns:+ The merged dictionary.+ """+ reject_bare_str_or_path(paths, param_name="paths")+ base_path, *override_paths = paths+ merged_dict = load_toml_from_path(path=base_path)+ for override_path in override_paths:+ if override_dict := load_toml_from_path_if_exists(override_path):+ deep_update(merged_dict, updates=override_dict)+ return merged_dict+++def present_toml_override_paths(*, paths: Sequence[str | Path]) -> list[str | Path]:+ """The override files ``load_toml_from_base_and_overrides`` actually reads: every path after the base that exists."""+ _base_path, *override_paths = paths+ return [override_path for override_path in override_paths if path_exists(override_path)]+++def describe_toml_base_and_overrides(*, paths: Sequence[str | Path]) -> str:+ """Name the files ``load_toml_from_base_and_overrides`` would merge, for a message.++ The base, then only the overrides that exist: a user fixing a refusal edits one of the files+ that were actually read, and an absent override is not one of them.+ """+ base_path = paths[0]+ description = f"'{base_path}'"+ present_overrides = [f"'{override_path}'" for override_path in present_toml_override_paths(paths=paths)]+ if present_overrides:+ description += f" with overrides {', '.join(present_overrides)}"+ return descriptiondiff --git a/subject_grants.toml b/subject_grants.tomlindex 5933b6d4f..5df25c444 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -2052,10 +2052,6 @@ rationale = "Loads model specs from the gateway config; single operand."param = "backend_name"rationale = "Loads model specs for the named backend; single operand."-["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary.check_backend_credentials"]-param = "path"-rationale = "Verb–object: validates/checks the path; single operand."-["pipelex/cogt/model_backends/backend_library.py::InferenceBackendLibrary.get_inference_backend"]param = "backend_name"rationale = "Keyed accessor by the backend_name; single operand."@@ -2072,10 +2068,6 @@ rationale = "Factory from source: builds the result from the backend_name; singlparam = "name"rationale = "Factory from source: builds the result from the name; single operand."-["pipelex/cogt/model_routing/routing_profile_loader.py::load_active_routing_profile"]-param = "routing_profile_library_path"-rationale = "Deck/file op on the routing_profile_library_path; single operand."-["pipelex/cogt/models/deck_manifest.py::DeckSyncReport.files_with_status"]param = "status"rationale = "Deck/file op on the status; single operand."@@ -5576,10 +5568,6 @@ rationale = "Verb-object: merges the gateway model specs; merge context stays keparam = "gateway_api_key"rationale = "Derivation: hashes the gateway API key into a distinct id; single operand."-["pipelex/system/pipelex_service/pipelex_service_config.py::is_pipelex_gateway_enabled"]-param = "backends_file_path"-rationale = "Predicate inspecting the backends file at the path; single operand."-["pipelex/system/pipelex_service/pipelex_service_config.py::load_pipelex_service_config_if_exists"]param = "config_dir"rationale = "Verb-object: loads from the config dir; single operand."@@ -6644,6 +6632,10 @@ rationale = "Parses/reads the doc; single operand."param = "doc"rationale = "Setter: installs the doc; single operand."+["pipelex/tools/misc/toml_utils.py::load_toml_from_base_and_overrides"]+param = "paths"+rationale = "Loads and merges the paths; single operand, same shape as its sibling load_toml_from_path_and_merge_with_overrides."+["pipelex/tools/misc/toml_utils.py::load_toml_from_content"]param = "content"rationale = "Parses/reads the content; single operand."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.pyindex aacd5898e..d8616ddf5 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@@ -42,11 +42,13 @@ def pipelex_routed_to_openai_for_e2e() -> Iterator[None]:routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-pipe-img-gen-e2e-validation-"))routing_override_path = routing_override_dir / routing_profiles_path.namesave_toml_to_path(routing_profiles_doc, path=str(routing_override_path))- routing_monkeypatch.setattr(- type(config_manager),- "routing_profiles_file_path",- property(lambda _self: str(routing_override_path)),- )++ # The whole sequence, not the base alone: a personal `routing_profiles_override.toml` on this+ # machine would otherwise layer over the pinned document and route this test elsewhere.+ def pinned_routing_profile_paths(_self: object, **_kwargs: object) -> list[Path]:+ return [routing_override_path]++ routing_monkeypatch.setattr(type(config_manager), "routing_profiles_file_paths", pinned_routing_profile_paths)get_console().print("[cyan]Routing to backend:[/cyan] openai (for e2e validation test)")try:diff --git a/tests/integration/pipelex/cli/commands/init/test_cache_priming.py b/tests/integration/pipelex/cli/commands/init/test_cache_priming.pyindex c84f5610c..2f6b32eb9 100644--- a/tests/integration/pipelex/cli/commands/init/test_cache_priming.py+++ b/tests/integration/pipelex/cli/commands/init/test_cache_priming.py@@ -37,6 +37,8 @@ from pipelex.system.pipelex_service.remote_config_cache import (from pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcherif TYPE_CHECKING:+ from collections.abc import Callable+from pytest_mock import MockerFixtureINIT_COMMAND_MODULE = "pipelex.cli.commands.init.command"@@ -107,6 +109,22 @@ def isolated_cache_dir(tmp_path: Path, mocker: MockerFixture) -> Path:return fake_global_dir+def _layered_or_pinned(layered_backends: Path) -> Callable[..., list[Path]]:+ """A stand-in for `ConfigLoader.backends_file_paths` that keeps honouring `config_dir`.++ Patched on the class, the method serves every caller: the layered sequence only when no+ directory is named, and that directory's own base and override otherwise — which is the whole+ contract the priming helper relies on when it passes the target directory.+ """++ def backends_file_paths(*, config_dir: Path | None = None) -> list[Path]:+ if config_dir is None:+ return [layered_backends]+ return [config_dir / "inference" / "backends.toml", config_dir / "inference" / "backends_override.toml"]++ return backends_file_paths++class TestCachePriming:@pytest.mark.usefixtures("isolated_cache_dir")def test_init_primes_cache_when_online(self, mocker: MockerFixture) -> None:@@ -215,7 +233,7 @@ class TestCachePriming:resolves to first.Setup:- - layered ``backends.toml`` (default ``config_manager.backends_file_path``) has gateway DISABLED.+ - layered ``backends.toml`` (default ``config_manager.backends_file_paths()``) has gateway DISABLED.- target_config_dir's ``backends.toml`` has gateway ENABLED.Expected: priming runs (gateway enabled at the target). Without the fix, the helper@@ -226,12 +244,7 @@ class TestCachePriming:layered_backends = layered_dir / "inference" / "backends.toml"layered_backends.parent.mkdir(parents=True, exist_ok=True)layered_backends.write_text("[pipelex_gateway]\nenabled = false\n", encoding="utf-8")- mocker.patch.object(- ConfigLoader,- "backends_file_path",- new_callable=mocker.PropertyMock,- return_value=layered_backends,- )+ mocker.patch.object(ConfigLoader, "backends_file_paths", side_effect=_layered_or_pinned(layered_backends))# Target init dir says gateway IS enabled. The priming helper must read THIS file.target_dir = tmp_path / "target_dir"@@ -273,12 +286,7 @@ class TestCachePriming:layered_backends = layered_dir / "inference" / "backends.toml"layered_backends.parent.mkdir(parents=True, exist_ok=True)layered_backends.write_text("[pipelex_gateway]\nenabled = true\n", encoding="utf-8")- mocker.patch.object(- ConfigLoader,- "backends_file_path",- new_callable=mocker.PropertyMock,- return_value=layered_backends,- )+ mocker.patch.object(ConfigLoader, "backends_file_paths", side_effect=_layered_or_pinned(layered_backends))# Target says gateway disabled — priming should respect that and become a no-op.target_dir = tmp_path / "target_dir"diff --git a/tests/integration/pipelex/fixtures/combo_fixtures.py b/tests/integration/pipelex/fixtures/combo_fixtures.pyindex 05d445386..8816171f5 100644--- a/tests/integration/pipelex/fixtures/combo_fixtures.py+++ b/tests/integration/pipelex/fixtures/combo_fixtures.py@@ -64,11 +64,13 @@ def _setup_routing_for_backend(backend_name: str) -> tuple[MonkeyPatch, Path]:routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-override-"))routing_override_path = routing_override_dir / routing_profiles_path.namesave_toml_to_path(routing_profiles_doc, path=str(routing_override_path))- routing_monkeypatch.setattr(- type(config_manager),- "routing_profiles_file_path",- property(lambda _self: str(routing_override_path)),- )++ # The whole sequence, not the base alone: a personal `routing_profiles_override.toml` on this+ # machine would otherwise layer over the pinned document and route this test elsewhere.+ def pinned_routing_profile_paths(_self: object, **_kwargs: object) -> list[Path]:+ return [routing_override_path]++ routing_monkeypatch.setattr(type(config_manager), "routing_profiles_file_paths", pinned_routing_profile_paths)get_console().print(f"[cyan]Routing to backend:[/cyan] {backend_name}")# Reinitialize Pipelex with correct routingdiff --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.pyindex dd691296b..32d9b48f2 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@@ -50,11 +50,13 @@ def pipelex_routed_to_openai() -> Iterator[None]:routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-pipe-img-gen-validation-"))routing_override_path = routing_override_dir / routing_profiles_path.namesave_toml_to_path(routing_profiles_doc, path=str(routing_override_path))- routing_monkeypatch.setattr(- type(config_manager),- "routing_profiles_file_path",- property(lambda _self: str(routing_override_path)),- )++ # The whole sequence, not the base alone: a personal `routing_profiles_override.toml` on this+ # machine would otherwise layer over the pinned document and route this test elsewhere.+ def pinned_routing_profile_paths(_self: object, **_kwargs: object) -> list[Path]:+ return [routing_override_path]++ routing_monkeypatch.setattr(type(config_manager), "routing_profiles_file_paths", pinned_routing_profile_paths)get_console().print("[cyan]Routing to backend:[/cyan] openai (for blueprint-validation test)")try:diff --git a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.pyindex 8e83b0b05..c7f6e2e67 100644--- a/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py+++ b/tests/integration/pipelex/pipes/operator/pipe_img_gen/test_pipe_img_gen_google_blueprint_validation.py@@ -51,11 +51,13 @@ def pipelex_routed_to_google() -> Iterator[None]:routing_override_dir = Path(tempfile.mkdtemp(prefix="pipelex-routing-pipe-img-gen-google-validation-"))routing_override_path = routing_override_dir / routing_profiles_path.namesave_toml_to_path(routing_profiles_doc, path=str(routing_override_path))- routing_monkeypatch.setattr(- type(config_manager),- "routing_profiles_file_path",- property(lambda _self: str(routing_override_path)),- )++ # The whole sequence, not the base alone: a personal `routing_profiles_override.toml` on this+ # machine would otherwise layer over the pinned document and route this test elsewhere.+ def pinned_routing_profile_paths(_self: object, **_kwargs: object) -> list[Path]:+ return [routing_override_path]++ routing_monkeypatch.setattr(type(config_manager), "routing_profiles_file_paths", pinned_routing_profile_paths)get_console().print("[cyan]Routing to backend:[/cyan] google (for blueprint-validation test)")try:diff --git a/tests/unit/pipelex/cli/dev/test_config_sync_exclusions.py b/tests/unit/pipelex/cli/dev/test_config_sync_exclusions.pyindex 449bc5cea..1e82469bb 100644--- a/tests/unit/pipelex/cli/dev/test_config_sync_exclusions.py+++ b/tests/unit/pipelex/cli/dev/test_config_sync_exclusions.py@@ -28,6 +28,33 @@ class TestConfigSyncExclusions:"""It is written into the directory at init and at migrate, and is never a kit template."""assert CONFIG_DIR_GITIGNORE_NAME in CONFIG_SYNC_EXCLUDED_FILES+ def test_a_personal_inference_override_reads_as_in_sync(self, tmp_path: Path) -> None:+ """The two inference overrides are personal files with no kit counterpart, at any depth.++ Through `has_diff_dirs` with the real constants: the exclusion is matched by bare name, and+ this is the assertion that the name is in the set the command actually passes.+ """+ kit_side = tmp_path / "kit" / "inference"+ project_side = tmp_path / "project" / "inference"+ kit_side.mkdir(parents=True)+ project_side.mkdir(parents=True)+ for side in (kit_side, project_side):+ (side / "backends.toml").write_text("[openai]\nenabled = true", encoding="utf-8")+ (side / "routing_profiles.toml").write_text('active = "all_openai"', encoding="utf-8")+ (project_side / "backends_override.toml").write_text("[openai]\nenabled = false", encoding="utf-8")+ (project_side / "routing_profiles_override.toml").write_text('active = "all_anthropic"', encoding="utf-8")++ assert (+ has_diff_dirs(+ dir1=tmp_path / "project",+ dir2=tmp_path / "kit",+ exclude_files=CONFIG_SYNC_EXCLUDED_FILES,+ exclude_dirs=GIT_IGNORED_CONFIG_DIRS,+ exclude_patterns=CONFIG_SYNC_EXCLUDED_PATTERNS,+ )+ is False+ )+def test_a_real_backup_name_is_excluded(self) -> None:"""Migrating in a checkout must not make the next `make check` red."""backup = backup_path_for(path=Path("pipelex_override.toml"), moment=MOMENT)diff --git a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py b/tests/unit/pipelex/cli/test_agent_doctor_cmd.pyindex 46a561f5e..3b8dce956 100644--- a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py+++ b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py@@ -20,7 +20,7 @@ from pipelex.cli.commands.doctor_cmd import (TelemetryConfigCheck,TelemetryConfigFinding,)-from pipelex.cogt.model_backends.backend_library import BackendCredentialsReport+from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsReportfrom pipelex.core.validation import MIGRATE_COMMANDfrom pipelex.system.console_target import ConsoleTargetdiff --git a/tests/unit/pipelex/cli/test_doctor_backend_checks.py b/tests/unit/pipelex/cli/test_doctor_backend_checks.pyindex d09c4093d..84d61e128 100644--- a/tests/unit/pipelex/cli/test_doctor_backend_checks.py+++ b/tests/unit/pipelex/cli/test_doctor_backend_checks.py@@ -41,6 +41,12 @@ def _write_backends_toml(config_dir: Path, content: str = BACKENDS_TOML) -> Pathreturn backends_toml+def _write_backends_override(config_dir: Path, content: str) -> Path:+ override = config_dir / "inference" / "backends_override.toml"+ override.write_text(content, encoding="utf-8")+ return override++class TestDoctorBackendChecks:def test_credentials_backends_toml_missing(self, tmp_path: Path) -> None:"""No backends.toml means the credentials check fails with a clear message."""@@ -90,7 +96,7 @@ class TestDoctorBackendChecks:def test_credentials_broad_failure_reported(self, tmp_path: Path, mocker: MockerFixture) -> None:"""Any unexpected failure during the scan becomes a finding, not a crash."""_write_backends_toml(tmp_path)- mocker.patch("pipelex.cli.commands.doctor_cmd.load_toml_from_path", side_effect=RuntimeError("kaboom"))+ mocker.patch("pipelex.cli.commands.doctor_cmd.load_toml_from_base_and_overrides", side_effect=RuntimeError("kaboom"))healthy, reports, message = check_backend_credentials(config_dir=tmp_path)@@ -195,6 +201,32 @@ class TestDoctorBackendChecks:shutil.copytree(Path(str(get_kit_configs_dir())) / "inference", tmp_path / "inference")return tmp_path / "inference" / "backends"+ def test_credentials_read_the_override_over_the_base(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """A backend the personal override disables is not asked for credentials, and one it enables is."""+ _write_backends_toml(tmp_path)+ _write_backends_override(tmp_path, "[openai]\nenabled = false\n\n[azure]\nenabled = true\n")+ monkeypatch.delenv("TEST_DOCTOR_OPENAI_KEY", raising=False)+ monkeypatch.delenv("TEST_DOCTOR_AZURE_KEY", raising=False)++ healthy, reports, _ = check_backend_credentials(config_dir=tmp_path)++ assert healthy is False+ assert "openai" not in reports+ assert reports["azure"].missing_vars == ["TEST_DOCTOR_AZURE_KEY"]++ def test_backend_files_read_the_override_over_the_base(self, tmp_path: Path) -> None:+ """The file probe walks the merged document: a backend the override turns off is not probed,+ one it turns on is — and the loader it probes with is handed the same merged document.+ """+ self._copy_kit_inference(tmp_path)+ _write_backends_override(tmp_path, "[openai]\nenabled = false\n\n[vertexai]\nenabled = true\n")++ healthy, reports, _ = check_backend_files(config_dir=tmp_path)++ assert healthy is True+ assert "openai" not in reports+ assert reports["vertexai"].is_valid is True+def test_backend_files_stock_kit_is_healthy(self, tmp_path: Path) -> None:"""The shipped defaults enable the gateway and ship its override file; the probe hands theloader no gateway config, and that must not be reported as a malformed file.diff --git a/tests/unit/pipelex/cli/test_doctor_check_models.py b/tests/unit/pipelex/cli/test_doctor_check_models.pyindex f4b5c68c3..0d89a7c45 100644--- a/tests/unit/pipelex/cli/test_doctor_check_models.py+++ b/tests/unit/pipelex/cli/test_doctor_check_models.py@@ -13,11 +13,18 @@ from typing import TYPE_CHECKING, Anyimport pytestfrom pipelex.cli.commands.doctor_cmd import BackendFileReport, check_models-from pipelex.cogt.exceptions import InferenceBackendLibraryError, ModelDeckValidationError+from pipelex.cogt.exceptions import (+ InferenceBackendLibraryError,+ InferenceBackendLibraryValidationError,+ ModelDeckValidationError,+ RoutingProfileLibraryError,+)from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableErrorfrom pipelex.system.pipelex_service.types import RemoteConfigSourceif TYPE_CHECKING:+ from pathlib import Path+from pytest_mock import MockerFixture@@ -188,3 +195,41 @@ class TestCheckModels:assert reports["openai"].is_valid is Falseassert reports["portkey"].is_valid is Trueassert reports["portkey"].error_message is None++ @pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")+ def test_an_active_profile_naming_no_profile_is_a_reported_finding(self, models_manager: Any) -> None:+ """The likeliest override typo — `active = "nope"` — is the routing library's own refusal, and the doctor must report it, not crash."""+ models_manager.setup.side_effect = RoutingProfileLibraryError("Active profile 'nope' not found in the routing profile library")++ healthy, message, reports = check_models()++ assert healthy is False+ assert "Active profile 'nope' not found" in message+ assert reports == {}++ @pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")+ def test_global_pins_both_documents_as_base_plus_override(self, models_manager: Any, tmp_path: Path) -> None:+ """`--global` hands the model manager that directory's base and its own override, for both documents."""+ check_models(config_dir=tmp_path)++ kwargs = models_manager.setup.call_args.kwargs+ assert kwargs["backends_library_paths"] == [tmp_path / "inference" / "backends.toml", tmp_path / "inference" / "backends_override.toml"]+ assert kwargs["routing_profile_library_paths"] == [+ tmp_path / "inference" / "routing_profiles.toml",+ tmp_path / "inference" / "routing_profiles_override.toml",+ ]++ @pytest.mark.usefixtures("healthy_backend_files")+ def test_a_backends_document_that_does_not_parse_is_a_reported_finding(self, mocker: MockerFixture, models_manager: Any) -> None:+ """The gateway gate reads the merged document before any load; its refusal is the Models row's, not a crash."""+ mocker.patch(+ "pipelex.cli.commands.doctor_cmd.is_pipelex_gateway_enabled",+ side_effect=InferenceBackendLibraryValidationError("Invalid inference backend library 'x' with overrides 'y': TOML parsing error"),+ )++ healthy, message, reports = check_models()++ assert healthy is False+ assert "TOML parsing error" in message+ assert reports == {}+ models_manager.setup.assert_not_called()diff --git a/tests/unit/pipelex/cli/test_doctor_display_report.py b/tests/unit/pipelex/cli/test_doctor_display_report.pyindex 6e48c976d..4f373f1d9 100644--- a/tests/unit/pipelex/cli/test_doctor_display_report.py+++ b/tests/unit/pipelex/cli/test_doctor_display_report.py@@ -17,7 +17,7 @@ from pipelex.cli.commands.doctor_cmd import (display_health_report,doctor_cmd,)-from pipelex.cogt.model_backends.backend_library import BackendCredentialsReport+from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsReportfrom pipelex.cogt.models.deck_manifest import DeckFileStatus, DeckSyncReportfrom pipelex.core.validation import MIGRATE_COMMANDdiff --git a/tests/unit/pipelex/cli/test_doctor_fix_mode.py b/tests/unit/pipelex/cli/test_doctor_fix_mode.pyindex 61ac3a958..d673c2793 100644--- a/tests/unit/pipelex/cli/test_doctor_fix_mode.py+++ b/tests/unit/pipelex/cli/test_doctor_fix_mode.py@@ -17,7 +17,7 @@ from pipelex.cli.commands.doctor_cmd import (do_doctor_cmd,)from pipelex.cli.commands.init.ui.types import InitFocus-from pipelex.cogt.model_backends.backend_library import BackendCredentialsReport+from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsReportfrom pipelex.cogt.models.deck_manifest import DeckFileStatus, DeckSyncReportfrom pipelex.core.validation import MIGRATE_COMMANDfrom pipelex.migration.plan import MigrationPlan, MigrationReportdiff --git a/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.py b/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.pynew file mode 100644index 000000000..973f2c6d8--- /dev/null+++ b/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.py@@ -0,0 +1,84 @@+"""`pipelex init` decides "gateway enabled" on the merged backends document, and says so when a write to the base cannot take.++The init writers edit the base `backends.toml` while the runtime reads it with `backends_override.toml`+merged over it. Two consequences are pinned here: the terms prompt fires for a gateway enabled only by an+override, and declining the terms — which disables the gateway in the base — warns when an override still+pins it on, naming the files, instead of leaving the next boot to refuse for terms the user just declined.+"""++from __future__ import annotations++import io+from pathlib import Path+from typing import TYPE_CHECKING++from rich.console import Console++from pipelex.cli.commands.init.backends import warn_if_gateway_pinned_by_override+from pipelex.cli.commands.init.command import _check_gateway_terms_if_needed # pyright: ignore[reportPrivateUsage]++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++BASE_GATEWAY_OFF = "[pipelex_gateway]\nenabled = false\n"+OVERRIDE_GATEWAY_ON = "[pipelex_gateway]\nenabled = true\n"+++def _write_backends(config_dir: Path, *, base: str, override: str | None) -> Path:+ inference_dir = config_dir / "inference"+ inference_dir.mkdir(parents=True)+ backends_toml_path = inference_dir / "backends.toml"+ backends_toml_path.write_text(base)+ if override is not None:+ (inference_dir / "backends_override.toml").write_text(override)+ return backends_toml_path+++def _capturing_console() -> tuple[Console, io.StringIO]:+ buffer = io.StringIO()+ return Console(file=buffer, force_terminal=False, width=200), buffer+++class TestWarnIfGatewayPinnedByOverride:+ def test_says_nothing_when_the_base_is_the_whole_story(self, tmp_path: Path) -> None:+ backends_toml_path = _write_backends(tmp_path, base=BASE_GATEWAY_OFF, override=None)+ console, buffer = _capturing_console()++ assert warn_if_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path) is False+ assert buffer.getvalue() == ""++ def test_names_the_override_that_still_enables_the_gateway(self, tmp_path: Path) -> None:+ backends_toml_path = _write_backends(tmp_path, base=BASE_GATEWAY_OFF, override=OVERRIDE_GATEWAY_ON)+ console, buffer = _capturing_console()++ assert warn_if_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path) is True+ assert "backends_override.toml" in buffer.getvalue()+ assert "still enabled" in buffer.getvalue()+++class TestCheckGatewayTermsIfNeeded:+ def test_a_gateway_enabled_only_by_an_override_is_prompted_for_terms_and_warned_on_decline(self, tmp_path: Path, mocker: MockerFixture) -> None:+ backends_toml_path = _write_backends(tmp_path, base=BASE_GATEWAY_OFF, override=OVERRIDE_GATEWAY_ON)+ console, buffer = _capturing_console()+ mocker.patch("pipelex.cli.commands.init.command.load_pipelex_service_config_if_exists", return_value=None)+ prompt = mocker.patch("pipelex.cli.commands.init.command.prompt_gateway_acceptance", return_value=False)+ mocker.patch("pipelex.cli.commands.init.command.display_gateway_declined_message")+ record_terms = mocker.patch("pipelex.cli.commands.init.command.update_service_terms_acceptance")+ mocker.patch.object(Path, "home", return_value=tmp_path / "home")++ _check_gateway_terms_if_needed(console=console, backends_toml_path=backends_toml_path)++ prompt.assert_called_once()+ record_terms.assert_called_once()+ assert record_terms.call_args.kwargs["accepted"] is False+ assert "backends_override.toml" in buffer.getvalue()++ def test_a_gateway_disabled_in_the_merged_document_is_not_prompted(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The reverse: enabled in the base, switched off by the override — no terms needed."""+ backends_toml_path = _write_backends(tmp_path, base=OVERRIDE_GATEWAY_ON, override=BASE_GATEWAY_OFF)+ console, _ = _capturing_console()+ prompt = mocker.patch("pipelex.cli.commands.init.command.prompt_gateway_acceptance")++ _check_gateway_terms_if_needed(console=console, backends_toml_path=backends_toml_path)++ prompt.assert_not_called()diff --git a/tests/unit/pipelex/cli/test_show_cmd.py b/tests/unit/pipelex/cli/test_show_cmd.pyindex 4e09fabc4..c37bf0e8c 100644--- a/tests/unit/pipelex/cli/test_show_cmd.py+++ b/tests/unit/pipelex/cli/test_show_cmd.py@@ -160,7 +160,7 @@ class TestShowCmd:)mocker.patch("pipelex.cli.commands.show_cmd.get_models_manager", return_value=models_manager)mocked_config_manager = mocker.patch("pipelex.cli.commands.show_cmd.config_manager")- mocked_config_manager.backends_file_path = tmp_path / "backends.toml"+ mocked_config_manager.backends_file_paths.return_value = [tmp_path / "backends.toml"]mocked_config_manager.backends_dir_path = tmp_path / "backends"lenient_library = SimpleNamespace(root={backend.name: backend for backend in backends}, load=mocker.Mock())library_class_mock = mocker.patch("pipelex.cli.commands.show_cmd.InferenceBackendLibrary", return_value=lenient_library)diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py b/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.pyindex 60988e5c8..796eee455 100644--- a/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py@@ -147,7 +147,7 @@ class TestAStaleBackendDirectory:library = InferenceBackendLibrary.make_empty()library.load(secrets_provider=EnvSecretsProvider(),- backends_library_path=str(library_path),+ backends_library_paths=[library_path],backends_dir_path=str(self._backends_dir(machine)),gateway_config=gateway_config,lenient=lenient,diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.py b/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.pyindex efabb18de..f564e24ba 100644--- a/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.py+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.py@@ -4,7 +4,6 @@ from pytest_mock import MockerFixturefrom pipelex.cogt.model_backends.backend_credentials import (BackendCredentialsErrorMsgFactory,BackendCredentialsReport,- CredentialsValidationReport,)from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProviderfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract@@ -51,19 +50,6 @@ class TestBackendCredentials:assert report.placeholder_vars == ["OPENAI_ORG_ID"]assert report.all_credentials_valid is False- def test_credentials_validation_report_round_trip(self):- """CredentialsValidationReport holds its constructed field values."""- valid_report = make_report(backend_name="anthropic", missing_vars=[], placeholder_vars=[])- invalid_report = make_report(backend_name="openai", missing_vars=["OPENAI_API_KEY"], placeholder_vars=[])- validation_report = CredentialsValidationReport(- backend_reports={"anthropic": valid_report, "openai": invalid_report},- all_backends_valid=False,- )- assert validation_report.backend_reports["anthropic"] == valid_report- assert validation_report.backend_reports["openai"] == invalid_report- assert validation_report.backend_reports["anthropic"].all_credentials_valid is True- assert validation_report.all_backends_valid is False-def test_one_variable_missing_env_provider(self):"""The env-provider branch tells the user to add the variable to the environment or .env file."""error_msg = BackendCredentialsErrorMsgFactory.make_one_variable_missing_error_msg(diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_library_leniency.py b/tests/unit/pipelex/cogt/model_backends/test_backend_library_leniency.pyindex d5a4c67b2..df74c40a1 100644--- a/tests/unit/pipelex/cogt/model_backends/test_backend_library_leniency.py+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_library_leniency.py@@ -144,7 +144,7 @@ class TestBackendLibraryLeniency:library = InferenceBackendLibrary.make_empty()library.load(secrets_provider=EnvSecretsProvider(),- backends_library_path=backends_library_path,+ backends_library_paths=[Path(backends_library_path)],backends_dir_path=backends_dir_path,lenient=lenient,)diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.py b/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.pynew file mode 100644index 000000000..a2c51de7a--- /dev/null+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_library_overrides.py@@ -0,0 +1,165 @@+"""`backends_override.toml` layers over `backends.toml`: enabled flips, the rest of the table survives."""++from pathlib import Path++import pytest+from pytest_mock import MockerFixture++from pipelex.cogt.exceptions import InferenceBackendLibraryNotFoundError, InferenceBackendLibraryValidationError+from pipelex.cogt.model_backends.backend_library import InferenceBackendLibrary+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider++BACKENDS_TOML = """+[acme]+display_name = "Acme"+enabled = false+api_key = "sk-not-a-real-key"++[other]+display_name = "Other"+enabled = true+api_key = "sk-not-a-real-key"+"""++MODEL_SPECS_TOML = """+[defaults]+model_type = "llm"+sdk = "openai_responses"++["one"]+model_id = "one"+"""+++class TestBackendLibraryOverrides:+ def _write_base(self, tmp_path: Path) -> tuple[Path, Path]:+ backends_dir = tmp_path / "backends"+ backends_dir.mkdir()+ (backends_dir / "acme.toml").write_text(MODEL_SPECS_TOML)+ (backends_dir / "other.toml").write_text(MODEL_SPECS_TOML)+ base_path = tmp_path / "backends.toml"+ base_path.write_text(BACKENDS_TOML)+ return base_path, backends_dir++ def _load(self, *, paths: list[Path], backends_dir: Path, include_disabled: bool = False) -> InferenceBackendLibrary:+ library = InferenceBackendLibrary.make_empty()+ library.load(+ secrets_provider=EnvSecretsProvider(),+ backends_library_paths=paths,+ backends_dir_path=str(backends_dir),+ include_disabled=include_disabled,+ )+ return library++ def test_the_base_alone_is_what_it_was(self, tmp_path: Path) -> None:+ """The control: an absent override changes nothing."""+ base_path, backends_dir = self._write_base(tmp_path)++ library = self._load(paths=[base_path, tmp_path / "backends_override.toml"], backends_dir=backends_dir)++ assert library.all_enabled_backends() == ["other"]++ def test_an_override_enables_a_backend_and_keeps_the_rest_of_its_table(self, tmp_path: Path) -> None:+ base_path, backends_dir = self._write_base(tmp_path)+ override_path = tmp_path / "backends_override.toml"+ override_path.write_text("[acme]\nenabled = true\n")++ library = self._load(paths=[base_path, override_path], backends_dir=backends_dir)++ assert library.all_enabled_backends() == ["acme", "other"]+ acme = library.get_inference_backend("acme")+ assert acme is not None+ assert acme.api_key == "sk-not-a-real-key"++ def test_an_override_disables_a_backend(self, tmp_path: Path) -> None:+ base_path, backends_dir = self._write_base(tmp_path)+ override_path = tmp_path / "backends_override.toml"+ override_path.write_text("[other]\nenabled = false\n")++ library = self._load(paths=[base_path, override_path], backends_dir=backends_dir)++ assert library.all_enabled_backends() == []++ def test_the_last_override_wins(self, tmp_path: Path) -> None:+ """Global then project: the project's file is the last word."""+ base_path, backends_dir = self._write_base(tmp_path)+ global_override = tmp_path / "global_override.toml"+ global_override.write_text("[acme]\nenabled = true\n[other]\nenabled = false\n")+ project_override = tmp_path / "project_override.toml"+ project_override.write_text("[other]\nenabled = true\n")++ library = self._load(paths=[base_path, global_override, project_override], backends_dir=backends_dir)++ assert library.all_enabled_backends() == ["acme", "other"]++ def test_a_missing_base_is_not_found_even_when_an_override_exists(self, tmp_path: Path) -> None:+ _, backends_dir = self._write_base(tmp_path)+ absent_base = tmp_path / "absent" / "backends.toml"+ override_path = tmp_path / "backends_override.toml"+ override_path.write_text("[acme]\nenabled = true\n")++ with pytest.raises(InferenceBackendLibraryNotFoundError) as refused:+ self._load(paths=[absent_base, override_path], backends_dir=backends_dir)++ assert str(absent_base) in str(refused.value)++ def test_a_refusal_names_the_base_and_the_override_that_was_read(self, tmp_path: Path) -> None:+ """The user edits one of these files to fix it, so the message has to say which were merged."""+ base_path, backends_dir = self._write_base(tmp_path)+ override_path = tmp_path / "backends_override.toml"+ override_path.write_text("[acme]\nenabled = 'not-a-bool'\n")+ absent_override = tmp_path / "absent_override.toml"++ with pytest.raises(InferenceBackendLibraryValidationError) as refused:+ self._load(paths=[base_path, override_path, absent_override], backends_dir=backends_dir)++ message = str(refused.value)+ assert str(base_path) in message+ assert str(override_path) in message+ assert str(absent_override) not in message++ def test_an_override_that_does_not_parse_is_the_librarys_refusal_and_names_the_file(self, tmp_path: Path) -> None:+ base_path, backends_dir = self._write_base(tmp_path)+ override_path = tmp_path / "backends_override.toml"+ override_path.write_text("[acme\nenabled = true\n")++ with pytest.raises(InferenceBackendLibraryValidationError) as refused:+ self._load(paths=[base_path, override_path], backends_dir=backends_dir)++ assert str(override_path) in str(refused.value)++ def test_a_merged_override_is_logged_and_an_absent_one_is_not(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The one trace a machine-wide override leaves in a run's log."""+ base_path, backends_dir = self._write_base(tmp_path)+ override_path = tmp_path / "backends_override.toml"+ logger = mocker.patch("pipelex.cogt.model_backends.backend_library.log")++ self._load(paths=[base_path, override_path], backends_dir=backends_dir)+ logger.info.assert_not_called()++ override_path.write_text("[acme]\nenabled = true\n")+ self._load(paths=[base_path, override_path], backends_dir=backends_dir)+ logged = " ".join(str(call.args[0]) for call in logger.info.call_args_list)+ assert str(override_path) in logged++ @pytest.mark.parametrize("lenient", [False, True])+ def test_a_scalar_where_a_table_was_meant_is_refused_in_both_modes(self, tmp_path: Path, lenient: bool) -> None:+ """`acme = false` is the likeliest half-written override; the merge replaces the table whole and the loader must say so."""+ base_path, backends_dir = self._write_base(tmp_path)+ override_path = tmp_path / "backends_override.toml"+ override_path.write_text("acme = false\n")++ library = InferenceBackendLibrary.make_empty()+ with pytest.raises(InferenceBackendLibraryValidationError) as refused:+ library.load(+ secrets_provider=EnvSecretsProvider(),+ backends_library_paths=[base_path, override_path],+ backends_dir_path=str(backends_dir),+ lenient=lenient,+ )++ message = str(refused.value)+ assert "acme" in message+ assert "expected a table" in message+ assert str(override_path) in message+ assert refused.value.backend_name == "acme"diff --git a/tests/unit/pipelex/cogt/model_backends/test_gateway_unknown_per_model_keys.py b/tests/unit/pipelex/cogt/model_backends/test_gateway_unknown_per_model_keys.pyindex a6ea4f434..b95a000f6 100644--- a/tests/unit/pipelex/cogt/model_backends/test_gateway_unknown_per_model_keys.py+++ b/tests/unit/pipelex/cogt/model_backends/test_gateway_unknown_per_model_keys.py@@ -39,7 +39,7 @@ class TestGatewayUnknownPerModelKeys:library = InferenceBackendLibrary.make_empty()library.load(secrets_provider=EnvSecretsProvider(),- backends_library_path=str(backends_library_path),+ backends_library_paths=[backends_library_path],backends_dir_path=str(backends_dir),gateway_config=GatewayConfig(model_specs=model_specs, aws_region="eu-west-3"),)diff --git a/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.py b/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.pynew file mode 100644index 000000000..6fca1e60b--- /dev/null+++ b/tests/unit/pipelex/cogt/model_routing/test_routing_profile_overrides.py@@ -0,0 +1,182 @@+"""`routing_profiles_override.toml` layers over `routing_profiles.toml`, and the loader's refusals are the boot's.++The exception classes matter as much as the merge: `RuntimeBoot` catches `RoutingProfileLibraryNotFoundError`+and `RoutingProfileDisabledBackendError` to turn them into a setup error, and a half-written override — `active`+flipped to a profile whose backend is still disabled — is exactly the case that reaches those clauses.+"""++from pathlib import Path++import pytest+from pytest_mock import MockerFixture++from pipelex.cogt.exceptions import RoutingProfileDisabledBackendError, RoutingProfileLibraryError, RoutingProfileLibraryNotFoundError+from pipelex.cogt.model_routing.routing_profile_loader import load_active_routing_profile++ROUTING_PROFILES_TOML = """+active = "on_acme"++[profiles.on_acme]+description = "Everything on acme"+default = "acme"+fallback_order = ["acme", "other"]++[profiles.on_other]+description = "Everything on other"+default = "other"++[profiles.with_routes]+description = "Routes to a backend that may be off"+default = "acme"++[profiles.with_routes.routes]+"gpt-*" = "other"+"""+++class TestRoutingProfileOverrides:+ def _write_base(self, tmp_path: Path) -> Path:+ base_path = tmp_path / "routing_profiles.toml"+ base_path.write_text(ROUTING_PROFILES_TOML)+ return base_path++ def test_the_base_alone_is_what_it_was(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)++ profile = load_active_routing_profile(+ routing_profile_library_paths=[base_path, tmp_path / "routing_profiles_override.toml"],+ enabled_backends=["acme"],+ )++ assert profile.name == "on_acme"+ assert profile.fallback_order == ["acme", "other"]++ def test_an_override_carrying_only_active_switches_the_profile(self, tmp_path: Path) -> None:+ """`active` is a required field, so this only works because the merge happens before validation."""+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "on_other"\n')++ profile = load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["other"])++ assert profile.name == "on_other"+ assert profile.default == "other"++ def test_an_override_can_add_a_profile_and_activate_it(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "mine"\n\n[profiles.mine]\ndescription = "Mine"\ndefault = "other"\n')++ profile = load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["other"])++ assert profile.name == "mine"+ assert profile.description == "Mine"++ def test_an_override_replaces_a_list_rather_than_extending_it(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('[profiles.on_acme]\nfallback_order = ["other"]\n')++ profile = load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme", "other"])++ assert profile.fallback_order == ["other"]++ def test_the_last_override_wins(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ global_override = tmp_path / "global_override.toml"+ global_override.write_text('active = "on_other"\n')+ project_override = tmp_path / "project_override.toml"+ project_override.write_text('active = "on_acme"\n')++ profile = load_active_routing_profile(+ routing_profile_library_paths=[base_path, global_override, project_override],+ enabled_backends=["acme"],+ )++ assert profile.name == "on_acme"++ def test_a_missing_base_is_not_found_even_when_an_override_exists(self, tmp_path: Path) -> None:+ absent_base = tmp_path / "absent" / "routing_profiles.toml"+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "on_other"\n')++ with pytest.raises(RoutingProfileLibraryNotFoundError) as refused:+ load_active_routing_profile(routing_profile_library_paths=[absent_base, override_path], enabled_backends=["other"])++ assert str(absent_base) in str(refused.value)++ def test_an_active_profile_that_does_not_exist_names_the_files_that_were_read(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "on_typo"\n')++ with pytest.raises(RoutingProfileLibraryError) as refused:+ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme"])++ message = str(refused.value)+ assert "on_typo" in message+ assert str(base_path) in message+ assert str(override_path) in message++ def test_an_invalid_document_is_a_library_error(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text("[profiles.on_acme]\nnot_a_field = 1\n")++ with pytest.raises(RoutingProfileLibraryError):+ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme"])++ def test_activating_a_profile_whose_default_backend_is_disabled_is_the_boots_disabled_backend_error(self, tmp_path: Path) -> None:+ """The half-written override: `active` flipped, the backend not enabled."""+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "on_other"\n')++ with pytest.raises(RoutingProfileDisabledBackendError) as refused:+ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme"])++ assert "other" in str(refused.value)++ def test_a_route_to_a_disabled_backend_is_the_same_error(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "with_routes"\n')++ with pytest.raises(RoutingProfileDisabledBackendError):+ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme"])++ def test_lenient_tolerates_a_disabled_backend(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "with_routes"\n')++ profile = load_active_routing_profile(+ routing_profile_library_paths=[base_path, override_path],+ enabled_backends=["acme"],+ lenient=True,+ )++ assert profile.name == "with_routes"++ def test_an_override_that_does_not_parse_is_the_librarys_refusal_and_names_the_file(self, tmp_path: Path) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ override_path.write_text('active = "on_other\n')++ with pytest.raises(RoutingProfileLibraryError) as refused:+ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme", "other"])++ assert str(override_path) in str(refused.value)++ def test_a_merged_override_is_logged_and_an_absent_one_is_not(self, tmp_path: Path, mocker: MockerFixture) -> None:+ base_path = self._write_base(tmp_path)+ override_path = tmp_path / "routing_profiles_override.toml"+ logger = mocker.patch("pipelex.cogt.model_routing.routing_profile_loader.log")++ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme", "other"])+ logger.info.assert_not_called()++ override_path.write_text('active = "on_other"\n')+ load_active_routing_profile(routing_profile_library_paths=[base_path, override_path], enabled_backends=["acme", "other"])+ logged = " ".join(str(call.args[0]) for call in logger.info.call_args_list)+ assert str(override_path) in loggeddiff --git a/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.py b/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.pynew file mode 100644index 000000000..cf9925d11--- /dev/null+++ b/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.py@@ -0,0 +1,86 @@+"""The two personal override files, read where the boot reads them: through the global `config_manager`.++A developer writes `~/.pipelex/inference/backends_override.toml` and `routing_profiles_override.toml`+once, and every project on the machine follows — the gate the boot branches on to fetch gateway+specs sees the override, the model manager's default paths carry it, and deleting the two files+restores the shipped default. Built on the kit's own inference tree so the shipped defaults are the+fixture, and lenient (`needs_inference=False`) so no credential on this machine is a precondition.+"""++from __future__ import annotations++import shutil+from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from pipelex.cogt.models.model_manager import ModelManager+from pipelex.kit.paths import get_kit_configs_dir+from pipelex.system.configuration.config_loader import CONFIG_DIR_NAME, INFERENCE_DIR_NAME+from pipelex.system.pipelex_service.pipelex_service_config import is_pipelex_gateway_enabled+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++GATEWAY_OFF_OVERRIDE = "[pipelex_gateway]\nenabled = false\n"+ANTHROPIC_PROFILE_OVERRIDE = 'active = "all_anthropic"\n'+++class TestInferenceConfigOverridesEndToEnd:+ @pytest.fixture+ def global_inference_dir(self, tmp_path: Path, mocker: MockerFixture) -> Path:+ """A faked home carrying the kit's inference tree, and a project root with no `.pipelex/`.++ `Path.home` and `Path.cwd` are what the global `config_manager` derives its tiers from on+ every call, so patching them is enough to point the real singleton at this tree.+ """+ fake_home = tmp_path / "home"+ inference_dir = fake_home / CONFIG_DIR_NAME / INFERENCE_DIR_NAME+ shutil.copytree(Path(str(get_kit_configs_dir())) / INFERENCE_DIR_NAME, inference_dir)+ project_root = tmp_path / "project"+ (project_root / ".git").mkdir(parents=True)+ mocker.patch.object(Path, "home", return_value=fake_home)+ mocker.patch.object(Path, "cwd", return_value=project_root)+ return inference_dir++ def _active_profile_name(self) -> str:+ models_manager = ModelManager()+ models_manager.setup(+ secrets_provider=EnvSecretsProvider(),+ gateway_config=None,+ gateway_config_source=None,+ needs_inference=False,+ )+ return models_manager.routing_profile.name++ @pytest.mark.usefixtures("global_inference_dir")+ def test_the_shipped_default_is_the_gateway(self) -> None:+ """The control, and the state the overrides must restore when deleted."""+ assert is_pipelex_gateway_enabled() is True+ assert self._active_profile_name() == "all_pipelex_gateway"++ def test_two_global_override_files_move_the_machine_off_the_gateway_and_deleting_them_moves_it_back(self, global_inference_dir: Path) -> None:+ backends_override = global_inference_dir / "backends_override.toml"+ routing_override = global_inference_dir / "routing_profiles_override.toml"+ backends_override.write_text(GATEWAY_OFF_OVERRIDE, encoding="utf-8")+ routing_override.write_text(ANTHROPIC_PROFILE_OVERRIDE, encoding="utf-8")++ assert is_pipelex_gateway_enabled() is False+ assert self._active_profile_name() == "all_anthropic"++ backends_override.unlink()+ routing_override.unlink()++ assert is_pipelex_gateway_enabled() is True+ assert self._active_profile_name() == "all_pipelex_gateway"++ def test_a_project_override_wins_over_the_global_one(self, global_inference_dir: Path, tmp_path: Path) -> None:+ """The project keeps its own inference files out of it: only its override is added, last."""+ (global_inference_dir / "routing_profiles_override.toml").write_text(ANTHROPIC_PROFILE_OVERRIDE, encoding="utf-8")+ project_inference_dir = tmp_path / "project" / CONFIG_DIR_NAME / INFERENCE_DIR_NAME+ project_inference_dir.mkdir(parents=True)+ (project_inference_dir / "routing_profiles_override.toml").write_text('active = "all_openai"\n', encoding="utf-8")++ assert self._active_profile_name() == "all_openai"diff --git a/tests/unit/pipelex/migration/test_config_dir_gitignore.py b/tests/unit/pipelex/migration/test_config_dir_gitignore.pyindex 405727245..47a400e3c 100644--- a/tests/unit/pipelex/migration/test_config_dir_gitignore.py+++ b/tests/unit/pipelex/migration/test_config_dir_gitignore.py@@ -9,11 +9,14 @@ from datetime import UTC, datetimefrom fnmatch import fnmatchfrom pathlib import Path+import pytest+from pipelex.cli.commands.init.config_files import init_configfrom pipelex.migration.backup import backup_path_for, rescue_path_forfrom pipelex.migration.gitignore import (BACKUP_IGNORE_PATTERN,CONFIG_DIR_GITIGNORE_NAME,+ PERSONAL_OVERRIDE_IGNORE_PATTERNS,ensure_config_dir_gitignore,)from pipelex.migration.run import migrate_config_directories@@ -81,6 +84,36 @@ class TestEnsureConfigDirGitignore:assert any(fnmatch("pipelex_override.toml.bak.20260818T121441Z", line) for line in written.splitlines() if line and not line.startswith("#"))+ @pytest.mark.parametrize(+ "relative_path",+ [+ "pipelex_override.toml",+ "pipelex_temporary_override.toml",+ "telemetry_override.toml",+ "inference/backends_override.toml",+ "inference/routing_profiles_override.toml",+ ],+ )+ def test_the_file_it_writes_ignores_every_personal_override(self, tmp_path: Path, relative_path: str) -> None:+ """A fresh project must not see a developer's own override in `git status`.++ Matched against the written file's rules, path and all: the inference overrides sit one+ directory down, so their rules carry the subdirectory and are anchored to this file.+ """+ ensure_config_dir_gitignore(directory=tmp_path)+ rules = [line for line in (tmp_path / CONFIG_DIR_GITIGNORE_NAME).read_text().splitlines() if line and not line.startswith("#")]++ assert any(fnmatch(relative_path, rule) for rule in rules)+ assert relative_path in PERSONAL_OVERRIDE_IGNORE_PATTERNS++ def test_the_file_it_writes_keeps_a_tracked_tier_file_visible(self, tmp_path: Path) -> None:+ """`pipelex_local.toml` and the environment tier are the project's, not a personal override."""+ ensure_config_dir_gitignore(directory=tmp_path)+ rules = [line for line in (tmp_path / CONFIG_DIR_GITIGNORE_NAME).read_text().splitlines() if line and not line.startswith("#")]++ for tracked_name in ("pipelex.toml", "pipelex_local.toml", "pipelex_dev.toml", "inference/backends.toml", "inference/routing_profiles.toml"):+ assert not any(fnmatch(tracked_name, rule) for rule in rules), tracked_name+def test_it_never_touches_a_gitignore_that_is_already_there(self, tmp_path: Path) -> None:"""Once the file exists it is a file in the user's repo, and theirs to maintain."""theirs = tmp_path / CONFIG_DIR_GITIGNORE_NAMEdiff --git a/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.py b/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.pyindex 219777e86..df6e19371 100644--- a/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.py+++ b/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.py@@ -7,6 +7,7 @@ from pathlib import Pathimport pytest+from pipelex.cogt.exceptions import InferenceBackendLibraryValidationErrorfrom pipelex.system.pipelex_service.pipelex_service_config import (PIPELEX_SERVICE_CONFIG_FILE_NAME,PipelexServiceAgreement,@@ -19,6 +20,13 @@ from pipelex.system.pipelex_service.pipelex_service_config import (class TestPipelexServiceConfig:"""Tests for PipelexServiceConfig and related functions."""+ def _write_backends(self, config_dir: Path, *, base: str, override: str | None = None) -> None:+ inference_dir = config_dir / "inference"+ inference_dir.mkdir(parents=True, exist_ok=True)+ (inference_dir / "backends.toml").write_text(base, encoding="utf-8")+ if override is not None:+ (inference_dir / "backends_override.toml").write_text(override, encoding="utf-8")+@pytest.mark.parametrize(("enabled_value", "expected"),[@@ -41,23 +49,63 @@ class TestPipelexServiceConfig:in a state the loader could not name: enabled with no specs, so refused as *"remote model specswere not provided"* on a strict boot, and silently dropped from the deck on a lenient one."""- backends_file = tmp_path / "backends.toml"- backends_file.write_text(f'[pipelex_gateway]\nenabled = {enabled_value}\napi_key = "x"\n', encoding="utf-8")+ self._write_backends(tmp_path, base=f'[pipelex_gateway]\nenabled = {enabled_value}\napi_key = "x"\n')- assert is_pipelex_gateway_enabled(backends_file_path=backends_file) is expected+ assert is_pipelex_gateway_enabled(config_dir=tmp_path) is expecteddef test_is_pipelex_gateway_enabled_defaults_to_enabled_when_the_key_is_absent(self, tmp_path: Path) -> None:"""No `enabled` key means enabled — the loader's default too."""- backends_file = tmp_path / "backends.toml"- backends_file.write_text('[pipelex_gateway]\napi_key = "x"\n', encoding="utf-8")+ self._write_backends(tmp_path, base='[pipelex_gateway]\napi_key = "x"\n')- assert is_pipelex_gateway_enabled(backends_file_path=backends_file) is True+ assert is_pipelex_gateway_enabled(config_dir=tmp_path) is Truedef test_is_pipelex_gateway_enabled_is_false_without_a_gateway_table(self, tmp_path: Path) -> None:- backends_file = tmp_path / "backends.toml"- backends_file.write_text('[openai]\napi_key = "x"\n', encoding="utf-8")+ self._write_backends(tmp_path, base='[openai]\napi_key = "x"\n')++ assert is_pipelex_gateway_enabled(config_dir=tmp_path) is False++ def test_is_pipelex_gateway_enabled_is_false_without_a_base_file(self, tmp_path: Path) -> None:+ """An override cannot stand in for the base: no document, no gateway."""+ inference_dir = tmp_path / "inference"+ inference_dir.mkdir(parents=True)+ (inference_dir / "backends_override.toml").write_text("[pipelex_gateway]\nenabled = true\n", encoding="utf-8")++ assert is_pipelex_gateway_enabled(config_dir=tmp_path) is False- assert is_pipelex_gateway_enabled(backends_file_path=backends_file) is False+ @pytest.mark.parametrize(+ ("base_enabled", "override_enabled", "expected"),+ [+ ("true", "false", False),+ ("false", "true", True),+ # The override is read with the same truthiness as the base.+ ("false", "1", True),+ ("true", "0", False),+ ],+ )+ def test_is_pipelex_gateway_enabled_reads_the_override_over_the_base(+ self, tmp_path: Path, base_enabled: str, override_enabled: str, expected: bool+ ) -> None:+ """The personal override is the loader's document too, so the gate must see it."""+ self._write_backends(+ tmp_path,+ base=f'[pipelex_gateway]\nenabled = {base_enabled}\napi_key = "x"\n',+ override=f"[pipelex_gateway]\nenabled = {override_enabled}\n",+ )++ assert is_pipelex_gateway_enabled(config_dir=tmp_path) is expected++ def test_is_pipelex_gateway_enabled_refuses_an_override_that_does_not_parse_with_the_librarys_class(self, tmp_path: Path) -> None:+ """A parse error must reach the boot as the library's refusal, which names the file, not as a raw `TomlError`."""+ inference_dir = tmp_path / "inference"+ inference_dir.mkdir()+ (inference_dir / "backends.toml").write_text("[pipelex_gateway]\nenabled = true\n")+ override_path = inference_dir / "backends_override.toml"+ override_path.write_text("[pipelex_gateway\nenabled = false\n")++ with pytest.raises(InferenceBackendLibraryValidationError) as refused:+ is_pipelex_gateway_enabled(config_dir=tmp_path)++ assert str(override_path) in str(refused.value)def test_gateway_config_default_terms_not_accepted(self) -> None:"""Test that gateway terms_accepted defaults to False."""diff --git a/tests/unit/pipelex/system/test_config_resolution.py b/tests/unit/pipelex/system/test_config_resolution.pyindex dbb519ede..08ed70009 100644--- a/tests/unit/pipelex/system/test_config_resolution.py+++ b/tests/unit/pipelex/system/test_config_resolution.py@@ -303,3 +303,116 @@ class TestConfigResolution:# Verify the path is valid and uses the correct separator for the platformassert global_dir.name == ".pipelex"assert global_dir.parent == fake_home++ def test_inference_file_paths_layer_the_overrides_over_the_resolved_base(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """Project base first, then the global override, then the project override — the last wins.++ The base is the project's file because it exists there; the global override still comes+ after it, so one machine-wide choice reaches a project that carries its own tracked base.+ """+ project_dir = tmp_path / "project"+ (project_dir / ".git").mkdir(parents=True)+ project_inference_dir = project_dir / ".pipelex" / "inference"+ project_inference_dir.mkdir(parents=True)+ (project_inference_dir / "backends.toml").write_text("[backends]")+ (project_inference_dir / "routing_profiles.toml").write_text("[routing]")+ global_home = tmp_path / "home"+ global_inference_dir = global_home / ".pipelex" / "inference"++ mocker.patch.object(Path, "cwd", return_value=project_dir)+ mocker.patch.object(Path, "home", return_value=global_home)++ loader = ConfigLoader()++ assert loader.backends_file_paths() == [+ project_inference_dir / "backends.toml",+ global_inference_dir / "backends_override.toml",+ project_inference_dir / "backends_override.toml",+ ]+ assert loader.routing_profiles_file_paths() == [+ project_inference_dir / "routing_profiles.toml",+ global_inference_dir / "routing_profiles_override.toml",+ project_inference_dir / "routing_profiles_override.toml",+ ]++ def test_inference_file_paths_fall_back_to_the_global_base_and_keep_both_overrides(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """A project with no inference files reads the global base, and its own override still layers last."""+ project_dir = tmp_path / "project"+ (project_dir / ".git").mkdir(parents=True)+ (project_dir / ".pipelex").mkdir(parents=True)+ global_home = tmp_path / "home"+ global_inference_dir = global_home / ".pipelex" / "inference"+ global_inference_dir.mkdir(parents=True)+ (global_inference_dir / "backends.toml").write_text("[backends]")++ mocker.patch.object(Path, "cwd", return_value=project_dir)+ mocker.patch.object(Path, "home", return_value=global_home)++ loader = ConfigLoader()++ assert loader.backends_file_paths() == [+ global_inference_dir / "backends.toml",+ global_inference_dir / "backends_override.toml",+ project_dir / ".pipelex" / "inference" / "backends_override.toml",+ ]++ def test_inference_file_paths_list_the_global_override_once_when_the_project_is_home(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """A project rooted at the home directory has one tier, not the same override twice."""+ home = tmp_path / "home"+ (home / ".git").mkdir(parents=True)+ inference_dir = home / ".pipelex" / "inference"+ inference_dir.mkdir(parents=True)+ (inference_dir / "backends.toml").write_text("[backends]")++ mocker.patch.object(Path, "cwd", return_value=home)+ mocker.patch.object(Path, "home", return_value=home)++ loader = ConfigLoader()++ assert loader.backends_file_paths() == [inference_dir / "backends.toml", inference_dir / "backends_override.toml"]++ def test_inference_file_paths_are_pinned_to_an_explicit_config_dir(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """With ``config_dir`` the sequence is that directory's base and its own override, nothing layered."""+ project_dir = tmp_path / "project"+ (project_dir / ".git").mkdir(parents=True)+ project_inference_dir = project_dir / ".pipelex" / "inference"+ project_inference_dir.mkdir(parents=True)+ (project_inference_dir / "backends.toml").write_text("[backends]")+ pinned_dir = tmp_path / "pinned"++ mocker.patch.object(Path, "cwd", return_value=project_dir)+ mocker.patch.object(Path, "home", return_value=tmp_path / "home")++ loader = ConfigLoader()++ assert loader.backends_file_paths(config_dir=pinned_dir) == [+ pinned_dir / "inference" / "backends.toml",+ pinned_dir / "inference" / "backends_override.toml",+ ]+ assert loader.routing_profiles_file_paths(config_dir=pinned_dir) == [+ pinned_dir / "inference" / "routing_profiles.toml",+ pinned_dir / "inference" / "routing_profiles_override.toml",+ ]++ def test_inference_file_paths_take_their_base_from_the_patchable_property(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The sequence's base is the public property, so a fixture that patches it redirects every reader.++ The integration fixtures boot on a routing document of their own by patching+ ``routing_profiles_file_path``; a sequence that resolved its base itself would read past+ the patch and boot those tests on the real file, silently, with the suite still green.+ """+ project_dir = tmp_path / "project"+ (project_dir / ".git").mkdir(parents=True)+ (project_dir / ".pipelex").mkdir(parents=True)+ patched_routing = tmp_path / "elsewhere" / "routing_profiles.toml"+ patched_backends = tmp_path / "elsewhere" / "backends.toml"++ mocker.patch.object(Path, "cwd", return_value=project_dir)+ mocker.patch.object(Path, "home", return_value=tmp_path / "home")+ mocker.patch.object(ConfigLoader, "routing_profiles_file_path", property(lambda _self: str(patched_routing)))+ mocker.patch.object(ConfigLoader, "backends_file_path", property(lambda _self: patched_backends))++ loader = ConfigLoader()++ assert loader.routing_profiles_file_paths()[0] == patched_routing+ assert loader.backends_file_paths()[0] == patched_backendsdiff --git a/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.py b/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.pynew file mode 100644index 000000000..aa67a10f6--- /dev/null+++ b/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.py@@ -0,0 +1,40 @@+"""A backends document that does not parse is a setup error naming the file, even when the gate reads it before the library does.++`RuntimeBoot` asks `is_pipelex_gateway_enabled` whether to fetch gateway specs before the backend library loads,+so a `backends_override.toml` with a stray quote used to surface there as a raw `TomlError` — outside every clause+the boot has for an unloadable library. The gate now raises the library's own refusal class, and this pins that+the boot turns it into the setup error the library's refusal gets.+"""++import pytest+from pytest_mock import MockerFixture++from pipelex.base_exceptions import PipelexSetupError+from pipelex.cogt.exceptions import InferenceBackendLibraryValidationError+from pipelex.pipelex import Pipelex+from pipelex.system.runtime import IntegrationMode, runtime_manager+++def _test_integration_mode() -> IntegrationMode:+ return IntegrationMode.CI if runtime_manager.is_ci_testing else IntegrationMode.PYTEST+++class TestRuntimeBootBackendsDocumentRefusal:+ def test_a_backends_document_that_does_not_parse_is_a_setup_error_that_names_the_file(self, mocker: MockerFixture) -> None:+ refusal = InferenceBackendLibraryValidationError(+ "Invalid inference backend library 'base' with overrides 'home/backends_override.toml': "+ "TOML parsing error in file 'home/backends_override.toml'"+ )+ mocker.patch("pipelex.runtime_boot.is_pipelex_gateway_enabled", side_effect=refusal)++ Pipelex.teardown_if_needed()+ try:+ with pytest.raises(PipelexSetupError) as raised:+ Pipelex.make(integration_mode=_test_integration_mode(), needs_inference=False)++ assert "home/backends_override.toml" in str(raised.value)+ assert raised.value.__cause__ is refusal+ finally:+ mocker.stopall() # the re-boot below must read the real gate+ Pipelex.teardown_if_needed()+ Pipelex.make(integration_mode=_test_integration_mode())diff --git a/tests/unit/pipelex/test_runtime_boot_routing_profile_refusals.py b/tests/unit/pipelex/test_runtime_boot_routing_profile_refusals.pynew file mode 100644index 000000000..c257dc157--- /dev/null+++ b/tests/unit/pipelex/test_runtime_boot_routing_profile_refusals.py@@ -0,0 +1,63 @@+"""The boot turns every refusal of the routing profile library into a setup error — with the class the loader raises.++Two `except` clauses in `RuntimeBoot` named `RoutingProfileLibraryNotFoundError` and+`RoutingProfileDisabledBackendError` while the loader raised `ModelManagerError` and+`RoutingProfileLibraryError`, so both were dead: a routing profile naming a disabled backend — the+half-written personal override, `active` flipped and the backend still off — reached the user as a+raw internal error instead of the setup error that says what to enable. The loader's own tests pin+what it raises; this module pins that the boot names those same classes. Rename one and both go red.+"""++import pytest+from pytest_mock import MockerFixture++from pipelex.base_exceptions import PipelexSetupError+from pipelex.cogt.exceptions import RoutingProfileDisabledBackendError, RoutingProfileLibraryError, RoutingProfileLibraryNotFoundError+from pipelex.pipelex import Pipelex+from pipelex.system.runtime import IntegrationMode, runtime_manager+++def _test_integration_mode() -> IntegrationMode:+ """The boot mode the session conftest uses, so a re-boot here matches the one it replaces."""+ return IntegrationMode.CI if runtime_manager.is_ci_testing else IntegrationMode.PYTEST+++class TestRuntimeBootRoutingProfileRefusals:+ @pytest.mark.parametrize(+ ("refusal", "expected_in_message"),+ [+ (+ RoutingProfileLibraryNotFoundError("Could not find routing profile library at 'x'"),+ "Config files are missing for the routing profile library",+ ),+ (+ RoutingProfileDisabledBackendError("Backend 'other', required for profile 'on_other' is not enabled"),+ "required for profile 'on_other' is not enabled",+ ),+ (RoutingProfileLibraryError("Active profile 'on_typo' not found in the routing profile library"), "Active profile 'on_typo' not found"),+ ],+ )+ def test_a_routing_profile_refusal_is_a_setup_error_that_keeps_the_loaders_account(+ self,+ mocker: MockerFixture,+ refusal: Exception,+ expected_in_message: str,+ ) -> None:+ """Injected at the seam the real loader fails through, `models_manager.setup`, one class per clause."""+ refusing_models_manager = mocker.Mock()+ refusing_models_manager.setup.side_effect = refusal++ Pipelex.teardown_if_needed()+ try:+ with pytest.raises(PipelexSetupError) as raised:+ Pipelex.make(+ integration_mode=_test_integration_mode(),+ needs_inference=False,+ models_manager=refusing_models_manager,+ )++ assert expected_in_message in str(raised.value)+ assert raised.value.__cause__ is refusal+ finally:+ Pipelex.teardown_if_needed()+ Pipelex.make(integration_mode=_test_integration_mode())diff --git a/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py b/tests/unit/pipelex/test_runtime_boot_stale_backend_error.pyindex ca0b51d5b..6c7f94e0d 100644--- a/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py+++ b/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py@@ -116,7 +116,7 @@ class TestAStaleBackendFileTheLedgerCannotFullyExplain:with pytest.raises(BACKEND_LIBRARY_REFUSED) as refused:library.load(secrets_provider=EnvSecretsProvider(),- backends_library_path=str(machine / INFERENCE_DIR_NAME / "backends.toml"),+ backends_library_paths=[machine / INFERENCE_DIR_NAME / "backends.toml"],backends_dir_path=str(machine / INFERENCE_DIR_NAME / BACKENDS_DIR_NAME),gateway_config=None,lenient=False,diff --git a/tests/unit/pipelex/tools/misc/test_toml_base_and_overrides.py b/tests/unit/pipelex/tools/misc/test_toml_base_and_overrides.pynew file mode 100644index 000000000..c9dfa6997--- /dev/null+++ b/tests/unit/pipelex/tools/misc/test_toml_base_and_overrides.py@@ -0,0 +1,66 @@+"""`load_toml_from_base_and_overrides`: the first path is the document, the rest are optional layers."""++from pathlib import Path++import pytest++from pipelex.tools.misc.toml_utils import load_toml_from_base_and_overrides+++class TestLoadTomlFromBaseAndOverrides:+ def test_the_base_alone_is_the_document(self, tmp_path: Path) -> None:+ base = tmp_path / "base.toml"+ base.write_text('[acme]\nenabled = false\nname = "Acme"\n')++ merged = load_toml_from_base_and_overrides(paths=[base, tmp_path / "absent_override.toml"])++ assert merged == {"acme": {"enabled": False, "name": "Acme"}}++ def test_a_missing_base_raises_even_when_an_override_exists(self, tmp_path: Path) -> None:+ """An override carries only the keys it sets, so it cannot stand in for the document."""+ override = tmp_path / "override.toml"+ override.write_text("[acme]\nenabled = true\n")++ with pytest.raises(FileNotFoundError):+ load_toml_from_base_and_overrides(paths=[tmp_path / "absent_base.toml", override])++ def test_an_override_merges_into_the_base_table_and_keeps_its_other_keys(self, tmp_path: Path) -> None:+ base = tmp_path / "base.toml"+ base.write_text('[acme]\nenabled = false\nname = "Acme"\n\n[other]\nenabled = true\n')+ override = tmp_path / "override.toml"+ override.write_text("[acme]\nenabled = true\n")++ merged = load_toml_from_base_and_overrides(paths=[base, override])++ assert merged == {"acme": {"enabled": True, "name": "Acme"}, "other": {"enabled": True}}++ def test_later_overrides_win_over_earlier_ones(self, tmp_path: Path) -> None:+ base = tmp_path / "base.toml"+ base.write_text('active = "base"\n')+ first = tmp_path / "first.toml"+ first.write_text('active = "first"\n')+ second = tmp_path / "second.toml"+ second.write_text('active = "second"\n')++ merged = load_toml_from_base_and_overrides(paths=[base, first, second])++ assert merged["active"] == "second"++ def test_a_list_is_replaced_not_extended(self, tmp_path: Path) -> None:+ """`deep_update` semantics: tables merge, everything else — lists included — is replaced whole."""+ base = tmp_path / "base.toml"+ base.write_text('[profile]\nfallback_order = ["a", "b"]\n')+ override = tmp_path / "override.toml"+ override.write_text('[profile]\nfallback_order = ["c"]\n')++ merged = load_toml_from_base_and_overrides(paths=[base, override])++ assert merged["profile"]["fallback_order"] == ["c"]++ def test_a_bare_path_is_refused(self, tmp_path: Path) -> None:+ """A single path where a sequence is expected would be iterated character by character."""+ base = tmp_path / "base.toml"+ base.write_text("[acme]\n")++ with pytest.raises(TypeError):+ load_toml_from_base_and_overrides(paths=base) # type: ignore[arg-type]diff --git a/wip/inference-config-overrides/plan.md b/wip/inference-config-overrides/plan.mdnew file mode 100644index 000000000..deaa38a7a--- /dev/null+++ b/wip/inference-config-overrides/plan.md@@ -0,0 +1,64 @@+---+status: active+item: L-260903-9fe4ad+---++# Override files for `backends.toml` and `routing_profiles.toml`++## Problem++The two inference documents, `.pipelex/inference/backends.toml` and `.pipelex/inference/routing_profiles.toml`, each resolved to exactly one file (the project's copy if it existed, otherwise `~/.pipelex/`) and were read whole. A developer who wanted to live on a non-default backend had to flip `[<backend>] enabled` and `active = "<profile>"` in two tracked files the kit mirrors, in every worktree and every sibling project: per-checkout dirt flagged by `check-config-sync`, one `git add -A` away from shipping a personal choice as the default. The concrete need was the manifold beta, which is not on `dev` yet; the mechanism is generic and was built and verified against the backends that are.++## Decisions++1. **Merge sequence is `[resolved base, global override, project override]`.** The base keeps winner-takes-all resolution; the overrides layer over it, global then project. This is deliberately not `pipelex.toml`'s order, where a project base beats a global override: every project carries a tracked `backends.toml`, so a project base that won would defeat a machine-wide override. With an explicit `config_dir` (doctor `--global`, an init targeting one directory) the sequence is that directory's base and its own override, mirroring `load_config(config_dir=)`.+2. **Two files, no environment variants, no `${VAR}` on `enabled` or `active`** — both are read raw before substitution and a non-empty placeholder string is truthy.+3. **An override carries only the keys it sets.** `deep_update` semantics: tables merge, scalars and lists replace. The merge runs before validation, which is what makes `active = "…"` alone a complete override of a document whose `active` field is required.+4. **One path sequence, one loader, every reader.** `ConfigLoader.backends_file_paths()` / `routing_profiles_file_paths()` build the sequence; `load_toml_from_base_and_overrides` reads it (base required, overrides optional); the backend library, the routing loader, `ModelManager.setup`, `is_pipelex_gateway_enabled`, `pipelex show backends` and the doctor's three probes all go through them. No caller builds `config_dir / "inference" / "backends.toml"` by hand any more.+5. **Writers keep writing the base.** The init flow's backend and routing editors read and write the base file only: their checkboxes must pre-fill from the file they will write, or a personal override would leak into the tracked file on save. `check_is_initialized` checks the base for the same reason. The one init reader that mirrors the boot, the cache-priming gate, reads the merged document.+6. **Skip lists get the two bare names.** `GIT_IGNORED_CONFIG_FILES` is matched by basename at every depth by the kit mirror, `check-config-sync`, `pipelex init` and the global bootstrap copy, so two names there cover all four.+7. **Gitignore in both places.** The repo's root `.gitignore` names the two files bare, like `pipelex_override.toml`. The `.pipelex/.gitignore` writer gains one line per personal override file — the two new ones and the three existing ones it never listed — so a fresh `pipelex init` project is safe by default; its create-if-absent contract is untouched, so projects set up earlier add the names to their own root `.gitignore` (filed for the cookbook and `pipelex-server`'s `worker`).+8. **The migration ledger is untouched.** The registry never enters `.pipelex/inference/` itself, only `inference/backends/`, so the overrides are outside every surface like their base files. One comment in `surfaces.py` says so.+9. **Two dead boot catches fixed on the way.** `RuntimeBoot` caught `RoutingProfileLibraryNotFoundError` and `RoutingProfileDisabledBackendError`, which the routing loader never raised (it raised `ModelManagerError` and `RoutingProfileLibraryError`), so the half-written override — `active` flipped, the backend still off — surfaced as a raw `CogtError`. The loader now raises the classes the boot names, keeps `RoutingProfileLibraryError` for an invalid document or an unknown `active`, and the boot gained a clause for that one too.+10. **`InferenceBackendLibrary.check_backend_credentials` deleted**, with `CredentialsValidationReport`: zero callers, and a raw reader of the base file that would have ignored the overrides.++## Steps++1. Constants, `_inference_file_paths`, `backends_file_paths` / `routing_profiles_file_paths` on `ConfigLoader`; `load_toml_from_base_and_overrides` and `describe_toml_base_and_overrides` in `toml_utils`.+2. Loaders and callers: `backend_library.py`, `routing_profile_loader.py`, `model_manager.py`, `pipelex_service_config.py`, `init/command.py`, `doctor_cmd.py`, `show_cmd.py`, `runtime_boot.py`.+3. `kit/paths.py`, root `.gitignore`, `.worktreeinclude`, `migration/gitignore.py`, `surfaces.py` comment, `config_check.py` comment, `init/backends.py` docstring.+4. Tests: the helper, the path sequence, both loaders' override modules, the gate, the doctor probes, the sync exclusion, the written `.gitignore`, the boot clauses through an injected models manager, and an end-to-end module against the global `config_manager` with the kit tree in a faked home.+5. Docs: `inference-backend-config.md` (tree, "Personal overrides", "Custom deck files", loading process), `features/configuration.md`, `contribute/configuration-defaults-and-overrides.md`, `under-the-hood/init-cli-flows.md`, `migration-ledger.md`, `configuration/index.md`, `tools/cli/show.md`; the two drift acks.+6. Changelog under `[Unreleased]`: Added, Changed (breaking loader signatures and exception classes), Removed.+7. `make agent-check`, the targeted suites, `make agent-test`; a manual run in a scratch `HOME` and a project-tier override in this worktree with `git status` and `make check-config-sync` clean.+8. PR against `dev`, `Closes L-260903-9fe4ad`; `/ledger-land` after the merge.++## Out of scope++- `backends_dir_path` and `deck_dir_path` stay single-directory `str` parameters; the per-backend files and the deck have their own mechanisms (the ledger, the manifest) and no override layer.+- The CLI's hint texts still send a user to `.pipelex/inference/backends.toml` to enable or disable a backend. That is still the right file for most users; an override-aware hint is a wording change for later.+- A `pipelex_service.toml` line in the written `.pipelex/.gitignore`: it is not an override and this repo ignores it by path.++## Revisions++- 2026-09-03, while implementing: decision 9 was planned as a fix "on the way" and turned out to need a third clause, because an `active` naming no profile — the likeliest typo in an override — was still `ModelManagerError`, which no clause named. The loader keeps `RoutingProfileLibraryError` for that case and the boot catches it through the same validation-message builder the other libraries use.++- 2026-09-03, pre-landing review of the PR: the sequence's base now comes from the `backends_file_path` / `routing_profiles_file_path` property rather than a second `resolve_config_file` call, because four integration fixtures (and `pipelex-server`'s temporal one) pin a routing profile by patching that property and the sequence read past the patch — every such test booted on the real file, green. The in-repo fixtures now patch `routing_profiles_file_paths` whole, so a developer's personal override cannot layer over the pinned document either; the server fixture is noted on `L-260903-36002a`. Four review decisions taken: the loaders log the override files they merged (the one trace a machine-wide override leaves); a file that does not parse is the library's refusal, raised by the library, the routing loader and `is_pipelex_gateway_enabled` alike, so the boot names the file instead of a raw `TomlError` escaping before any clause; the doctor's Models row catches `RoutingProfileLibraryError`, the class the loader now raises for the likeliest override typo; and `pipelex init` gates the terms prompt on the merged document and warns when declining the terms disables the gateway in a base an override still pins on. A backend whose value is not a table (`acme = false`) is refused by name in both modes rather than crashing on `.copy()`.++## Checkpoint — 2026-09-03, paused with the full suite green, before the PR++Everything in the Steps list through step 7's targeted runs is in the tree on `feature/Inference-config-overrides` (worktree `_pipelex--inference-config-overrides`), and the ledger item is claimed and references this plan.++What is verified:++- `make agent-check` is green end to end, including both drift acks (`config-docs`, `cli-docs`, staged under `.drift/acks/`).+- The targeted suites (`tests/unit/pipelex/{system,cogt,cli,migration,tools,kit}/`, the two boot modules, `tests/integration/pipelex/cli/commands/init/`, `tests/integration/pipelex/system/`) pass — thousands of tests, one skip that predates this work.+- By hand, in a scratch `HOME` over this repository's tracked base: the two global overrides put `pipelex show backends` on `all_anthropic` with the gateway gone, `pipelex doctor` reports the merged view, deleting the two files restores `all_pipelex_gateway`. A project-tier `routing_profiles_override.toml` in this worktree is invisible to `git status`, passes `make check-config-sync`, activates `all_mistral`, and its removal restores the default.+- The ledger follow-ups for the sibling projects' `.gitignore` are filed: `L-260903-6b77c1` (cookbook) and `L-260903-36002a` (`pipelex-server`, member `worker`).++- `make agent-test` passed, with one failure that was this session's own doing and not a defect: the project-tier manual check above wrote `active = "all_mistral"` into this worktree's `routing_profiles_override.toml` while the suite was running in the background, and `tests/unit/pipelex/pipe_operators/pipe_llm/test_template_image_analyzer.py` booted inside that window with a deck holding only Mistral handles. The override reached a real boot, which is the feature working; the module re-run clean after the file was removed passes. Lesson for the manual checks: never write a project-tier override into a worktree while a suite runs in it.++Next session, in order:++1. `ledger claim L-260903-9fe4ad --renew`, then `make agent-check` once more (the formatter is idempotent now).+2. Open the PR against `dev` with `Closes L-260903-9fe4ad` in the body; `/ledger-land` after the merge.