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.
Two managed gateways: the manifold dialect, and the seams that stop assuming there is only one (#1165)
Louis Choquelefec1a8486ad
diff --git a/.badges/tests.json b/.badges/tests.jsonindex bb6e3c9d2..09409c99d 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "11149",+ "message": "11633","color": "blue","cacheSeconds": 300}\ No newline at end of filediff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 275d6f775..de642dbda 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:9537c65f6feb9ee29c70d74fd8419797288448e0627d106c7931002163d012ff"+digest = "sha256:3c08bd5d68b5a30d96399cbe4f28ddec9734f9a92023bbf951984ea2a13bb32d"reviewed_by = "Louis Choquel"-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."+reviewed_at = "2026-09-03T12:55:36Z"+rationale = "Merge of origin/dev into feature/Two-gateways-2, re-reviewed on the merged tree. The triggers are this branch's half of the resolution: doctor_cmd, init/backends.py and init/command.py all move from the single-file reader to the merged backends document dev introduced, while keeping this branch's broad question — any Pipelex-managed gateway backend rather than pipelex_gateway by name. Concretely: the doctor's Models row now calls enabled_managed_gateway_sections(config_dir=...) inside dev's parse-error clause, so a broken override still answers as a Models-row failure and no row, flag, output key or exit code moved; init gates the terms prompt on the merged document via the same broad reader; and dev's override warning is generalized to warn_if_managed_gateway_pinned_by_override, which now names which managed backends an override still keeps enabled instead of naming the gateway alone. Reviewed docs/tools/cli/: init.md already states the broad terms rule for pipelex_gateway and pipelex_manifold and the cache-priming sentence already says any managed gateway backend, show.md already names both personal override files, and there is no doctor page there, so nothing under that directory is stale. pipelex/cli/agent_cli/CLAUDE.md documents init at the level of its flags and formats, none of which moved. Outside the declared targets I did update the two pages that describe the warning by name: under-the-hood/init-cli-flows.md and config-technical/inference-backend-config.md now state the broad reader and the renamed function."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -25,7 +25,7 @@ rationale = "Review round: doctor catches RoutingProfileLibraryError and a broke"pipelex/cli/agent_cli/commands/fix/app.py" = "blob:e6190d9bde6a05755c04bd21806f699461038ac0""pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:37b13a1ead7b55d601f53b23647c285fc85418cd""pipelex/cli/agent_cli/commands/fmt_cmd.py" = "blob:97d6fb6c328e0b718b1293bd6b73cba03edcb7dc"-"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:56093bbbd43dd478a058e45b69ae70b4ce3c6930"+"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:2ac42caed527dcd58c6acd82e2b697acefcfe046""pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:d37826d96099028a1ad5dbc5cbf8ce0cfdb01e30""pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"@@ -82,7 +82,7 @@ rationale = "Review round: doctor catches RoutingProfileLibraryError and a broke"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:73ac79646eee18d68df2f22d24c9fa3b9937c310"+"pipelex/cli/commands/doctor_cmd.py" = "blob:bf1ab5ce97647b91d6a79534250fcc60d726d71e""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 = "Review round: doctor catches RoutingProfileLibraryError and a broke"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:c22b74b29f0ff4d7f90072c8068247dfb4109e36"-"pipelex/cli/commands/init/command.py" = "blob:2aafd4493c7f94da0a320dac06465e88a761d858"+"pipelex/cli/commands/init/backends.py" = "blob:7823d8f323e826e36ca389bf3491576723786163"+"pipelex/cli/commands/init/command.py" = "blob:cc3449142cd39d6276a7b420f30e4ad0b0611409""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"@@ -127,7 +127,7 @@ rationale = "Review round: doctor catches RoutingProfileLibraryError and a broke"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:d67267571559006459628180f2c8b216ba7fee31""pipelex/cli/commands/which_cmd.py" = "blob:68661d4bab22e2c4dab183d59bd9f2c6dd573472""pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"-"pipelex/cli/error_handlers.py" = "blob:7a925ef0517bf9b01c3ca4b91ae54a70f57123a6"+"pipelex/cli/error_handlers.py" = "blob:41f33d7eae4d583f380f3ec34637733b0ca9d840""pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a""pipelex/cli/installed_methods.py" = "blob:09197f47baf8d7251d28d148a0544b4a23ee7365""pipelex/cli/method_resolver.py" = "blob:1230dde5f89ac28bbdcbcbbd0c1d485c71803caf"diff --git a/.env.example b/.env.exampleindex 6bc81c487..ad710cc16 100644--- a/.env.example+++ b/.env.example@@ -3,6 +3,13 @@# … No credit card required, time-limited offerPIPELEX_GATEWAY_API_KEY=+# [OPTIONAL] Pipelex Manifold — the Pipelex-operated inference service, currently in private beta.+# The endpoint is the service ORIGIN: scheme, host and port, with no "/v1" and no trailing path.+# Leave both blank unless you are in the beta: the backend ships disabled in backends.toml, and+# filling these in without enabling it there does nothing.+PIPELEX_MANIFOLD_ENDPOINT=+PIPELEX_MANIFOLD_API_KEY=+# OpenAI: to use models like GPT-4o and GPT-5OPENAI_API_KEY=diff --git a/.pipelex-dev/test_profiles.toml b/.pipelex-dev/test_profiles.tomlindex 1466342a7..18d88873a 100644--- a/.pipelex-dev/test_profiles.toml+++ b/.pipelex-dev/test_profiles.toml@@ -297,6 +297,31 @@ img_gen_models = ["gpt-image-1-mini"]extract_models = ["@from_pdf", "linkup-fetch"]search_models = ["linkup-standard"]+################################################################################+# Manifold Profile+################################################################################+# The `dev` profile's shape, served by Pipelex Manifold instead of the Pipelex+# Gateway. Deliberately not a copy of `dev`: the two catalogs are allowed to+# diverge, so this names what the manifold section actually serves. `linkup` is+# absent from it, and `@from_pdf` is not used because most of that collection is+# other backends' — the manifold text extractors are named directly.+#+# The three LLMs are chosen to cover all three of the dialect's completion SDKs+# in one run: `claude-4.5-haiku` on `anthropic` (POST /v1/messages),+# `gpt-4o-mini` on `manifold_responses`, `gemini-2.5-flash-lite` on+# `manifold_completions`.+[profiles.manifold]+description = "The dev model set, served by Pipelex Manifold (private beta)"+backends = ["pipelex_manifold", "internal"]+llm_models = [+ "claude-4.5-haiku",+ "gpt-4o-mini",+ "gemini-2.5-flash-lite",+]+img_gen_models = ["gpt-image-1-mini"]+extract_models = ["azure-document-intelligence", "linkup-fetch"]+search_models = ["linkup-standard"]+################################################################################# Coverage Profile################################################################################diff --git a/.pipelex/inference/backends.toml b/.pipelex/inference/backends.tomlindex 13495a407..eb2803675 100644--- a/.pipelex/inference/backends.toml+++ b/.pipelex/inference/backends.toml@@ -15,6 +15,15 @@ display_name = "⭐ Pipelex Gateway"enabled = true # Enable after accepting terms via `pipelex init config`api_key = "${PIPELEX_GATEWAY_API_KEY}"+# Pipelex Manifold is a closed private beta: leave it off unless you have been invited.+[pipelex_manifold]+display_name = "Pipelex Manifold (private beta)"+enabled = false+endpoint = "${PIPELEX_MANIFOLD_ENDPOINT}"+api_key = "${PIPELEX_MANIFOLD_API_KEY}"+model_specs_section = "manifold_model_specs"+auth_header = "x-pipelex-api-key"+[anthropic]enabled = trueapi_key = "${ANTHROPIC_API_KEY}"diff --git a/.pipelex/inference/backends/pipelex_manifold.toml b/.pipelex/inference/backends/pipelex_manifold.tomlnew file mode 100644index 000000000..1a9adc718--- /dev/null+++ b/.pipelex/inference/backends/pipelex_manifold.toml@@ -0,0 +1,56 @@+################################################################################+# Pipelex Manifold Local Overrides+################################################################################+#+# PRIVATE BETA:+#+# Pipelex Manifold is the Pipelex-operated inference service. It is in private+# beta, it ships disabled in backends.toml, and this file does nothing until you+# enable it there and set PIPELEX_MANIFOLD_ENDPOINT and PIPELEX_MANIFOLD_API_KEY.+#+################################################################################+#+# TELEMETRY NOTICE:+#+# Enabling pipelex_gateway alongside this backend enables identified telemetry+# from your machine, tied to your Pipelex Gateway API key (hashed for security).+# This is independent from your telemetry.toml settings.+#+# That client-side telemetry follows the gateway key and nothing else, so an+# installation running Pipelex Manifold ALONE sends none of it. Manifold is a+# Pipelex-operated service, though, so your usage of it is recorded server-side+# the way any hosted platform records the calls it serves.+#+# Either way we collect only technical data (model names, token counts, latency,+# error rates). We do NOT collect prompts, completions, pipe codes, or business+# data.+#+# This allows us to monitor service quality, enforce fair usage, and support you.+#+################################################################################+#+# WARNING: USE AT YOUR OWN RISK!+#+# The actual model configuration is fetched remotely from Pipelex servers.+# Any override in this file may cause unexpected behavior or failures,+# as the remote configuration may change at any time.+#+# If you must override, you may ONLY use these keys per model:+# - sdk+# - structure_method+#+# All other keys will be ignored.+#+# If you need custom configurations, consider using your own API keys+# with direct provider backends (openai, anthropic, etc.) instead.+#+# Documentation:+# https://docs.pipelex.com/latest/configuration/config-technical/inference-backend-config/+# Support: https://go.pipelex.com/discord+#+################################################################################++# Per-model overrides example:+# [gpt-4o]+# sdk = "manifold_completions"+# structure_method = "instructor/openai_tools"diff --git a/.pipelex/inference/routing_profiles.toml b/.pipelex/inference/routing_profiles.tomlindex 8b5d7d4c2..2fd6781aa 100644--- a/.pipelex/inference/routing_profiles.toml+++ b/.pipelex/inference/routing_profiles.toml@@ -28,6 +28,13 @@ active = "all_pipelex_gateway"description = "Use Pipelex Gateway for all its supported models"default = "pipelex_gateway"+# The same model names, served by the Pipelex-operated inference service instead. Switching between+# this profile and the one above needs no other edit: a model's wire id and sdk are per-backend, so+# decks, aliases and presets keep naming the same handles.+[profiles.all_pipelex_manifold]+description = "Use Pipelex Manifold (private beta) for all its supported models"+default = "pipelex_manifold"+[profiles.all_anthropic]description = "Use Anthropic backend for all its supported models"default = "anthropic"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c3b53a130..504c2353e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -25,13 +25,19 @@- **`pipelex-dev generate-projection-corpus`**: The generator of the shared fixture corpus that pins the two client-side inputs-template projections — the TypeScript one in `mthds` and its Python twin — against each other. Each client SDK now renders a pipe's fill-in template from the input-form descriptor it already has instead of asking a server for one, so the two renderings have to agree exactly, TOML `# concept:` comment lines included. The command pairs each pipe's descriptor with the expected template in both shapes (compact and explicit) and both formats (JSON and TOML), and records where that expectation deliberately differs from this engine's own inputs-template renderer: the expectation is authored from a reference projection that walks the descriptor, where the engine reflects the runtime content classes. Each class of difference is declared rather than discovered — an undeclared one fails the run, and so does a declared one that no longer occurs, so an engine fix retires its entry deliberately. A new corpus bundle covers what the existing probe bundles did not: a text field merely named `url` beside a real file position, optional file fields nested inside a structure, and both a fixed `[N]` and a variable `[]` slot over a structured concept. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **The projection corpus round-trips every template it pins through the input shaper**: `pipelex-dev generate-projection-corpus` now hands each projected template straight back to the runtime — both shapes, assembled exactly as an entry-pipe run assembles a caller's inputs — because a fill-in template exists to be filled in and run, and nothing checked that before. Twice the corpus pinned slots the runtime rejects outright and a human review round caught it rather than the capture; the second time the divergence gate absorbed the broken sites into a declared class and exited zero, since "differs from the engine" and "the engine refuses this value" are different questions. The verdict follows the same declared-never-discovered discipline as the divergence record, through an `EXPECTED_UNSHAPEABLE` registry mapping a pipe and shape to the item tracking the gap: an undeclared refusal fails the command naming the pipe, shape and error, a declared entry whose template has started shaping fails it too so a fix retires its declaration deliberately, and a declared one is stated in the manifest as an `unshapeable` entry carrying the contract-stable error class and its ledger item — so a known-open gap is recorded rather than blocking the capture. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).- **Include a method by address — fetch-on-miss**: a bundle referencing another method by address (`github.com/...->domain.pipe`) that misses the installed methods now fetches the package by reference — honoring an `@<tag>` pin, through the same grammar, bounds, and tags-only rules as a direct fetch, with the same hosted-parity warning for Python structure classes locally and a hard refusal on sandbox-hosted deployments — installs it into `~/.mthds/methods/` (atomic staging write, `.git/` stripped, fetch provenance recorded beside the manifest in a `.provenance.json` sidecar: address, tag, and the resolved commit SHA), and loads it so resolution proceeds. Once installed, the method is reused and the network is never touched again — including for a reference pinning a different tag, which warns and uses the installed copy. The former silent-miss warning in the library manager is now a real diagnostic: a miss that cannot be bridged (fetch disabled via the new `[interpreter.methods] fetch_on_miss` config or the `PIPELEX_METHODS_FETCH_ON_MISS` environment variable, an unfetchable address, or a failed fetch) raises an error naming the address and the remedy, never a silent pass. The install target is guarded by identity: two packages sharing a bare directory name but coming from different addresses collide with a loud error naming both addresses (never a silent load of the wrong package, never an overwrite), a concurrent install of the same package is tolerated (each attempt stages under a unique dot-prefixed directory, and losing the final rename race to a matching occupant uses the winner's copy), and a fetched package containing a symlink is refused outright, since a link's target would bypass the content scans. Installed-method lookup by full address is now case-insensitive, matching GitHub's owner/repository semantics and the fetch path's manifest-identity matching, and discovery skips dot-prefixed directories. See [Packages → Include by Address](building-methods/packages.md) and [Methods Configuration](configuration/config-practical/methods-config.md).+- **Pipelex Manifold, a second Pipelex-operated inference backend (private beta)**: `pipelex_manifold` joins `pipelex_gateway` in `backends.toml`, declared with `endpoint = "${PIPELEX_MANIFOLD_ENDPOINT}"` and `api_key = "${PIPELEX_MANIFOLD_API_KEY}"`, and a matching `all_pipelex_manifold` routing profile ships beside `all_pipelex_gateway`. It is **shipped disabled**, because a backend's `enabled` flag is read before any `${…}` variable is resolved — the boot has to know which managed backends are live in order to know which sections of the published configuration to read — so an installation that has not joined the beta would otherwise warn on every boot about a section it never asked for. The two services share model handles and differ only in the wire id and sdk each names, so decks, aliases and presets need no edit to move between them: switching profile is the whole change. A new provider package supplies the sdk set the manifold catalog names (`manifold_completions`, `manifold_responses`, `manifold_img_gen`, `manifold_extract`, `manifold_search`), with Claude travelling over the shared Anthropic driver rather than a manifold-specific one. Its endpoint rule is normative and has no fallback: the backend declares the service **origin with no `/v1`**, each client appends what it expects beneath it, and an endpoint that resolves to nothing disables the backend rather than defaulting to any other vendor's URL. Extract and search reach the service on its own routes rather than dressed as chat completions, and translate the counts those routes report into the token units the cost model prices, so the same work reports the same cost figure under either service. The service token travels on one header of the dialect's own, `x-pipelex-api-key`, on every protocol: the OpenAI-substrate factories and the native client set it directly, and the shared Anthropic driver reads it from the backend's `auth_header` field.+- **The gateway's request-shape refusals are classified**: the Pipelex inference gateway bounds what a request may weigh and how deeply it may nest, and refuses anything over those bounds itself — before authentication, before a provider sees the request. Those refusals now have a class in `classify_inference_error` instead of falling through the generic status ladder, so a caller who sent something too large reads *the request was too large for the inference gateway* rather than *the provider rejected the request*: a body over its cap and a storage object over its cap are caller-fixable size errors, a body nesting past the depth limit asks for a flatter structure, and a body whose declared size the gateway cannot read is an operator's problem, not the caller's. None is ever retried — an identical retry earns an identical refusal. The refusal is matched on the gateway's own error code and not on the reporting provider, because the same request reaches the gateway through the Portkey substrate, through plain `httpx` on the native extract and search routes, and through the shared Anthropic driver that Claude travels on. The same refusal can arrive under two codes, because the gateway renders it in the vocabulary of the route it came in on — its own `pig-0N` family on the LLM routes, its frozen `pipelex_*` contract codes on the native extract and search routes — so a file over its cap is recognized under both spellings and gives the caller the same remedy either way. Reading those contract codes at all required inverting one precedence: the native-route envelope puts a generic `invalid_request_error` in `error.type` beside the real code in `error.code`, so the two Pipelex-service Extract hops now read `code` first, which vendor hops do not (Anthropic's error section carries a `type` and no `code`). `ClassificationResult` gains a `gateway_request_limit` field and `ProviderErrorMetadata` the matching read-only property. Recognizing the code at all first required fixing where it is read on the Portkey substrate: that SDK's exception factory replaces the response payload with the refusal's message string, so `provider_error_code` came back empty for every error it raised — the code is now recovered from the response the SDK had already buffered. See [Error Model](under-the-hood/error-model.md).+- **The gateway's "cannot resolve this reference" refusals are classified**: a request may name a file rather than carry it — a `pipelex-storage://` key the Pipelex inference gateway resolves for the caller, or a document URL it fetches on their behalf — and when it cannot turn that reference into bytes it refuses the request itself. Every one of those refusals arrives on HTTP 400, so they all fell through the status ladder and told the caller to review the prompt: a mistyped storage key, an object this deployment cannot read, a URL the SSRF guard will not fetch from, a media type the pipeline does not accept — all one generic *the provider rejected the request*. They now have a class of their own beside the request-shape limits, and the members group by remedy rather than by wire code, so two codes share advice only when the caller's next move is the same. Three consequences are worth stating: a deployment that serves no storage references at all is an operator's problem and says so instead of asking the caller to fix an input that cannot help; a host the gateway refuses to fetch from is stated as the deliberate security policy it is, never as a fault to work around; and the LLM routes' single fail-closed slot for "cannot resolve" defers to the gateway's own message, which names which cause applied, rather than guessing. A URI whose scheme the route does not read is part of the family too, which is the refusal an `http://` document URL actually reaches. Like the request limits, none of them is ever retried — the gateway refused before a provider saw the request — and recognition keys on the gateway's own error code rather than on the reporting provider, since the same refusal reaches the runtime through the Portkey substrate, through plain `httpx` on the native extract and search routes, and through the shared Anthropic driver that Claude travels on. `ClassificationResult` gains a `gateway_unresolved_reference` field and `ProviderErrorMetadata` the matching read-only property. See [Error Model](under-the-hood/error-model.md).+- **The gateway's routing refusals are classified**: before a request can reach a provider the Pipelex inference gateway has to decide *which* provider — it reads the model out of the request, looks it up in its own routing table, and hands the call to the integration that serves it. When that resolution fails there is nowhere to send the request, so the gateway refuses it itself, and every one of those refusals arrives on HTTP 400. They therefore fell through the status ladder and read as a provider rejecting the caller's content: someone who named a model the deployment does not serve was told *the provider rejected the request — review the prompt, parameters, and inputs*, and received an `LLMCompletionError` rather than the `LLMModelNotFoundError` that case has always produced when the model deck itself cannot find a model. They now have a class of their own beside the request-shape limits and the unresolvable references, and it is `CONFIGURATION` throughout — nothing about the prompt, the parameters or the inputs causes any of them, and no edit to those avoids one. A model the gateway does not serve is a missing model and now renders as one, carrying the model handle so the pipe layer raises the same availability error it raises for a deck that cannot find a model. A model whose integration is switched off for want of a credential is the gateway operator's problem, not the caller's, so it says contact support rather than sending someone to rotate their own perfectly valid key or to go shopping for a different model. A model served over another protocol, or by an integration that does not serve the capability asked of it, is neither of those: the model exists and is served, so the advice says to change the model or the model deck and never claims the model was not found. Two of the gateway's routing codes stay deliberately outside the family, since no client that talks to one of our gateways produces either today — one refuses client-side routing forms our clients do not send, the other a path the gateway does not mount. Like the two families beside it none of these is ever retried, and recognition keys on the gateway's own error code rather than on the reporting provider. **Breaking for HTTP consumers**: moving the family from `CONTENT` to `CONFIGURATION` moves its domain from `INPUT` to `CONFIG`, so all four now answer **500** rather than 422 on any surface built on `ErrorReport.http_status` — the same answer a missing model has always drawn from the status ladder's 404 arm, and the right one in kind, but it puts these in server-error alerting and hands outer clients a status they retry. `ClassificationResult` gains a `gateway_routing_refusal` field and `ProviderErrorMetadata` the matching read-only property. See [Error Model](under-the-hood/error-model.md).+- **Per-model local overrides for any Pipelex-managed backend**: `backends/pipelex_manifold.toml` works exactly as `backends/pipelex_gateway.toml` does — the override file is found by the backend's own name, and neither file can reach the other's models. The permitted keys stay `sdk` and `structure_method`, deliberately identical across both: the model id is what the service resolves a request against, so overriding it locally turns a catalog problem into a single-machine one.### 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`.-+- **A Pipelex-managed inference backend is now anything that declares a model-specs section, not one hard-coded name (Breaking)**: The runtime used to know exactly one managed gateway, by name, in a dozen places. Naming a `model_specs_section` in a backend declaration is now what makes a backend managed, more than one can be live at once, and the single published configuration is fetched once and sliced into one per-backend view rather than merged — a handle one service serves and the other does not is a legitimate configuration, not a conflict. The deck-integrity check runs once per live managed service, and asks its section only about the handles the active routing profile actually routes there, because a union across services would accept a handle routed somewhere that cannot serve it while the same whole-deck check run twice would demand every handle appear under both. Whether the deck already resolved a handle stays a whole-waterfall question, since a waterfall's fallbacks may cross backends and the runtime walks the list until one resolves — restricting that half too would refuse a mixed-profile deck the runtime serves perfectly well. `pipelex_gateway` keeps reading its historical section without declaring it, since `backends.toml` is the user's own file and an upgrade never rewrites it. A managed backend whose `${…}` variables do not resolve, or whose declared section is absent from the published configuration, is **disabled with a warning naming it**; every bring-your-own-key backend keeps failing the boot loudly, which is the point of scoping the tolerance rather than granting it globally — a typo'd `ANTHROPIC_API_KEY` must not become a silently missing backend. Breaking: `is_gateway_backend` is gone, the backend loader takes `managed_gateway_configs` instead of a single gateway config, and `GatewayUnknownModelError` now names the backend it came from, reusing the attribution slot `CogtError` already carries.+- **Service terms are asked for any managed gateway backend, not for `pipelex_gateway` by name**: the boot puts an installation behind service-terms acceptance as soon as any Pipelex-managed gateway backend is enabled, and the init flows now ask that same question. Selecting only `pipelex_manifold` — through the interactive picker, through `pipelex-agent init --config`, or by enabling it by hand — prompts for the terms and records the acceptance, and `pipelex init agreement` reaches the prompt on such an installation instead of reporting that no acceptance is required. Acceptance stays a single global flag, so one answer covers every managed backend; declining now disables all of them rather than only the Portkey-cloud one. The offline cache priming step at the end of `pipelex init` asks the same question, so a manifold-only installation gets its offline fallback at init rather than at its first online boot.+- **Remote config pin moves to `pipelex_remote_config_13.json`**: version 13 is the first published artifact carrying `manifold_model_specs` beside `backend_model_specs`, so it is the first one a runtime reading the manifold section can be pointed at by default. Until now the beta reached that section only by overriding `PIPELEX_REMOTE_CONFIG_URL` at a locally served workbench artifact. The bump is inert for the Portkey-cloud path: version 13's `backend_model_specs`, `posthog` and `aws_region` compare identical to version 12's, so an installation with `[pipelex_manifold]` disabled reads exactly what it read before. Earlier releases stay pinned to `_12`, which is frozen.- **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.diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.mdindex 8411186f7..fe1305952 100644--- a/docs/configuration/config-technical/inference-backend-config.md+++ b/docs/configuration/config-technical/inference-backend-config.md@@ -635,7 +635,7 @@ 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.+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 a Pipelex-managed gateway backend is enabled on the merged document, so one switched on only by an override still gets the terms prompt; and when declining the terms disables those backends in the base while an override still pins one on, the command says so and names both the backend and the file to edit.### Custom deck filesdiff --git a/docs/errors/gateway-unknown-model-error.md b/docs/errors/gateway-unknown-model-error.mdindex a76a4a111..e19f8023b 100644--- a/docs/errors/gateway-unknown-model-error.md+++ b/docs/errors/gateway-unknown-model-error.md@@ -7,7 +7,7 @@ description: "Reference for the `GatewayUnknownModelError` Pipelex error class."# Gateway unknown model-A model handle referenced by the deck cannot be located in the active gateway specs.+A model handle the active routing profile sends to a managed gateway is absent from its specs.| Field | Value ||---|---|diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.mdindex 630b00e80..e9e43dbd6 100644--- a/docs/errors/inference-and-providers.md+++ b/docs/errors/inference-and-providers.md@@ -95,6 +95,13 @@ own page. Classes are grouped by subsystem.- [`LinkupError`](linkup-error.md) — Linkup- [`LinkupSearchEmptyResultError`](linkup-search-empty-result-error.md) — Linkup search empty result- [`LinkupSearchResponseError`](linkup-search-response-error.md) — Linkup search response+- [`ManifoldCredentialsError`](manifold-credentials-error.md) — Manifold credentials+- [`ManifoldEndpointError`](manifold-endpoint-error.md) — Manifold endpoint+- [`ManifoldError`](manifold-error.md) — Manifold+- [`ManifoldExtractResponseError`](manifold-extract-response-error.md) — Manifold extract response+- [`ManifoldFactoryError`](manifold-factory-error.md) — Manifold factory+- [`ManifoldSearchEmptyResultError`](manifold-search-empty-result-error.md) — Manifold search empty result+- [`ManifoldSearchResponseError`](manifold-search-response-error.md) — Manifold search response- [`MistralExtractResponseError`](mistral-extract-response-error.md) — Mistral extract response- [`MistralModelListingError`](mistral-model-listing-error.md) — Mistral model listing- [`MistralPluginError`](mistral-plugin-error.md) — Mistral plugindiff --git a/docs/errors/manifold-credentials-error.md b/docs/errors/manifold-credentials-error.mdnew file mode 100644index 000000000..9e6593aa3--- /dev/null+++ b/docs/errors/manifold-credentials-error.md@@ -0,0 +1,19 @@+---+title: "Manifold credentials"+description: "Reference for the `ManifoldCredentialsError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold credentials++| Field | Value |+|---|---|+| `error_type` | `ManifoldCredentialsError` |+| `title` | Manifold credentials |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-credentials-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`ManifoldError`](manifold-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/manifold-endpoint-error.md b/docs/errors/manifold-endpoint-error.mdnew file mode 100644index 000000000..aabc5cef3--- /dev/null+++ b/docs/errors/manifold-endpoint-error.md@@ -0,0 +1,21 @@+---+title: "Manifold endpoint"+description: "Reference for the `ManifoldEndpointError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold endpoint++The backend declares no usable endpoint for the Pipelex Manifold service.++| Field | Value |+|---|---|+| `error_type` | `ManifoldEndpointError` |+| `title` | Manifold endpoint |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-endpoint-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`ManifoldError`](manifold-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/manifold-error.md b/docs/errors/manifold-error.mdnew file mode 100644index 000000000..7ec333ece--- /dev/null+++ b/docs/errors/manifold-error.md@@ -0,0 +1,19 @@+---+title: "Manifold"+description: "Reference for the `ManifoldError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold++| Field | Value |+|---|---|+| `error_type` | `ManifoldError` |+| `title` | Manifold |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`CogtError`](cogt-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/manifold-extract-response-error.md b/docs/errors/manifold-extract-response-error.mdnew file mode 100644index 000000000..5c04fd348--- /dev/null+++ b/docs/errors/manifold-extract-response-error.md@@ -0,0 +1,19 @@+---+title: "Manifold extract response"+description: "Reference for the `ManifoldExtractResponseError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold extract response++| Field | Value |+|---|---|+| `error_type` | `ManifoldExtractResponseError` |+| `title` | Manifold extract response |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-extract-response-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`ManifoldError`](manifold-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/manifold-factory-error.md b/docs/errors/manifold-factory-error.mdnew file mode 100644index 000000000..f57728087--- /dev/null+++ b/docs/errors/manifold-factory-error.md@@ -0,0 +1,19 @@+---+title: "Manifold factory"+description: "Reference for the `ManifoldFactoryError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold factory++| Field | Value |+|---|---|+| `error_type` | `ManifoldFactoryError` |+| `title` | Manifold factory |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-factory-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`ManifoldError`](manifold-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/manifold-search-empty-result-error.md b/docs/errors/manifold-search-empty-result-error.mdnew file mode 100644index 000000000..c0acb457c--- /dev/null+++ b/docs/errors/manifold-search-empty-result-error.md@@ -0,0 +1,19 @@+---+title: "Manifold search empty result"+description: "Reference for the `ManifoldSearchEmptyResultError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold search empty result++| Field | Value |+|---|---|+| `error_type` | `ManifoldSearchEmptyResultError` |+| `title` | Manifold search empty result |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-search-empty-result-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`ManifoldError`](manifold-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/manifold-search-response-error.md b/docs/errors/manifold-search-response-error.mdnew file mode 100644index 000000000..858e2e1bd--- /dev/null+++ b/docs/errors/manifold-search-response-error.md@@ -0,0 +1,19 @@+---+title: "Manifold search response"+description: "Reference for the `ManifoldSearchResponseError` Pipelex error class."+---++<!-- pipelex:generated -->++# Manifold search response++| Field | Value |+|---|---|+| `error_type` | `ManifoldSearchResponseError` |+| `title` | Manifold search response |+| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-search-response-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.manifold.manifold_exceptions` |+| Parent class | [`ManifoldError`](manifold-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex ba32083b6..4c8fe33de 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -141,7 +141,7 @@ These commands do not have subcommands:Commands use different stdout formats depending on their purpose:-- **Markdown or JSON**: `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor` — markdown by default, JSON with `--format json`. Error format follows `--error-format` (defaults to `--format`'s value, so `--format json` flips both).+- **Markdown or JSON**: `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`, `migrate`, `codegen types`, `codegen check` — markdown by default, JSON with `--format json`. Error format follows `--error-format` (defaults to `--format`'s value, so `--format json` flips both).- **JSON or raw TOML**: `inputs` — structured JSON via `agent_success()` by default (`--format json`), or the raw TOML template printed directly to stdout with `--format toml`- **Raw TOML**: `concept`, `pipe` — TOML text printed directly to stdout- **Passthrough**: `fmt`, `lint` — raw `plxt` outputdiff --git a/docs/tools/cli/init.md b/docs/tools/cli/init.mdindex 699f723d0..e1a1aeafa 100644--- a/docs/tools/cli/init.md+++ b/docs/tools/cli/init.md@@ -50,7 +50,7 @@ pipelex init inference# Reconfigure telemetry settingspipelex init telemetry-# Review gateway terms+# Review the Pipelex service termspipelex init agreement```@@ -71,7 +71,7 @@ This command creates or resets a Pipelex config directory with:Every `init` target replaces the file with the template, so whatever was in it is gone. If a configuration file has simply fallen behind the current schema, [`pipelex migrate`](migrate.md) is the command: it rewrites the file in place and keeps every setting — your PostHog key, your Langfuse credentials, your exporters. `pipelex doctor` tells you which of the two you have.!!! note "Offline cache priming"- When Pipelex Gateway is enabled, `pipelex init` also primes an on-disk copy of the gateway's remote config at `~/.pipelex/cache/remote_config.json`. This lets later setup, validation, and dry-runs work even when the remote config service is briefly unreachable. If you run `pipelex init` while offline, it prints a yellow warning and skips priming — re-run it online to enable offline dry-runs.+ When any Pipelex-managed gateway backend is enabled, `pipelex init` also primes an on-disk copy of the published remote config at `~/.pipelex/cache/remote_config.json`. This lets later setup, validation, and dry-runs work even when the remote config service is briefly unreachable. If you run `pipelex init` while offline, it prints a yellow warning and skips priming — re-run it online to enable offline dry-runs.## Interactive Setup Flow@@ -110,9 +110,9 @@ All fields are optional:| Field | Type | Description ||-------|------|-------------|-| `backends` | `list[str]` | Backend keys to enable (e.g. `openai`, `anthropic`, `pipelex_gateway`). Omit to keep template defaults. |+| `backends` | `list[str]` | Backend keys to enable (e.g. `openai`, `anthropic`, `pipelex_gateway`, `pipelex_manifold`). Omit to keep template defaults. || `primary_backend` | `str` | Required only when 2+ backends are selected and `pipelex_gateway` is not among them. |-| `accept_gateway_terms` | `bool` | Required when `pipelex_gateway` is in backends. |+| `accept_gateway_terms` | `bool` | Required when any Pipelex-managed gateway backend (`pipelex_gateway`, `pipelex_manifold`) is in backends. The terms are the Pipelex service's, so one acceptance covers every managed backend. |Telemetry is not configured via `--config`: init seeds a `telemetry.toml` from a template (a global init writes an active one; a project init drops a commented-out one).diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex 69160aa0b..f58516fa3 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -237,8 +237,8 @@ The three steps live in three modules. Only the per-provider Extract functions s| Module | Step | What it owns ||--------|------|--------------|-| `pipelex/cogt/inference/error_classification.py` | Extract | `ProviderErrorMetadata`, `SDKErrorEnvelope`, `UserAction`, `UserActionKind`, the 12 `extract_*_metadata` functions, plus pure discriminators (`is_quota_exhaustion`, `is_content_policy_violation`, `is_network_error`) exposed as `@property` on the metadata |-| `pipelex/cogt/inference/error_classify.py` | Classify | `classify_inference_error()` — provider-blind mapping from `ProviderErrorMetadata` → `ClassificationResult(category, user_action_kind, is_model_not_found)` |+| `pipelex/cogt/inference/error_classification.py` | Extract | `ProviderErrorMetadata`, `SDKErrorEnvelope`, `UserAction`, `UserActionKind`, `GatewayRequestLimit`, `GatewayUnresolvedReference`, `GatewayRoutingRefusal`, the `extract_*_metadata` functions, plus pure discriminators (`is_quota_exhaustion`, `is_content_policy_violation`, `is_network_error`, `gateway_request_limit`, `gateway_unresolved_reference`, `gateway_routing_refusal`) exposed as `@property` on the metadata |+| `pipelex/cogt/inference/error_classify.py` | Classify | `classify_inference_error()` — provider-blind mapping from `ProviderErrorMetadata` → `ClassificationResult(category, user_action_kind, is_model_not_found, gateway_request_limit, gateway_unresolved_reference, gateway_routing_refusal)` || `pipelex/cogt/inference/error_render.py` | Render | `render_inference_error()` — picks the `CogtError` subclass from `InferenceErrorFamily` plus `is_model_not_found` (e.g. `LLMModelNotFoundError` vs `LLMCompletionError`) |Provider-specific nuance is normalized away in Extract (e.g. Google's `code` becomes `status_code`; AWS Bedrock error codes are mapped to HTTP statuses), so Classify has no provider branching. HTTP status drives classification; status-less errors dispatch on the SDK exception type name. The `tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py` meta-test walks every `ProviderName` against the extract-fn registry so adding a new provider without wiring it fails fast.@@ -263,6 +263,95 @@ class ProviderErrorMetadata(BaseModel):`UserAction` pairs a discrete `UserActionKind` (`WAIT_AND_RETRY`, `CHECK_BILLING`, `CHECK_CREDENTIALS`, `CHANGE_INPUT`, `CHANGE_MODEL`, `CONTACT_SUPPORT`, `UNKNOWN`) with a free-form `detail` string — so the CLI can render consistent guidance while keeping provider-specific text.+### The Gateway's Own Refusals++Not every failure on an inference call comes from a provider. The Pipelex inference gateway refuses some requests itself, before a model ever sees them, and it does so for three different reasons: the request is outside what it will carry, a reference the request depends on cannot be turned into content, or it cannot decide which provider should serve the request at all. All three arrive with the gateway's own error codes, and each has a runtime enum naming its outcomes — `GatewayRequestLimit`, `GatewayUnresolvedReference` and `GatewayRoutingRefusal`.++#### What the request may weigh++The gateway bounds what a request may weigh and how deeply it may nest, and refuses anything over those bounds itself — the body cap runs ahead of authentication, on the request headers alone, so the request never reaches a model at all.++| Gateway code | HTTP | `GatewayRequestLimit` | Category / action | What the caller is told |+|---|---|---|---|---|+| `pig-07` | 413 | `BODY_TOO_LARGE` | `CONTENT` / `CHANGE_INPUT` | the request was too large — send less in one call |+| `pig-08` | 411 | `BODY_LENGTH_REQUIRED` | `CONFIGURATION` / `CONTACT_SUPPORT` | the gateway could not read the request's declared size |+| `pig-10` | 413 | `OBJECT_TOO_LARGE` | `CONTENT` / `CHANGE_INPUT` | a file the request refers to is over the per-file limit |+| `pipelex_storage_object_too_large` | 413 | `OBJECT_TOO_LARGE` | `CONTENT` / `CHANGE_INPUT` | the same limit, as the native routes name it |+| `pipelex_document_too_large` | 413 | `OBJECT_TOO_LARGE` | `CONTENT` / `CHANGE_INPUT` | a document the gateway fetched by URL is over that limit |+| `pig-11` | 400 | `BODY_TOO_DEEP` | `CONTENT` / `CHANGE_INPUT` | the request nests too deeply — flatten the inputs or the output structure |++Three of the four are the caller's to fix and none of the four is ever retried: the gateway refused the request before a provider saw it, so an identical retry earns an identical refusal. `pig-08` is the exception in kind rather than in retryability — an HTTP client framed the request in a way the gateway will not bound (a chunked body, or an unreadable `Content-Length`), which no client the runtime ships produces, so it points at the transport stack rather than at the inputs.++A few details are worth knowing before touching this:++- **The code is the discriminator, not the provider.** A request reaches the gateway through whichever SDK its dialect calls for — the Portkey substrate, plain `httpx` on the native extract and search routes, and the shared Anthropic driver that Claude travels on — so the same refusal arrives under more than one `ProviderName`. `pig-` is the gateway's own code namespace, so matching on the code alone is both necessary and sufficient. Every Extract hop that can carry one of these recovers the code into `provider_error_code` — including the Portkey substrate, where it has to be read back off the response: Portkey's own exception factory replaces the payload with the message string, so `exc.body` there is never the document the code lives in.+- **The check runs before the status ladder.** An explicit code from a service we operate is a more specific verdict than any status bucket, and 413 / 411 / 400 would otherwise be read as a provider rejecting the prompt. It cannot collide with the quota rules, which only fire on 402 and 429.+- **The advice names no numbers.** The caps belong to the deployment, they differ between deployments, and the gateway already states its own figures in the message the advice sits beside. `_render_gateway_limit_detail` in the Render step is also where a per-plan message belongs once the hosted product's tier limits are wired through — the gateway knows nothing of users, organizations or plans, so only the runtime can say "your plan allows files up to N MB".+- **One failure can wear two codes, and reading `type` first loses one of them.** The gateway renders a refusal in the vocabulary of the route it arrived on: its own `pig-0N` family on the LLM routes, where the client is speaking a provider's protocol, and its frozen `pipelex_*` contract codes on the native `/v1/pipelex/extract` and `/v1/pipelex/search` routes. So "this file is over its cap" is `pig-10` on one and `pipelex_storage_object_too_large` on the other, and a caller cannot tell which route their extract took. The native-route envelope also puts a generic `invalid_request_error` in `error.type` beside the real code in `error.code`, so the two Pipelex-service Extract hops read `code` before `type` — the inverse of the vendor-facing precedence, which stays as it is because Anthropic's error section carries a `type` and no `code` at all. Reading `type` first there replaces the whole `pipelex_*` vocabulary with one bucket.++#### When a reference cannot be resolved++The second of the gateway's three families. A request may *name* a file rather than carry it — a `pipelex-storage://` key the gateway resolves for the caller, or a document URL it fetches on their behalf — and when it cannot turn that reference into bytes it refuses the request itself, again before a provider sees it. So the family above bounds what the request may weigh; this one says a reference the request depends on could not be turned into content. `GatewayUnresolvedReference` is the runtime's name for each outcome.++| Gateway code | HTTP | `GatewayUnresolvedReference` | Category / action | What the caller is told |+|---|---|---|---|---|+| `pig-09` | 400 | `REFERENCE_UNRESOLVED` | `CONTENT` / `CHANGE_INPUT` | a file reference could not be resolved — the message names the cause |+| `pipelex_storage_uri_invalid` | 400 | `STORAGE_REFERENCE_INVALID` | `CONTENT` / `CHANGE_INPUT` | the storage reference is malformed — check it against the key the upload returned |+| `pipelex_storage_unreadable` | 400 | `STORAGE_OBJECT_UNREADABLE` | `CONTENT` / `CHANGE_INPUT` | the object is not there, or cannot be read |+| `pipelex_storage_uri_unsupported` | 400 | `STORAGE_NOT_SERVED` | `CONFIGURATION` / `CONTACT_SUPPORT` | this deployment serves no storage references at all |+| `pipelex_unsupported_uri_scheme` | 400 | `DOCUMENT_URL_REFUSED` | `CONTENT` / `CHANGE_INPUT` | send an `https://` URL, a `data:` URL, or a `pipelex-storage://` reference |+| `pipelex_document_scheme_refused` | 400 | `DOCUMENT_URL_REFUSED` | `CONTENT` / `CHANGE_INPUT` | the same remedy — the fetch's own scheme check |+| `pipelex_document_address_refused` | 400 | `DOCUMENT_URL_REFUSED` | `CONTENT` / `CHANGE_INPUT` | the same remedy — the resolved address is not publicly routable |+| `pipelex_document_redirect_refused` | 400 | `DOCUMENT_URL_REFUSED` | `CONTENT` / `CHANGE_INPUT` | the same remedy — the gateway does not follow redirects |+| `pipelex_document_host_refused` | 400 | `DOCUMENT_HOST_REFUSED` | `CONTENT` / `CHANGE_INPUT` | documents are not fetched from that host, as a matter of security policy |+| `pipelex_document_unreachable` | 400 | `DOCUMENT_UNREACHABLE` | `CONTENT` / `CHANGE_INPUT` | check the document is live and publicly reachable |+| `pipelex_document_empty` | 400 | `DOCUMENT_CONTENT_UNUSABLE` | `CONTENT` / `CHANGE_INPUT` | the document was fetched and cannot be used |+| `pipelex_document_unsupported_type` | 400 | `DOCUMENT_CONTENT_UNUSABLE` | `CONTENT` / `CHANGE_INPUT` | the same — a media type the pipeline does not accept |+| `pipelex_document_bad_data_url` | 400 | `DOCUMENT_CONTENT_UNUSABLE` | `CONTENT` / `CHANGE_INPUT` | the same — a `data:` URL that could not be decoded |++Everything said above about the request limits holds here too — the code is the discriminator rather than the provider, the check runs ahead of the status ladder, and the advice defers every specific to the gateway's own message, which already names the key, the host, the status or the media type. Three things are particular to this family:++- **The members group by remedy, not by wire code.** Two codes share a member only when the caller's next move is the same, which is why the URL-shape refusals are one member. Two of them are scheme checks in different places and both belong there: `classifyExtractInput` runs before any fetch and admits only `https:`, `data:` and `pipelex-storage://`, so an `http://` URL is refused as `pipelex_unsupported_uri_scheme`, and `pipelex_document_scheme_refused` is the fetch's own check on what by then can only be an `https://` URL. `pipelex_document_host_refused` is deliberately *not* folded in with them: the caller can act on all four, but only that one has to be stated as the deliberate security refusal it is. Advice that reads as a fault to work around — revise the prompt, use a smaller file — sends someone hunting for a problem in a document that is perfectly fine.+- **One member is not the caller's problem at all.** `pipelex_storage_uri_unsupported` means no bucket is configured, so the deployment does not serve the scheme: no input avoids it, and telling the caller to fix theirs is wrong in kind. It is the family's one `CONFIGURATION` / `CONTACT_SUPPORT` arm, the same call `BODY_LENGTH_REQUIRED` gets among the request limits.+- **`pig-09` is one code for every storage failure but "over its cap", and the advice says so.** On the LLM routes the client is speaking a provider's protocol, so the gateway's `pig-0N` family is the only vocabulary available and it has a single fail-closed slot for "cannot resolve" — no bucket configured, not a storage reference, no such object, an object it cannot read, a type no provider takes, or no way to hand a file to the provider the model resolves to. The message carries the difference; the code does not, so `REFERENCE_UNRESOLVED` defers to the message rather than guessing which it was. The native `/v1/pipelex/*` routes name each cause with its own frozen contract code, which is why the rest of the table is `pipelex_*`.++`pig-09` also folds in causes that are not the caller's to repair — no bucket configured, and no way to hand a file to the provider the model resolves to — because the LLM routes have one slot for all of them. The native routes name the first of those separately (`pipelex_storage_uri_unsupported`, `CONTACT_SUPPORT`), so the same storage-less deployment reads differently by route. Splitting `pig-09` is a gateway-side change, filed on `pipelex-manifold` as `L-260901-f2b554`.++#### When the model cannot be routed++The third family, and the one no request escapes: whatever else it asks, it has to be *routed* first — the gateway reads the model out of it, looks that model up in its own routing table, and hands the call to the integration that serves it. When that resolution fails there is no provider to send the request to, so the gateway refuses it itself. `GatewayRoutingRefusal` is the runtime's name for each outcome.++| Gateway code | HTTP | `GatewayRoutingRefusal` | Category / action | What the caller is told |+|---|---|---|---|---|+| `pig-01` | 400 | `UNKNOWN_MODEL` | `CONFIGURATION` / `CHANGE_MODEL` | the gateway serves no such model — and if the deck lists it, the deck and the gateway disagree |+| `pig-02` | 400 | `DISABLED_INTEGRATION` | `CONFIGURATION` / `CONTACT_SUPPORT` | the model's integration is not enabled on this deployment — its credentials are unset |+| `pig-05` | 400 | `WRONG_PROTOCOL` | `CONFIGURATION` / `CHANGE_MODEL` | the model is served, but not over the protocol the request used for it |+| `pig-06` | 400 | `UNSERVED_CAPABILITY` | `CONFIGURATION` / `CHANGE_MODEL` | the model's integration does not serve that capability (extract, search) |++Everything said about the two families above holds here too — the code is the discriminator rather than the provider, the check runs ahead of the status ladder, the advice defers every specific to the gateway's own message, and nothing is ever retried. Four things are particular to this family:++- **The category is `CONFIGURATION`, never `CONTENT`, and that is the whole bug this family fixes.** Nothing in the prompt, the parameters or the inputs causes any of these, and no edit to them avoids one. Before the family existed all four fell through to the status ladder's 400 arm, so a caller who named a model the deployment does not serve was told *"The provider rejected the request — review the prompt, parameters, and inputs"* and received an `LLMCompletionError`.+- **Every member is its own wire code, unlike the two families above.** Grouping is by remedy in all three, and here each code names a different thing that has to change — so the grouping happens to be one-to-one rather than by design.+- **Only `pig-01` sets `is_model_not_found`.** The flag is not a category: it selects the family's `*ModelNotFoundError` class, which `pipe_operator.py` re-raises as a `PipeOperatorModelAvailabilityError` carrying the model handle — the pipe-level error a caller already gets when the model deck itself cannot find a model. `pig-01` is exactly that case seen from the gateway. For `pig-05` and `pig-06` the model *does* exist and *is* served, so claiming it was not found would be false; they stay on the generic failure class and carry the distinction in the advice.+- **`pig-02` is the family's `CONTACT_SUPPORT` arm**, the same call `STORAGE_NOT_SERVED` and `BODY_LENGTH_REQUIRED` get. A switched-off integration is the gateway operator's fact: `CHECK_CREDENTIALS` would send a hosted caller to rotate their own perfectly valid key, and `CHANGE_MODEL` would send them shopping for a model over an unset variable. The gateway's message names the integration and the variables to set, and the advice points at it.++**Moving the family to `CONFIGURATION` moves its HTTP answer too, and that is worth stating out loud.** `InferenceErrorCategory.CONFIGURATION` implies `ErrorDomain.CONFIG`, which `error_domain_to_http_status` renders as **500**, where `CONTENT` implies `INPUT` and renders as 422. So on any surface built on `ErrorReport.http_status`, all four of these now answer 500 where they answered 422 — the same answer the status ladder's 404 arm has always given a missing model, and the right one in kind, since none of them is a property of what the caller submitted. Two consequences follow: these land in server-error alerting rather than client-error, and 500 is a status outer HTTP clients and orchestrators retry. "Never retried" above is a statement about `InferenceErrorCategory.is_retryable` inside this process; it says nothing about what a caller's own client does with the status, and an outer retry of any of these earns an identical refusal.++`pig-05` and `pig-06` are as often a deck-versus-gateway disagreement as a caller's mistake — the runtime picks the protocol and the route from its own model deck — so both details say "your model deck" out loud rather than only "pick another model", which would leave an operator hunting for a model problem that is a configuration problem.++Two of the gateway's routing codes are deliberately **not** in the family, because no client the runtime ships can produce either:++| Code | HTTP | Why it stays with the status ladder |+|---|---|---|+| `pig-03` | 400 | "the client tried to route" — a refused `x-portkey-*` header, the `?model=` query form, a `@<slug>/<model>` virtual-key model, or a path and body naming different models. No client that talks to a Pipelex-operated gateway today sends one, so reaching it means a client bug rather than a caller's or an operator's mistake. Two limits on that: `tests/unit/pipelex/providers/manifold/test_manifold_clients.py` pins the manifold clients against the four steering headers *by name* while the gateway refuses on an allow-list, so a `portkey_ai` release sending some other `x-portkey-*` header would turn every request into a `pig-03` with that test still green; and the gateway img-gen worker does send `x-portkey-config`, which Portkey's cloud reads and one of our gateways refuses — harmless while `pipelex_gateway` keeps its default endpoint, a client bug the day it names one of ours. |+| `pig-04` | 404 | "this gateway does not serve `<method> <path>`" — the proxy policy refusing a path only the catch-all could answer, unreachable while the runtime calls only the routes the gateway mounts. Being a 404 the ladder reads it as model-not-found, which is wrong in kind — but a served-path drift is a deployment bug to surface loudly rather than a verdict to soften. |++`pig-05` is mapped but not reachable from today's runtime: it is raised only on a native Google protocol path (`/v1/<v1|v1alpha|v1beta>/models/<model>:generateContent`, or its `streamGenerateContent` twin, under the gateway's own `/v1` prefix), and no worker speaks that protocol to the gateway — both service plugins build their LLM workers on the OpenAI substrate, and the manifold's native client serves only the `/v1/pipelex/*` extract and search routes. The entry costs nothing and is right the day such a path is wired. One trap waits there, pinned by a test rather than left to be discovered: Google's Extract hop reads the symbolic `status` a Google error carries (`RESOURCE_EXHAUSTED` and friends), and the gateway's envelope has no `error.status` — only a top-level `status: "failure"`, which that hop returns as though it were a provider code. A native Google path needs that hop taught the gateway's envelope first.++Nothing in any of the three families is ever retried, and no two of them overlap: a code names a bound the request exceeded, a reference that could not be resolved, or a request that could not be routed. `pig-09` and `pig-10` are the clearest illustration — the same middleware raises both, one when the object cannot be resolved and one when it is over its cap.++The gateway's remaining codes belong to no family and classify on their status like anything else. For the storage deadline outcomes (`pig_storage_timeout` at 504, `pig_storage_client_disconnected` at 499) that is the right reading — a timeout is a timeout. For `pig-12` at 400, the LLM routes' "no storage bucket is configured", it is not: it is the operator's fact and reads as a prompt to revise, exactly as `pipelex_storage_uri_unsupported` does not on the native routes. One map entry into `GatewayUnresolvedReference.STORAGE_NOT_SERVED` closes it, filed as `L-260901-0859e8`.+### The `instructor` UnwrapOn structured-generation paths, `instructor` wraps the real SDK exception in an `InstructorRetryException`. `extract_underlying_sdk_exception()` recovers it, so it routes through the same per-provider categorization as the plain-text path. A genuinely unrecognized inner exception (e.g. a `pydantic.ValidationError` from a schema mismatch) lands in `UNKNOWN` rather than being mis-labelled as a `CONTENT`-policy violation.diff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.mdindex 083a1c5f6..b59f77a42 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. "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:+When inference is **not** forced and backends already exist, service terms are still checked. The question is the broad one — is *any* Pipelex-managed gateway backend enabled — because the terms are the Pipelex service's rather than one dialect's, and it is read off the merged backends document pinned to the target directory (`enabled_managed_gateway_sections(config_dir=…)`), so a managed backend switched on only by that directory's `backends_override.toml` is prompted for terms too. Declining writes `enabled = false` into the base for every managed backend, and `warn_if_managed_gateway_pinned_by_override` names the ones an override still keeps on:```pythonif not needs_inference and backends_existed_before:diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex a71c8fdd4..a83491356 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -6,7 +6,7 @@ Machine-first CLI for running and validating Pipelex method bundles (`.mthds` fiTwo independent options control the two output streams:-- `--format markdown|json` — **success/useful output**. Defaults to markdown. Accepted by `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`, `codegen types`, `codegen check`. Goes to stdout. Threaded explicitly to `agent_success_formatted()` from each command function — no hidden state.+- `--format markdown|json` — **success/useful output**. Defaults to markdown. Accepted by `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`, `migrate`, `codegen types`, `codegen check`. Goes to stdout. Threaded explicitly to `agent_success_formatted()` from each command function — no hidden state.- `--error-format markdown|json` — **error reporting** (stderr). Optional. When omitted, **inherits the value of `--format`**, so `--format json` still flips both as it did historically. Accepted by the same commands as `--format`.Only the error format is backed by a module-level `ContextVar` in `agent_output.py` (`_agent_cli_error_format`). The reason: `agent_error()` is called from sites that don't see the Typer option — factory init failures (`agent_cli_factory.py`), the unknown-command handler in `PipelexAgentCLI.get_command`, runner validation in the app callback, and any future site in shared library/runtime code. The ContextVar lets all of them honor `--error-format` (or `--format`'s inherited value) for free. JSON is the default so errors raised before any command opts in stay machine-parseable.diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.pyindex 56093bbbd..2ac42caed 100644--- a/pipelex/cli/agent_cli/commands/init_cmd.py+++ b/pipelex/cli/agent_cli/commands/init_cmd.py@@ -18,7 +18,7 @@ from pipelex.cli.commands.init.backends import get_selected_backend_keys, updatefrom pipelex.cli.commands.init.command import attempt_prime_remote_config_cachefrom pipelex.cli.commands.init.config_files import init_configfrom pipelex.cli.commands.init.ui.backends_ui import get_backend_options_from_toml-from pipelex.cogt.model_backends.backend import PipelexBackend+from pipelex.cogt.model_backends.backend import MANAGED_GATEWAY_BACKEND_NAMES, PipelexBackendfrom pipelex.cogt.model_routing.routing_profile import PipelexRoutingProfilefrom pipelex.cogt.models.deck_manifest import compute_kit_manifest, write_manifestfrom pipelex.kit.paths import get_kit_configs_dir@@ -215,8 +215,10 @@ def _configure_backends(update_backends_in_toml(toml_doc, selected_indices=selected_indices, backend_options=backend_options)save_toml_to_path(toml_doc, path=backends_toml_path)- # Handle pipelex_gateway terms acceptance (only when explicitly provided)- if PipelexBackend.GATEWAY in requested_backends:+ # Any managed gateway backend puts this installation behind the service terms — the same+ # question the boot asks. Asked the gateway-only way, `accept_gateway_terms` was silently+ # dropped for a manifold-only request and the next inference boot refused to start.+ if any(backend_name in requested_backends for backend_name in MANAGED_GATEWAY_BACKEND_NAMES):accept_terms = config.get("accept_gateway_terms")if accept_terms is not None:config_manager.global_config_dir.mkdir(parents=True, exist_ok=True)diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex 73ac79646..bf1ab5ce9 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -38,7 +38,6 @@ from pipelex.cogt.exceptions import ()from pipelex.cogt.model_backends.backend_credentials import BackendCredentialsErrorMsgFactory, BackendCredentialsReportfrom pipelex.cogt.model_backends.backend_library import InferenceBackendLibrary-from 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 ModelManagerfrom pipelex.config import get_config@@ -55,8 +54,9 @@ from pipelex.system.pipelex_service.exceptions import (RemoteConfigUnavailableError,RemoteConfigValidationError,)+from pipelex.system.pipelex_service.managed_gateway_configs import build_managed_gateway_configsfrom pipelex.system.pipelex_service.pipelex_service_config import (- is_pipelex_gateway_enabled,+ enabled_managed_gateway_sections,load_pipelex_service_config_if_exists,)from pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcher@@ -72,6 +72,7 @@ from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProviderif TYPE_CHECKING:from collections.abc import Mapping+ from pipelex.cogt.model_backends.gateway_config import GatewayConfigfrom pipelex.system.pipelex_service.types import RemoteConfigSource@@ -1091,20 +1092,20 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strmsg = f"Backend configuration error: {first_error}"return False, msg, backend_file_reports- # Fetch gateway model specs if Gateway is enabled.+ # Fetch the managed gateways' model specs if any managed gateway backend is enabled.# 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_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_dir- gateway_config: GatewayConfig | None = None+ managed_gateway_configs: dict[str, GatewayConfig] | None = Nonegateway_config_source: RemoteConfigSource | None = Nonetry:- gateway_enabled = is_pipelex_gateway_enabled(config_dir=config_dir)+ managed_gateway_sections = enabled_managed_gateway_sections(config_dir=config_dir)except InferenceBackendLibraryValidationError as exc:return False, f"Error checking models: {exc}", backend_file_reports- if gateway_enabled:+ if managed_gateway_sections: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@@ -1112,11 +1113,10 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strreturn False, "Pipelex Gateway is enabled but terms have not been accepted", backend_file_reportstry:result = RemoteConfigFetcher.fetch_remote_config()- remote_config = result.configgateway_config_source = result.source- gateway_config = GatewayConfig(- model_specs=remote_config.backend_model_specs,- aws_region=remote_config.aws_region,+ managed_gateway_configs = build_managed_gateway_configs(+ remote_config=result.config,+ managed_gateway_sections=managed_gateway_sections,)except (RemoteConfigUnavailableError, RemoteConfigValidationError) as exc:return False, f"Failed to fetch Pipelex Gateway remote configuration: {exc}", backend_file_reports@@ -1134,7 +1134,7 @@ def check_models(*, config_dir: Path | None = None) -> tuple[bool, str, dict[strtry:models_manager.setup(secrets_provider=secrets_provider,- gateway_config=gateway_config,+ managed_gateway_configs=managed_gateway_configs,gateway_config_source=gateway_config_source,backends_library_paths=backends_library_override,backends_dir_path=backends_dir_override,diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.pyindex c22b74b29..7823d8f32 100644--- a/pipelex/cli/commands/init/backends.py+++ b/pipelex/cli/commands/init/backends.py@@ -26,12 +26,12 @@ from pipelex.cli.commands.init.ui.gateway_ui import (display_gateway_declined_message,prompt_gateway_acceptance,)-from pipelex.cogt.model_backends.backend import PipelexBackend+from pipelex.cogt.model_backends.backend import MANAGED_GATEWAY_BACKEND_NAMESfrom 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.system.pipelex_service.pipelex_service_config import is_pipelex_gateway_enabled+from pipelex.system.pipelex_service.pipelex_service_config import enabled_managed_gateway_sectionsfrom pipelex.tools.misc.toml_utils import describe_toml_base_and_overrides, load_toml_from_path, load_toml_with_tomlkit, save_toml_to_path@@ -80,35 +80,45 @@ 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.+def warn_if_managed_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 a managed backend.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.+ personal ``backends_override.toml`` files merged over it. Disabling the managed gateway backends+ 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.++ It asks the broad question rather than the gateway-only one for the reason the write above is+ broad: the terms are the Pipelex service's, so any managed backend an override pins back on puts+ the installation behind them again.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.+ True when a managed gateway backend 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):+ still_enabled = sorted(enabled_managed_gateway_sections(config_dir=config_dir))+ if not still_enabled:return Falsedescription = 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)}. "+ f"[yellow]⚠ A Pipelex-managed gateway backend is still enabled by a personal override: "+ f"{escape(', '.join(still_enabled))} in {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.+def disable_managed_gateway_backends(backends_toml_path: Path) -> None:+ """Disable every Pipelex-managed gateway backend in backends.toml.++ Declining the service terms, or failing to record acceptance, has to leave *no* managed backend+ enabled: the terms are the Pipelex service's terms rather than one dialect's, so a boot that+ reaches the service through any of them is refused for want of the same acceptance.Args:backends_toml_path: Path to the backends.toml file.@@ -118,8 +128,12 @@ def disable_gateway_backend(backends_toml_path: Path) -> None:toml_doc = load_toml_with_tomlkit(backends_toml_path)- if PipelexBackend.GATEWAY in toml_doc:- toml_doc[PipelexBackend.GATEWAY]["enabled"] = False # type: ignore[index]+ disabled_any = False+ for backend_name in MANAGED_GATEWAY_BACKEND_NAMES:+ if backend_name in toml_doc:+ toml_doc[backend_name]["enabled"] = False # type: ignore[index]+ disabled_any = True+ if disabled_any:save_toml_to_path(toml_doc, path=backends_toml_path)@@ -172,9 +186,10 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confi# No stdin available for the install prompt — skip the optional IDE extension suggestion.log.debug(f"IDE extension suggestion skipped: {exc}")- # Check if pipelex_gateway is selected and handle terms acceptance prompt+ # Any managed gateway backend puts this installation behind the service terms, so the+ # prompt asks the same question the boot does rather than the narrower gateway-only one.gateway_terms_accepted: bool | None = None- if PipelexBackend.GATEWAY in selected_backends:+ if any(backend_name in selected_backends for backend_name in MANAGED_GATEWAY_BACKEND_NAMES):gateway_accepted = prompt_gateway_acceptance(console=console)if gateway_accepted:@@ -184,8 +199,8 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confidisplay_gateway_declined_message(console=console)gateway_terms_accepted = False- # Remove pipelex_gateway from selected indices- selected_indices = [idx for idx in selected_indices if backend_options[idx][0] != PipelexBackend.GATEWAY]+ # Declining removes every managed backend, not only the one that raised the prompt.+ selected_indices = [idx for idx in selected_indices if backend_options[idx][0] not in MANAGED_GATEWAY_BACKEND_NAMES]# Business logic: Update and save backends.toml first (local operation)update_backends_in_toml(toml_doc, selected_indices=selected_indices, backend_options=backend_options)@@ -205,12 +220,12 @@ def customize_backends_config(*, is_first_time_setup: bool = False, target_confi# terms writer's dict assignment raise TypeError rather than a TOMLKitError.log.warning(f"Could not save gateway terms acceptance to global config: {terms_exc}")if gateway_terms_accepted:- # Gateway enabled in backends.toml but terms not recorded — runtime will fail.- # Disable gateway as a safety measure.+ # A managed backend is enabled in backends.toml but terms are not recorded —+ # the runtime will fail. Disable them as a safety measure.try:- disable_gateway_backend(backends_toml_path)+ disable_managed_gateway_backends(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)+ warn_if_managed_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 2aafd4493..cc3449142 100644--- a/pipelex/cli/commands/init/command.py+++ b/pipelex/cli/commands/init/command.py@@ -11,9 +11,9 @@ from rich.prompt import Confirmfrom pipelex.cli.commands.init.backends import (customize_backends_config,- disable_gateway_backend,+ disable_managed_gateway_backends,get_selected_backend_keys,- warn_if_gateway_pinned_by_override,+ warn_if_managed_gateway_pinned_by_override,)from pipelex.cli.commands.init.config_files import init_configfrom pipelex.cli.commands.init.credentials import prompt_credentials@@ -34,7 +34,7 @@ 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 (- is_pipelex_gateway_enabled,+ enabled_managed_gateway_sections,load_pipelex_service_config_if_exists,)from pipelex.system.pipelex_service.remote_config_cache import RemoteConfigCache@@ -49,7 +49,8 @@ class CachePrimingResult(BaseModel):afterwards. ``error_message`` is populated when the fetch was attempted but failed (offline atinit time) *or* when the fetch succeeded but the cache could not be persisted, read back, orvalidated as a usable ``RemoteConfig`` (e.g. a read-only or full cache directory). ``None``- means priming was skipped (gateway disabled or terms not accepted) or that it succeeded.+ means priming was skipped (no managed gateway backend enabled, or terms not accepted) or that+ it succeeded."""model_config = ConfigDict(extra="forbid", strict=True)@@ -66,8 +67,12 @@ def attempt_prime_remote_config_cache(*, target_config_dir: Path | None = None)structured JSON field).Skipped (``primed=False, error_message=None``) when:- - the gateway is disabled in ``backends.toml`` (BYOK has nothing to cache), or- - gateway terms have not been accepted (we cannot fetch without consent).+ - no managed gateway backend is enabled in ``backends.toml`` (BYOK has nothing to cache), or+ - the service terms have not been accepted (we cannot fetch without consent).++ The question is the boot's — *any* managed gateway backend — rather than the Portkey-cloud+ one's, because what gets cached is the single published configuration carrying every managed+ backend's section: a manifold-only installation has exactly as much to cache as a gateway one.Always passes ``require_fresh=True`` to the fetcher: priming's only job is to write a freshcache, so silently accepting an existing cached fallback would be a misleading success. When@@ -81,13 +86,14 @@ def attempt_prime_remote_config_cache(*, target_config_dir: Path | None = None)Args: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.+ ``backends.toml`` and its own ``backends_override.toml``) to decide whether a managed+ gateway backend 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 not is_pipelex_gateway_enabled(config_dir=target_config_dir):+ if not enabled_managed_gateway_sections(config_dir=target_config_dir):return CachePrimingResult(primed=False)service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)@@ -128,7 +134,7 @@ def prime_remote_config_cache(*, console: Console, target_config_dir: Path | NonPrints a yellow warning to the console when a fetch was attempted and failed; otherwisesilent. Used by ``pipelex init`` so the user knows priming didn't happen and how to retry.- ``target_config_dir`` is forwarded so the gateway-enabled check inspects the directory+ ``target_config_dir`` is forwarded so the managed-gateway check inspects the directorybeing initialized rather than the layered config (see ``attempt_prime_remote_config_cache``)."""result = attempt_prime_remote_config_cache(target_config_dir=target_config_dir)@@ -154,7 +160,10 @@ def _check_gateway_terms_if_needed(*, console: Console, backends_toml_path: Pathif not backends_toml_path.exists():return- if not is_pipelex_gateway_enabled(config_dir=backends_toml_path.parent.parent):+ # Any managed gateway backend puts this installation behind the service terms — the same+ # question the boot asks. Asking only about the Portkey-cloud one leaves a manifold-only+ # install unable to record acceptance through any supported step.+ if not enabled_managed_gateway_sections(config_dir=backends_toml_path.parent.parent):return# Gateway is enabled - check if terms are already accepted (always global)@@ -172,9 +181,10 @@ 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 — and say so if an override still pins it on- disable_gateway_backend(backends_toml_path)- warn_if_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path)+ # Actually disable the managed gateway backends in backends.toml — and say so if an+ # override still pins one on+ disable_managed_gateway_backends(backends_toml_path)+ warn_if_managed_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path)def determine_needs(@@ -425,16 +435,18 @@ def execute_initialization(def _init_agreement(*, console: Console) -> None:"""Handle the agreement-only initialization flow.- This prompts the user to accept Pipelex Gateway terms without resetting any configuration.- If gateway is not enabled, it informs the user that no action is needed.+ This prompts the user to accept the Pipelex service terms without resetting any configuration,+ and it is the human CLI's only way to record acceptance after the fact. It therefore asks the+ same question the boot asks — is ANY managed gateway backend enabled — rather than the narrower+ gateway-only one, which would report that nothing is needed on an installation the boot refuses+ to start for want of exactly this.Args:console: Rich Console instance for user interaction."""- # Check if gateway is even enabled- if not is_pipelex_gateway_enabled():+ if not enabled_managed_gateway_sections():console.print()- console.print("[green]✓ Pipelex Gateway is not enabled.[/green]")+ console.print("[green]✓ No Pipelex-managed gateway backend is enabled.[/green]")console.print("[dim]No terms acceptance is required.[/dim]")console.print()return@@ -468,8 +480,8 @@ def _init_agreement(*, console: Console) -> None:# Disable the gateway since terms were declinedbackends_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)+ disable_managed_gateway_backends(backends_toml_path)+ warn_if_managed_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path)console.print()diff --git a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.pyindex 13cfa4cdd..9b28098f4 100644--- a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py+++ b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py@@ -17,6 +17,7 @@ from pipelex.runtime_hub import get_consolefrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.configuration.configs import ConfigPathsfrom pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError, RemoteConfigValidationError+from pipelex.system.pipelex_service.pipelex_service_config import enabled_managed_gateway_sectionsfrom pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcherfrom pipelex.tools.misc.exceptions import TomlErrorfrom pipelex.tools.misc.json_utils import deep_update@@ -39,32 +40,30 @@ MODEL_TYPES = ["llm", "img_gen", "text_extractor", "search"]DEFAULT_MODEL_TYPE = "llm"-def _extract_models_from_backend_toml(backend_path: Path) -> dict[str, list[str]]:- """Extract model handles from a backend TOML file, grouped by model type.+def _group_handles_by_model_type(*, specs: dict[str, Any]) -> dict[str, list[str]]:+ """Group a table of model specs by model type.++ One function for both sources on purpose: a local backend TOML and a remote-config model-specs+ section carry the same shape — one table per model handle, an optional `defaults` table naming+ the model type the rest inherit — so reading them differently is how the two drift.Args:- backend_path: Path to the backend TOML file.+ specs: The specs table, keyed by model handle.Returns:- Dictionary mapping model_type to list of model handles.+ Dictionary mapping model_type to a sorted list of model handles."""- try:- config = load_toml_from_path(str(backend_path))- except (TomlError, OSError):- return {}+ defaults = specs.get("defaults", {})+ default_model_type: str = DEFAULT_MODEL_TYPE+ if isinstance(defaults, dict):+ defaults_dict = cast("dict[str, Any]", defaults)+ default_type_raw = defaults_dict.get("model_type")+ if default_type_raw:+ default_model_type = str(default_type_raw)- # Get defaults- defaults = config.get("defaults", {})- default_model_type = defaults.get("model_type", DEFAULT_MODEL_TYPE)+ models_by_type: dict[str, list[str]] = {model_type: [] for model_type in MODEL_TYPES}- models_by_type: dict[str, list[str]] = {- "llm": [],- "img_gen": [],- "text_extractor": [],- "search": [],- }-- for key, value in config.items():+ for key, value in specs.items():# Skip defaults and non-dict entriesif key == "defaults" or not isinstance(value, dict):continue@@ -89,64 +88,62 @@ def _extract_models_from_backend_toml(backend_path: Path) -> dict[str, list[str]return models_by_type-def _fetch_gateway_models() -> dict[str, list[str]]:- """Fetch model handles from Pipelex Gateway remote config, grouped by model type.+def _extract_models_from_backend_toml(backend_path: Path) -> dict[str, list[str]]:+ """Extract model handles from a backend TOML file, grouped by model type.++ Args:+ backend_path: Path to the backend TOML file.Returns:Dictionary mapping model_type to list of model handles.-- Raises:- RemoteConfigUnavailableError: The Gateway config is unreachable and no usable cache- exists — ``require_fresh=True`` refuses any cached fallback.- RemoteConfigValidationError: The Gateway responded with a payload that does not match- the expected schema."""- # ``require_fresh=True`` guarantees we never bake stale or missing Gateway model specs- # into committed files. Any ``RemoteConfigUnavailableError`` / ``RemoteConfigValidationError``- # propagates so the command refuses to proceed rather than writing fixtures silently- # missing every ``pipelex_gateway`` model.- result = RemoteConfigFetcher.fetch_remote_config(require_fresh=True)- model_specs = dict(result.config.backend_model_specs)+ try:+ config = load_toml_from_path(str(backend_path))+ except (TomlError, OSError):+ return {}- # Get defaults- defaults = model_specs.get("defaults", {})- default_model_type: str = DEFAULT_MODEL_TYPE- if isinstance(defaults, dict):- defaults_dict = cast("dict[str, Any]", defaults)- default_type_raw = defaults_dict.get("model_type")- if default_type_raw:- default_model_type = str(default_type_raw)+ return _group_handles_by_model_type(specs=config)- models_by_type: dict[str, list[str]] = {- "llm": [],- "img_gen": [],- "text_extractor": [],- "search": [],- }- for key, value in model_specs.items():- # Skip defaults and non-dict entries- if key == "defaults" or not isinstance(value, dict):- continue+def _fetch_managed_gateway_models() -> dict[str, dict[str, list[str]]]:+ """Fetch model handles for every enabled managed gateway backend, grouped by model type.- # Skip rules sub-sections- if ".rules" in key:- continue+ A *managed gateway backend* is one that declares a `model_specs_section`, and there can be more+ than one of them — the Portkey-cloud `pipelex_gateway` and `pipelex_manifold` today. Which+ section a backend reads is its own declaration, so this asks `enabled_managed_gateway_sections`+ rather than naming any backend here: hardcoding one name is exactly what kept this command+ blind to the second gateway.- # Determine model type (cast for type safety)- value_dict = cast("dict[str, Any]", value)- model_type_raw = value_dict.get("model_type", default_model_type)- model_type = str(model_type_raw) if model_type_raw else default_model_type+ Returns:+ Dictionary mapping backend name to its {model_type: [model handles]}. Empty when no managed+ gateway backend is enabled, in which case the remote config is never fetched at all.- # Add to appropriate list- if model_type in models_by_type:- models_by_type[model_type].append(key)+ Raises:+ RemoteConfigUnavailableError: The remote config is unreachable and no usable cache+ exists — ``require_fresh=True`` refuses any cached fallback.+ RemoteConfigValidationError: The service responded with a payload that does not match+ the expected schema.+ """+ sections = enabled_managed_gateway_sections()+ if not sections:+ return {}- # Sort model lists- for model_list in models_by_type.values():- model_list.sort()+ # ``require_fresh=True`` guarantees we never bake stale or missing model specs into committed+ # files. Any ``RemoteConfigUnavailableError`` / ``RemoteConfigValidationError`` propagates so+ # the command refuses to proceed rather than writing fixtures silently missing every managed+ # gateway model.+ result = RemoteConfigFetcher.fetch_remote_config(require_fresh=True)- return models_by_type+ models_by_backend: dict[str, dict[str, list[str]]] = {}+ for backend_name, section_name in sorted(sections.items()):+ section = result.config.get_model_specs_section(section_name)+ if section is None:+ # The artifact carries no such section: a real answer, and the same posture the runtime+ # takes — that backend simply serves nothing here, rather than failing the whole run.+ continue+ models_by_backend[backend_name] = _group_handles_by_model_type(specs=dict(section))++ return models_by_backenddef _collect_all_model_availability() -> dict[str, Any]:@@ -171,12 +168,15 @@ def _collect_all_model_availability() -> dict[str, Any]:backends_dir = config_manager.backends_dir_path+ # Managed gateway backends are handled separately below: their models come from the published+ # artifact, so a local TOML of the same name holds overrides and never the model list.+ managed_backends = _fetch_managed_gateway_models()+# Process each backend TOML filefor backend_file in sorted(backends_dir.glob("*.toml")):backend_name = backend_file.stem- # Skip pipelex_gateway (handled separately)- if backend_name == "pipelex_gateway":+ if backend_name in managed_backends:continuemodels_by_type = _extract_models_from_backend_toml(backend_file)@@ -185,11 +185,11 @@ def _collect_all_model_availability() -> dict[str, Any]:if models_by_type.get(model_type):result[model_type][backend_name] = models_by_type[model_type]- # Add Pipelex Gateway models- gateway_models = _fetch_gateway_models()- for model_type in MODEL_TYPES:- if gateway_models.get(model_type):- result[model_type]["pipelex_gateway"] = gateway_models[model_type]+ # Add each managed gateway backend's models+ for backend_name, models_by_type in managed_backends.items():+ for model_type in MODEL_TYPES:+ if models_by_type.get(model_type):+ result[model_type][backend_name] = models_by_type[model_type]return result@@ -617,9 +617,10 @@ def preprocess_test_models_cmd() -> None:"""Preprocess test models from backend TOMLs and generate fixture files.- This command reads all backend TOML configurations and the Pipelex Gateway- remote config to build a complete mapping of available models. It can optionally- generate a Python fixture file with pre-computed (model, backend) pairs.+ This command reads all backend TOML configurations and, for every enabled managed gateway+ backend, its own section of the published remote config, to build a complete mapping of+ available models. It can optionally generate a Python fixture file with pre-computed+ (model, backend) pairs.Args:profile: Test profile to use (ci, dev, coverage, full).@@ -678,15 +679,15 @@ def preprocess_test_models_cmd(console.print()sys.exit(1)except (RemoteConfigUnavailableError, RemoteConfigValidationError) as exc:- # Pipelex Gateway remote config is unavailable or stale. This command regenerates- # committed files (model_availability.json, _generated_model_sets.py), so it must- # refuse rather than write fixtures missing every pipelex_gateway model.+ # The remote config is unavailable or stale. This command regenerates committed files+ # (model_availability.json, _generated_model_sets.py), so it must refuse rather than write+ # fixtures missing every managed gateway backend's models.if quiet:- console.print(f"[red]✗ Preprocessing failed:[/red] Gateway config unavailable - {escape(str(exc))}")+ console.print(f"[red]✗ Preprocessing failed:[/red] Remote config unavailable - {escape(str(exc))}")else:error_panel = Panel(- f"[red]✗[/red] Pipelex Gateway remote configuration is unavailable\n\n[dim]{escape(str(exc))}[/dim]",- title="[bold red]Gateway Config Unavailable[/bold red]",+ f"[red]✗[/red] The Pipelex service's remote configuration is unavailable\n\n[dim]{escape(str(exc))}[/dim]",+ title="[bold red]Remote Config Unavailable[/bold red]",border_style="red",padding=(1, 2),)@@ -694,7 +695,7 @@ def preprocess_test_models_cmd(console.print()console.print("[bold yellow]Recommended Actions:[/bold yellow]")console.print(" • Run [cyan]pipelex init[/cyan] while online to prime the remote config cache")- console.print(" • Fixture generation must not proceed without fresh Gateway model specs")+ console.print(" • Fixture generation must not proceed without fresh managed gateway model specs")console.print()sys.exit(1)except Exception as exc: # ruff: ignore[blind-except]diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.pyindex 7a925ef05..41f33d7ea 100644--- a/pipelex/cli/error_handlers.py+++ b/pipelex/cli/error_handlers.py@@ -608,6 +608,10 @@ def handle_gateway_unknown_model_error(exc: GatewayUnknownModelError) -> NoReturin the gateway specs (either freshly fetched or loaded from cache). Branches theremediation on the provenance of the gateway config.+ **The backend is named rather than assumed.** More than one managed gateway can be live at+ once, so telling the user to disable `pipelex_gateway` when it was the other service that could+ not serve the handle would send them to fix the wrong line of their configuration.+Args:exc: The gateway unknown model error exception"""@@ -615,7 +619,9 @@ def handle_gateway_unknown_model_error(exc: GatewayUnknownModelError) -> NoReturprint_traceback_if_requested(console=console)console.print("\n[bold red]❌ Unknown gateway model handle[/bold red]\n")+ backend_name = escape(exc.backend_name or "")console.print(f"[bold cyan]Model handle:[/bold cyan] [yellow]'{escape(exc.model_name)}'[/yellow]")+ console.print(f"[bold cyan]Backend:[/bold cyan] [yellow]{backend_name}[/yellow]")console.print(f"[bold cyan]Config source:[/bold cyan] [yellow]{escape(exc.source)}[/yellow]")console.print(f"\n[bold red]Error:[/bold red] {escape(str(exc))}\n")@@ -624,10 +630,10 @@ def handle_gateway_unknown_model_error(exc: GatewayUnknownModelError) -> NoReturcase RemoteConfigSource.FRESH:console.print(" • Check the model handle for typos against [cyan]pipelex doctor[/cyan]")console.print(" • Update the deck to reference a model the gateway currently exposes")- console.print(" • Or disable [cyan]pipelex_gateway[/cyan] in [cyan].pipelex/inference/backends.toml[/cyan] to fall back to BYOK")+ console.print(f" • Or disable [cyan]{backend_name}[/cyan] in [cyan].pipelex/inference/backends.toml[/cyan] to fall back to BYOK")case RemoteConfigSource.CACHED:console.print(" • The on-disk cache may be stale — run [cyan]pipelex init[/cyan] while online to refresh it")- console.print(" • Or disable [cyan]pipelex_gateway[/cyan] in [cyan].pipelex/inference/backends.toml[/cyan] to operate offline (BYOK)")+ console.print(f" • Or disable [cyan]{backend_name}[/cyan] in [cyan].pipelex/inference/backends.toml[/cyan] to operate offline (BYOK)")console.print()console.print(f"[dim]For more information: {URLs.gateway_docs}[/dim]")diff --git a/pipelex/cogt/exceptions.py b/pipelex/cogt/exceptions.pyindex 79d8d4d5b..6ad08b2da 100644--- a/pipelex/cogt/exceptions.py+++ b/pipelex/cogt/exceptions.py@@ -517,33 +517,40 @@ class ModelDeckValidationError(CogtError):class GatewayUnknownModelError(CogtError):- """A model handle referenced by the deck cannot be located in the active gateway specs.+ """A model handle the active routing profile sends to a managed gateway is absent from its specs.Carries the provenance of the gateway config (``FRESH`` vs ``CACHED``) so the message canbranch: a cached-source failure suggests stale gateway specs and points the user at``pipelex init`` to refresh while online; a fresh-source failure is a genuinemisconfiguration.++ **And it carries the backend name**, because more than one managed gateway can be live at once+ and "which one" is then a question the message has to answer — the handle may be perfectly+ present in the other service's section, which is a legitimate configuration rather than a+ contradiction."""error_category = InferenceErrorCategory.CONFIGURATION- def __init__(self, model_name: str, source: RemoteConfigSource) -> None:+ def __init__(self, model_name: str, backend_name: str, source: RemoteConfigSource) -> None:self.model_name = model_name+ self.backend_name = backend_nameself.source = sourcematch source:case RemoteConfigSource.FRESH:msg = (- f"Model handle '{model_name}' is referenced by the active model deck but is not present "- "in the Pipelex Gateway specs we just fetched. Either the model name is wrong, the gateway "- "no longer offers it, or your deck overrides need updating.\n"- " - Run `pipelex doctor` to inspect the active gateway models.\n"- " - Disable pipelex_gateway in .pipelex/inference/backends.toml to fall back to BYOK."+ f"Model handle '{model_name}' is routed to backend '{backend_name}' by the active routing profile, "+ f"but is not present in the model specs we just fetched for it. Either the model name is wrong, that "+ f"gateway no longer offers it, or your deck overrides need updating.\n"+ f" - Run `pipelex doctor` to inspect the active gateway models.\n"+ f" - Route this model to another backend in .pipelex/inference/routing_profiles.toml.\n"+ f" - Or disable {backend_name} in .pipelex/inference/backends.toml to fall back to BYOK.")case RemoteConfigSource.CACHED:msg = (- f"Model handle '{model_name}' is referenced by the active model deck but is not present "- "in the Pipelex Gateway specs loaded from the on-disk cache. The cache may be stale.\n"- " - Run `pipelex init` while online to refresh the cached gateway config.\n"- " - Or disable pipelex_gateway in .pipelex/inference/backends.toml to operate offline (BYOK)."+ f"Model handle '{model_name}' is routed to backend '{backend_name}' by the active routing profile, "+ f"but is not present in the model specs loaded for it from the on-disk cache. The cache may be stale.\n"+ f" - Run `pipelex init` while online to refresh the cached gateway config.\n"+ f" - Or disable {backend_name} in .pipelex/inference/backends.toml to operate offline (BYOK).")super().__init__(msg)diff --git a/pipelex/cogt/inference/error_classification.py b/pipelex/cogt/inference/error_classification.pyindex e1a49738b..b22e586f1 100644--- a/pipelex/cogt/inference/error_classification.py+++ b/pipelex/cogt/inference/error_classification.py@@ -44,6 +44,285 @@ _STATUSLESS_TRANSPORT_TYPE_NAMES: frozenset[str] = frozenset()+class GatewayRequestLimit(StrEnum):+ """A request-shape refusal raised by the Pipelex inference gateway itself.++ The gateway bounds what a request may weigh and how deeply it may nest, and+ refuses anything over those bounds *before* the request reaches a provider —+ the body cap and the length rule run ahead of authentication, on the headers+ alone. Those refusals are not inference failures and must not read as one: a+ caller who sent something too large has a limit to respect, not a prompt to+ revise, and nothing about a retry can help.++ Each member corresponds to one of the gateway's own error codes, which is the+ contract between the two repositories — the wording of a refusal is free to+ change, the code is not.+ """++ #: ``pig-07`` at HTTP 413 — the declared body size is over the gateway's cap+ #: for its media type (JSON or multipart).+ BODY_TOO_LARGE = "body_too_large"+ #: ``pig-08`` at HTTP 411 — the body's size cannot be read at all: a chunked+ #: body, or a ``Content-Length`` that is not a byte count. No HTTP client the+ #: runtime uses produces this; it exists so that an unusual one fails closed+ #: and legibly rather than being buffered to find out how big it is.+ BODY_LENGTH_REQUIRED = "body_length_required"+ #: HTTP 413 — a file the request only *refers* to is over its cap: a+ #: ``pipelex-storage://`` object the gateway resolved, or a document it+ #: fetched by URL. The same "too large" family as ``BODY_TOO_LARGE``, one+ #: indirection further out. It arrives under three codes because the gateway+ #: renders the same failure twice — ``pig-10`` on the LLM routes, where its+ #: own ``pig-0N`` family is the only vocabulary available, and+ #: ``pipelex_storage_object_too_large`` / ``pipelex_document_too_large`` on+ #: the native ``/v1/pipelex/*`` routes, whose wire contract is its own.+ OBJECT_TOO_LARGE = "object_too_large"+ #: ``pig-11`` at HTTP 400 — the parsed body nests deeper than the gateway's+ #: depth limit. Not a byte question: nesting costs two bytes a level, so a+ #: body well under any size cap can still overflow a walker.+ BODY_TOO_DEEP = "body_too_deep"+++# The gateway's error codes, mapped to what the runtime does about them.+#+# **Matched on the code alone, with no check on ``provider``**, and that is the+# design rather than an omission. A request reaches the gateway through whichever+# SDK its dialect calls for — the Portkey substrate (reported as ``GATEWAY``),+# plain ``httpx`` on the native extract/search routes (``GATEWAY`` as well), and+# the shared Anthropic driver that Claude travels on (reported as ``ANTHROPIC``) —+# so the reporting provider does not identify the gateway. ``pig-`` and+# ``pipelex_`` are both the gateway's own code namespaces and no vendor emits into+# either, so the code alone is both necessary and sufficient.+#+# **One failure can appear under two codes**, and leaving out the second one is+# how a caller reads "the provider rejected the request" for a file they can+# simply make smaller. The gateway renders a refusal in the vocabulary of the+# route it arrived on: its own ``pig-0N`` family on the LLM routes, where the+# client is speaking a provider's protocol, and its frozen ``pipelex_*`` contract+# codes on the native ``/v1/pipelex/*`` extract and search routes. A new limit has+# to be looked for in both.+_GATEWAY_REQUEST_LIMIT_BY_CODE: dict[str, GatewayRequestLimit] = {+ "pig-07": GatewayRequestLimit.BODY_TOO_LARGE,+ "pig-08": GatewayRequestLimit.BODY_LENGTH_REQUIRED,+ "pig-10": GatewayRequestLimit.OBJECT_TOO_LARGE,+ "pig-11": GatewayRequestLimit.BODY_TOO_DEEP,+ # The native routes' rendering of the same "over its cap" refusal: a storage+ # object the gateway resolved, and a document it fetched by URL.+ "pipelex_storage_object_too_large": GatewayRequestLimit.OBJECT_TOO_LARGE,+ "pipelex_document_too_large": GatewayRequestLimit.OBJECT_TOO_LARGE,+}+++class GatewayUnresolvedReference(StrEnum):+ """A "cannot resolve this reference" refusal raised by the Pipelex inference gateway itself.++ A request may name a file rather than carry it — a ``pipelex-storage://`` key+ the gateway resolves for the caller, or a document URL it fetches on their+ behalf. When it cannot turn that reference into bytes it refuses the request+ itself, before a provider sees it. Like the request-shape limits these are not+ inference failures and must not read as one: a caller who mistyped a storage+ key, pointed at an object this deployment cannot read, or aimed a URL at a host+ the gateway will not fetch from has a *reference* to fix, not a prompt to+ revise, and nothing about a retry can help.++ The members group by remedy rather than by wire code: two codes share a member+ only when the caller's next move is the same. Every member defers the specifics+ — the key, the host, the status, the media type — to the gateway's own refusal+ message, which already names them.++ Each member corresponds to one or more of the gateway's own error codes, which+ is the contract between the two repositories — the wording of a refusal is free+ to change, the code is not.+ """++ #: ``pig-09`` at HTTP 400 — the LLM routes' single fail-closed slot for "this+ #: reference cannot be resolved". Every storage failure but "over its cap"+ #: arrives under it (no bucket configured, not a storage reference, no such+ #: object, an object that cannot be read, a type no provider takes, no way to+ #: hand a file to the provider this model resolves to) because there the client+ #: speaks a provider's protocol and the gateway's own ``pig-0N`` family is the+ #: only vocabulary available. The message carries the difference; the code does+ #: not, so the advice defers to it.+ REFERENCE_UNRESOLVED = "reference_unresolved"+ #: ``pipelex_storage_uri_invalid`` at HTTP 400 — the reference does not obey the+ #: key grammar (the path-traversal guard refuses under the same code).+ STORAGE_REFERENCE_INVALID = "storage_reference_invalid"+ #: ``pipelex_storage_unreadable`` at HTTP 400 — the object is not there, or the+ #: gateway's role may not read it. Deliberately one member: the gateway does not+ #: tell a caller which of the two it was, and neither may we.+ STORAGE_OBJECT_UNREADABLE = "storage_object_unreadable"+ #: ``pipelex_storage_uri_unsupported`` at HTTP 400 — no bucket is configured, so+ #: this deployment does not serve ``pipelex-storage://`` references at all.+ #: Nothing about the inputs causes it: it is an operator's problem.+ STORAGE_NOT_SERVED = "storage_not_served"+ #: HTTP 400 — the document URL was refused before or during the fetch, on its+ #: form rather than on what it served: ``pipelex_unsupported_uri_scheme`` (a+ #: scheme the route does not read) and ``pipelex_document_scheme_refused`` (the+ #: fetch's own check, reachable only for an unparseable URL now that the route+ #: admits ``https:`` alone), ``pipelex_document_address_refused`` (the resolved+ #: address is not publicly routable) and ``pipelex_document_redirect_refused``+ #: (the origin answered a redirect, which the gateway will not follow).+ DOCUMENT_URL_REFUSED = "document_url_refused"+ #: ``pipelex_document_host_refused`` at HTTP 400 — the gateway's SSRF guard+ #: refuses to fetch documents from this host. Its own member rather than a share+ #: of ``DOCUMENT_URL_REFUSED`` because the advice has to state a deliberate+ #: security policy: the caller can act, but nothing about their document is at+ #: fault and no amount of reshaping it will help.+ DOCUMENT_HOST_REFUSED = "document_host_refused"+ #: ``pipelex_document_unreachable`` at HTTP 400 — the origin answered a+ #: non-success status. Not retried: the gateway renders it 400, a retry would+ #: re-run a whole inference call to re-fetch the document, and the common case+ #: is a URL that is simply wrong.+ DOCUMENT_UNREACHABLE = "document_unreachable"+ #: HTTP 400 — the document was fetched, and what came back cannot be used:+ #: ``pipelex_document_empty`` (served empty), ``pipelex_document_unsupported_type``+ #: (a media type the pipeline does not accept) and ``pipelex_document_bad_data_url``+ #: (a ``data:`` URL that cannot be decoded).+ DOCUMENT_CONTENT_UNUSABLE = "document_content_unusable"+++# The gateway's unresolvable-reference codes, mapped to what the runtime does+# about them.+#+# **Matched on the code alone, with no check on ``provider``**, for exactly the+# reason ``_GATEWAY_REQUEST_LIMIT_BY_CODE`` is: the reporting provider does not+# identify the gateway (three SDK hops report three provider names), while ``pig-``+# and ``pipelex_`` are the gateway's own code namespaces and no vendor emits into+# either.+#+# **Disjoint from the request-limit map by construction.** The two families answer+# different questions — one bounds the request's shape, the other says a reference+# could not be resolved — and a code belongs to exactly one of them. ``pig-09`` and+# ``pig-10`` are the clearest illustration: the same middleware raises both, one+# when the object is over its cap and one when it cannot be resolved at all.+_GATEWAY_UNRESOLVED_REFERENCE_BY_CODE: dict[str, GatewayUnresolvedReference] = {+ "pig-09": GatewayUnresolvedReference.REFERENCE_UNRESOLVED,+ # The native ``/v1/pipelex/*`` routes' own contract codes, where the gateway+ # names each cause instead of folding them into one fail-closed slot.+ "pipelex_storage_uri_invalid": GatewayUnresolvedReference.STORAGE_REFERENCE_INVALID,+ "pipelex_storage_unreadable": GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE,+ "pipelex_storage_uri_unsupported": GatewayUnresolvedReference.STORAGE_NOT_SERVED,+ "pipelex_document_scheme_refused": GatewayUnresolvedReference.DOCUMENT_URL_REFUSED,+ # The scheme refusal a caller actually reaches. ``classifyExtractInput`` runs+ # before any fetch and admits only ``https:``, ``data:`` and+ # ``pipelex-storage://``, so an ``http://`` URL is refused here rather than by+ # the fetch above — which by then can only see URLs that already start with+ # ``https://``.+ "pipelex_unsupported_uri_scheme": GatewayUnresolvedReference.DOCUMENT_URL_REFUSED,+ "pipelex_document_address_refused": GatewayUnresolvedReference.DOCUMENT_URL_REFUSED,+ "pipelex_document_redirect_refused": GatewayUnresolvedReference.DOCUMENT_URL_REFUSED,+ "pipelex_document_host_refused": GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED,+ "pipelex_document_unreachable": GatewayUnresolvedReference.DOCUMENT_UNREACHABLE,+ "pipelex_document_empty": GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE,+ "pipelex_document_unsupported_type": GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE,+ "pipelex_document_bad_data_url": GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE,+}+++class GatewayRoutingRefusal(StrEnum):+ """A "cannot route this request" refusal raised by the Pipelex inference gateway itself.++ Before a request can reach a provider the gateway has to decide *which*+ provider — it reads the model out of the request, looks it up in its own+ routing table, and hands the call to the integration that serves it. When+ that resolution fails it refuses the request itself, with codes of its own.+ These are not inference failures and must not read as one: a caller who named+ a model this deployment does not serve has a *model* to change or a+ deployment to fix, not a prompt to revise, and nothing about a retry can help.++ Every member is its own wire code here, unlike the two families beside it —+ not by accident but because each names a different thing that has to change.+ The one they nearly share is the flag: ``UNKNOWN_MODEL`` is the only member+ that means "this deployment does not know that model", so it is the only one+ the Classify step renders as a ``*ModelNotFoundError``.++ Each member corresponds to one of the gateway's own error codes, which is the+ contract between the two repositories — the wording of a refusal is free to+ change, the code is not.+ """++ #: ``pig-01`` at HTTP 400 — the request body names one that no integration+ #: this deployment carries lists. Reached from the runtime by a model deck+ #: whose handle the gateway does not serve: a stale deck, a typo in a+ #: ``.mthds`` file's model, or a model the deployment deliberately does not+ #: carry.+ #:+ #: **The code covers two other facts and does not distinguish them**: a body+ #: that names no model, and a body the gateway could not parse at all — its+ #: model reader returns "no model" from a bare ``catch`` around the JSON and+ #: multipart reads alike, so a truncated or non-conforming payload lands here+ #: too. Only the gateway's message says which, which is why the rendered+ #: advice defers to it rather than asserting a deck disagreement (see+ #: ``_render_gateway_routing_refusal_detail``). Splitting the code is a+ #: gateway-side change, filed on ``pipelex-manifold`` as L-260902-701614.+ UNKNOWN_MODEL = "unknown_model"+ #: ``pig-02`` at HTTP 400 — the model resolves, but to an integration the+ #: deployment has switched off because a credential variable is unset. Nothing+ #: about the request causes it and no request avoids it: the gateway's own+ #: message names the integration and the variables whoever operates it must+ #: set.+ DISABLED_INTEGRATION = "disabled_integration"+ #: ``pig-05`` at HTTP 400 — a native-protocol path names a model that another+ #: provider serves. Today that is only Google's generative shape —+ #: ``/v1/<v1|v1alpha|v1beta>/models/<model>:generateContent`` or its+ #: ``streamGenerateContent`` twin, under the gateway's own ``/v1`` prefix —+ #: the one ``nativeProtocolPaths.ts`` admits. Reaching it means the model deck and the+ #: gateway disagree about which backend serves a model: the model exists and+ #: is served, just not over the protocol the runtime spoke to ask for it.+ WRONG_PROTOCOL = "wrong_protocol"+ #: ``pig-06`` at HTTP 400 — a model reached one of the native+ #: ``/v1/pipelex/*`` routes (extract, search) whose integration's provider does+ #: not serve that capability. Again a deck-versus-gateway disagreement, or a+ #: model named on a pipe it cannot serve: the message names the integration,+ #: the provider and the capability.+ UNSERVED_CAPABILITY = "unserved_capability"+++# The gateway's routing-refusal codes, mapped to what the runtime does about them.+#+# **Matched on the code alone, with no check on ``provider``**, for exactly the+# reason the two maps above are: the reporting provider does not identify the+# gateway. These arrive under more than one ``ProviderName`` — the Portkey+# substrate and the OpenAI substrate that carries every chat call both report+# ``GATEWAY``, plain ``httpx`` on the native routes reports ``GATEWAY`` too, and+# Claude travels on the shared Anthropic driver — while ``pig-`` is the gateway's+# own code namespace and no vendor emits into it.+#+# **Two of the gateway's routing codes are deliberately absent**, and the omission+# is the scope decision rather than an oversight:+#+# - ``pig-03`` ("the client tried to route") refuses a ``x-portkey-*`` steering+# header, the ``?model=`` query form, a ``@<slug>/<model>`` virtual-key model, or+# a path and body naming different models. No client that talks to a+# Pipelex-operated gateway today produces any of those, so reaching it means a+# client bug rather than a caller's or an operator's mistake, and the status+# ladder's reading is as good as any.+#+# Two limits on that sentence, because it is the whole reason the code stays+# out. ``tests/unit/pipelex/providers/manifold/test_manifold_clients.py`` pins+# the manifold clients against the four steering headers by name, while the+# gateway refuses on an *allow*-list — so a ``portkey_ai`` release that starts+# sending some other ``x-portkey-*`` header turns every request into a+# ``pig-03`` with that test still green. And ``gateway_img_gen_worker.py`` does+# send ``x-portkey-config`` on every image call, which Portkey's cloud reads and+# a Pipelex-operated gateway refuses: harmless while ``pipelex_gateway`` keeps+# its default endpoint, and a client bug the day that backend names one of ours.+# - ``pig-04`` ("this gateway does not serve ``<method> <path>``") is the proxy+# policy refusing a path only the catch-all could answer, and it is a 404, so the+# ladder already reads it as model-not-found — wrong in kind, but unreachable+# while the runtime calls only the routes the gateway mounts, and a served-path+# drift is a deployment bug to surface loudly rather than a verdict to soften.+#+# ``pig-09`` is not a routing refusal either: it belongs to the+# unresolvable-reference family, which ``_GATEWAY_UNRESOLVED_REFERENCE_BY_CODE``+# reads.+_GATEWAY_ROUTING_REFUSAL_BY_CODE: dict[str, GatewayRoutingRefusal] = {+ "pig-01": GatewayRoutingRefusal.UNKNOWN_MODEL,+ "pig-02": GatewayRoutingRefusal.DISABLED_INTEGRATION,+ "pig-05": GatewayRoutingRefusal.WRONG_PROTOCOL,+ "pig-06": GatewayRoutingRefusal.UNSERVED_CAPABILITY,+}++def _resolve_sdk_exception_type(exc: BaseException, *, status_code: int | None) -> str:"""Return the ``sdk_exception_type`` name, normalizing status-less httpx transport errors.@@ -110,6 +389,65 @@ class ProviderErrorMetadata(BaseModel):):return False+ @property+ def gateway_request_limit(self) -> GatewayRequestLimit | None:+ """Which of the gateway's request-shape limits this refusal hit, if any.++ Reads ``provider_error_code``, which every Extract hop that can carry a+ gateway refusal populates: the shared Anthropic driver recovers it from the+ ``{"error": {"code": …}}`` body the gateway renders, the OpenAI substrate+ reads the same value off ``exc.code`` after its SDK pre-unwraps that body,+ and the Portkey substrate re-parses the response because its SDK replaces+ ``exc.body`` with the message string (see ``extract_gateway_metadata``).++ Returns ``None`` for every other refusal — including the gateway's "cannot+ resolve this reference" codes and its routing refusals, each a separate+ family read by ``gateway_unresolved_reference`` and+ ``gateway_routing_refusal``.+ """+ if self.provider_error_code is None:+ return None+ return _GATEWAY_REQUEST_LIMIT_BY_CODE.get(self.provider_error_code)++ @property+ def gateway_unresolved_reference(self) -> GatewayUnresolvedReference | None:+ """Which of the gateway's unresolvable-reference refusals this is, if any.++ Reads ``provider_error_code`` off the same Extract hops+ ``gateway_request_limit`` does, and for the same reason: a request that+ names a file rather than carrying it can be refused by the gateway before+ any provider sees it, and the code is the only thing that says so.++ The three gateway families are disjoint — a code names a bound the request+ exceeded, a reference that could not be resolved, or a request that could+ not be routed, never two of them — so the Classify step may read them in+ any order. Returns ``None`` for every other refusal, the gateway's routing+ codes included.+ """+ if self.provider_error_code is None:+ return None+ return _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE.get(self.provider_error_code)++ @property+ def gateway_routing_refusal(self) -> GatewayRoutingRefusal | None:+ """Which of the gateway's routing refusals this is, if any.++ Reads ``provider_error_code`` off the same Extract hops the two properties+ above do, and for the same reason: the gateway can refuse to route a+ request before any provider sees it, and the code is the only thing that+ says so. Without this the whole family falls through to the status ladder's+ 400 arm and a caller who named a model the deployment does not serve is+ told to review their prompt.++ Disjoint from both other families by construction, so the Classify step may+ read the three in any order. Returns ``None`` for every other refusal,+ including the gateway's own ``pig-03`` and ``pig-04``, which the runtime's+ own clients cannot produce (see ``_GATEWAY_ROUTING_REFUSAL_BY_CODE``).+ """+ if self.provider_error_code is None:+ return None+ return _GATEWAY_ROUTING_REFUSAL_BY_CODE.get(self.provider_error_code)+@propertydef is_content_policy_violation(self) -> bool:"""Whether the error indicates a content policy / safety filter violation.@@ -478,6 +816,42 @@ def _provider_error_code_from_flat_body(body: Any) -> str | None:return None+def _pipelex_service_error_code_from_body(body: Any) -> str | None:+ """Read the error code off a body a Pipelex-operated gateway rendered, preferring ``code``.++ Same traversal as ``_provider_error_code_from_body`` then+ ``_provider_error_code_from_flat_body`` — nested ``{"error": {…}}`` first, then+ the top level, which is where the vendored OpenAI client leaves it after+ pre-unwrapping — **but reading ``code`` before ``type``**, and that inversion+ is the whole point of the function.++ Our own services put the *specific* code in ``code`` and a generic+ OpenAI-shaped bucket in ``type``: every refusal on the native+ ``/v1/pipelex/*`` routes is rendered as+ ``{"error": {"message": …, "type": "invalid_request_error", "code":+ "pipelex_document_too_large"}}``. The vendor-facing precedence is right for+ Anthropic, whose error section carries a ``type`` and no ``code`` at all, and+ wrong here — it replaces every ``pipelex_*`` code with+ ``invalid_request_error`` and the code never reaches the classifier.++ The gateway's fail-closed shape carries only ``code`` (no ``type`` beside it),+ so the ``pig-0N`` family reads identically through either precedence.+ """+ if not isinstance(body, dict):+ return None+ body_dict = cast("dict[str, Any]", body)+ error_section = body_dict.get("error")+ sections: list[dict[str, Any]] = []+ if isinstance(error_section, dict):+ sections.append(cast("dict[str, Any]", error_section))+ sections.append(body_dict)+ for section in sections:+ code = section.get("code") or section.get("type")+ if isinstance(code, str):+ return code+ return None++def _parse_response_text_body(response: Any) -> tuple[Any | None, str | None]:"""Read ``response.text`` and recover ``(body, provider_error_code)`` on a best-effort basis.@@ -698,13 +1072,84 @@ def extract_huggingface_metadata(exc: BaseException) -> ProviderErrorMetadata:)+def extract_manifold_metadata(exc: BaseException) -> ProviderErrorMetadata:+ """Distill a raw-httpx failure against the Pipelex Manifold service into metadata.++ The manifold plugin's native routes (``/v1/pipelex/extract``, ``/v1/pipelex/search``) are not+ OpenAI-shaped, so they are called with plain ``httpx`` rather than through a vendor SDK. That+ leaves two exception shapes to distill:++ - ``httpx.HTTPStatusError``, which carries the whole ``response`` — status, headers, and a body+ this reads as JSON on a best-effort basis;+ - ``httpx.RequestError`` (connect, timeout, read), which carries only a request; every+ status-related field comes back as ``None``, and the class name is what the classify step+ matches on to call it a network failure.++ **The error code is read ``code`` first**, via ``_pipelex_service_error_code_from_body``, and+ the ordinary vendor-facing precedence would lose it here. A refusal these routes raise+ themselves is rendered as ``{"error": {"message": …, "type": "invalid_request_error", "code":+ "pipelex_document_too_large"}}`` — the generic bucket in ``type``, the frozen contract code the+ classifier actually needs in ``code`` — so reading ``type`` first replaces every ``pipelex_*``+ code with ``invalid_request_error``. The gateway's fail-closed ``pig-0N`` shape carries no+ ``type`` at all, so it reads the same either way.++ **It reports ``ProviderName.GATEWAY``**, and that is a decision rather than an oversight: the+ manifold service *is* the same gateway codebase, so it phrases quota exhaustion and rate+ limiting identically, and every ``match`` on ``ProviderName`` would need a second arm with the+ same body to say otherwise. Which of the two services answered is already carried by the error's+ model handle and backend name.+ """+ response = getattr(exc, "response", None)+ status_code = getattr(response, "status_code", None)+ if not isinstance(status_code, int):+ status_code = None+ headers = getattr(response, "headers", None)+ request_id: str | None = None+ retry_after_seconds: float | None = None+ if headers is not None:+ request_id_value = headers.get("x-request-id") or headers.get("x-portkey-trace-id")+ if isinstance(request_id_value, str):+ request_id = request_id_value+ retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))+ body: Any | None = None+ if response is not None:+ try:+ body = response.json()+ except (json.JSONDecodeError, UnicodeDecodeError, ValueError):+ # A refusal the service did not render as JSON is still a refusal; the status code and+ # the message carry it, and insisting on a body here would trade a classified error for+ # a decode error raised while classifying one.+ body = None+ provider_error_code = _pipelex_service_error_code_from_body(body)+ return ProviderErrorMetadata(+ provider=ProviderName.GATEWAY,+ sdk_exception_type=type(exc).__name__,+ message=str(exc),+ status_code=status_code,+ request_id=request_id,+ retry_after_seconds=retry_after_seconds,+ provider_error_code=provider_error_code,+ body=body,+ )++def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata:"""Distill a Portkey/Gateway SDK exception into a ``ProviderErrorMetadata``.- ``APIStatusError`` subclasses expose ``status_code``, ``response`` (httpx),- and ``body`` (already a pre-parsed dict — Portkey mirrors the OpenAI SDK- style here). ``APIConnectionError`` / ``APITimeoutError`` carry only a- request; every status field comes back as ``None``.+ ``APIStatusError`` subclasses expose ``status_code``, ``response`` (httpx) and+ ``body``. ``APIConnectionError`` / ``APITimeoutError`` carry only a request;+ every status field comes back as ``None``.++ **``body`` cannot be trusted to be the payload here**, and that is the whole+ reason for the response fallback below. Portkey's own+ ``_make_status_error_from_response`` sets ``body`` to+ ``json.loads(text)["error"]["message"]`` — the *message string*, not the+ document — so on every refusal the SDK itself raises there is no dict to read a+ code from. Reading ``exc.body`` alone recovered ``provider_error_code = None``+ for every Portkey-substrate error the runtime ever saw. A dict does reach here+ on the paths that bypass Portkey's factory (the vendored OpenAI client the+ image workers fall back to pre-unwraps ``body["error"]``), so the dict probe+ stays first and the response is only re-parsed when it came up empty."""status_code = getattr(exc, "status_code", None)if not isinstance(status_code, int):@@ -719,7 +1164,18 @@ def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata:request_id = request_id_valueretry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))body: Any = getattr(exc, "body", None)- provider_error_code = _provider_error_code_from_body(body) or _provider_error_code_from_flat_body(body)+ provider_error_code = _pipelex_service_error_code_from_body(body)+ if provider_error_code is None:+ # The response is still buffered — the SDK just read ``.text`` off it to+ # build the message — so the payload it discarded is recoverable here+ # rather than lost. A recovered code means the helper parsed a document, so+ # it also replaces the stringified ``body`` and the in-process+ # content-policy scan gets structure back instead of one rendered sentence.+ recovered_body, _ = _parse_response_text_body(response)+ recovered_code = _pipelex_service_error_code_from_body(recovered_body)+ provider_error_code = recovered_code+ if recovered_code is not None:+ body = recovered_bodyreturn ProviderErrorMetadata(provider=ProviderName.GATEWAY,sdk_exception_type=type(exc).__name__,diff --git a/pipelex/cogt/inference/error_classify.py b/pipelex/cogt/inference/error_classify.pyindex 8a8cafdaf..5852595c1 100644--- a/pipelex/cogt/inference/error_classify.py+++ b/pipelex/cogt/inference/error_classify.py@@ -16,7 +16,13 @@ SDK exception type name.from pydantic import BaseModelfrom pipelex.cogt.exceptions import InferenceErrorCategory-from pipelex.cogt.inference.error_classification import SDKErrorEnvelope, UserActionKind+from pipelex.cogt.inference.error_classification import (+ GatewayRequestLimit,+ GatewayRoutingRefusal,+ GatewayUnresolvedReference,+ SDKErrorEnvelope,+ UserActionKind,+)class ClassificationResult(BaseModel):@@ -30,6 +36,26 @@ class ClassificationResult(BaseModel):category: InferenceErrorCategoryuser_action_kind: UserActionKindis_model_not_found: bool = False+ # Which of the inference gateway's request-shape limits was hit, when the+ # refusal came from the gateway itself rather than from a provider. Like+ # ``is_model_not_found`` this is a flag rather than a category: it does not+ # change the retry decision, it lets the Render step say which limit was hit+ # instead of falling back to the generic "the provider rejected the request".+ gateway_request_limit: GatewayRequestLimit | None = None+ # Which of the gateway's unresolvable-reference refusals this is, when the+ # request named a file the gateway could not turn into bytes. A flag for the+ # same reason as the field above: the retry decision is unchanged, but the+ # Render step can say which reference failed and how, instead of telling a+ # caller with a mistyped storage key to revise their prompt.+ gateway_unresolved_reference: GatewayUnresolvedReference | None = None+ # Which of the gateway's routing refusals this is, when the gateway could not+ # decide which provider should serve the request at all. A flag for the same+ # reason as the two fields above: the retry decision is unchanged, but the+ # Render step can say that the *gateway* refused to route the model, instead+ # of telling a caller who named a model it does not serve to revise their+ # prompt — or, for the three whose model does exist, instead of the generic+ # "the requested model was not found".+ gateway_routing_refusal: GatewayRoutingRefusal | None = None# Status-less SDK exception type names recognizable regardless of provider:@@ -94,6 +120,130 @@ def _classify_statusless(metadata: SDKErrorEnvelope) -> ClassificationResult:)+def _classify_gateway_request_limit(*, limit: GatewayRequestLimit) -> ClassificationResult:+ """Classify a request-shape refusal the inference gateway raised on its own.++ None of these is retryable and none is a provider failure: the gateway refused+ the request before a provider ever saw it, and sending the identical request+ again earns the identical refusal.+ """+ match limit:+ case GatewayRequestLimit.BODY_TOO_LARGE | GatewayRequestLimit.OBJECT_TOO_LARGE | GatewayRequestLimit.BODY_TOO_DEEP:+ # The caller sent more than the deployment serves — a smaller input is+ # the whole remedy, and it is theirs to make.+ return ClassificationResult(+ category=InferenceErrorCategory.CONTENT,+ user_action_kind=UserActionKind.CHANGE_INPUT,+ gateway_request_limit=limit,+ )+ case GatewayRequestLimit.BODY_LENGTH_REQUIRED:+ # Nothing about the *content* is wrong here: an HTTP client framed the+ # request in a way the gateway will not bound. No client the runtime+ # ships produces it, so reaching this means something in the transport+ # stack changed — which is an operator's problem, not the caller's.+ return ClassificationResult(+ category=InferenceErrorCategory.CONFIGURATION,+ user_action_kind=UserActionKind.CONTACT_SUPPORT,+ gateway_request_limit=limit,+ )+++def _classify_gateway_unresolved_reference(*, reference: GatewayUnresolvedReference) -> ClassificationResult:+ """Classify an unresolvable-reference refusal the inference gateway raised on its own.++ None of these is retryable, for the same reason none of the request-shape+ limits is: the gateway refused before a provider saw the request, and the same+ reference resolves the same way the second time. That includes+ ``DOCUMENT_UNREACHABLE``, where the origin *could* have been transiently down —+ the gateway renders it a 400, a retry would re-run a whole inference call just+ to re-fetch a document, and the common case is a URL that is simply wrong.+ """+ match reference:+ case (+ GatewayUnresolvedReference.REFERENCE_UNRESOLVED+ | GatewayUnresolvedReference.STORAGE_REFERENCE_INVALID+ | GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE+ | GatewayUnresolvedReference.DOCUMENT_URL_REFUSED+ | GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED+ | GatewayUnresolvedReference.DOCUMENT_UNREACHABLE+ | GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE+ ):+ # The reference is the caller's to fix — a different key, a different+ # URL, or the file uploaded where the gateway can reach it.+ # ``DOCUMENT_HOST_REFUSED`` belongs here too: the refusal is a security+ # policy rather than a fault, but the caller is still the one who can+ # act on it, and the Render step is where that distinction is stated.+ return ClassificationResult(+ category=InferenceErrorCategory.CONTENT,+ user_action_kind=UserActionKind.CHANGE_INPUT,+ gateway_unresolved_reference=reference,+ )+ case GatewayUnresolvedReference.STORAGE_NOT_SERVED:+ # This deployment serves no ``pipelex-storage://`` references at all,+ # because no bucket is configured for it. Nothing about the inputs+ # causes it and no input can avoid it — it is an operator's problem,+ # like ``BODY_LENGTH_REQUIRED``.+ return ClassificationResult(+ category=InferenceErrorCategory.CONFIGURATION,+ user_action_kind=UserActionKind.CONTACT_SUPPORT,+ gateway_unresolved_reference=reference,+ )+++def _classify_gateway_routing_refusal(*, refusal: GatewayRoutingRefusal) -> ClassificationResult:+ """Classify a routing refusal the inference gateway raised on its own.++ Every member is ``CONFIGURATION``: nothing in the prompt, the parameters or the+ inputs causes any of these, and no edit to them avoids one. That is the whole+ point of the family — without it all four take the status ladder's 400 arm and+ read as a provider rejecting the caller's content.++ None is retryable, for the reason none of the other two gateway families is:+ the gateway refused before a provider saw the request, and an identical retry+ earns an identical refusal.+ """+ match refusal:+ case GatewayRoutingRefusal.UNKNOWN_MODEL:+ # The deployment does not know that model at all — which is exactly+ # what the ``is_model_not_found`` flag means, so this is the one member+ # that gets it. It selects the family's ``*ModelNotFoundError`` class,+ # which ``pipe_operator.py`` re-raises as a+ # ``PipeOperatorModelAvailabilityError`` carrying the model handle: the+ # same pipe-level error a caller gets when the deck itself cannot find+ # a model, which is this case seen from the gateway.+ return ClassificationResult(+ category=InferenceErrorCategory.CONFIGURATION,+ user_action_kind=UserActionKind.CHANGE_MODEL,+ is_model_not_found=True,+ gateway_routing_refusal=refusal,+ )+ case GatewayRoutingRefusal.WRONG_PROTOCOL | GatewayRoutingRefusal.UNSERVED_CAPABILITY:+ # The model exists and is served — it just cannot do what was asked, or+ # was asked over a protocol its integration does not speak. So the flag+ # stays unset: telling a caller the model was not found would be false,+ # and the Render step carries the real distinction. ``CHANGE_MODEL`` is+ # still what an end caller can do about it.+ return ClassificationResult(+ category=InferenceErrorCategory.CONFIGURATION,+ user_action_kind=UserActionKind.CHANGE_MODEL,+ gateway_routing_refusal=refusal,+ )+ case GatewayRoutingRefusal.DISABLED_INTEGRATION:+ # The integration is switched off because whoever operates the gateway+ # never set its credential. The deployment is what has to change, not+ # the request — so this is the family's ``CONTACT_SUPPORT`` arm, the+ # same call ``STORAGE_NOT_SERVED`` and ``BODY_LENGTH_REQUIRED`` get.+ # ``CHECK_CREDENTIALS`` would send a hosted caller to rotate their own+ # perfectly valid key; ``CHANGE_MODEL`` would send them shopping for a+ # model over an operator's unset variable. The flag stays unset: the+ # handle resolved, so this is not a model the deployment does not know.+ return ClassificationResult(+ category=InferenceErrorCategory.CONFIGURATION,+ user_action_kind=UserActionKind.CONTACT_SUPPORT,+ gateway_routing_refusal=refusal,+ )++def classify_inference_error(metadata: SDKErrorEnvelope) -> ClassificationResult:"""Classify an inference SDK error from its structured metadata.@@ -110,6 +260,34 @@ def classify_inference_error(metadata: SDKErrorEnvelope) -> ClassificationResultif status_code is None:return _classify_statusless(metadata)+ # The inference gateway's own request-shape refusals come first: an explicit+ # code from a service we operate is a more specific verdict than any status+ # bucket, and the statuses they arrive on (413, 411, 400) would otherwise be+ # read as a provider rejecting the prompt. They cannot collide with the quota+ # rules below, which only fire on 402 and 429.+ gateway_request_limit = metadata.gateway_request_limit+ if gateway_request_limit is not None:+ return _classify_gateway_request_limit(limit=gateway_request_limit)++ # And its "cannot resolve this reference" refusals, for the same reason and on+ # the same footing. The two code sets are disjoint — a code names either a+ # bound the request exceeded or a reference that could not be resolved — so the+ # order between these two branches carries no meaning. Both arrive on 400,+ # which the status ladder would read as a provider rejecting the prompt.+ gateway_unresolved_reference = metadata.gateway_unresolved_reference+ if gateway_unresolved_reference is not None:+ return _classify_gateway_unresolved_reference(reference=gateway_unresolved_reference)++ # And its refusals to route the request at all, on the same footing again. All+ # three gateway code sets are disjoint, so the order among these branches+ # carries no meaning; what matters is that all three run ahead of the status+ # ladder. Every routing refusal arrives on 400, which the ladder would read as+ # a provider rejecting the prompt — for a model the gateway does not serve, is+ # not configured to reach, or cannot ask what was asked.+ gateway_routing_refusal = metadata.gateway_routing_refusal+ if gateway_routing_refusal is not None:+ return _classify_gateway_routing_refusal(refusal=gateway_routing_refusal)+# Quota exhaustion is decided by the provider-aware ``is_quota_exhaustion``# property and takes precedence over the HTTP status: providers signal it on# different statuses (OpenAI/Anthropic 429, Mistral/Gateway 402, AWS 400).diff --git a/pipelex/cogt/inference/error_render.py b/pipelex/cogt/inference/error_render.pyindex f9f8abb27..4c9c81fb9 100644--- a/pipelex/cogt/inference/error_render.py+++ b/pipelex/cogt/inference/error_render.py@@ -21,7 +21,14 @@ from pipelex.cogt.exceptions import (SearchJobFailureError,SearchModelNotFoundError,)-from pipelex.cogt.inference.error_classification import SDKErrorEnvelope, UserAction, UserActionKind+from pipelex.cogt.inference.error_classification import (+ GatewayRequestLimit,+ GatewayRoutingRefusal,+ GatewayUnresolvedReference,+ SDKErrorEnvelope,+ UserAction,+ UserActionKind,+)from pipelex.cogt.inference.error_classify import ClassificationResult@@ -57,8 +64,153 @@ def _format_message(metadata: SDKErrorEnvelope, *, model_desc: str) -> str:return f"{metadata.provider} inference failed for model '{model_desc}'{status_part}: {metadata.message}"+def _render_gateway_limit_detail(*, limit: GatewayRequestLimit) -> str:+ """Produce the advice for a request-shape refusal the inference gateway raised itself.++ Deliberately says nothing about a number. The caps are the deployment's, they+ differ between deployments, and the gateway already names its own figures in+ the message this detail sits beside — repeating a compiled-in guess here is how+ advice starts contradicting the refusal it explains.++ **This is where a per-plan message belongs** once the hosted product's tier+ limits are wired through: the gateway knows nothing of users, organisations or+ plans, so "your plan allows files up to N MB" can only be said from here.+ """+ match limit:+ case GatewayRequestLimit.BODY_TOO_LARGE:+ return "The request was too large for the inference gateway — send less in one call, or use smaller inputs."+ case GatewayRequestLimit.OBJECT_TOO_LARGE:+ return "A file the request refers to is over the inference gateway's per-file size limit — use a smaller file."+ case GatewayRequestLimit.BODY_TOO_DEEP:+ return "The request nests too deeply for the inference gateway — flatten the inputs or the output structure."+ case GatewayRequestLimit.BODY_LENGTH_REQUIRED:+ return (+ "The inference gateway could not read the request's declared size and refused it: it requires a "+ "Content-Length and does not accept a chunked body. Nothing about the inputs causes this — contact support."+ )+++def _render_gateway_unresolved_reference_detail(*, reference: GatewayUnresolvedReference) -> str:+ """Produce the advice for a reference the inference gateway could not resolve.++ Names no key, host, status or media type, for the same reason+ ``_render_gateway_limit_detail`` names no number: the gateway's own refusal+ message sits beside this detail and already states the specifics. What this+ text adds is what the caller should *do*, which the message does not say.+ """+ match reference:+ case GatewayUnresolvedReference.REFERENCE_UNRESOLVED:+ return (+ "A file reference in the request could not be resolved by the inference gateway — "+ "the error message names the cause; fix the reference it names."+ )+ case GatewayUnresolvedReference.STORAGE_REFERENCE_INVALID:+ return "The pipelex-storage:// reference in the request is malformed — check it against the key the upload returned."+ case GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE:+ return (+ "The referenced storage object does not exist or cannot be read — check that the reference points at a file "+ "uploaded to this deployment."+ )+ case GatewayUnresolvedReference.STORAGE_NOT_SERVED:+ return (+ "This inference gateway does not serve pipelex-storage:// references at all — no storage is configured for it. "+ "Nothing about the inputs causes this — contact support."+ )+ case GatewayUnresolvedReference.DOCUMENT_URL_REFUSED:+ return (+ "The inference gateway refused the document URL — send a plain public https:// URL, a data: URL, or a "+ "pipelex-storage:// reference, and give the final address rather than one that redirects."+ )+ case GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED:+ return (+ "The inference gateway does not fetch documents from that host, as a matter of security policy: private and "+ "internal addresses are never fetched. Host the document at a publicly reachable address, or upload it to "+ "Pipelex storage and reference it from there."+ )+ case GatewayUnresolvedReference.DOCUMENT_UNREACHABLE:+ return (+ "The document could not be fetched from its URL — check that it is live and publicly reachable, and try again "+ "if its host was temporarily down."+ )+ case GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE:+ return (+ "The document was fetched but cannot be used — the error message says whether it was served empty, in a media "+ "type the pipeline does not accept, or as a data: URL that could not be decoded."+ )+++def _render_gateway_routing_refusal_detail(*, refusal: GatewayRoutingRefusal) -> str:+ """Produce the advice for a request the inference gateway refused to route.++ Names no model, integration, protocol or capability, for the same reason+ ``_render_gateway_limit_detail`` names no number: the gateway's own refusal+ message sits beside this detail and already states every specific. What this+ text adds is what the caller — or whoever operates the deployment — should+ *do*, which the message does not say.++ Every member whose remedy could be a deck edit says "the model deck" out loud.+ The runtime picks the model, the protocol and the route from its own deck, so+ those refusals usually mean the deck and the gateway disagree about a model+ rather than that the caller chose badly, and advice that only said "pick+ another model" would send an operator hunting for a model problem that is a+ configuration problem.+ """+ match refusal:+ case GatewayRoutingRefusal.UNKNOWN_MODEL:+ # The second sentence is hedged deliberately. ``pig-01`` is the gateway's+ # answer to three different facts — it serves no such model, the body+ # named none, and the body could not be parsed at all (its model reader+ # returns "no model" from a bare ``catch``) — and the wire code does not+ # tell them apart. Only the gateway's own message does, so the advice+ # sends the reader there before it sends them to the deck: asserting a+ # deck-versus-gateway disagreement outright would be a confident lie for+ # the other two causes. Splitting the code is the real fix, filed on+ # ``pipelex-manifold`` as L-260902-701614.+ return (+ "The inference gateway does not serve that model — pick a model this deployment serves. Its own message is "+ "the authority on which: the same code also answers a request it could not read a model out of at all. "+ "If it names a model your model deck lists, the deck and the gateway disagree about what is available."+ )+ case GatewayRoutingRefusal.DISABLED_INTEGRATION:+ return (+ "The model is served by an integration this inference gateway has not enabled — its credentials are unset. "+ "Nothing about the request causes this, and none of your own credentials are at fault: the error message "+ "names the integration and the variables whoever operates the gateway has to set. Contact support."+ )+ case GatewayRoutingRefusal.WRONG_PROTOCOL:+ return (+ "The inference gateway serves that model, but not over the protocol the request used for it — your model "+ "deck names a different backend for it than the gateway routes it to. Correct the deck, or pick another model."+ )+ case GatewayRoutingRefusal.UNSERVED_CAPABILITY:+ return (+ "The model's integration does not serve that capability on the inference gateway — the error message names "+ "the provider and what was asked of it. Pick a model whose provider serves it, or correct the model deck."+ )++def _render_detail(metadata: SDKErrorEnvelope, *, classification: ClassificationResult) -> str:"""Produce the free-form user-facing advice text for the classified error."""+ if classification.gateway_request_limit is not None:+ # Branches ahead of the action kind rather than inside it: the limit names+ # the remedy more precisely than the kind does, and two of the four limits+ # would otherwise land on advice that is simply wrong for them.+ return _render_gateway_limit_detail(limit=classification.gateway_request_limit)+ if classification.gateway_unresolved_reference is not None:+ # Same reason, one indirection further out: every member here would+ # otherwise render "review the prompt, parameters, and inputs" for a+ # reference the caller has to repair, and one of them for a security+ # refusal that no reshaping of the inputs can get around.+ return _render_gateway_unresolved_reference_detail(reference=classification.gateway_unresolved_reference)+ if classification.gateway_routing_refusal is not None:+ # Same reason a third time, and here the action kind is too coarse for+ # every member rather than for some: ``CHANGE_MODEL`` renders "the+ # requested model was not found", which is right only for ``pig-01`` and+ # false for ``pig-05`` and ``pig-06``, whose model exists and is served —+ # and for ``pig-02``, whose model resolves but to an integration that is+ # switched off. ``CONTACT_SUPPORT`` renders "the error could not be+ # classified" for a refusal that named itself precisely.+ return _render_gateway_routing_refusal_detail(refusal=classification.gateway_routing_refusal)match classification.user_action_kind:case UserActionKind.WAIT_AND_RETRY:if metadata.retry_after_seconds is not None:diff --git a/pipelex/cogt/model_backends/backend.py b/pipelex/cogt/model_backends/backend.pyindex de067c211..089a18fc4 100644--- a/pipelex/cogt/model_backends/backend.py+++ b/pipelex/cogt/model_backends/backend.py@@ -8,11 +8,24 @@ from pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.system.configuration.config_model import ConfigModelfrom pipelex.tools.typing.pydantic_utils import empty_dict_factory_of, empty_list_factory_of+# The remote-config section the legacy gateway backend's specs come from. It is spelled here as a+# *compatibility default* rather than only in the shipped `backends.toml`, and the distinction+# matters: `backends.toml` is the user's own file on disk, written before this field existed and+# never rewritten by an upgrade, so a declaration that does not name a section has to keep meaning+# what it always meant. Every new managed backend states its section explicitly.+LEGACY_GATEWAY_MODEL_SPECS_SECTION = "backend_model_specs"++# The section the manifold dialect's catalog is published under, beside the legacy one in the same+# artifact. Named here so the kit config, the fetcher's dummy and the tests cannot drift apart on a+# string literal.+MANIFOLD_MODEL_SPECS_SECTION = "manifold_model_specs"+class PipelexBackend(StrEnum):"""Special Pipelex-managed inference backends."""GATEWAY = "pipelex_gateway"+ MANIFOLD = "pipelex_manifold"INTERNAL = "internal" # Software-only backend, runs locally without AI@property@@ -20,20 +33,39 @@ class PipelexBackend(StrEnum):match self:case PipelexBackend.GATEWAY:return "Pipelex Gateway"+ case PipelexBackend.MANIFOLD:+ return "Pipelex Manifold"case PipelexBackend.INTERNAL:return "Internal (software-only)"- @classmethod- def is_gateway_backend(cls, backend_name: str) -> bool:- try:- the_backend = cls(backend_name)- except ValueError:- return False- match the_backend:- case PipelexBackend.GATEWAY:- return True- case PipelexBackend.INTERNAL:- return False++# The Pipelex-managed gateway backends the kit ships, in a stable order so a message built from them+# reads the same every time.+#+# This is a *second*, narrower way of naming a managed gateway than `resolve_model_specs_section`, and+# it exists for the callers that hold only a backend name and no configuration — an inference worker+# asserting a provider behaviour that follows from running behind our gateway codebase, for instance.+# Wherever the configuration is in hand, the declared section is the authority.+MANAGED_GATEWAY_BACKEND_NAMES: tuple[str, ...] = (PipelexBackend.GATEWAY, PipelexBackend.MANIFOLD)+++def resolve_model_specs_section(*, backend_name: str, declared_section: str | None) -> str | None:+ """The remote-config section this backend's model specs come from, or `None` when it has none.++ **Declaring a section is what makes a backend a managed gateway backend**: its model specs+ arrive from the Pipelex service's published artifact rather than from a local per-backend TOML.+ A backend with no section resolves to `None` and loads its specs from its own file, which is+ every BYOK backend and the internal one.++ The one name that resolves to a section it did not declare is `pipelex_gateway`, and only+ because its declarations predate the field — see `LEGACY_GATEWAY_MODEL_SPECS_SECTION`. An+ explicit declaration always wins, including on that name.+ """+ if declared_section is not None:+ return declared_section+ if backend_name == PipelexBackend.GATEWAY:+ return LEGACY_GATEWAY_MODEL_SPECS_SECTION+ return Noneclass InferenceBackend(ConfigModel):diff --git a/pipelex/cogt/model_backends/backend_factory.py b/pipelex/cogt/model_backends/backend_factory.pyindex 061ba0c8d..820251ab9 100644--- a/pipelex/cogt/model_backends/backend_factory.py+++ b/pipelex/cogt/model_backends/backend_factory.py@@ -13,6 +13,10 @@ class InferenceBackendBlueprint(ConfigModel):enabled: bool = Trueendpoint: str | None = Noneapi_key: str | None = None+ # Naming a remote-config section is what declares this backend a *managed gateway* backend: its+ # model specs arrive from the Pipelex service's published artifact rather than from a local+ # per-backend TOML. See `resolve_model_specs_section`, which is the only reader.+ model_specs_section: str | None = Nonelisted_constraints: list[ListedConstraint] = Field(default_factory=empty_list_factory_of(ListedConstraint))valued_constraints: dict[ValuedConstraint, Any] = Field(default_factory=empty_dict_factory_of(ValuedConstraint))extra_config: dict[str, Any] = Field(default_factory=dict)diff --git a/pipelex/cogt/model_backends/backend_library.py b/pipelex/cogt/model_backends/backend_library.pyindex acce4b348..753b0de71 100644--- a/pipelex/cogt/model_backends/backend_library.py+++ b/pipelex/cogt/model_backends/backend_library.py@@ -14,7 +14,7 @@ from pipelex.cogt.exceptions import (InferenceBackendLibraryValidationError,InferenceModelSpecError,)-from pipelex.cogt.model_backends.backend import InferenceBackend, PipelexBackend+from pipelex.cogt.model_backends.backend import InferenceBackend, resolve_model_specs_sectionfrom pipelex.cogt.model_backends.backend_factory import (InferenceBackendBlueprint,InferenceBackendFactory,@@ -110,12 +110,13 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):backends_library_paths: Sequence[Path],backends_dir_path: str,include_disabled: bool = False,- gateway_config: GatewayConfig | None = None,+ managed_gateway_configs: dict[str, GatewayConfig] | None = None,lenient: bool = False,):"""Load backend configurations from TOML files.- For pipelex_gateway, uses the provided remote config and merges with local overrides.+ For a managed gateway backend, uses that backend's slice of the fetched remote config and+ merges with local overrides from a file named after the backend.**A file left behind by a schema change is carried forward rather than fatal.** When a localper-backend TOML is refused, the `inference-backend` ledger is replayed over that one file@@ -139,10 +140,12 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):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.- lenient: When True, skip a backend whose *credentials* cannot be resolved, or the- gateway backend when no `gateway_config` was handed in, instead of raising — that- is the whole of the tolerance. A malformed configuration (an unknown+ managed_gateway_configs: One gateway configuration per managed backend, keyed by backend+ name. A managed backend absent from this mapping has no live specs — see the+ per-backend branch below for what that means in each mode.+ lenient: When True, skip a backend whose *credentials* cannot be resolved, or a managed+ gateway backend when no `managed_gateway_configs` were handed in, instead of+ raising — that is the whole of the tolerance. A malformed configuration (an unknownor invalid key, a model spec that is not a table, a missing per-backend TOML) staysfatal in both modes: a config typo must never silently delete a backend, because thecommands that boot leniently (validate, show, dry runs) would then report the far@@ -190,6 +193,23 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):continueif runtime_manager.is_ci_testing and backend_name == "vertexai":continue+ # Read before substitution, deliberately: the section is a plain literal with no `${…}`+ # in it, and whether this backend is *managed* decides how the substitution below is+ # allowed to fail. Reading it off the validated blueprint would be too late.+ declared_model_specs_section = self._declared_model_specs_section(backend_dict=inference_backend_blueprint_dict_raw)+ model_specs_section = resolve_model_specs_section(+ backend_name=backend_name,+ declared_section=declared_model_specs_section,+ )+ # **The tolerance below keys on the DECLARATION, not on the resolved section**, and the+ # two come apart on exactly one name. `pipelex_gateway` is handed a section by+ # compatibility default so a `backends.toml` written before the field keeps working, so+ # it is managed without declaring anything — and keying on managed-ness would hand it a+ # tolerance it never had: an unset `PIPELEX_GATEWAY_API_KEY` would stop being a boot+ # failure with a remediation message and become a silently missing backend, which is the+ # behaviour delta on the Portkey-cloud path this work must not make. A declaration is+ # something only the kit writes, and only for a backend it also ships disabled.+ tolerates_missing_variables = declared_model_specs_section is not Nonetry:inference_backend_blueprint_dict = apply_to_strings_recursive(inference_backend_blueprint_dict_raw, transform_func=substitute_vars_with_provider@@ -210,6 +230,29 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):if lenient:log.verbose(f"Skipping backend '{backend_name}': missing credential variable '{var_not_found_exc.var_name}'")continue+ if tolerates_missing_variables:+ # **Scoped to backends that DECLARE a model specs section, and the scoping is+ # the whole point.** Such a backend is one the kit can ship *declared* —+ # `pipelex_manifold` ships declared and disabled, and joining the beta is+ # enabling it and setting two variables — so an installation that has enabled+ # one and not yet filled in its variables must not fail to boot over them.+ # Disabled with a named warning is exactly the posture the gateway itself takes+ # toward an integration missing its variables. (An installation that has not+ # joined never reaches here at all: a disabled backend is skipped above, and the+ # one loader that asks for disabled backends asks leniently.)+ #+ # Every other backend keeps today's fatal boot — `pipelex_gateway` included,+ # since it declares no section — because widening this would mean a user who+ # typos ANTHROPIC_API_KEY or PIPELEX_GATEWAY_API_KEY stops getting a boot+ # failure and starts getting a silently missing backend that resurfaces much+ # later as a model-resolution error, a behaviour delta on paths this work must+ # not touch.+ log.warning(+ f"Backend '{backend_name}' is disabled: it is a Pipelex-managed gateway backend and the variable "+ f"'{var_not_found_exc.var_name}' it needs is not set. Set it to enable this backend, or set "+ f"`enabled = false` on it in {library_paths_description} to silence this warning."+ )+ continuemsg = (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"@@ -249,25 +292,38 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):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+ # A managed gateway backend takes its specs from the fetched artifact; everything+ # else reads its own local file.backend_config_source: strmodel_spec_source: ModelSpecSource- if PipelexBackend.is_gateway_backend(backend_name):- if gateway_config is None:+ if model_specs_section is not None:+ if managed_gateway_configs is None:if lenient: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 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.+ # A caller's omission rather than a user's, and the two are told apart by+ # *which* input is missing. `None` means the caller supplied no managed+ # configs at all while this document declares one enabled — reachable only by+ # loading the library directly without them.msg = (- 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"+ f"Backend '{backend_name}' is enabled in {library_paths_description} and declares model specs section "+ f"'{model_specs_section}', but no model specs were given to the loader for it: pass it in "+ "`managed_gateway_configs`, or disable the backend")raise InferenceBackendLibraryError(msg, backend_name=backend_name)- extra_config["aws_region"] = gateway_config.aws_region+ gateway_config = managed_gateway_configs.get(backend_name)+ if gateway_config is None:+ # A mapping that was supplied and simply has no entry for this backend is the+ # user's situation, not the caller's: the config builder walked this same file+ # and found the published artifact carried no such section, warning by name as+ # it skipped. Disabled here, quietly, because that warning was already said.+ log.verbose(f"Skipping backend '{backend_name}': the Pipelex configuration carries no '{model_specs_section}' section")+ continue+ # Only when the artifact actually carried one. The manifold service is built+ # without a region on purpose: nothing on its path reads it back, because its+ # Bedrock credentials live gateway-side.+ if gateway_config.aws_region is not None:+ extra_config["aws_region"] = gateway_config.aws_regionmodel_spec_source = ModelSpecSource.REMOTE_GATEWAYmodel_specs_dict, backend_config_source = self._load_gateway_model_specs(gateway_config=gateway_config,@@ -321,6 +377,18 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):# first did not already say.self._stale_warning = stale_configuration_warning(plans=stale_plans, walked_dirs=config_manager.existing_config_dirs) if stale_plans else None+ @classmethod+ def _declared_model_specs_section(cls, *, backend_dict: dict[str, Any]) -> str | None:+ """The `model_specs_section` this declaration states, read straight off the raw table.++ Non-string values return `None` rather than raising: the blueprint validation a few lines+ later is what reports a malformed declaration, and it says so with the backend and the file+ in front of the analysis. Answering "not managed" here just means that report happens on the+ normal path instead of from inside a pre-check.+ """+ declared = backend_dict.get("model_specs_section")+ return declared if isinstance(declared, str) else None+@classmethoddef _build_backend_model_specs(cls,@@ -466,8 +534,13 @@ class InferenceBackendLibrary(RootModel[InferenceBackendLibraryRoot]):Raises:InferenceBackendCredentialsError: If variable substitution fails."""- # Load local overrides if they exist- path_to_local_overrides = f"{backends_dir_path}/{PipelexBackend.GATEWAY}.toml"+ # Load local overrides if they exist. The path follows the *backend's own name*, so+ # `backends/pipelex_manifold.toml` overrides the manifold backend exactly as+ # `backends/pipelex_gateway.toml` overrides the legacy one — and neither can reach the+ # other's models. Built through the shared helper for the reason its docstring gives: a+ # backend name is an unvalidated top-level TOML key, and a quoted absolute-path key would+ # otherwise escape the backends directory.+ path_to_local_overrides = str(backend_toml_path(backends_dir_path=backends_dir_path, backend_name=backend_name))local_overrides = load_toml_from_path_if_exists(path=path_to_local_overrides) or {}# Merge remote config with local overridesdiff --git a/pipelex/cogt/model_backends/gateway_config.py b/pipelex/cogt/model_backends/gateway_config.pyindex 08b33d606..5bf6dc803 100644--- a/pipelex/cogt/model_backends/gateway_config.py+++ b/pipelex/cogt/model_backends/gateway_config.py@@ -7,10 +7,25 @@ from pipelex.cogt.model_backends.model_spec_factory import BackendModelSpecs, Inclass GatewayConfig(BaseModel):+ """One managed gateway backend's slice of the fetched artifact.++ There is one of these per declared managed backend, built from that backend's named section of+ the single fetched artifact. They are held in a `dict[backend_name, GatewayConfig]` rather than+ merged, because the two services are two services: a handle that one serves and the other does+ not is a legitimate configuration, not a conflict to resolve.+ """+model_config = ConfigDict(extra="forbid")- model_specs: BackendModelSpecs = Field(description="Model specifications for Pipelex Gateway (model_name -> spec dict)")- aws_region: str = Field(description="AWS region")+ model_specs: BackendModelSpecs = Field(description="Model specifications for this managed gateway (model_name -> spec dict)")+ aws_region: str | None = Field(+ default=None,+ description=(+ "AWS region, threaded into the backend's extra_config. Optional because it is a top-level key of the artifact rather than "+ "a property of a section, and only a direct-SDK Bedrock backend ever reads it back — nothing on the manifold path does, "+ "because Bedrock credentials live gateway-side. A managed config built without one simply contributes no region."+ ),+ )def drop_unknown_gateway_defaults(*, gateway_model_specs: BackendModelSpecs) -> BackendModelSpecs:diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.pyindex 13e287d0b..a48e4ca10 100644--- a/pipelex/cogt/models/model_manager.py+++ b/pipelex/cogt/models/model_manager.py@@ -67,7 +67,7 @@ class ModelManager(ModelManagerAbstract):self,*,secrets_provider: SecretsProviderAbstract,- gateway_config: GatewayConfig | None,+ managed_gateway_configs: dict[str, GatewayConfig] | None,gateway_config_source: RemoteConfigSource | None,needs_inference: bool = True,backends_library_paths: Sequence[Path] | None = None,@@ -83,7 +83,7 @@ class ModelManager(ModelManagerAbstract):secrets_provider=secrets_provider,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,+ managed_gateway_configs=managed_gateway_configs,lenient=not needs_inference,)# The loader parks its stale-configuration warning rather than logging it, so that the@@ -103,17 +103,19 @@ class ModelManager(ModelManagerAbstract):self.model_deck = self.build_deck(enabled_backends=enabled_backends, model_deck_blueprint=deck_blueprint)self._enforce_gateway_model_membership(- gateway_config=gateway_config,+ managed_gateway_configs=managed_gateway_configs,gateway_config_source=gateway_config_source,+ enabled_backends=enabled_backends,)def _enforce_gateway_model_membership(self,- gateway_config: GatewayConfig | None,+ managed_gateway_configs: dict[str, GatewayConfig] | None,*,gateway_config_source: RemoteConfigSource | None,+ enabled_backends: list[str],) -> None:- """Fail loudly when the deck references a handle the gateway should provide but cannot.+ """Fail loudly when a handle routed to a managed gateway is absent from that gateway's specs.Runs even when ``missing_presets_reaction = "log"`` (the default), because a missinggateway model is a distinct failure mode from a generic preset mismatch: it means the@@ -121,8 +123,22 @@ class ModelManager(ModelManagerAbstract):declared. Surfacing this as ``GatewayUnknownModelError`` lets the agent CLI hint atcache-refresh remediation when the config was sourced from the on-disk fallback.- We only fire the check when both ``gateway_config`` and ``gateway_config_source`` are- set — that is, when the gateway is actually live in this setup pass.+ We only fire the check when both the configs and ``gateway_config_source`` are set — that+ is, when a managed gateway is actually live in this setup pass.++ **One check per live managed service, run separately — not a union across them.** With two+ services the old shape breaks in two directions at once. It was a union membership test+ ("is this handle in the deck *or* in the one gateway's specs?"), which with two sections+ would pass a handle that neither service can actually serve as long as the *other* one can.+ And ``_collect_deck_referenced_handles`` walks the whole deck, so running the old check+ separately against both would demand every deck handle appear in *both* sections — which+ the mixed profile cannot satisfy and the parked families contradict.++ **The resolution is the routing profile.** Each per-service check validates only the deck+ handles the active profile actually routes to that service. A handle legitimately absent+ from one section is then not an error, the mixed profile stays expressible, and the case+ that matters — the profile routes a handle to a service whose section does not carry it —+ still fails loudly at boot.Waterfall semantics: a waterfall reference is "known" if AT LEAST ONE of itsfallbacks resolves to a known handle. At runtime the deck walks the list and uses@@ -130,24 +146,52 @@ class ModelManager(ModelManagerAbstract):so a deck like ``["future-model", "current-model"]`` is perfectly valid as long as``current-model`` is in the gateway specs."""- if gateway_config is None or gateway_config_source is None:+ if not managed_gateway_configs or gateway_config_source is None:returndeck = self.get_model_deck()- gateway_spec_names = {name for name in gateway_config.model_specs if name != "defaults"}+ referenced_handles = self._collect_deck_referenced_handles(deck)- for handle, model_type in self._collect_deck_referenced_handles(deck):- try:- ref = ModelReference.parse(handle)- except ModelReferenceParseError:- continue- candidates = self._resolve_terminal_candidates(deck=deck, ref=ref, model_type=model_type)- if not candidates:- continue- if any(candidate in deck.inference_models or candidate in gateway_spec_names for candidate in candidates):- continue- # No candidate resolves to a known handle. Report the first one — it's the- # primary the user is asking for; subsequent entries are fallbacks.- raise GatewayUnknownModelError(model_name=candidates[0], source=gateway_config_source)+ for backend_name, gateway_config in managed_gateway_configs.items():+ gateway_spec_names = {name for name in gateway_config.model_specs if name != "defaults"}+ for handle, model_type in referenced_handles:+ try:+ ref = ModelReference.parse(handle)+ except ModelReferenceParseError:+ continue+ candidates = self._resolve_terminal_candidates(deck=deck, ref=ref, model_type=model_type)+ # Only the candidates this service is responsible for. A candidate the profile sends+ # to a BYOK backend, to the internal one, or to the *other* managed service is not+ # this check's business; the generic missing-handle path covers those.+ routed_here = [+ candidate+ for candidate in candidates+ if self._routes_to_backend(candidate=candidate, backend_name=backend_name, enabled_backends=enabled_backends)+ ]+ if not routed_here:+ continue+ # ``deck.inference_models`` is consulted over the WHOLE candidate list, not just the+ # part routed here, and the difference is load-bearing. That map is built by routing+ # every handle through the active profile and keeping the ones whose matched backend+ # has a spec, so membership in it already means "resolvable under this profile",+ # whichever backend serves it — which is exactly what ``_resolve_waterfall`` walks at+ # runtime. Narrowing this half to ``routed_here`` would refuse a waterfall whose+ # working fallback lives on another backend, and the runtime would have served it.+ if any(candidate in deck.inference_models for candidate in candidates):+ continue+ # The section lookup, by contrast, is only about what THIS service carries.+ if any(candidate in gateway_spec_names for candidate in routed_here):+ continue+ # No candidate resolves to a known handle. Report the first one — it's the+ # primary the user is asking for; subsequent entries are fallbacks.+ raise GatewayUnknownModelError(model_name=routed_here[0], backend_name=backend_name, source=gateway_config_source)++ def _routes_to_backend(self, *, candidate: str, backend_name: str, enabled_backends: list[str]) -> bool:+ """Whether the active routing profile sends this handle to this backend."""+ backend_match = self.routing_profile.get_backend_match_for_model(+ enabled_backends=enabled_backends,+ model_name=candidate,+ )+ return backend_match is not None and backend_match.backend_name == backend_name@classmethoddef _collect_deck_referenced_handles(cls, deck: ModelDeck) -> list[tuple[str, ModelType]]:diff --git a/pipelex/cogt/models/model_manager_abstract.py b/pipelex/cogt/models/model_manager_abstract.pyindex cc0252d6c..927903a09 100644--- a/pipelex/cogt/models/model_manager_abstract.py+++ b/pipelex/cogt/models/model_manager_abstract.py@@ -23,7 +23,7 @@ class ModelManagerAbstract(ABC):self,*,secrets_provider: SecretsProviderAbstract,- gateway_config: GatewayConfig | None,+ managed_gateway_configs: dict[str, GatewayConfig] | None,gateway_config_source: RemoteConfigSource | None,needs_inference: bool = True,) -> None:diff --git a/pipelex/kit/configs/inference/backends.toml b/pipelex/kit/configs/inference/backends.tomlindex 13495a407..eb2803675 100644--- a/pipelex/kit/configs/inference/backends.toml+++ b/pipelex/kit/configs/inference/backends.toml@@ -15,6 +15,15 @@ display_name = "⭐ Pipelex Gateway"enabled = true # Enable after accepting terms via `pipelex init config`api_key = "${PIPELEX_GATEWAY_API_KEY}"+# Pipelex Manifold is a closed private beta: leave it off unless you have been invited.+[pipelex_manifold]+display_name = "Pipelex Manifold (private beta)"+enabled = false+endpoint = "${PIPELEX_MANIFOLD_ENDPOINT}"+api_key = "${PIPELEX_MANIFOLD_API_KEY}"+model_specs_section = "manifold_model_specs"+auth_header = "x-pipelex-api-key"+[anthropic]enabled = trueapi_key = "${ANTHROPIC_API_KEY}"diff --git a/pipelex/kit/configs/inference/backends/pipelex_manifold.toml b/pipelex/kit/configs/inference/backends/pipelex_manifold.tomlnew file mode 100644index 000000000..1a9adc718--- /dev/null+++ b/pipelex/kit/configs/inference/backends/pipelex_manifold.toml@@ -0,0 +1,56 @@+################################################################################+# Pipelex Manifold Local Overrides+################################################################################+#+# PRIVATE BETA:+#+# Pipelex Manifold is the Pipelex-operated inference service. It is in private+# beta, it ships disabled in backends.toml, and this file does nothing until you+# enable it there and set PIPELEX_MANIFOLD_ENDPOINT and PIPELEX_MANIFOLD_API_KEY.+#+################################################################################+#+# TELEMETRY NOTICE:+#+# Enabling pipelex_gateway alongside this backend enables identified telemetry+# from your machine, tied to your Pipelex Gateway API key (hashed for security).+# This is independent from your telemetry.toml settings.+#+# That client-side telemetry follows the gateway key and nothing else, so an+# installation running Pipelex Manifold ALONE sends none of it. Manifold is a+# Pipelex-operated service, though, so your usage of it is recorded server-side+# the way any hosted platform records the calls it serves.+#+# Either way we collect only technical data (model names, token counts, latency,+# error rates). We do NOT collect prompts, completions, pipe codes, or business+# data.+#+# This allows us to monitor service quality, enforce fair usage, and support you.+#+################################################################################+#+# WARNING: USE AT YOUR OWN RISK!+#+# The actual model configuration is fetched remotely from Pipelex servers.+# Any override in this file may cause unexpected behavior or failures,+# as the remote configuration may change at any time.+#+# If you must override, you may ONLY use these keys per model:+# - sdk+# - structure_method+#+# All other keys will be ignored.+#+# If you need custom configurations, consider using your own API keys+# with direct provider backends (openai, anthropic, etc.) instead.+#+# Documentation:+# https://docs.pipelex.com/latest/configuration/config-technical/inference-backend-config/+# Support: https://go.pipelex.com/discord+#+################################################################################++# Per-model overrides example:+# [gpt-4o]+# sdk = "manifold_completions"+# structure_method = "instructor/openai_tools"diff --git a/pipelex/kit/configs/inference/routing_profiles.toml b/pipelex/kit/configs/inference/routing_profiles.tomlindex 8b5d7d4c2..2fd6781aa 100644--- a/pipelex/kit/configs/inference/routing_profiles.toml+++ b/pipelex/kit/configs/inference/routing_profiles.toml@@ -28,6 +28,13 @@ active = "all_pipelex_gateway"description = "Use Pipelex Gateway for all its supported models"default = "pipelex_gateway"+# The same model names, served by the Pipelex-operated inference service instead. Switching between+# this profile and the one above needs no other edit: a model's wire id and sdk are per-backend, so+# decks, aliases and presets keep naming the same handles.+[profiles.all_pipelex_manifold]+description = "Use Pipelex Manifold (private beta) for all its supported models"+default = "pipelex_manifold"+[profiles.all_anthropic]description = "Use Anthropic backend for all its supported models"default = "anthropic"diff --git a/pipelex/providers/anthropic/anthropic_factory.py b/pipelex/providers/anthropic/anthropic_factory.pyindex aab4f4629..7348c916b 100644--- a/pipelex/providers/anthropic/anthropic_factory.py+++ b/pipelex/providers/anthropic/anthropic_factory.py@@ -33,6 +33,16 @@ class AnthropicSdkVariant(StrEnum):BEDROCK_ANTHROPIC = "bedrock_anthropic"+class AnthropicExtraField(StrEnum):+ AUTH_HEADER = "auth_header"+++# The anthropic SDK refuses to build a client without a non-empty api_key, so a backend that+# authenticates on a header of its own still needs something in that slot. Same workaround, and+# same wording, as the OpenAI-substrate factories.+_PLACEHOLDER_API_KEY = "unused-auth-via-backend-header"++class AnthropicFactory:@staticmethoddef make_anthropic_client(@@ -52,6 +62,23 @@ class AnthropicFactory:match sdk_variant:case AnthropicSdkVariant.ANTHROPIC:+ auth_header_config = backend.get_extra_config(AnthropicExtraField.AUTH_HEADER)+ if auth_header_config is not None:+ # The backend speaks the Anthropic protocol but authenticates on a header of+ # its own rather than on `x-api-key`. The Pipelex Manifold service is the case+ # this exists for: it reads `x-pipelex-api-key` (or an `Authorization` bearer)+ # and never looks at `x-api-key`, so a key left in the SDK's own slot reaches+ # it as an anonymous request. Carry it in the named header instead — the same+ # move the manifold OpenAI-substrate factories already make.+ if not backend.api_key:+ msg = f"Backend '{backend.name}' sets '{AnthropicExtraField.AUTH_HEADER}' but carries no api_key"+ raise AnthropicFactoryError(msg)+ return AsyncAnthropic(+ api_key=_PLACEHOLDER_API_KEY,+ base_url=backend.endpoint,+ max_retries=transport_max_retries,+ default_headers={str(auth_header_config): backend.api_key},+ )return AsyncAnthropic(api_key=backend.api_key,base_url=backend.endpoint,diff --git a/pipelex/providers/builtins.py b/pipelex/providers/builtins.pyindex d5a0febf8..ab781fe36 100644--- a/pipelex/providers/builtins.py+++ b/pipelex/providers/builtins.py@@ -10,6 +10,7 @@ from pipelex.providers.gateway.gateway_plugin import GatewayPluginfrom pipelex.providers.google.google_plugin import GooglePluginfrom pipelex.providers.huggingface.huggingface_plugin import HuggingFacePluginfrom pipelex.providers.linkup.linkup_plugin import LinkupPlugin+from pipelex.providers.manifold.manifold_plugin import ManifoldPluginfrom pipelex.providers.mistral.mistral_plugin import MistralPluginfrom pipelex.providers.openai.openai_plugin import OpenAIPluginfrom pipelex.providers.openrouter.openrouter_plugin import OpenRouterPlugin@@ -37,6 +38,7 @@ KERNEL_BUILTIN_PLUGINS: list[PipelexPlugin] = [SecretsPlugin(),OpenAIPlugin(),GatewayPlugin(),+ ManifoldPlugin(),PortkeyPlugin(),AnthropicPlugin(),MistralPlugin(),diff --git a/pipelex/providers/manifold/__init__.py b/pipelex/providers/manifold/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/pipelex/providers/manifold/manifold_completions_factory.py b/pipelex/providers/manifold/manifold_completions_factory.pynew file mode 100644index 000000000..ab3935896--- /dev/null+++ b/pipelex/providers/manifold/manifold_completions_factory.py@@ -0,0 +1,136 @@+"""The Chat Completions factory for the Pipelex Manifold service.++**It subclasses `OpenAICompletionsFactory` and carries its own copy of the document override.**+Documents travel to a Pipelex-operated gateway as a `ChatCompletionContentPartImageParam` holding a+data URL, not as an OpenAI file part: the gateway translates that part into whatever document format+the provider it picked actually wants, and the base class's file part is not something it can+translate. The Portkey-path factory makes exactly the same move for exactly the same reason —+because it is the same gateway codebase on the other end.++Subclassing *that* factory instead of copying its override was considered and rejected: it also+carries the Portkey extract-response parsing for four providers and a Portkey header build, none of+which this path wants, and inheriting from it would make the eventual retirement of the Portkey+package an untangling rather than a deletion. The duplication is the price the two-gateways design+already agreed to pay, and it dies whole with the path it belongs to.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from typing_extensions import override++from pipelex.cogt.document.prompt_document_utils import prep_prompt_documents+from pipelex.cogt.image.prompt_image import PromptImageDetail+from pipelex.cogt.image.prompt_image_utils import prep_prompt_images+from pipelex.config import get_config+from pipelex.providers.manifold.manifold_constants import ManifoldOpenAISdkVariant+from pipelex.providers.manifold.manifold_exceptions import ManifoldFactoryError+from pipelex.providers.manifold.manifold_factory import ManifoldFactory+from pipelex.providers.openai.openai_completions_factory import OpenAICompletionsFactory+from pipelex.tools.uri.prepared_file import PreparedFileBase64, PreparedFileHttpUrl, PreparedFileLocalPath++if TYPE_CHECKING:+ # Deferred imports: avoid pulling heavy SDK at module-load time+ import openai+ from openai.types.chat import ChatCompletionMessageParam++ from pipelex.cogt.inference.inference_job_abstract import InferenceJobAbstract+ from pipelex.cogt.llm.llm_job import LLMJob+ from pipelex.cogt.model_backends.backend import InferenceBackend+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+ from pipelex.plugins.model_handle import ModelHandle+++class ManifoldCompletionsFactory(OpenAICompletionsFactory):+ @override+ async def make_simple_messages(+ self,+ llm_job: LLMJob,+ ) -> list[ChatCompletionMessageParam]:+ """Documents travel as an `image_url` data URL, which the gateway translates per provider."""+ # Deferred imports: avoid pulling heavy SDK at module-load time+ from openai.types.chat import ( # ruff: ignore[import-outside-top-level]+ ChatCompletionContentPartImageParam,+ ChatCompletionContentPartParam,+ ChatCompletionContentPartTextParam,+ ChatCompletionSystemMessageParam,+ ChatCompletionUserMessageParam,+ )+ from openai.types.chat.chat_completion_content_part_image_param import ImageURL as OpenAIImageURL # ruff: ignore[import-outside-top-level]++ llm_prompt = llm_job.llm_prompt+ messages: list[ChatCompletionMessageParam] = []+ user_contents: list[ChatCompletionContentPartParam] = []+ if system_content := llm_prompt.system_text:+ messages.append(ChatCompletionSystemMessageParam(role="system", content=system_content))+ if user_prompt_text := llm_prompt.user_text:+ user_part_text = ChatCompletionContentPartTextParam(text=user_prompt_text, type="text")+ user_contents.append(user_part_text)+ if llm_prompt.user_images:+ detail = llm_job.job_params.image_detail or PromptImageDetail.AUTO+ prepped_images = await prep_prompt_images(prompt_images=llm_prompt.user_images, is_http_url_enabled=self.is_http_url_enabled)+ for prepped_image in prepped_images:+ url: str+ match prepped_image:+ case PreparedFileHttpUrl():+ url = prepped_image.url+ case PreparedFileBase64():+ url = prepped_image.as_data_url()+ case PreparedFileLocalPath():+ msg = "PreparedFileLocalPath is not supported for images - should be converted to base64"+ raise TypeError(msg)++ image_url_obj = OpenAIImageURL(url=url, detail=detail.as_openai_detail)+ image_param = ChatCompletionContentPartImageParam(image_url=image_url_obj, type="image_url")+ user_contents.append(image_param)++ # Documents must always be base64 encoded for the image_url form, whatever the images+ # setting allows: an http URL here would reach the gateway as a link it does not fetch.+ if llm_prompt.user_documents:+ prepped_documents = await prep_prompt_documents(prompt_documents=llm_prompt.user_documents, is_http_url_enabled=False)+ for prepped_document in prepped_documents:+ match prepped_document:+ case PreparedFileBase64():+ doc_url = prepped_document.as_data_url()+ image_url_obj = OpenAIImageURL(url=doc_url, detail="auto")+ doc_param = ChatCompletionContentPartImageParam(image_url=image_url_obj, type="image_url")+ user_contents.append(doc_param)+ case PreparedFileHttpUrl() | PreparedFileLocalPath():+ msg = f"{type(prepped_document).__name__} is not supported for documents - should be converted to base64"+ raise TypeError(msg)++ messages.append(ChatCompletionUserMessageParam(role="user", content=user_contents))+ return messages++ @classmethod+ def make_openai_client_for_completions(+ cls,+ model_handle: ModelHandle,+ *,+ backend: InferenceBackend,+ ) -> openai.AsyncOpenAI:+ # Deferred import: avoid pulling heavy SDK at module-load time+ import openai # ruff: ignore[import-outside-top-level]++ if not ManifoldOpenAISdkVariant.is_completions(model_handle.sdk):+ msg = f"ModelHandle '{model_handle}' is not supported by '{cls.__name__}'"+ raise ManifoldFactoryError(msg)++ return openai.AsyncOpenAI(+ base_url=ManifoldFactory.get_base_url(backend=backend),+ # Auth travels in the service's own header, not in the OpenAI Authorization one. The SDK+ # has rejected an empty api_key since 2.34.0, so the slot holds a placeholder the+ # gateway never reads.+ api_key="unused-auth-via-manifold-header",+ # Tier 1 transport retry: set explicitly from config rather than inheriting the SDK+ # default, so a transport_max_retries override applies to this path too.+ max_retries=get_config().inference.transport_max_retries,+ default_headers=ManifoldFactory.make_auth_headers(backend=backend),+ )++ @override+ def make_extras(+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str+ ) -> tuple[dict[str, str], dict[str, Any]]:+ return ManifoldFactory.make_extras(inference_model=inference_model, inference_job=inference_job, output_desc=output_desc)diff --git a/pipelex/providers/manifold/manifold_constants.py b/pipelex/providers/manifold/manifold_constants.pynew file mode 100644index 000000000..3ded42917--- /dev/null+++ b/pipelex/providers/manifold/manifold_constants.py@@ -0,0 +1,88 @@+"""The manifold dialect's names: its sdk set, its one wire header, and its route paths.++Everything the manifold plugin needs to name is named here rather than imported from+``providers/portkey/`` or ``providers/gateway/``. The duplication is deliberate — it is the+no-intertwining rule from the two-gateways design, and it is what keeps the eventual retirement of+the Portkey path a module deletion rather than an untangling.+"""++from enum import StrEnum++# The header the Pipelex Manifold service reads the caller's token from.+#+# The gateway is a continuation of the Portkey AI Gateway, and the name its inherited auth layer+# answers to is `x-portkey-api-key`. Until 2026-09-03 that was the single word of the vendor's+# vocabulary still on the manifold wire; the gateway now translates this spelling to that one before+# its auth runs (`src/pig/serviceTokenHeader.ts` there), which is what let the rename happen — it+# had no runtime-only half. This is the one header the dialect sends about itself, on every+# protocol: the OpenAI-substrate factories and the native client put it there directly, and the+# shared Anthropic driver reads it from the backend's `auth_header` field, so the value in+# `backends.toml` must spell it exactly as this constant does.+MANIFOLD_AUTH_HEADER = "x-pipelex-api-key"++# The OpenAI and Portkey SDKs both expect their `base_url` to already carry the API version segment+# (`AsyncOpenAI`'s default is `https://api.openai.com/v1`, `AsyncPortkey`'s is+# `https://api.portkey.ai/v1`), and both then append their own route beneath it. The Anthropic SDK+# is the opposite: its default is `https://api.anthropic.com` and it appends `/v1/messages` itself.+#+# So the backend declares the **origin**, with no version segment, and each client appends what it+# needs. Verified against the installed SDKs rather than assumed — spike 5 lost a day to a+# `/v1`-suffixed endpoint under the Anthropic SDK producing `POST /v1/v1/messages`, which the proxy+# forwarded and answered 200-shaped.+MANIFOLD_API_VERSION_SEGMENT = "/v1"++# pig's own routes, beneath the version segment. They serve extraction and web search as themselves+# rather than dressed as chat completions; their wire contract is frozen gateway-side in+# `src/pig/pipelex/schemas.ts`.+MANIFOLD_EXTRACT_ROUTE = "/pipelex/extract"+MANIFOLD_SEARCH_ROUTE = "/pipelex/search"+++class ManifoldSdk(StrEnum):+ """The sdk values the manifold catalog section may name.++ `anthropic` is deliberately absent: Claude reaches the manifold service over the *shared*+ Anthropic SDK driver, which is not part of this package and outlives the Portkey retirement.+ """++ COMPLETIONS = "manifold_completions"+ RESPONSES = "manifold_responses"+ IMG_GEN = "manifold_img_gen"+ EXTRACT = "manifold_extract"+ SEARCH = "manifold_search"+++class ManifoldOpenAISdkVariant(StrEnum):+ """The two OpenAI-substrate sdks, and which of the two shapes each factory serves.++ A factory checks its own variant so that a catalog entry naming `manifold_responses` cannot be+ served by the completions factory (or the reverse) through a mis-registration — the failure+ would otherwise be a wrong request shape at the provider rather than a refusal at build time.+ """++ MANIFOLD_COMPLETIONS = "manifold_completions"+ MANIFOLD_RESPONSES = "manifold_responses"++ @classmethod+ def is_completions(cls, sdk: str) -> bool:+ try:+ variant = cls(sdk)+ except ValueError:+ return False+ match variant:+ case cls.MANIFOLD_COMPLETIONS:+ return True+ case cls.MANIFOLD_RESPONSES:+ return False++ @classmethod+ def is_responses(cls, sdk: str) -> bool:+ try:+ variant = cls(sdk)+ except ValueError:+ return False+ match variant:+ case cls.MANIFOLD_COMPLETIONS:+ return False+ case cls.MANIFOLD_RESPONSES:+ return Truediff --git a/pipelex/providers/manifold/manifold_exceptions.py b/pipelex/providers/manifold/manifold_exceptions.pynew file mode 100644index 000000000..3f09d121b--- /dev/null+++ b/pipelex/providers/manifold/manifold_exceptions.py@@ -0,0 +1,34 @@+from pipelex.cogt.exceptions import CogtError+++class ManifoldError(CogtError):+ pass+++class ManifoldFactoryError(ManifoldError):+ pass+++class ManifoldCredentialsError(ManifoldError):+ pass+++class ManifoldEndpointError(ManifoldError):+ """The backend declares no usable endpoint for the Pipelex Manifold service.++ Its own error rather than a credentials one, because the remedy is a different variable and+ because there is deliberately no default to fall back on: an empty-resolving endpoint that+ silently became a vendor's public URL would carry our service token to the wrong company.+ """+++class ManifoldExtractResponseError(ManifoldError):+ pass+++class ManifoldSearchResponseError(ManifoldError):+ pass+++class ManifoldSearchEmptyResultError(ManifoldError):+ passdiff --git a/pipelex/providers/manifold/manifold_extract_worker.py b/pipelex/providers/manifold/manifold_extract_worker.pynew file mode 100644index 000000000..c96e10486--- /dev/null+++ b/pipelex/providers/manifold/manifold_extract_worker.py@@ -0,0 +1,153 @@+"""Document extraction over the Pipelex Manifold service's own route.++Thin on purpose. The gateway's ``POST /v1/pipelex/extract`` answers in the runtime's *own* model —+an ``ExtractOutput`` of ``Page``s, keyed by page index — so the whole response side is one+``model_validate``, whichever provider the gateway picked. That is the largest deletion the native+route buys over the chat costume, where each provider's wire shape needed its own parser.++Two things this worker does that a thinner one would get wrong.++**It builds the request body field by field.** Several ``ExtractJobParams`` fields are deliberately+not part of the contract, and the gateway refuses them at *any* value including their own defaults —+so a ``model_dump()`` of the params would send ``should_caption_images=false`` and be refused. See+``manifold_schemas``.++**It translates the service's usage units into the runtime's.** The route reports honest counts+(``usage.pages``), and the runtime's cost model is per million tokens. Left untranslated the job+would report a cost of zero — silently, because ``nb_tokens_by_category`` simply stays empty and+nothing raises. The megatoken convention is inherited from the chat costume and kept deliberately:+it is what makes an extraction's cost figure directly comparable between the two dialects, which is+what the mixed-profile bring-up needs in order to mean anything.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any, cast++from pydantic import ValidationError+from typing_extensions import override++from pipelex.cogt.exceptions import SdkTypeError+from pipelex.cogt.extract.exceptions import ExtractInputError+from pipelex.cogt.extract.extract_output import ExtractOutput+from pipelex.cogt.extract.extract_worker_abstract import ExtractWorkerAbstract+from pipelex.cogt.inference.error_render import InferenceErrorFamily+from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory+from pipelex.providers.manifold.manifold_constants import MANIFOLD_EXTRACT_ROUTE+from pipelex.providers.manifold.manifold_exceptions import ManifoldExtractResponseError+from pipelex.providers.manifold.manifold_native_client import ManifoldNativeClient+from pipelex.providers.manifold.manifold_schemas import ManifoldExtractInput, ManifoldExtractParams, ManifoldExtractRequest+from pipelex.runtime_hub import get_storage_provider+from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error+from pipelex.tools.uri.uri_resolver import make_base64_url_from_any_uri++if TYPE_CHECKING:+ from pipelex.cogt.extract.extract_job import ExtractJob+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+ from pipelex.reporting.reporting_protocol import ReportingProtocol++# The runtime prices per million; the route counts pages. One page is one megatoken, in both+# categories, which is exactly what the chat costume reports and what the abstract worker's own+# fallback would produce — so a cost figure means the same thing on either dialect.+MANIFOLD_UNIT_TOKENS = 1_000_000+++class ManifoldExtractWorker(ExtractWorkerAbstract):+ def __init__(+ self,+ sdk_instance: Any,+ extra_config: dict[str, Any],+ inference_model: InferenceModelSpec,+ reporting_delegate: ReportingProtocol | None = None,+ ):+ super().__init__(+ extra_config=extra_config,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )++ if not isinstance(sdk_instance, ManifoldNativeClient):+ msg = f"Provided extraction sdk_instance for {self.__class__.__name__} is not a ManifoldNativeClient: it's a '{type(sdk_instance)}'"+ raise SdkTypeError(msg)++ self.client: ManifoldNativeClient = sdk_instance++ @override+ async def _extract_pages(+ self,+ extract_job: ExtractJob,+ ) -> ExtractOutput:+ request = await self._make_request(extract_job=extract_job)+ response_body = await self.client.post_json(+ route=MANIFOLD_EXTRACT_ROUTE,+ body=request.model_dump(exclude_none=True),+ family=InferenceErrorFamily.EXTRACT,+ inference_model=self.inference_model,+ )+ self._record_usage(response_body=response_body, extract_job=extract_job)+ try:+ return ExtractOutput.model_validate(response_body)+ except ValidationError as exc:+ msg = f"Could not parse the extraction response for model '{self.inference_model.name}': {format_pydantic_validation_error(exc)}"+ raise ManifoldExtractResponseError(msg) from exc++ async def _make_request(self, *, extract_job: ExtractJob) -> ManifoldExtractRequest:+ """The body, with the input in the form the picked provider can actually reach.++ Which form that is follows from what the *catalog* says the model takes, not from a list of+ model names kept in step by hand: a web-page extractor is handed the page's own URL, and+ everything else is handed the bytes inline. The gateway fetches ``https:`` and reads+ ``data:``, and nothing else — a local path or a ``pipelex-storage://`` URI has to become+ bytes on this side, because the gateway holds no credentials for our storage.+ """+ extract_input = extract_job.extract_input+ job_params = extract_job.job_params+ params = ManifoldExtractParams(+ max_nb_images=job_params.max_nb_images,+ render_js=job_params.render_js,+ include_raw_html=job_params.include_raw_html,+ )++ if self.is_web_page_supported:+ if not extract_input.document_uri:+ msg = f"Extract model '{self.inference_model.name}' fetches web pages and needs a document_uri"+ raise ExtractInputError(msg)+ return ManifoldExtractRequest(+ model=self.inference_model.model_id,+ input=ManifoldExtractInput(document_uri=extract_input.document_uri),+ params=params,+ )++ storage = get_storage_provider()+ if image_uri := extract_input.image_uri:+ base64_url = await make_base64_url_from_any_uri(uri=image_uri, storage_provider=storage)+ return ManifoldExtractRequest(+ model=self.inference_model.model_id,+ input=ManifoldExtractInput(image_uri=base64_url),+ params=params,+ )+ if document_uri := extract_input.document_uri:+ base64_url = await make_base64_url_from_any_uri(uri=document_uri, storage_provider=storage)+ return ManifoldExtractRequest(+ model=self.inference_model.model_id,+ input=ManifoldExtractInput(document_uri=base64_url),+ params=params,+ )+ msg = "No image nor document URI provided in ExtractJob"+ raise ExtractInputError(msg)++ def _record_usage(self, *, response_body: dict[str, Any], extract_job: ExtractJob) -> None:+ extract_tokens_usage = extract_job.job_report.extract_tokens_usage+ if not extract_tokens_usage:+ return+ usage: object = response_body.get("usage")+ if not isinstance(usage, dict):+ return+ nb_pages: object = cast("dict[str, Any]", usage).get("pages")+ if not isinstance(nb_pages, int):+ return+ nb_tokens: NbTokensByCategoryDict = {+ TokenCategory.INPUT: nb_pages * MANIFOLD_UNIT_TOKENS,+ TokenCategory.OUTPUT: nb_pages * MANIFOLD_UNIT_TOKENS,+ }+ extract_tokens_usage.nb_tokens_by_category = nb_tokensdiff --git a/pipelex/providers/manifold/manifold_factory.py b/pipelex/providers/manifold/manifold_factory.pynew file mode 100644index 000000000..e38a31d1f--- /dev/null+++ b/pipelex/providers/manifold/manifold_factory.py@@ -0,0 +1,157 @@+"""How every manifold client is built: the endpoint rule, the token, and the per-request extras.++**The endpoint rule is normative and it is why this class exists at all.** The backend declares the+Pipelex Manifold service's *origin* — scheme, host and port, with no version segment — and each+client appends what its own SDK expects beneath it. See `manifold_constants` for the probe that+established which SDK appends what.++**There is no fallback endpoint, deliberately.** The Portkey-path sibling reads+``backend.endpoint or PORTKEY_GATEWAY_URL``, which is right there: an unset endpoint means "use the+vendor's cloud". Copied here it would mean that an empty-resolving ``PIPELEX_MANIFOLD_ENDPOINT``+silently builds a client aimed at ``api.portkey.ai`` carrying the *manifold* service token — a live+billable request to the wrong vendor, with nothing anywhere reporting it. So an absent endpoint is a+refusal, and the backend loader's own missing-variable path disables the backend with a named+warning long before this is reached.+"""++from __future__ import annotations++import random+from typing import TYPE_CHECKING, Any++from pipelex.cogt.img_gen.img_gen_gemini_mapping import ImgGenGeminiMapping+from pipelex.cogt.img_gen.img_gen_job import ImgGenJob+from pipelex.cogt.llm.llm_job import LLMJob+from pipelex.providers.manifold.manifold_constants import MANIFOLD_API_VERSION_SEGMENT, MANIFOLD_AUTH_HEADER+from pipelex.providers.manifold.manifold_exceptions import ManifoldCredentialsError, ManifoldEndpointError++if TYPE_CHECKING:+ from portkey_ai import AsyncPortkey++ from pipelex.cogt.img_gen.img_gen_job_components import ImgGenJobParams+ from pipelex.cogt.inference.inference_job_abstract import InferenceJobAbstract+ from pipelex.cogt.model_backends.backend import InferenceBackend+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+++class ManifoldFactory:+ @classmethod+ def get_origin(cls, backend: InferenceBackend) -> str:+ """The service origin the backend declares, with any trailing slash removed.++ A trailing slash is stripped rather than refused because it is the one shape of a correct+ answer a human types by accident, and it would otherwise produce a doubled separator in+ every path this class builds.+ """+ endpoint = (backend.endpoint or "").strip().rstrip("/")+ if not endpoint:+ msg = (+ f"Backend '{backend.name}' declares no endpoint for the Pipelex Manifold service. "+ f"Set PIPELEX_MANIFOLD_ENDPOINT to the service origin (scheme, host and port, with no '/v1'). "+ f"There is no default: a request built without one would reach a vendor this token is not for."+ )+ raise ManifoldEndpointError(msg)+ return endpoint++ @classmethod+ def get_base_url(cls, backend: InferenceBackend) -> str:+ """The origin plus the version segment, for the SDKs that expect one in their `base_url`."""+ return f"{cls.get_origin(backend=backend)}{MANIFOLD_API_VERSION_SEGMENT}"++ @classmethod+ def get_api_key(cls, backend: InferenceBackend) -> str:+ if not backend.api_key:+ msg = f"Backend '{backend.name}' carries no api_key for the Pipelex Manifold service; set PIPELEX_MANIFOLD_API_KEY"+ raise ManifoldCredentialsError(msg)+ return backend.api_key++ @classmethod+ def make_auth_headers(cls, backend: InferenceBackend) -> dict[str, str]:+ """The whole of what the manifold dialect puts on the wire about itself: one token header.++ No config id, no provider name, no routing of any kind — the service decides which provider+ serves a model from the model id in the request body, and refuses a client that tries to say+ otherwise. Building this dict by hand rather than through the vendor's header helper is what+ makes that property readable here instead of dependent on a library's constructor defaults.+ """+ return {MANIFOLD_AUTH_HEADER: cls.get_api_key(backend=backend)}++ @classmethod+ def make_portkey_client(cls, backend: InferenceBackend) -> AsyncPortkey:+ """The image path's client.++ `portkey_ai` is a beta-only dependency of this package: the image worker reuses the vendor+ SDK's `images.generate` / `images.edit` methods for their multipart serialization, which is+ the part that was expensive to get right. Everything else in this package is built on the+ OpenAI SDK or on plain HTTP. See the deletion trigger in `manifold_img_gen_worker`.+ """+ from portkey_ai import AsyncPortkey # ruff: ignore[import-outside-top-level]++ return AsyncPortkey(+ base_url=cls.get_base_url(backend=backend),+ api_key=cls.get_api_key(backend=backend),+ debug=cls.is_debug_enabled(backend=backend),+ )++ @classmethod+ def is_debug_enabled(cls, backend: InferenceBackend) -> bool:+ """Read from the backend's own configuration and from nothing else.++ The Portkey-path sibling routes this through the telemetry manager's+ `pipelex_gateway.portkey` knobs. Reusing those here would put one configuration block in+ charge of two services, which is the seam the two-gateways design exists to avoid.+ """+ return bool(backend.extra_config.get("debug", False))++ @classmethod+ def _make_gemini_image_config(cls, inference_model: InferenceModelSpec, *, job_params: ImgGenJobParams) -> dict[str, str]:+ """The gemini `image_config` block, honouring the portable size.++ Same resolution as the native Google worker: a requested size (tier or exact) goes through+ the model's taxonomy rules, an unset size omits `image_size` so the provider applies its own+ default, and a model with no usable taxonomy falls back to the ratio alone rather than+ guessing.+ """+ if job_params.size is None:+ taxonomy = ImgGenGeminiMapping.optional_img_gen_taxonomy(inference_model)+ if taxonomy is None:+ return {"aspect_ratio": ImgGenGeminiMapping.aspect_ratio_literal(job_params.aspect_ratio)}+ else:+ taxonomy = ImgGenGeminiMapping.img_gen_taxonomy(inference_model)+ resolved = ImgGenGeminiMapping.resolve_image_config(+ taxonomy,+ aspect_ratio=job_params.aspect_ratio,+ size=job_params.size,+ model_name=inference_model.name,+ )+ image_config: dict[str, str] = {"aspect_ratio": resolved.aspect_ratio}+ if resolved.image_size is not None:+ image_config["image_size"] = resolved.image_size+ return image_config++ @classmethod+ def make_extras(+ cls, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str+ ) -> tuple[dict[str, str], dict[str, Any]]:+ """The per-request headers and body additions.++ `output_desc` is part of the shared factory signature and is unused on this path: it exists+ for the Portkey-path tracing header that names the job, and the manifold dialect sends no+ tracing headers in the beta.+ """+ del output_desc+ extra_headers: dict[str, str] = {}+ extra_body: dict[str, Any] = {}+ if inference_model.extra_headers:+ # Per-model outbound headers the catalog sets — `anthropic-beta` is the live example.+ # None of these is routing: the service refuses any client header that tries to choose a+ # provider, and passes the rest through to whichever one it picked.+ extra_headers.update(inference_model.extra_headers)++ if isinstance(inference_job, LLMJob) and inference_model.model_id.lower().startswith("mistral-") and inference_job.job_params.seed is None:+ # Mistral models really want a non-null seed.+ extra_body["seed"] = random.randint(0, 1000000)+ elif isinstance(inference_job, ImgGenJob) and inference_model.model_id.startswith("gemini"):+ extra_body["image_config"] = cls._make_gemini_image_config(inference_model, job_params=inference_job.job_params)++ return extra_headers, extra_bodydiff --git a/pipelex/providers/manifold/manifold_img_gen_worker.py b/pipelex/providers/manifold/manifold_img_gen_worker.pynew file mode 100644index 000000000..c460306c0--- /dev/null+++ b/pipelex/providers/manifold/manifold_img_gen_worker.py@@ -0,0 +1,253 @@+"""Image generation and editing through the Pipelex Manifold service.++**This module is the one place the manifold plugin depends on `portkey_ai`, and the dependency has a+deletion trigger.** The two-gateways design ruled that the manifold plugin must not depend on the+vendor's library — "when Portkey retires as a vendor, the library retires with it" — and the+engineering review of 2026-08-25 lifted that rule *for the beta only*, so the image path could reuse+work that was already proven live rather than being ported first. Reusing `AsyncPortkey` buys one+specific thing: its `images.generate` / `images.edit` methods carry the multipart serialization for+image edits, which is the part that was expensive to get right.++**Delete this dependency when** the manifold image path is ported to the OpenAI SDK — the mapping+can be read out of the Portkey SDK's own source. What changes then is this module's client and its+exception arms; nothing else in the package imports the vendor library. Until that happens, the+design page's claim that the manifold plugin does not depend on `portkey_ai` is false, which is why+the lift is written into the design rather than only into a plan.++**The response shapes this worker parses are only the ones the manifold catalog names.** Every+`manifold_img_gen` entry is an Azure GPT Image model, and the gateway's own configuration serves+them from one integration. The Portkey path's worker also carries a Black Forest Labs Flux 2 Pro+branch and a FAL queue-polling branch; neither has a model on this path, so neither is carried here.+A response that matches nothing is refused with what it actually contained, and restoring a branch+is a `git show` away.+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any, cast++from portkey_ai import AsyncPortkey++# The vendored openai package is the one AsyncPortkey is built from, so the exceptions it raises are+# the vendored classes (not the real `openai` package's) — there is no public re-export in portkey_ai.+from portkey_ai._vendor import openai as portkey_vendored_openai # ruff: ignore[import-private-name]+from portkey_ai.api_resources import exceptions as portkey_exceptions+from pydantic import ValidationError+from typing_extensions import override++from pipelex.cogt.exceptions import ImgGenGenerationError, ImgGenParameterError, InferenceErrorCategory, SdkTypeError+from pipelex.cogt.image.generated_image import GeneratedImageRawDetails+from pipelex.cogt.image.image_size import ImageSize+from pipelex.cogt.img_gen.img_gen_args_factory import ImageFileTuple, ImgGenArgsFactory+from pipelex.cogt.img_gen.img_gen_worker_abstract import ImgGenWorkerAbstract+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind, extract_gateway_metadata+from pipelex.cogt.inference.error_classify import classify_inference_error+from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error+from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory+from pipelex.providers.manifold.manifold_schemas import ManifoldImgGenAzureGptImage+from pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error++if TYPE_CHECKING:+ from pipelex.cogt.img_gen.img_gen_job import ImgGenJob+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+ from pipelex.reporting.reporting_protocol import ReportingProtocol+++class ManifoldImgGenWorker(ImgGenWorkerAbstract):+ def __init__(+ self,+ sdk_instance: Any,+ inference_model: InferenceModelSpec,+ reporting_delegate: ReportingProtocol | None = None,+ ):+ super().__init__(inference_model=inference_model, reporting_delegate=reporting_delegate)++ if not isinstance(sdk_instance, AsyncPortkey):+ msg = f"Provided ImgGen sdk_instance for {self.__class__.__name__} is not of type portkey_ai.AsyncPortkey: it's a '{type(sdk_instance)}'"+ raise SdkTypeError(msg)++ self.portkey_client: AsyncPortkey = sdk_instance++ @override+ async def _gen_image(+ self,+ img_gen_job: ImgGenJob,+ ) -> GeneratedImageRawDetails:+ one_image_list = await self._gen_image_list(img_gen_job=img_gen_job, nb_images=1)+ return one_image_list[0]++ @override+ async def _gen_image_list(+ self,+ img_gen_job: ImgGenJob,+ *,+ nb_images: int,+ ) -> list[GeneratedImageRawDetails]:+ if self.inference_model.rules is None:+ msg = f"Model '{self.inference_model.name}' does not have rules configured"+ raise ImgGenParameterError(msg)+ args_dict = await ImgGenArgsFactory.make_args_for_model(+ model_rules=self.inference_model.rules,+ img_gen_job=img_gen_job,+ nb_images=nb_images,+ model_id=self.inference_model.model_id,+ model_name=self.inference_model.name,+ )++ image_files: list[ImageFileTuple] | None = args_dict.pop("image", None)+ response_dict = await self._call_images_api(image_files=image_files, args_dict=args_dict)+ self._record_usage(response_dict=response_dict, img_gen_job=img_gen_job)+ return self._make_generated_images(response_dict=response_dict)++ async def _call_images_api(self, *, image_files: list[ImageFileTuple] | None, args_dict: dict[str, Any]) -> dict[str, Any]:+ """One call, one dict back — whichever of the two Images routes the job needs.++ There is no `endpoint_path` here and no config id: the manifold dialect puts the model in the+ body and lets the gateway decide who serves it, so which *route* is called is the SDK+ method's business and which *provider* answers is the gateway's.+ """+ # Declared rather than inferred: the SDK's image methods are typed with `**kwargs: Unknown`,+ # so calling them with a spread argument dict leaves pyright unable to name the result.+ response: Any+ try:+ if image_files is not None:+ # OpenAI's Images API splits generation and editing across two routes, and only+ # /images/edits accepts input images (/images/generations rejects them with a 400+ # "Unknown parameter"). The shape of the multipart body is the SDK's business too: a+ # list under `image` is serialized as `image[]` parts, a single file as the bare+ # `image` field. That distinction is not cosmetic — a server handed repeated bare+ # `image` parts keeps one and silently drops the rest, so an edit of several images+ # would come back as a plausible edit of the first.+ images_arg: Any = image_files[0] if len(image_files) == 1 else list(image_files)+ response = await self.portkey_client.images.edit(image=images_arg, **args_dict) # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]+ else:+ response = await self.portkey_client.images.generate(**args_dict) # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]+ except (portkey_exceptions.APIError, portkey_vendored_openai.APIError) as exc:+ metadata = extract_gateway_metadata(exc)+ classification = classify_inference_error(metadata)+ raise render_inference_error(+ metadata=metadata,+ classification=classification,+ family=InferenceErrorFamily.IMG_GEN,+ model_desc=self.inference_model.desc,+ model_handle=self.inference_model.name,+ ) from exc+ except json.JSONDecodeError as exc:+ # A 2xx carrying a body that is not JSON — an intermediary's HTML error page is the way+ # this happens — makes the SDK's own decode raise. `JSONDecodeError` is not an `APIError`+ # and so falls through the arm above; left raw it is neither a `PipelexError` nor+ # annotated with the model, which means it escapes the Temporal error bridge and gets+ # retried, billing a second generation for the same job.+ msg = f"The Pipelex Manifold service returned a non-JSON body for model '{self.inference_model.name}'"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CONTACT_SUPPORT,+ detail="The gateway returned a malformed response — retry, and report this if it persists",+ ),+ provider_metadata=None,+ ) from exc++ raw_response = cast("object", response.model_dump(serialize_as_any=True)) # pyright: ignore[reportUnknownMemberType]+ if not isinstance(raw_response, dict):+ msg = f"Response from model '{self.inference_model.name}' did not serialize to an object: it is a '{type(raw_response).__name__}'"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The gateway returned an unexpected response shape — try a different model",+ ),+ provider_metadata=None,+ )+ return cast("dict[str, Any]", raw_response)++ def _record_usage(self, *, response_dict: dict[str, Any], img_gen_job: ImgGenJob) -> None:+ if (usage_dict := response_dict.get("usage")) and (img_gen_tokens_usage := img_gen_job.job_report.img_gen_tokens_usage):+ nb_tokens: NbTokensByCategoryDict = {}+ if input_tokens := usage_dict.get("prompt_tokens") or usage_dict.get("input_tokens"):+ nb_tokens[TokenCategory.INPUT] = input_tokens+ if output_tokens := usage_dict.get("completion_tokens") or usage_dict.get("output_tokens"):+ nb_tokens[TokenCategory.OUTPUT] = output_tokens+ img_gen_tokens_usage.nb_tokens_by_category = nb_tokens++ def _make_generated_images(self, *, response_dict: dict[str, Any]) -> list[GeneratedImageRawDetails]:+ try:+ azure_gpt_image = ManifoldImgGenAzureGptImage.model_validate(response_dict)+ except ValidationError as exc:+ msg = f"Could not parse the image generation response for model '{self.inference_model.name}': {format_pydantic_validation_error(exc)}"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The gateway returned an unexpected response shape — try a different model",+ ),+ provider_metadata=None,+ ) from exc++ if not azure_gpt_image.data:+ msg = f"Response from model '{self.inference_model.name}' carries no 'data' images"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The gateway returned an unexpected response shape — try a different model",+ ),+ provider_metadata=None,+ )++ width, height = self._parse_size(size=azure_gpt_image.size)++ generated_images: list[GeneratedImageRawDetails] = []+ for image in azure_gpt_image.data:+ if not image.b64_json:+ msg = f"No base64 image data received from model '{self.inference_model.name}'"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.CONTENT,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail="The gateway returned no image data — try rephrasing the prompt or using a different model",+ ),+ provider_metadata=None,+ )+ generated_images.append(+ GeneratedImageRawDetails(+ base64_str=image.b64_json,+ size=ImageSize(width=width, height=height),+ image_format=azure_gpt_image.output_format,+ ),+ )+ return generated_images++ def _parse_size(self, *, size: str) -> tuple[int, int]:+ size_split = size.split("x")+ if len(size_split) != 2:+ msg = f"Size from img gen response is not a valid size: '{size}'"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The gateway returned a malformed image size — try a different model",+ ),+ provider_metadata=None,+ )+ width_str, height_str = size_split+ try:+ return int(width_str), int(height_str)+ except ValueError as exc:+ msg = f"Size from img gen response has non-numeric dimensions: '{size}'"+ raise ImgGenGenerationError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The gateway returned a malformed image size — try a different model",+ ),+ provider_metadata=None,+ ) from excdiff --git a/pipelex/providers/manifold/manifold_native_client.py b/pipelex/providers/manifold/manifold_native_client.pynew file mode 100644index 000000000..87b77fd2e--- /dev/null+++ b/pipelex/providers/manifold/manifold_native_client.py@@ -0,0 +1,97 @@+"""The HTTP client for the Pipelex Manifold service's own routes.++``POST /v1/pipelex/extract`` and ``POST /v1/pipelex/search`` are not OpenAI-shaped — they serve+document extraction and web search as themselves rather than dressed as chat completions — so they+are called with plain ``httpx`` rather than through a vendor SDK wrapped around a chat body.++**Building the request by hand is what makes the wire readable.** Two properties of the manifold+dialect live in this one method and can be asserted in a test that reads the request it built: the+only header about us is the service token, and the body carries the model with nothing about+routing. A client whose constructor defaults decide the headers cannot say that.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import httpx++from pipelex.cogt.inference.error_classification import extract_manifold_metadata+from pipelex.cogt.inference.error_classify import classify_inference_error+from pipelex.cogt.inference.error_render import render_inference_error+from pipelex.cogt.inference.transport_retry import request_with_transport_retry+from pipelex.config import get_config+from pipelex.providers.manifold.manifold_exceptions import ManifoldError+from pipelex.providers.manifold.manifold_factory import ManifoldFactory++if TYPE_CHECKING:+ from pipelex.cogt.inference.error_render import InferenceErrorFamily+ from pipelex.cogt.model_backends.backend import InferenceBackend+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec++# Generous, and deliberately so: a deep web search or a many-page extraction is a slow call, and the+# runtime's own job-level timeouts are the ones that should bound it. Matches the SDK-less image+# path's floor rather than inventing a second number.+MANIFOLD_NATIVE_TIMEOUT_SECONDS = 600.0+++class ManifoldNativeClient:+ """One route call, one dict back — or a categorized inference error."""++ def __init__(self, *, backend: InferenceBackend) -> None:+ self.base_url = ManifoldFactory.get_base_url(backend=backend)+ self.auth_headers = ManifoldFactory.make_auth_headers(backend=backend)++ async def post_json(+ self,+ *,+ route: str,+ body: dict[str, Any],+ family: InferenceErrorFamily,+ inference_model: InferenceModelSpec,+ ) -> dict[str, Any]:+ url = f"{self.base_url}{route}"++ async def _send() -> httpx.Response:+ async with httpx.AsyncClient() as client:+ response = await client.post(+ url,+ headers={**self.auth_headers, "Content-Type": "application/json"},+ json=body,+ timeout=MANIFOLD_NATIVE_TIMEOUT_SECONDS,+ )+ response.raise_for_status()+ return response++ try:+ # These are billable, non-idempotent POSTs — a search that reached the provider has been+ # paid for — so an ambiguous 5xx is not retried. The retry stays on the failures that+ # prove no work was done.+ http_response = await request_with_transport_retry(+ send_request=_send,+ max_retries=get_config().inference.transport_max_retries,+ retry_on_ambiguous_failure=False,+ )+ except httpx.HTTPError as exc:+ metadata = extract_manifold_metadata(exc)+ classification = classify_inference_error(metadata)+ raise render_inference_error(+ metadata=metadata,+ classification=classification,+ family=family,+ model_desc=inference_model.desc,+ model_handle=inference_model.name,+ ) from exc++ try:+ payload: Any = http_response.json()+ except ValueError as exc:+ # A 2xx whose body is not JSON — an intermediary's error page is how this happens. Left+ # raw it is neither a `PipelexError` nor annotated with the model, so it would escape+ # the Temporal error bridge and be retried against a call that was already paid for.+ msg = f"The Pipelex Manifold service returned a non-JSON body for model '{inference_model.name}'"+ raise ManifoldError(msg) from exc+ if not isinstance(payload, dict):+ msg = f"The Pipelex Manifold service returned a '{type(payload).__name__}' rather than an object for model '{inference_model.name}'"+ raise ManifoldError(msg)+ return payload # pyright: ignore[reportUnknownVariableType]diff --git a/pipelex/providers/manifold/manifold_plugin.py b/pipelex/providers/manifold/manifold_plugin.pynew file mode 100644index 000000000..cb3df2b58--- /dev/null+++ b/pipelex/providers/manifold/manifold_plugin.py@@ -0,0 +1,176 @@+"""The manifold sdk set, registered.++One registration per ``(family, sdk)`` the Pipelex Manifold service serves. The pairing worth+noticing is ``(IMG_GEN, manifold_completions)``: some image models answer on the Chat Completions+shape rather than on the Images API, and the catalog says which by giving them ``model_type =+"img_gen"`` while leaving them on the default completions sdk — so the same sdk name is registered+under two families, served by two different workers.++``anthropic`` is deliberately not here. Claude reaches the manifold service over the *shared*+Anthropic SDK driver, which authenticates on whichever header the backend names; that driver is not+part of this package and outlives the Portkey retirement.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from pipelex.plugins.contract import PLUGIN_API_VERSION+from pipelex.plugins.inference_backend_registry import InferenceFamily+from pipelex.plugins.model_handle import ModelHandle+from pipelex.providers.manifold.manifold_constants import ManifoldSdk++if TYPE_CHECKING:+ from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract+ from pipelex.cogt.model_backends.backend import InferenceBackend+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+ from pipelex.plugins.registrar import PluginRegistrar+ from pipelex.plugins.sdk_client_registry import SdkClientRegistry+ from pipelex.reporting.reporting_protocol import ReportingProtocol+++def _make_manifold_completions_worker(+ *,+ inference_model: InferenceModelSpec,+ backend: InferenceBackend,+ sdk_clients: SdkClientRegistry,+ reporting_delegate: ReportingProtocol | None,+) -> InferenceWorkerAbstract:+ from pipelex.providers.manifold.manifold_completions_factory import ManifoldCompletionsFactory # ruff: ignore[import-outside-top-level]+ from pipelex.providers.openai.openai_completions_llm_worker import OpenAICompletionsLLMWorker # ruff: ignore[import-outside-top-level]++ model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)+ sdk_instance = sdk_clients.get_or_create(+ handle=model_handle,+ build=lambda: ManifoldCompletionsFactory.make_openai_client_for_completions(model_handle=model_handle, backend=backend),+ )+ return OpenAICompletionsLLMWorker(+ openai_completions_factory=ManifoldCompletionsFactory(is_http_url_enabled=False),+ sdk_instance=sdk_instance,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )+++def _make_manifold_responses_worker(+ *,+ inference_model: InferenceModelSpec,+ backend: InferenceBackend,+ sdk_clients: SdkClientRegistry,+ reporting_delegate: ReportingProtocol | None,+) -> InferenceWorkerAbstract:+ from pipelex.providers.manifold.manifold_responses_factory import ManifoldResponsesFactory # ruff: ignore[import-outside-top-level]+ from pipelex.providers.openai.openai_responses_llm_worker import OpenAIResponsesLLMWorker # ruff: ignore[import-outside-top-level]++ model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)+ sdk_instance = sdk_clients.get_or_create(+ handle=model_handle,+ build=lambda: ManifoldResponsesFactory.make_openai_client_for_responses(model_handle=model_handle, backend=backend),+ )+ return OpenAIResponsesLLMWorker(+ openai_responses_factory=ManifoldResponsesFactory(is_http_url_enabled=False),+ sdk_instance=sdk_instance,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )+++def _make_manifold_completions_img_gen_worker(+ *,+ inference_model: InferenceModelSpec,+ backend: InferenceBackend,+ sdk_clients: SdkClientRegistry,+ reporting_delegate: ReportingProtocol | None,+) -> InferenceWorkerAbstract:+ from pipelex.providers.manifold.manifold_completions_factory import ManifoldCompletionsFactory # ruff: ignore[import-outside-top-level]+ from pipelex.providers.openai.openai_completions_img_gen_worker import OpenAICompletionsImgGenWorker # ruff: ignore[import-outside-top-level]++ model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)+ sdk_instance = sdk_clients.get_or_create(+ handle=model_handle,+ build=lambda: ManifoldCompletionsFactory.make_openai_client_for_completions(model_handle=model_handle, backend=backend),+ )+ return OpenAICompletionsImgGenWorker(+ openai_completions_factory=ManifoldCompletionsFactory(is_http_url_enabled=False),+ sdk_instance=sdk_instance,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )+++def _make_manifold_img_gen_worker(+ *,+ inference_model: InferenceModelSpec,+ backend: InferenceBackend,+ sdk_clients: SdkClientRegistry,+ reporting_delegate: ReportingProtocol | None,+) -> InferenceWorkerAbstract:+ from pipelex.providers.manifold.manifold_factory import ManifoldFactory # ruff: ignore[import-outside-top-level]+ from pipelex.providers.manifold.manifold_img_gen_worker import ManifoldImgGenWorker # ruff: ignore[import-outside-top-level]++ model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)+ sdk_instance = sdk_clients.get_or_create(+ handle=model_handle,+ build=lambda: ManifoldFactory.make_portkey_client(backend=backend),+ )+ return ManifoldImgGenWorker(+ sdk_instance=sdk_instance,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )+++def _make_manifold_extract_worker(+ *,+ inference_model: InferenceModelSpec,+ backend: InferenceBackend,+ sdk_clients: SdkClientRegistry,+ reporting_delegate: ReportingProtocol | None,+) -> InferenceWorkerAbstract:+ from pipelex.providers.manifold.manifold_extract_worker import ManifoldExtractWorker # ruff: ignore[import-outside-top-level]+ from pipelex.providers.manifold.manifold_native_client import ManifoldNativeClient # ruff: ignore[import-outside-top-level]++ model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)+ sdk_instance = sdk_clients.get_or_create(handle=model_handle, build=lambda: ManifoldNativeClient(backend=backend))+ return ManifoldExtractWorker(+ sdk_instance=sdk_instance,+ extra_config=backend.extra_config,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )+++def _make_manifold_search_worker(+ *,+ inference_model: InferenceModelSpec,+ backend: InferenceBackend,+ sdk_clients: SdkClientRegistry,+ reporting_delegate: ReportingProtocol | None,+) -> InferenceWorkerAbstract:+ from pipelex.providers.manifold.manifold_native_client import ManifoldNativeClient # ruff: ignore[import-outside-top-level]+ from pipelex.providers.manifold.manifold_search_worker import ManifoldSearchWorker # ruff: ignore[import-outside-top-level]++ model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)+ sdk_instance = sdk_clients.get_or_create(handle=model_handle, build=lambda: ManifoldNativeClient(backend=backend))+ return ManifoldSearchWorker(+ sdk_instance=sdk_instance,+ inference_model=inference_model,+ reporting_delegate=reporting_delegate,+ )+++class ManifoldPlugin:+ """Built-in driver for the Pipelex Manifold service, serving all inference families."""++ name = "manifold"+ targets_api = PLUGIN_API_VERSION++ def register(self, registrar: PluginRegistrar) -> None:+ registrar.add_inference_backend(family=InferenceFamily.LLM, sdk=ManifoldSdk.COMPLETIONS, make_worker=_make_manifold_completions_worker)+ registrar.add_inference_backend(family=InferenceFamily.LLM, sdk=ManifoldSdk.RESPONSES, make_worker=_make_manifold_responses_worker)+ registrar.add_inference_backend(family=InferenceFamily.IMG_GEN, sdk=ManifoldSdk.IMG_GEN, make_worker=_make_manifold_img_gen_worker)+ registrar.add_inference_backend(+ family=InferenceFamily.IMG_GEN, sdk=ManifoldSdk.COMPLETIONS, make_worker=_make_manifold_completions_img_gen_worker+ )+ registrar.add_inference_backend(family=InferenceFamily.EXTRACT, sdk=ManifoldSdk.EXTRACT, make_worker=_make_manifold_extract_worker)+ registrar.add_inference_backend(family=InferenceFamily.SEARCH, sdk=ManifoldSdk.SEARCH, make_worker=_make_manifold_search_worker)diff --git a/pipelex/providers/manifold/manifold_responses_factory.py b/pipelex/providers/manifold/manifold_responses_factory.pynew file mode 100644index 000000000..2f7d9b856--- /dev/null+++ b/pipelex/providers/manifold/manifold_responses_factory.py@@ -0,0 +1,57 @@+"""The Responses-API factory for the Pipelex Manifold service.++Thin, unlike its Chat Completions sibling: the Responses shape carries documents as its own input+parts, so there is no gateway-specific message override to copy. All this class supplies is the+client — built under the endpoint rule, authenticated on the service's header — and the per-request+extras.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import openai+from typing_extensions import override++from pipelex.config import get_config+from pipelex.providers.manifold.manifold_constants import ManifoldOpenAISdkVariant+from pipelex.providers.manifold.manifold_exceptions import ManifoldFactoryError+from pipelex.providers.manifold.manifold_factory import ManifoldFactory+from pipelex.providers.openai.openai_responses_factory import OpenAIResponsesFactory++if TYPE_CHECKING:+ from pipelex.cogt.inference.inference_job_abstract import InferenceJobAbstract+ from pipelex.cogt.model_backends.backend import InferenceBackend+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+ from pipelex.plugins.model_handle import ModelHandle+++class ManifoldResponsesFactory(OpenAIResponsesFactory):+ @classmethod+ def make_openai_client_for_responses(+ cls,+ model_handle: ModelHandle,+ *,+ backend: InferenceBackend,+ ) -> openai.AsyncOpenAI:+ if not ManifoldOpenAISdkVariant.is_responses(model_handle.sdk):+ msg = f"ModelHandle '{model_handle}' is not supported by '{cls.__name__}'"+ raise ManifoldFactoryError(msg)++ return openai.AsyncOpenAI(+ base_url=ManifoldFactory.get_base_url(backend=backend),+ # Auth travels in the service's own header, not in the OpenAI Authorization one. The SDK+ # has rejected an empty api_key since 2.34.0, so the slot holds a placeholder the+ # gateway never reads.+ api_key="unused-auth-via-manifold-header",+ # Tier 1 transport retry: set explicitly from config rather than inheriting the SDK+ # default, so a transport_max_retries override applies to this path too.+ max_retries=get_config().inference.transport_max_retries,+ default_headers=ManifoldFactory.make_auth_headers(backend=backend),+ )++ @override+ def make_extras(+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str+ ) -> tuple[dict[str, str], dict[str, Any]]:+ return ManifoldFactory.make_extras(inference_model=inference_model, inference_job=inference_job, output_desc=output_desc)diff --git a/pipelex/providers/manifold/manifold_schemas.py b/pipelex/providers/manifold/manifold_schemas.pynew file mode 100644index 000000000..d447e07d0--- /dev/null+++ b/pipelex/providers/manifold/manifold_schemas.py@@ -0,0 +1,89 @@+"""The wire shapes the manifold plugin sends and reads.++Two groups, and they are owned by different sides.++**The native-route requests** (`ManifoldExtractRequest`, `ManifoldSearchRequest`) are this plugin's+half of a contract the *gateway* owns and freezes, in `src/pig/pipelex/schemas.ts`. They are written+out field by field rather than derived from the runtime's job-params models, and that is the point:+several fields of `ExtractJobParams` are deliberately absent from the contract and the gateway+**refuses** them at any value, including their own defaults. A worker that reached for+`model_dump()` would send `should_caption_images=false` and be refused; one that sent them and had+them ignored would be told a parameter was honoured when it was dropped. Building the body+explicitly is what makes the absence visible in this file rather than surprising at request time.++**The image response** is Azure's, as the gateway forwards it.+"""++from __future__ import annotations++from typing import Any++from pydantic import BaseModel, ConfigDict, Field+++class ManifoldExtractInput(BaseModel):+ """Exactly one of the two is set; the gateway refuses neither-or-both."""++ document_uri: str | None = None+ image_uri: str | None = None+++class ManifoldExtractParams(BaseModel):+ """The extract parameters the contract *does* carry.++ `max_nb_images` keeps the runtime's own semantics — `None` unlimited, `0` none, `N` a per-page+ cap. `render_js` and `include_raw_html` are honoured by the web-fetch provider alone, and the+ gateway refuses a non-null value on a provider that cannot honour them.+ """++ max_nb_images: int | None = None+ render_js: bool | None = None+ include_raw_html: bool | None = None+++class ManifoldExtractRequest(BaseModel):+ model: str+ input: ManifoldExtractInput+ params: ManifoldExtractParams | None = None+++class ManifoldSearchRequest(BaseModel):+ """Flat, and with no `depth`: the model id carries it — `linkup/standard` versus `linkup/deep`."""++ model: str+ query: str+ include_images: bool | None = None+ include_inline_citations: bool | None = None+ max_results: int | None = None+ include_domains: list[str] | None = None+ exclude_domains: list[str] | None = None+ from_date: str | None = None+ to_date: str | None = None+ output_schema: dict[str, Any] | None = None+++class ManifoldImgGenAzureGptImageDatum(BaseModel):+ """One generated image.++ `b64_json` is optional here although Azure always sends it on a successful generation, so that a+ datum arriving without one gets the error it deserves — the image was filtered, which is the+ caller's prompt to change — rather than a parse failure blamed on the model.+ """++ model_config = ConfigDict(extra="ignore")++ b64_json: str | None = None+++class ManifoldImgGenAzureGptImage(BaseModel):+ """The Azure GPT Image response, as the gateway forwards it unchanged.++ `size` and `output_format` arrive as Azure wrote them and are what the runtime needs to build a+ `GeneratedImageRawDetails`; `data` carries the images themselves.+ """++ model_config = ConfigDict(extra="ignore")++ size: str = Field(description="Size of the image, as WIDTHxHEIGHT")+ output_format: str = Field(description="Output format of the image")+ data: list[ManifoldImgGenAzureGptImageDatum] = []diff --git a/pipelex/providers/manifold/manifold_search_worker.py b/pipelex/providers/manifold/manifold_search_worker.pynew file mode 100644index 000000000..07b43e36a--- /dev/null+++ b/pipelex/providers/manifold/manifold_search_worker.py@@ -0,0 +1,167 @@+"""Web search over the Pipelex Manifold service's own route.++Thin, like its extraction sibling, and for the same reason: ``POST /v1/pipelex/search`` answers with+the search itself rather than with a chat completion whose message content is a JSON string that has+to be decoded before it means anything.++**No ``depth`` on the wire.** The model id carries it — ``linkup/standard`` versus ``linkup/deep`` —+and a second source for a decision the gateway takes from one place is a source of disagreement, not+of flexibility.++**Usage arrives as searches and has to become tokens.** See ``manifold_extract_worker`` for the+whole of that reasoning; the failure it prevents is a cost of zero reported with no error at all.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any, cast++from typing_extensions import override++from pipelex.cogt.exceptions import InferenceErrorCategory, SdkTypeError+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind+from pipelex.cogt.inference.error_render import InferenceErrorFamily+from pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstract+from pipelex.cogt.search.structured_search_payload import extract_structured_search_payload+from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory+from pipelex.core.stuffs.document_content import DocumentContent+from pipelex.core.stuffs.search_result_content import SearchResultContent+from pipelex.providers.manifold.manifold_constants import MANIFOLD_SEARCH_ROUTE+from pipelex.providers.manifold.manifold_exceptions import ManifoldSearchEmptyResultError, ManifoldSearchResponseError+from pipelex.providers.manifold.manifold_extract_worker import MANIFOLD_UNIT_TOKENS+from pipelex.providers.manifold.manifold_native_client import ManifoldNativeClient+from pipelex.providers.manifold.manifold_schemas import ManifoldSearchRequest++if TYPE_CHECKING:+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+ from pipelex.cogt.search.search_job import SearchJob+ from pipelex.reporting.reporting_protocol import ReportingProtocol+ from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar+++class ManifoldSearchWorker(SearchWorkerAbstract):+ def __init__(+ self,+ sdk_instance: Any,+ inference_model: InferenceModelSpec,+ reporting_delegate: ReportingProtocol | None = None,+ ):+ super().__init__(inference_model=inference_model, reporting_delegate=reporting_delegate)++ if not isinstance(sdk_instance, ManifoldNativeClient):+ msg = f"Provided search sdk_instance for {self.__class__.__name__} is not a ManifoldNativeClient: it's a '{type(sdk_instance)}'"+ raise SdkTypeError(msg)++ self.client: ManifoldNativeClient = sdk_instance++ @override+ async def _search_sourced_answer(+ self,+ search_job: SearchJob,+ ) -> SearchResultContent:+ response_body = await self._call_search(search_job=search_job, output_schema=None)++ answer: Any = response_body.get("answer")+ if not isinstance(answer, str):+ msg = f"The search response for model '{self.inference_model.name}' carries no answer"+ raise ManifoldSearchResponseError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The gateway returned a malformed search response — try a different model",+ ),+ provider_metadata=None,+ )++ raw_sources: Any = response_body.get("sources") or []+ sources = [+ DocumentContent(+ title=source["name"],+ url=source["url"],+ public_url=source["url"],+ snippet=source["snippet"],+ mime_type="text/html",+ )+ for source in cast("list[dict[str, Any]]", raw_sources)+ ]++ return SearchResultContent(answer=answer, sources=sources)++ @override+ async def _search_structured(+ self,+ search_job: SearchJob,+ *,+ schema: type[BaseModelTypeVar],+ ) -> dict[str, Any]:+ response_body = await self._call_search(search_job=search_job, output_schema=schema.model_json_schema())++ # The route answers with a `{data, sources}` envelope, and the contract of a structured+ # search is the payload alone — it is validated against the caller's output structure class,+ # which has nowhere to put sources. The envelope is recognised *structurally* rather than+ # demanded, so the day the gateway stops asking for sources this worker keeps working on the+ # bare payload it then returns.+ #+ # `usage` is dropped first, and that line is load-bearing. On this route usage sits *beside*+ # the envelope rather than inside a chat completion the way the costume put it, and the+ # recognition is by the key set being exactly {data, sources} — so leaving a third key there+ # makes the whole response look like the payload, which then validates against an output+ # class whose fields have defaults and returns an all-defaults object with no error+ # anywhere. Usage has already been recorded by the time this runs.+ envelope = {key: value for key, value in response_body.items() if key != "usage"}+ payload = extract_structured_search_payload(response=envelope, schema=schema)+ if payload is not None:+ return payload+ # The response was an object but carried no structured payload: the search ran and found+ # nothing to fill the output structure with. That is the query's fault, not the model's.+ msg = f"The structured search for model '{self.inference_model.name}' returned an empty structured result"+ raise ManifoldSearchEmptyResultError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail="The search found nothing to fill your output structure — try a broader query or a wider date range",+ ),+ provider_metadata=None,+ )++ async def _call_search(self, *, search_job: SearchJob, output_schema: dict[str, Any] | None) -> dict[str, Any]:+ job_params = search_job.job_params+ search_setting = job_params.search_setting+ request = ManifoldSearchRequest(+ model=self.inference_model.model_id,+ query=search_job.query,+ include_images=search_setting.include_images,+ include_inline_citations=search_setting.include_inline_citations,+ max_results=search_setting.max_results,+ include_domains=job_params.include_domains,+ exclude_domains=job_params.exclude_domains,+ from_date=job_params.from_date,+ to_date=job_params.to_date,+ output_schema=output_schema,+ )+ response_body = await self.client.post_json(+ route=MANIFOLD_SEARCH_ROUTE,+ body=request.model_dump(exclude_none=True),+ family=InferenceErrorFamily.SEARCH,+ inference_model=self.inference_model,+ )+ self._record_usage(response_body=response_body, search_job=search_job)+ return response_body++ def _record_usage(self, *, response_body: dict[str, Any], search_job: SearchJob) -> None:+ search_tokens_usage = search_job.job_report.search_tokens_usage+ if not search_tokens_usage:+ return+ usage: object = response_body.get("usage")+ if not isinstance(usage, dict):+ return+ nb_searches: object = cast("dict[str, Any]", usage).get("searches")+ if not isinstance(nb_searches, int):+ return+ nb_tokens: NbTokensByCategoryDict = {+ TokenCategory.INPUT: nb_searches * MANIFOLD_UNIT_TOKENS,+ TokenCategory.OUTPUT: nb_searches * MANIFOLD_UNIT_TOKENS,+ }+ search_tokens_usage.nb_tokens_by_category = nb_tokensdiff --git a/pipelex/providers/openai/openai_completions_img_gen_worker.py b/pipelex/providers/openai/openai_completions_img_gen_worker.pyindex 014874d9c..6a476fa15 100644--- a/pipelex/providers/openai/openai_completions_img_gen_worker.py+++ b/pipelex/providers/openai/openai_completions_img_gen_worker.py@@ -17,6 +17,7 @@ from pipelex.cogt.inference.error_classification import UserAction, UserActionKifrom pipelex.cogt.inference.error_classify import classify_inference_errorfrom pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_errorfrom pipelex.cogt.inference.inference_constants import InferenceOutputType+from pipelex.cogt.model_backends.backend import MANAGED_GATEWAY_BACKEND_NAMESfrom pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.providers.openai.openai_completions_factory import OpenAICompletionsFactoryfrom pipelex.reporting.reporting_protocol import ReportingProtocol@@ -54,10 +55,13 @@ class OpenAICompletionsImgGenWorker(ImgGenWorkerAbstract):) -> GeneratedImageRawDetails:log.debug(f"Generating image with model: {self.inference_model.tag}")image_format: ImageFormat | None = None- if self.inference_model.backend_name == "pipelex_gateway":+ # Both Pipelex-managed gateways, not just the Portkey-cloud one: the manifold service relays+ # the same models through the same gateway codebase, so it normalises a completions image+ # response the same way — a URL to a PNG, with no format to read off the bytes.+ if self.inference_model.backend_name in MANAGED_GATEWAY_BACKEND_NAMES:if img_gen_job.job_params.output_format and not img_gen_job.job_params.output_format.is_png:msg = (- f"Completions ImgGen worker for Pipelex Gateway only supports PNG output format. "+ f"Completions ImgGen worker for backend '{self.inference_model.backend_name}' only supports PNG output format. "f"Requested output format: {img_gen_job.job_params.output_format}")raise ImgGenParameterError(msg)@@ -124,7 +128,8 @@ class OpenAICompletionsImgGenWorker(ImgGenWorkerAbstract):if image_format is None:msg = (f"OpenAI response message is a URL but output_format is not set. This shouldn't be possible. "- f"This response should only happen when using backend 'blackboxai' or 'pipelex_gateway'. "+ f"This response should only happen when using backend 'blackboxai' or a Pipelex-managed gateway "+ f"({', '.join(MANAGED_GATEWAY_BACKEND_NAMES)}). "f"Backend is: '{self.inference_model.backend_name}'")raise ImgGenParameterError(msg)diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex 52c17d027..e232df80f 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -64,10 +64,10 @@ from pipelex.cogt.exceptions import (RoutingProfileLibraryNotFoundError,)from pipelex.cogt.inference.inference_manager import InferenceManager+from pipelex.cogt.model_backends.backend import PipelexBackendfrom pipelex.cogt.model_backends.backend_credentials import (BackendCredentialsErrorMsgFactory,)-from pipelex.cogt.model_backends.gateway_config import GatewayConfigfrom pipelex.cogt.models.model_manager import ModelManagerfrom pipelex.cogt.models.model_manager_abstract import ModelManagerAbstractfrom pipelex.config import get_config@@ -101,8 +101,9 @@ from pipelex.system.pipelex_service.exceptions import (InferenceSetupRequiredError,RemoteConfigStaleWarning,)+from pipelex.system.pipelex_service.managed_gateway_configs import build_managed_gateway_configsfrom pipelex.system.pipelex_service.pipelex_service_config import (- is_pipelex_gateway_enabled,+ enabled_managed_gateway_sections,load_pipelex_service_config_if_exists,)from pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcher@@ -129,6 +130,7 @@ from pipelex.urls import URLsif TYPE_CHECKING:from collections.abc import Sequence+ from pipelex.cogt.model_backends.gateway_config import GatewayConfigfrom pipelex.plugins.contract import PipelexPluginfrom pipelex.plugins.plugin_group import PluginGroupfrom pipelex.system.pipelex_service.remote_config import RemoteConfig@@ -377,29 +379,31 @@ 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 service is the Pipelex Gateway+ # Which Pipelex-managed gateway backends are enabled, and which section of the published+ # artifact each takes its model specs from. More than one can be live at once — the Portkey+ # cloud service and the manifold one are two services, sharing this one artifact, this one+ # fetch and its one cache, and nothing else.try:- is_pipelex_service_enabled = is_pipelex_gateway_enabled()+ managed_gateway_sections = enabled_managed_gateway_sections()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_exc+ is_pipelex_service_enabled = bool(managed_gateway_sections)effective_needs_model_specs = needs_model_specs if needs_model_specs is not None else needs_inferenceremote_config: RemoteConfig | None = None- gateway_config: GatewayConfig | None = None+ managed_gateway_configs: dict[str, GatewayConfig] | None = Nonegateway_config_source: RemoteConfigSource | None = Noneif is_pipelex_service_enabled:if not effective_needs_model_specs:# Use dummy config when inference is not needed (for testing without network access)remote_config = RemoteConfigFetcher.make_dummy_remote_config()- gateway_model_specs = remote_config.backend_model_specs- gateway_config = GatewayConfig(- model_specs=gateway_model_specs,- aws_region=remote_config.aws_region,+ managed_gateway_configs = build_managed_gateway_configs(+ remote_config=remote_config,+ managed_gateway_sections=managed_gateway_sections,)# Keep ``gateway_config_source`` as ``None``: the dummy specs are an empty# placeholder, not real Gateway data. ``ModelManager._enforce_gateway_model_membership``@@ -411,6 +415,10 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# Terms acceptance is only required for actual inference usage, not for# read-only operations like fetching model specs for validation.# Also skip for CI mode — automated pipelines don't require human consent.+ #+ # **One gate, for any managed gateway backend.** The terms are the Pipelex service's+ # terms, not one dialect's: a boot that reaches the service at all passes through+ # here, whichever managed backend asked for it.if needs_inference and integration_mode.requires_terms_acceptance:pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)# First-run check: fires if inference has never been configured@@ -430,10 +438,9 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.remote_config = remote_config_result.configgateway_config_source = remote_config_result.sourcelog.verbose(f"Successfully fetched Pipelex Gateway remote configuration (source={gateway_config_source})")- gateway_model_specs = remote_config.backend_model_specs- gateway_config = GatewayConfig(- model_specs=gateway_model_specs,- aws_region=remote_config.aws_region,+ managed_gateway_configs = build_managed_gateway_configs(+ remote_config=remote_config,+ managed_gateway_sections=managed_gateway_sections,)# Stale operation: warn loudly so machine consumers can re-surface the provenance.# Emission lives at this orchestration layer (not in the fetcher) so the fetcher@@ -499,11 +506,27 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.secrets_provider = secrets_provider_registry.get_required(method=secrets_config.method)(secrets_config)# Disable Pipelex telemetry when:+ # - the legacy gateway backend is not enabled, OR# - inference is not needed (no live runs to track), OR# - the gateway config came from the cache (stale specs imply potentially stale model# identities; phoning home about pipe runs in that state would pollute metrics).+ #+ # **The first condition asks about `pipelex_gateway` specifically, not about managed backends+ # in general**, and the distinct id is why: it is derived from `PIPELEX_GATEWAY_API_KEY`, which+ # a manifold backend neither has nor can stand in for — its own key is, for the private beta,+ # one token shared by every participant, so keying on it would produce a single indistinguishable+ # user rather than an identity. Asked the general way, a manifold-only installation would be+ # required to hold a gateway key it has no other use for and would fail to boot without one.+ # The common beta case is unaffected: a participant who keeps `pipelex_gateway` enabled has a+ # real gateway key, and their manifold runs are tracked under it like everything else.+ #+ # Read off the mapping computed above rather than by asking the document a second time. The+ # two answers are the same one — the gateway resolves to a section whenever it is enabled —+ # and a second read would be a second chance for an unparseable file to escape the clause+ # that frames it as a backend-library refusal.gateway_source_is_cached = gateway_config_source is not None and gateway_config_source.is_cached- is_pipelex_telemetry_enabled = is_pipelex_service_enabled and needs_inference and not gateway_source_is_cached+ is_gateway_enabled = PipelexBackend.GATEWAY in managed_gateway_sections+ is_pipelex_telemetry_enabled = is_gateway_enabled and needs_inference and not gateway_source_is_cachedself.telemetry_manager = TelemetryFactory.make_telemetry_manager(secrets_provider=secrets_provider,integration_mode=integration_mode,@@ -574,7 +597,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# this; do not read ``config_dir`` as "only this directory is read" for inference.self.models_manager.setup(secrets_provider=secrets_provider,- gateway_config=gateway_config,+ managed_gateway_configs=managed_gateway_configs,gateway_config_source=gateway_config_source,needs_inference=needs_inference,)diff --git a/pipelex/system/pipelex_service/managed_gateway_configs.py b/pipelex/system/pipelex_service/managed_gateway_configs.pynew file mode 100644index 000000000..23aaa6bd8--- /dev/null+++ b/pipelex/system/pipelex_service/managed_gateway_configs.py@@ -0,0 +1,58 @@+"""Slice the one fetched artifact into one gateway configuration per enabled managed backend.++Its own module rather than a method on the boot, because the doctor asks the same question the boot+does and must get the same answer: it probes a specific `backends.toml` (project vs `--global`) and+then stands up a `ModelManager` over what it found. A second implementation there would be a second+opinion on which backend reads which section.+"""++from pipelex import log+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION+from pipelex.cogt.model_backends.gateway_config import GatewayConfig+from pipelex.system.pipelex_service.remote_config import RemoteConfig+++def build_managed_gateway_configs(+ *,+ remote_config: RemoteConfig,+ managed_gateway_sections: dict[str, str],+) -> dict[str, GatewayConfig]:+ """One gateway configuration per enabled managed backend, sliced out of the one fetched artifact.++ **One fetch, N configs, kept apart rather than merged.** The artifact is one document with one+ version, so there is exactly one network call and one disk cache; but a handle that one service+ serves and the other does not is a legitimate configuration and not a conflict to resolve, so the+ sections never meet.++ A backend whose declared section is absent from the published artifact is **disabled with a named+ warning** rather than fatal — the same posture as a managed backend missing one of its `${…}`+ variables, and for the same reason: the kit can ship a managed backend declared, so an+ installation that has not joined must not fail to boot over a section it never asked for.++ Args:+ remote_config: The artifact, fresh or from the on-disk cache.+ managed_gateway_sections: `{backend_name: section_name}`, from `enabled_managed_gateway_sections`.++ Returns:+ `{backend_name: GatewayConfig}`, carrying an entry only for a backend whose section was+ actually published.+ """+ managed_gateway_configs: dict[str, GatewayConfig] = {}+ for backend_name, section_name in managed_gateway_sections.items():+ model_specs = remote_config.get_model_specs_section(section_name)+ if model_specs is None:+ log.warning(+ f"Backend '{backend_name}' is disabled: it is a Pipelex-managed gateway backend taking its model specs from the "+ f"'{section_name}' section of the Pipelex configuration, and the configuration we read carries no such section. "+ f"Set `enabled = false` on it in your backends.toml to silence this warning."+ )+ continue+ managed_gateway_configs[backend_name] = GatewayConfig(+ model_specs=model_specs,+ # `aws_region` is a top-level key of the artifact rather than a property of a section, and+ # it belongs to the legacy gateway's slice alone: it is threaded into that backend's+ # `extra_config`, and nothing on the manifold path reads it back because there the Bedrock+ # credentials live gateway-side.+ aws_region=remote_config.aws_region if section_name == LEGACY_GATEWAY_MODEL_SPECS_SECTION else None,+ )+ return managed_gateway_configsdiff --git a/pipelex/system/pipelex_service/pipelex_details.py b/pipelex/system/pipelex_service/pipelex_details.pyindex 4ebb8a96c..50f44524f 100644--- a/pipelex/system/pipelex_service/pipelex_details.py+++ b/pipelex/system/pipelex_service/pipelex_details.py@@ -2,7 +2,7 @@ import osfrom pipelex.tools.misc.hash_utils import hash_sha256-_DEFAULT_REMOTE_CONFIG_URL = "https://pipelex-config.s3.eu-west-3.amazonaws.com/pipelex_remote_config_12.json"+_DEFAULT_REMOTE_CONFIG_URL = "https://pipelex-config.s3.eu-west-3.amazonaws.com/pipelex_remote_config_13.json"REMOTE_CONFIG_URL_ENV_VAR = "PIPELEX_REMOTE_CONFIG_URL"diff --git a/pipelex/system/pipelex_service/pipelex_service_config.py b/pipelex/system/pipelex_service/pipelex_service_config.pyindex 72e6415e2..51b91f8b5 100644--- a/pipelex/system/pipelex_service/pipelex_service_config.py+++ b/pipelex/system/pipelex_service/pipelex_service_config.py@@ -5,7 +5,7 @@ from pydantic import Field, ValidationErrorfrom pipelex import logfrom pipelex.cogt.exceptions import InferenceBackendLibraryValidationError-from pipelex.cogt.model_backends.backend import PipelexBackend+from pipelex.cogt.model_backends.backend import PipelexBackend, resolve_model_specs_sectionfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.configuration.config_model import ConfigModelfrom pipelex.system.configuration.config_surface import (@@ -77,9 +77,88 @@ def _service_config_the_ledger_can_explain(*, config_path: Path) -> PipelexServireturn service_config+def _backends_document(*, config_dir: Path | None) -> dict[str, Any] | None:+ """The merged ``backends.toml`` document, or ``None`` when there is no base file.++ The same document the library loader reads: the base first, then every+ ``backends_override.toml`` that exists, deep-merged in order — from+ ``config_manager.backends_file_paths``. Both readers below go through here so neither can end+ up branching on a narrower view of the configuration than the loader they feed.++ 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.+ """+ backends_file_paths = config_manager.backends_file_paths(config_dir=config_dir)+ try:+ return load_toml_from_base_and_overrides(paths=backends_file_paths)+ except FileNotFoundError:+ return None+ 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_exc+++def enabled_managed_gateway_sections(*, config_dir: Path | None = None) -> dict[str, str]:+ """The enabled managed gateway backends, each mapped to the remote-config section its specs come from.++ A *managed gateway backend* is one whose model specs arrive from the Pipelex service's published+ artifact rather than from a local per-backend TOML, and naming a section is what declares it one+ — see `resolve_model_specs_section`, which also explains why `pipelex_gateway` resolves to a+ section it never declared. There can now be more than one, which is why the boot asks this+ question rather than the single-name one below.++ Read here, off the raw document, for the same reason `is_pipelex_gateway_enabled` is: the boot+ needs the answer *before* it can load the backend library, because what it fetches is the input+ to that load. It applies the same truthiness reading of `enabled`, for the same reason.++ Args:+ config_dir: Read the document at that directory — its ``backends.toml`` and its own+ ``backends_override.toml`` — exactly as below. ``None`` (default) reads the layered+ document.++ Returns:+ ``{backend_name: section_name}``, empty when no managed gateway backend is enabled.++ Raises:+ InferenceBackendLibraryValidationError: a file in the document does not parse — see+ `_backends_document`.+ """+ backends_toml = _backends_document(config_dir=config_dir)+ if backends_toml is None:+ return {}++ sections: dict[str, str] = {}+ for backend_name, backend_table in backends_toml.items():+ if not isinstance(backend_table, dict):+ continue+ backend_dict = cast("dict[str, Any]", backend_table)+ if not bool(backend_dict.get("enabled", True)):+ continue+ declared_section = backend_dict.get("model_specs_section")+ section = resolve_model_specs_section(+ backend_name=backend_name,+ declared_section=declared_section if isinstance(declared_section, str) else None,+ )+ if section is not None:+ sections[backend_name] = section+ return sections++def is_pipelex_gateway_enabled(*, config_dir: Path | None = None) -> bool:"""Check if pipelex_gateway is enabled in the backends configuration.+ Narrower than `enabled_managed_gateway_sections` on purpose, and still the right question for+ the callers that ask it: the boot's telemetry decision and the test-session plugin are about+ the Portkey-cloud service specifically, not about managed backends in general.++ Two callers that read like they belong here do not. Terms acceptance asks the broad question+ because the terms are the Pipelex service's rather than one dialect's — see `_init_agreement`+ and `customize_backends_config`. And `pipelex init`'s cache priming asks it because what it+ caches is the single published configuration carrying every managed backend's section, so a+ manifold-only installation has exactly as much to prime as a gateway one.+This reads the backends document directly without loading the full backend library — thesame document the loader reads: the base ``backends.toml`` with every ``backends_override.toml``merged over it, from ``config_manager.backends_file_paths``.@@ -104,18 +183,12 @@ def is_pipelex_gateway_enabled(*, config_dir: Path | None = None) -> bool: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.+ InferenceBackendLibraryValidationError: a file in the document does not parse — see+ `_backends_document`."""- 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:+ backends_toml = _backends_document(config_dir=config_dir)+ if backends_toml is None: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/system/pipelex_service/remote_config.py b/pipelex/system/pipelex_service/remote_config.pyindex 86360c473..c266a3f1c 100644--- a/pipelex/system/pipelex_service/remote_config.py+++ b/pipelex/system/pipelex_service/remote_config.py@@ -1,3 +1,5 @@+from typing import cast+from pydantic import BaseModel, ConfigDict, Fieldfrom pipelex.cogt.model_backends.model_spec_factory import BackendModelSpecs@@ -13,8 +15,41 @@ class PipelexPosthogConfig(BaseModel):class RemoteConfig(BaseModel):+ """The single artifact the Pipelex service publishes, carrying one model-specs section per managed gateway.++ `backend_model_specs` is the legacy gateway's section and stays a declared field. Every other+ section — `manifold_model_specs` today — arrives through `extra="allow"`, which is what makes+ adding one a non-breaking change for a client that predates it: an older runtime parses the+ artifact and simply never asks for the new section.+ """+model_config = ConfigDict(extra="allow")posthog: PipelexPosthogConfig = Field(description="Posthog configuration")backend_model_specs: BackendModelSpecs = Field(description="Model specifications for Pipelex Gateway (model_name -> spec dict)")aws_region: str = Field(description="AWS region")++ def get_model_specs_section(self, section_name: str) -> BackendModelSpecs | None:+ """The named model-specs section, or ``None`` when the artifact does not carry one.++ Looked up by name rather than by field, because which section a managed backend reads is+ declared in that backend's configuration and the runtime learns it at boot. ``None`` is a+ real answer and not an error here: a backend declaring a section the published artifact does+ not carry is disabled with a named warning, the same posture as a missing variable.++ **The lookup is confined to the artifact's own content** — its declared fields and the extra+ sections it was published with — rather than being a bare ``getattr`` on the model. The name+ arrives from `model_specs_section` in the user's own `backends.toml`, and a bare ``getattr``+ would answer for pydantic's machinery too: ``model_config`` and ``model_fields`` are both+ plain dicts on a v2 model, so either would pass the shape check below and be carried+ onwards as if the service had published it. Confined this way, an unmeant name is simply a+ section the artifact does not carry, and earns the named disabling warning it should.+ """+ raw: object | None+ if section_name in type(self).model_fields:+ raw = getattr(self, section_name)+ else:+ raw = (self.__pydantic_extra__ or {}).get(section_name)+ if not isinstance(raw, dict):+ return None+ return cast("BackendModelSpecs", raw)diff --git a/pipelex/system/pipelex_service/remote_config_fetcher.py b/pipelex/system/pipelex_service/remote_config_fetcher.pyindex 3e0c9e711..e7e3b487e 100644--- a/pipelex/system/pipelex_service/remote_config_fetcher.py+++ b/pipelex/system/pipelex_service/remote_config_fetcher.py@@ -37,6 +37,7 @@ import httpxfrom pydantic import BaseModel, ConfigDict, Field, ValidationErrorfrom tenacity import RetryCallState, retry, retry_if_exception_type, stop_after_attempt, wait_exponential+from pipelex.cogt.model_backends.backend import MANIFOLD_MODEL_SPECS_SECTIONfrom pipelex.system.pipelex_service.exceptions import (RemoteConfigFetchError,RemoteConfigUnavailableError,@@ -115,6 +116,11 @@ class RemoteConfigFetcher:def make_dummy_remote_config(cls) -> RemoteConfig:"""Create a default RemoteConfig for testing in offline environments.+ **Every managed gateway's section is present and empty, not just the legacy one.** An absent+ section means "this backend's specs were not published" and earns a disabling warning; on+ this path that would be a warning about a backend nobody asked for, since the boots that+ take this branch (``pipelex-agent models``, validation, dry runs) need no specs at all.+Returns:A minimal RemoteConfig with analytics disabled and empty model specs."""@@ -127,6 +133,7 @@ class RemoteConfigFetcher:),backend_model_specs={},aws_region="us-east-1",+ **{MANIFOLD_MODEL_SPECS_SECTION: {}},)@classmethoddiff --git a/subject_grants.toml b/subject_grants.tomlindex 5df25c444..88731402e 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -348,9 +348,9 @@ rationale = "Verb-object: fixes the bundle at bundle_path; options stay keyword.param = "input_file"rationale = "Renders the input file to a graph; single operand."-["pipelex/cli/commands/init/backends.py::disable_gateway_backend"]+["pipelex/cli/commands/init/backends.py::disable_managed_gateway_backends"]param = "backends_toml_path"-rationale = "Edits the backends TOML at the path to disable the gateway; single operand."+rationale = "Edits the backends TOML at the path to disable the managed gateway backends; single operand."["pipelex/cli/commands/init/backends.py::get_selected_backend_keys"]param = "backends_toml_path"@@ -1796,6 +1796,10 @@ rationale = "Parses the response; single operand."param = "value"rationale = "Parses the value; single operand."+["pipelex/cogt/inference/error_classification.py::_pipelex_service_error_code_from_body"]+param = "body"+rationale = "Reads an error code out of one body dict, exactly as its siblings _provider_error_code_from_body and _provider_error_code_from_flat_body do; the body is the single obvious operand and all three read as one verb-object sentence."+["pipelex/cogt/inference/error_classification.py::_provider_error_code_from_body"]param = "body"rationale = "Extracts/derives from the body; single operand."@@ -1852,6 +1856,10 @@ rationale = "Extracts from the exc; single operand."param = "exc"rationale = "Extracts from the exc; single operand."+["pipelex/cogt/inference/error_classification.py::extract_manifold_metadata"]+param = "exc"+rationale = "Extracts from the exc; single operand."+["pipelex/cogt/inference/error_classification.py::extract_mistral_metadata"]param = "exc"rationale = "Extracts from the exc; single operand."@@ -2032,10 +2040,6 @@ rationale = "Keyed accessor by the key; single operand."param = "model_name"rationale = "Keyed accessor by the model_name; single operand."-["pipelex/cogt/model_backends/backend.py::PipelexBackend.is_gateway_backend"]-param = "backend_name"-rationale = "Predicate on the backend_name; single operand."-["pipelex/cogt/model_backends/backend_credentials.py::BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg"]param = "backend_credential_reports"rationale = "Factory from source: builds the result from the backend_credential_reports; single operand."@@ -2237,8 +2241,8 @@ param = "deck"rationale = "Keyed accessor by the deck; single operand."["pipelex/cogt/models/model_manager.py::ModelManager._enforce_gateway_model_membership"]-param = "gateway_config"-rationale = "Operates on the gateway_config; single operand (qualifiers keyword-only)."+param = "managed_gateway_configs"+rationale = "Operates on the managed gateway configs; single operand (qualifiers keyword-only)."["pipelex/cogt/models/model_manager.py::ModelManager._extract_choice_handle"]param = "choice"@@ -5088,6 +5092,58 @@ rationale = "Plugin protocol register: the registrar is the sole sink the pluginparam = "date_str"rationale = "Parses/consumes the date_str; single operand."+["pipelex/providers/manifold/manifold_completions_factory.py::ManifoldCompletionsFactory.make_openai_client_for_completions"]+param = "model_handle"+rationale = "Factory from source: builds the result from the model_handle; single operand."++["pipelex/providers/manifold/manifold_constants.py::ManifoldOpenAISdkVariant.is_completions"]+param = "sdk"+rationale = "Predicate on the sdk; single operand."++["pipelex/providers/manifold/manifold_constants.py::ManifoldOpenAISdkVariant.is_responses"]+param = "sdk"+rationale = "Predicate on the sdk; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory._make_gemini_image_config"]+param = "inference_model"+rationale = "Factory from source: builds the result from the inference_model; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.get_api_key"]+param = "backend"+rationale = "Derives the value from the backend config; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.get_base_url"]+param = "backend"+rationale = "Derives the value from the backend config; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.get_origin"]+param = "backend"+rationale = "Derives the value from the backend config; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.is_debug_enabled"]+param = "backend"+rationale = "Predicate: reports whether debug logging is enabled for the backend; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.make_auth_headers"]+param = "backend"+rationale = "Factory from source: builds the result from the backend; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.make_extras"]+param = "inference_model"+rationale = "Factory from source: builds the result from the inference_model; single operand."++["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory.make_portkey_client"]+param = "backend"+rationale = "Factory from source: builds the result from the backend; single operand."++["pipelex/providers/manifold/manifold_plugin.py::ManifoldPlugin.register"]+param = "registrar"+rationale = "Plugin protocol register: the registrar is the sole sink the plugin populates."++["pipelex/providers/manifold/manifold_responses_factory.py::ManifoldResponsesFactory.make_openai_client_for_responses"]+param = "model_handle"+rationale = "Factory from source: builds the result from the model_handle; single operand."+["pipelex/providers/mistral/mistral_config.py::MistralConfig.get_reasoning_level"]param = "effort"rationale = "Maps the reasoning effort to a provider reasoning level; single operand."@@ -5572,6 +5628,10 @@ rationale = "Derivation: hashes the gateway API key into a distinct id; single oparam = "config_dir"rationale = "Verb-object: loads from the config dir; single operand."+["pipelex/system/pipelex_service/remote_config.py::RemoteConfig.get_model_specs_section"]+param = "section_name"+rationale = "Keyed accessor by the section_name; single operand."+["pipelex/system/pipelex_service/remote_config_cache.py::RemoteConfigCache.store"]param = "remote_config_payload"rationale = "Verb-object: stores the payload; options stay keyword."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex 6422223fd..b4467219c 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -155,6 +155,13 @@ LinkupError | Linkup | https://docs.pipelex.com/latest/errors/linkup-error/LinkupSearchEmptyResultError | Linkup search empty result | https://docs.pipelex.com/latest/errors/linkup-search-empty-result-error/LinkupSearchResponseError | Linkup search response | https://docs.pipelex.com/latest/errors/linkup-search-response-error/ListWhereSingularError | List where singular | https://docs.pipelex.com/latest/errors/list-where-singular-error/+ManifoldCredentialsError | Manifold credentials | https://docs.pipelex.com/latest/errors/manifold-credentials-error/+ManifoldEndpointError | Manifold endpoint | https://docs.pipelex.com/latest/errors/manifold-endpoint-error/+ManifoldError | Manifold | https://docs.pipelex.com/latest/errors/manifold-error/+ManifoldExtractResponseError | Manifold extract response | https://docs.pipelex.com/latest/errors/manifold-extract-response-error/+ManifoldFactoryError | Manifold factory | https://docs.pipelex.com/latest/errors/manifold-factory-error/+ManifoldSearchEmptyResultError | Manifold search empty result | https://docs.pipelex.com/latest/errors/manifold-search-empty-result-error/+ManifoldSearchResponseError | Manifold search response | https://docs.pipelex.com/latest/errors/manifold-search-response-error/MethodDependencyFetchError | Method dependency fetch | https://docs.pipelex.com/latest/errors/method-dependency-fetch-error/MethodFetchDisabledError | Method fetch disabled | https://docs.pipelex.com/latest/errors/method-fetch-disabled-error/MethodFetchError | Method fetch | https://docs.pipelex.com/latest/errors/method-fetch-error/diff --git a/tests/integration/pipelex/cli/commands/init/test_cache_priming.py b/tests/integration/pipelex/cli/commands/init/test_cache_priming.pyindex 2f6b32eb9..868aceab0 100644--- a/tests/integration/pipelex/cli/commands/init/test_cache_priming.py+++ b/tests/integration/pipelex/cli/commands/init/test_cache_priming.py@@ -6,8 +6,8 @@ These tests pin the helper's behaviour:the raw payload to ``~/.pipelex/cache/remote_config.json`` (priming).- When offline at init time, priming logs a yellow warning and continues — the cache staysempty, the user has been told, init does not crash.-- When the gateway is disabled in ``backends.toml``, priming is a no-op (BYOK setups have- nothing to cache).+- When no managed gateway backend is enabled in ``backends.toml``, priming is a no-op (BYOK setups+ have nothing to cache). Any managed backend counts — the published configuration is one artifact.- When a cache already exists, a fresh fetch overwrites it (refresh, not skip)."""@@ -23,6 +23,7 @@ import pytestfrom rich.console import Consolefrom pipelex.cli.commands.init.command import prime_remote_config_cache+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION, MANIFOLD_MODEL_SPECS_SECTION, PipelexBackendfrom pipelex.system.configuration.config_loader import ConfigLoaderfrom pipelex.system.pipelex_service.pipelex_service_agreement import (PipelexServiceAgreement,@@ -42,6 +43,7 @@ if TYPE_CHECKING:from pytest_mock import MockerFixtureINIT_COMMAND_MODULE = "pipelex.cli.commands.init.command"+GATEWAY_ONLY_SECTIONS = {PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION}# Capture the unpatched classmethod at module import — the session conftest replaces# ``fetch_remote_config`` with a cache shim that bypasses ``httpx``. We need the real@@ -129,7 +131,7 @@ class TestCachePriming:@pytest.mark.usefixtures("isolated_cache_dir")def test_init_primes_cache_when_online(self, mocker: MockerFixture) -> None:"""Gateway enabled + terms accepted + online → cache file written under the global dir."""- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value=GATEWAY_ONLY_SECTIONS)mocker.patch(f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -153,7 +155,7 @@ class TestCachePriming:@pytest.mark.usefixtures("isolated_cache_dir")def test_init_warns_when_offline(self, mocker: MockerFixture) -> None:"""Gateway enabled + terms accepted + offline + no cache → warn, do not crash, no cache file."""- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value=GATEWAY_ONLY_SECTIONS)mocker.patch(f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -178,8 +180,8 @@ class TestCachePriming:@pytest.mark.usefixtures("isolated_cache_dir")def test_init_skips_priming_when_gateway_disabled(self, mocker: MockerFixture) -> None:- """Gateway disabled in backends → priming is a no-op (no fetch, no cache write)."""- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=False)+ """No managed gateway backend enabled → priming is a no-op (no fetch, no cache write)."""+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value={})fetch_spy = mocker.spy(RemoteConfigFetcher, "fetch_remote_config")httpx_get_mock = mocker.patch("httpx.get", side_effect=httpx.ConnectError("no network"))@@ -204,7 +206,7 @@ class TestCachePriming:cache_path = RemoteConfigCache.cache_path()stale_on_disk_before = json.loads(cache_path.read_text(encoding="utf-8"))- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value=GATEWAY_ONLY_SECTIONS)mocker.patch(f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -304,6 +306,39 @@ class TestCachePriming:assert httpx_get_mock.call_count == 0assert not RemoteConfigCache.cache_path().exists()+ @pytest.mark.usefixtures("isolated_cache_dir")+ def test_priming_runs_for_a_manifold_only_installation(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """Priming asks the boot's question — is *any* managed gateway backend enabled — not the+ Portkey-cloud one's. The published configuration is one artifact carrying every managed+ backend's section, so a manifold-only installation has exactly as much to cache as a+ gateway one, and skipping it left the first offline dry-run after init with no fallback.+ """+ target_dir = tmp_path / "target_dir"+ target_backends = target_dir / "inference" / "backends.toml"+ target_backends.parent.mkdir(parents=True, exist_ok=True)+ target_backends.write_text(+ f"[{PipelexBackend.GATEWAY}]\nenabled = false\n\n"+ f"[{PipelexBackend.MANIFOLD}]\nenabled = true\nmodel_specs_section = {MANIFOLD_MODEL_SPECS_SECTION!r}\n",+ encoding="utf-8",+ )++ mocker.patch(+ f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",+ return_value=_accepted_service_config(),+ )+ mocker.patch(+ "pipelex.system.runtime.RuntimeManager.is_in_codex_cloud",+ new_callable=mocker.PropertyMock,+ return_value=False,+ )+ mocker.patch.object(RemoteConfigFetcher, "fetch_remote_config", _ORIGINAL_FETCH_REMOTE_CONFIG)+ mocker.patch("httpx.get", return_value=_make_httpx_response(_fake_remote_payload()))++ console = mocker.create_autospec(Console, instance=True)+ prime_remote_config_cache(console=console, target_config_dir=target_dir)++ assert RemoteConfigCache.cache_path().exists(), "a manifold-only installation is behind the same published configuration — priming must run"+@pytest.mark.usefixtures("isolated_cache_dir")def test_init_warns_when_cache_write_fails(self, mocker: MockerFixture) -> None:"""Online fetch succeeds but the cache write fails → priming reports failure, not success.@@ -313,7 +348,7 @@ class TestCachePriming:while no usable cache exists, so ``pipelex-agent init`` would emit ``cache_primed: true``and a later offline run would hit ``RemoteConfigUnavailableError``."""- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value=GATEWAY_ONLY_SECTIONS)mocker.patch(f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -345,7 +380,7 @@ class TestCachePriming:``RemoteConfig``, otherwise ``pipelex-agent init`` would emit ``cache_primed: true`` whilea later offline run hits ``RemoteConfigUnavailableError``."""- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value=GATEWAY_ONLY_SECTIONS)mocker.patch(f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -376,7 +411,7 @@ class TestCachePriming:stale_on_disk = json.loads(cache_path.read_text(encoding="utf-8"))assert stale_on_disk["raw_config"]["aws_region"] == "eu-west-1"- mocker.patch(f"{INIT_COMMAND_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(f"{INIT_COMMAND_MODULE}.enabled_managed_gateway_sections", return_value=GATEWAY_ONLY_SECTIONS)mocker.patch(f"{INIT_COMMAND_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),diff --git a/tests/integration/pipelex/cli/test_init_cmd_backend_customization.py b/tests/integration/pipelex/cli/test_init_cmd_backend_customization.pyindex ba47ead6c..cb5c7adb9 100644--- a/tests/integration/pipelex/cli/test_init_cmd_backend_customization.py+++ b/tests/integration/pipelex/cli/test_init_cmd_backend_customization.py@@ -289,3 +289,75 @@ class TestBackendCustomization:# The gateway must be disabled since its terms could not be recorded.toml_doc = load_toml_with_tomlkit(str(test_backends))assert toml_doc[PipelexBackend.GATEWAY]["enabled"] is False # type: ignore[index]+++class TestTermsAreAskedForAnyManagedGateway:+ """The terms are the Pipelex service's terms, not one dialect's.++ The boot gate asks the broad question — any enabled managed gateway backend puts the install+ behind service-terms acceptance (`runtime_boot`). These prompts have to ask the same question,+ or selecting the manifold service alone produces a configuration that init calls complete and+ the next inference boot refuses, with no init step that records acceptance.+ """++ @staticmethod+ def _prepare(tmp_path: Path, mocker: MockerFixture) -> Path:+ inference_dir = tmp_path / ".pipelex" / "inference"+ inference_dir.mkdir(parents=True)+ test_backends = inference_dir / "backends.toml"+ shutil.copy2(Path(str(get_kit_configs_dir())) / "inference" / "backends.toml", test_backends)++ mock_config_manager = mocker.MagicMock()+ mock_config_manager.pipelex_config_dir = tmp_path / ".pipelex"+ mock_config_manager.global_config_dir = tmp_path / ".pipelex"+ mocker.patch("pipelex.cli.commands.init.backends.config_manager", mock_config_manager)+ mocker.patch("pipelex.cli.commands.init.backends.get_console", return_value=mocker.MagicMock())+ return test_backends++ @staticmethod+ def _answer(mocker: MockerFixture, *, selection: str, accepts_terms: bool) -> None:+ prompt_inputs = [selection]+ confirm_inputs = [accepts_terms]++ def prompt_side_effect(*args: Any, **_kwargs: Any) -> str:+ if not prompt_inputs:+ question = str(args[0]) if args else "<unknown prompt>"+ msg = f"Unexpected prompt without predefined input: {question}"+ raise AssertionError(msg)+ return prompt_inputs.pop(0)++ def confirm_side_effect(*args: Any, **_kwargs: Any) -> bool:+ if not confirm_inputs:+ question = str(args[0]) if args else "<unknown confirmation>"+ msg = f"Unexpected confirm without predefined input: {question}"+ raise AssertionError(msg)+ return confirm_inputs.pop(0)++ mocker.patch("rich.prompt.Prompt.ask", side_effect=prompt_side_effect)+ mocker.patch("rich.prompt.Confirm.ask", side_effect=confirm_side_effect)++ def test_selecting_only_the_manifold_service_records_terms_acceptance(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """Accepting must persist, exactly as it does for the Portkey-cloud service."""+ test_backends = self._prepare(tmp_path, mocker)+ recorded = mocker.patch("pipelex.cli.commands.init.backends.update_service_terms_acceptance")+ manifold_index = get_backend_indices_helper(str(test_backends), [PipelexBackend.MANIFOLD])[0]+ self._answer(mocker, selection=str(manifold_index), accepts_terms=True)++ customize_backends_config()++ recorded.assert_called_once()+ assert recorded.call_args.kwargs["accepted"] is True+ toml_doc = load_toml_with_tomlkit(str(test_backends))+ assert toml_doc[PipelexBackend.MANIFOLD]["enabled"] is True # type: ignore[index]++ def test_declining_removes_the_manifold_service_from_the_selection(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The same guarantee the gateway decline path gives: refused terms leave nothing enabled."""+ test_backends = self._prepare(tmp_path, mocker)+ mocker.patch("pipelex.cli.commands.init.backends.update_service_terms_acceptance")+ manifold_index = get_backend_indices_helper(str(test_backends), [PipelexBackend.MANIFOLD])[0]+ self._answer(mocker, selection=str(manifold_index), accepts_terms=False)++ customize_backends_config()++ toml_doc = load_toml_with_tomlkit(str(test_backends))+ assert toml_doc[PipelexBackend.MANIFOLD]["enabled"] is False # type: ignore[index]diff --git a/tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py b/tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.pyindex ac05ab834..190b1af2c 100644--- a/tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py+++ b/tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py@@ -16,6 +16,7 @@ import pytestfrom pipelex import logfrom pipelex.cogt.exceptions import GatewayUnknownModelError+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION, PipelexBackendfrom pipelex.pipelex import Pipelexfrom pipelex.system.pipelex_service.remote_config import PipelexPosthogConfig, RemoteConfigfrom pipelex.system.pipelex_service.remote_config_fetcher import (@@ -80,7 +81,10 @@ class TestGatewayUnknownModel:``GatewayUnknownModelError(source=FRESH)`` with the missing model name surfaced."""Pipelex.teardown_if_needed()- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch("pipelex.system.runtime.RuntimeManager.is_in_codex_cloud",new_callable=mocker.PropertyMock,@@ -102,6 +106,7 @@ class TestGatewayUnknownModel:assert exc_info.value.source == RemoteConfigSource.FRESHassert exc_info.value.model_name, "the error must carry the missing model name"assert exc_info.value.model_name in str(exc_info.value), "the error message must surface the missing model name"+ assert exc_info.value.backend_name == PipelexBackend.GATEWAY, "with more than one managed gateway, the error has to say which"finally:Pipelex.teardown_if_needed()log.reset()@@ -115,7 +120,10 @@ class TestGatewayUnknownModel:fetching specs."""Pipelex.teardown_if_needed()- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch("pipelex.system.runtime.RuntimeManager.is_in_codex_cloud",new_callable=mocker.PropertyMock,@@ -141,7 +149,10 @@ class TestGatewayUnknownModel:message must point at ``pipelex init`` (while online) to refresh the cache."""Pipelex.teardown_if_needed()- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch("pipelex.system.runtime.RuntimeManager.is_in_codex_cloud",new_callable=mocker.PropertyMock,diff --git a/tests/integration/pipelex/system/pipelex_service/test_offline_baseline.py b/tests/integration/pipelex/system/pipelex_service/test_offline_baseline.pyindex 1ef97b27e..35551443e 100644--- a/tests/integration/pipelex/system/pipelex_service/test_offline_baseline.py+++ b/tests/integration/pipelex/system/pipelex_service/test_offline_baseline.py@@ -16,6 +16,7 @@ import httpximport pytestfrom pipelex import log+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION, PipelexBackendfrom pipelex.pipelex import Pipelexfrom pipelex.system.configuration.config_loader import ConfigLoaderfrom pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError@@ -60,7 +61,7 @@ class TestOfflineBaseline:"""Pipelex.teardown_if_needed()- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=False)+ mocker.patch(f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections", return_value={})mocker.patch("pipelex.system.runtime.RuntimeManager.is_in_codex_cloud",new_callable=mocker.PropertyMock,@@ -108,7 +109,10 @@ class TestOfflineBaseline:agreement=PipelexServiceAgreement(terms_accepted=True),onboarding=PipelexServiceOnboarding(inference_setup_completed=True),)- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch(f"{RUNTIME_BOOT_MODULE}.load_pipelex_service_config_if_exists",return_value=service_config,diff --git a/tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py b/tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.pyindex ef900f5ac..fe6726da3 100644--- a/tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py+++ b/tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py@@ -24,6 +24,7 @@ import httpximport pytestfrom pipelex import log+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION, PipelexBackendfrom pipelex.pipelex import Pipelexfrom pipelex.system.configuration.config_loader import ConfigLoaderfrom pipelex.system.pipelex_service.exceptions import (@@ -104,7 +105,10 @@ class TestSetupWithCache:session_result = RemoteConfigFetcher.fetch_remote_config() # patched to session cacheRemoteConfigCache.store(session_result.config.model_dump(mode="json"))- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch(f"{RUNTIME_BOOT_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -145,7 +149,10 @@ class TestSetupWithCache:"""Pipelex.teardown_if_needed()- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch(f"{RUNTIME_BOOT_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -187,7 +194,10 @@ class TestSetupWithCache:cached_at=datetime.now(tz=UTC),)- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch(f"{RUNTIME_BOOT_MODULE}.load_pipelex_service_config_if_exists",return_value=_accepted_service_config(),@@ -218,7 +228,7 @@ class TestSetupWithCache:"""Pipelex.teardown_if_needed()- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=False)+ mocker.patch(f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections", return_value={})mocker.patch("pipelex.system.runtime.RuntimeManager.is_in_codex_cloud",new_callable=mocker.PropertyMock,diff --git a/tests/unit/pipelex/cli/agent_cli/test_agent_init_managed_gateway_terms.py b/tests/unit/pipelex/cli/agent_cli/test_agent_init_managed_gateway_terms.pynew file mode 100644index 000000000..ca7c21a7a--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_agent_init_managed_gateway_terms.py@@ -0,0 +1,52 @@+"""`pipelex-agent init` records service-terms acceptance for any managed gateway backend.++The agent flow takes `accept_gateway_terms` as an explicit instruction. Asked the gateway-only way,+that instruction was silently dropped for a request naming only the manifold service — and since+the same flow marks inference setup complete unconditionally, the next inference boot refused with+`GatewayTermsNotAcceptedError` on a configuration the agent had been told was finished.+"""++from __future__ import annotations++import shutil+from pathlib import Path+from typing import TYPE_CHECKING, Any++from pipelex.cli.agent_cli.commands.init_cmd import _configure_backends # pyright: ignore[reportPrivateUsage]+from pipelex.cogt.model_backends.backend import PipelexBackend+from pipelex.kit.paths import get_kit_configs_dir++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++def _backends_files(tmp_path: Path) -> tuple[Path, Path]:+ """The user's backends.toml (a copy of the kit template) and the template itself."""+ template = Path(str(get_kit_configs_dir())) / "inference" / "backends.toml"+ user_file = tmp_path / "backends.toml"+ shutil.copy2(template, user_file)+ return user_file, template+++class TestAgentInitTermsForAnyManagedGateway:+ def test_a_manifold_only_request_persists_the_acceptance_it_was_given(self, tmp_path: Path, mocker: MockerFixture) -> None:+ user_file, template = _backends_files(tmp_path)+ mocker.patch("pipelex.cli.agent_cli.commands.init_cmd.config_manager", mocker.MagicMock(global_config_dir=tmp_path))+ recorded = mocker.patch("pipelex.cli.agent_cli.commands.init_cmd.update_service_terms_acceptance")++ config: dict[str, Any] = {"backends": [PipelexBackend.MANIFOLD], "accept_gateway_terms": True}+ _configure_backends(config=config, backends_toml_path=user_file, template_backends_path=template)++ recorded.assert_called_once()+ assert recorded.call_args.kwargs["accepted"] is True++ def test_a_byok_only_request_records_nothing(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The guard: no managed backend means no terms question, whatever the config carries."""+ user_file, template = _backends_files(tmp_path)+ mocker.patch("pipelex.cli.agent_cli.commands.init_cmd.config_manager", mocker.MagicMock(global_config_dir=tmp_path))+ recorded = mocker.patch("pipelex.cli.agent_cli.commands.init_cmd.update_service_terms_acceptance")++ config: dict[str, Any] = {"backends": ["anthropic"], "accept_gateway_terms": True}+ _configure_backends(config=config, backends_toml_path=user_file, template_backends_path=template)++ recorded.assert_not_called()diff --git a/tests/unit/pipelex/cli/commands/test_init_agreement_any_managed_gateway.py b/tests/unit/pipelex/cli/commands/test_init_agreement_any_managed_gateway.pynew file mode 100644index 000000000..a1f183e58--- /dev/null+++ b/tests/unit/pipelex/cli/commands/test_init_agreement_any_managed_gateway.py@@ -0,0 +1,45 @@+"""`pipelex init agreement` is the recovery path, and it has to cover every managed gateway.++The boot puts an installation behind service-terms acceptance as soon as *any* managed gateway+backend is enabled. This command is the human CLI's only way to record that acceptance after the+fact, so a question narrower than the boot's leaves a manifold-only installation with no supported+step that unblocks it — the command reports there is nothing to accept while the boot refuses to+start for want of exactly that.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from pipelex.cli.commands.init.command import _init_agreement # pyright: ignore[reportPrivateUsage]+from pipelex.cogt.model_backends.backend import PipelexBackend++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++MANIFOLD_ONLY_SECTIONS = {PipelexBackend.MANIFOLD: "manifold_model_specs"}+++class TestInitAgreementCoversEveryManagedGateway:+ def test_a_manifold_only_installation_is_prompted_rather_than_told_nothing_is_needed(self, mocker: MockerFixture) -> None:+ """The dead end this closes: the terms panel must appear, and acceptance must persist."""+ mocker.patch("pipelex.cli.commands.init.command.enabled_managed_gateway_sections", return_value=MANIFOLD_ONLY_SECTIONS)+ mocker.patch("pipelex.cli.commands.init.command.load_pipelex_service_config_if_exists", return_value=None)+ mocker.patch("rich.prompt.Confirm.ask", return_value=True)+ recorded = mocker.patch("pipelex.cli.commands.init.command.update_service_terms_acceptance")++ _init_agreement(console=mocker.MagicMock())++ recorded.assert_called_once()+ assert recorded.call_args.kwargs["accepted"] is True++ def test_no_managed_gateway_at_all_still_reports_nothing_to_accept(self, mocker: MockerFixture) -> None:+ """The guard: a BYOK-only installation must keep its early exit, and prompt for nothing."""+ mocker.patch("pipelex.cli.commands.init.command.enabled_managed_gateway_sections", return_value={})+ recorded = mocker.patch("pipelex.cli.commands.init.command.update_service_terms_acceptance")+ asked = mocker.patch("rich.prompt.Confirm.ask")++ _init_agreement(console=mocker.MagicMock())++ recorded.assert_not_called()+ asked.assert_not_called()diff --git a/tests/unit/pipelex/cli/dev/test_preprocess_test_models_cmd.py b/tests/unit/pipelex/cli/dev/test_preprocess_test_models_cmd.pyindex 435f984b1..d2f9fcefd 100644--- a/tests/unit/pipelex/cli/dev/test_preprocess_test_models_cmd.py+++ b/tests/unit/pipelex/cli/dev/test_preprocess_test_models_cmd.py@@ -3,8 +3,9 @@import pytestfrom pytest_mock import MockerFixture+from pipelex.cli.dev_cli.commands import preprocess_test_models_cmdfrom pipelex.cli.dev_cli.commands.preprocess_test_models_cmd import (- _fetch_gateway_models, # pyright: ignore[reportPrivateUsage]+ _fetch_managed_gateway_models, # pyright: ignore[reportPrivateUsage])from pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError, RemoteConfigValidationErrorfrom pipelex.system.pipelex_service.remote_config_fetcher import RemoteConfigFetcher@@ -14,18 +15,61 @@ class TestPreprocessTestModelsCmd:@pytest.mark.parametrize("gateway_error",[- RemoteConfigUnavailableError("gateway offline"),- RemoteConfigValidationError("gateway schema break"),+ RemoteConfigUnavailableError("service offline"),+ RemoteConfigValidationError("service schema break"),],)- def test_fetch_gateway_models_propagates_fresh_refusal(self, mocker: MockerFixture, gateway_error: Exception) -> None:- """``require_fresh=True`` must refuse to proceed when the Gateway config is unavailable+ def test_fetch_managed_gateway_models_propagates_fresh_refusal(self, mocker: MockerFixture, gateway_error: Exception) -> None:+ """``require_fresh=True`` must refuse to proceed when the remote config is unavailableor stale. The error propagates instead of being swallowed into empty model lists, so- offline fixture generation cannot silently drop every ``pipelex_gateway`` model.+ offline fixture generation cannot silently drop every managed gateway model."""+ mocker.patch.object(+ preprocess_test_models_cmd,+ "enabled_managed_gateway_sections",+ return_value={"pipelex_gateway": "backend_model_specs"},+ )mocker.patch.object(RemoteConfigFetcher, "fetch_remote_config", side_effect=gateway_error)with pytest.raises((RemoteConfigUnavailableError, RemoteConfigValidationError)) as exc_info:- _fetch_gateway_models()+ _fetch_managed_gateway_models()assert exc_info.value is gateway_error, "the fresh-config refusal must propagate verbatim, not be converted into empty model lists"++ def test_fetch_managed_gateway_models_skips_the_fetch_when_none_is_enabled(self, mocker: MockerFixture) -> None:+ """No managed gateway backend means no reason to reach the network at all."""+ mocker.patch.object(preprocess_test_models_cmd, "enabled_managed_gateway_sections", return_value={})+ fetch = mocker.patch.object(RemoteConfigFetcher, "fetch_remote_config")++ assert _fetch_managed_gateway_models() == {}+ fetch.assert_not_called()++ def test_fetch_managed_gateway_models_reads_each_backend_its_own_section(self, mocker: MockerFixture) -> None:+ """The point of the generalization: two managed backends, two sections, no hardcoded name.++ A backend whose declared section the artifact does not carry contributes nothing rather+ than failing the run — the same posture the runtime takes.+ """+ mocker.patch.object(+ preprocess_test_models_cmd,+ "enabled_managed_gateway_sections",+ return_value={+ "pipelex_gateway": "backend_model_specs",+ "pipelex_manifold": "manifold_model_specs",+ "absent_gateway": "no_such_section",+ },+ )+ sections = {+ "backend_model_specs": {"defaults": {"model_type": "llm"}, "on-the-cloud": {}},+ "manifold_model_specs": {"defaults": {"model_type": "llm"}, "in-our-vpc": {"model_type": "search"}},+ }+ config = mocker.Mock()+ config.get_model_specs_section.side_effect = sections.get+ mocker.patch.object(RemoteConfigFetcher, "fetch_remote_config", return_value=mocker.Mock(config=config))++ result = _fetch_managed_gateway_models()++ assert set(result) == {"pipelex_gateway", "pipelex_manifold"}+ assert result["pipelex_gateway"]["llm"] == ["on-the-cloud"]+ assert result["pipelex_manifold"]["llm"] == []+ assert result["pipelex_manifold"]["search"] == ["in-our-vpc"]diff --git a/tests/unit/pipelex/cli/test_doctor_check_models.py b/tests/unit/pipelex/cli/test_doctor_check_models.pyindex 0d89a7c45..0ded8946f 100644--- a/tests/unit/pipelex/cli/test_doctor_check_models.py+++ b/tests/unit/pipelex/cli/test_doctor_check_models.py@@ -19,7 +19,9 @@ from pipelex.cogt.exceptions import (ModelDeckValidationError,RoutingProfileLibraryError,)+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION, PipelexBackendfrom pipelex.system.pipelex_service.exceptions import RemoteConfigUnavailableError+from pipelex.system.pipelex_service.remote_config import PipelexPosthogConfig, RemoteConfigfrom pipelex.system.pipelex_service.types import RemoteConfigSourceif TYPE_CHECKING:@@ -38,7 +40,7 @@ class TestCheckModels:@pytest.fixturedef gateway_disabled(self, mocker: MockerFixture) -> None:- mocker.patch("pipelex.cli.commands.doctor_cmd.is_pipelex_gateway_enabled", return_value=False)+ mocker.patch("pipelex.cli.commands.doctor_cmd.enabled_managed_gateway_sections", return_value={})@pytest.fixturedef models_manager(self, mocker: MockerFixture) -> Any:@@ -76,13 +78,16 @@ class TestCheckModels:assert message == "Models are valid"assert reports == {}models_manager.setup.assert_called_once()- assert models_manager.setup.call_args.kwargs["gateway_config"] is None+ assert models_manager.setup.call_args.kwargs["managed_gateway_configs"] is Nonemodels_manager.validate_model_deck.assert_called_once()@pytest.mark.usefixtures("healthy_backend_files")def test_gateway_enabled_missing_service_config(self, mocker: MockerFixture) -> None:"""Gateway enabled without a service config is unhealthy."""- mocker.patch("pipelex.cli.commands.doctor_cmd.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ "pipelex.cli.commands.doctor_cmd.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch("pipelex.cli.commands.doctor_cmd.load_pipelex_service_config_if_exists", return_value=None)healthy, message, _ = check_models()@@ -93,7 +98,10 @@ class TestCheckModels:@pytest.mark.usefixtures("healthy_backend_files")def test_gateway_enabled_terms_not_accepted(self, mocker: MockerFixture) -> None:"""Gateway enabled with unaccepted terms is unhealthy."""- mocker.patch("pipelex.cli.commands.doctor_cmd.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ "pipelex.cli.commands.doctor_cmd.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )service_config = SimpleNamespace(agreement=SimpleNamespace(terms_accepted=False))mocker.patch("pipelex.cli.commands.doctor_cmd.load_pipelex_service_config_if_exists", return_value=service_config)@@ -105,7 +113,10 @@ class TestCheckModels:@pytest.mark.usefixtures("healthy_backend_files")def test_gateway_enabled_remote_fetch_failure(self, mocker: MockerFixture) -> None:"""A failed remote-config fetch is unhealthy with the fetch error in the message."""- mocker.patch("pipelex.cli.commands.doctor_cmd.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ "pipelex.cli.commands.doctor_cmd.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )service_config = SimpleNamespace(agreement=SimpleNamespace(terms_accepted=True))mocker.patch("pipelex.cli.commands.doctor_cmd.load_pipelex_service_config_if_exists", return_value=service_config)mocker.patch(@@ -120,12 +131,19 @@ class TestCheckModels:@pytest.mark.usefixtures("healthy_backend_files")def test_gateway_enabled_passes_gateway_config_to_setup(self, mocker: MockerFixture, models_manager: Any) -> None:- """A successful fetch builds a GatewayConfig and threads it into the model setup."""- mocker.patch("pipelex.cli.commands.doctor_cmd.is_pipelex_gateway_enabled", return_value=True)+ """A successful fetch builds one GatewayConfig per managed backend and threads them into the model setup."""+ mocker.patch(+ "pipelex.cli.commands.doctor_cmd.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )service_config = SimpleNamespace(agreement=SimpleNamespace(terms_accepted=True))mocker.patch("pipelex.cli.commands.doctor_cmd.load_pipelex_service_config_if_exists", return_value=service_config)fetch_result = SimpleNamespace(- config=SimpleNamespace(backend_model_specs={}, aws_region="eu-west-3"),+ config=RemoteConfig(+ posthog=PipelexPosthogConfig(project_api_key="", endpoint="", is_geoip_enabled=False, is_debug_enabled=False),+ backend_model_specs={},+ aws_region="eu-west-3",+ ),source=RemoteConfigSource.FRESH,)mocker.patch("pipelex.cli.commands.doctor_cmd.RemoteConfigFetcher.fetch_remote_config", return_value=fetch_result)@@ -135,8 +153,9 @@ class TestCheckModels:assert healthy is Trueassert message == "Models are valid"setup_kwargs = models_manager.setup.call_args.kwargs- assert setup_kwargs["gateway_config"] is not None- assert setup_kwargs["gateway_config"].aws_region == "eu-west-3"+ managed_gateway_configs = setup_kwargs["managed_gateway_configs"]+ assert managed_gateway_configs is not None+ assert managed_gateway_configs[PipelexBackend.GATEWAY].aws_region == "eu-west-3"assert setup_kwargs["gateway_config_source"] == RemoteConfigSource.FRESH@pytest.mark.usefixtures("healthy_backend_files", "gateway_disabled")@@ -221,9 +240,9 @@ class TestCheckModels:@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."""+ """The managed-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",+ "pipelex.cli.commands.doctor_cmd.enabled_managed_gateway_sections",side_effect=InferenceBackendLibraryValidationError("Invalid inference backend library 'x' with overrides 'y': TOML parsing error"),)diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.pyindex e3d0028e7..0f467c3b0 100644--- a/tests/unit/pipelex/cli/test_error_handlers_more.py+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py@@ -337,7 +337,7 @@ class TestErrorHandlersExtended:expected_phrase: str,) -> None:"""The unknown-model handler branches its remediation on config provenance."""- exc = GatewayUnknownModelError(model_name="mystery-model", source=config_source)+ exc = GatewayUnknownModelError(model_name="mystery-model", backend_name="pipelex_manifold", source=config_source)with pytest.raises(typer.Exit) as exc_info:handle_gateway_unknown_model_error(exc)@@ -346,6 +346,7 @@ class TestErrorHandlersExtended:output = console.export_text()assert "Unknown gateway model handle" in outputassert "'mystery-model'" in output+ assert "pipelex_manifold" in output, "the remediation must name the backend that could not serve the handle"assert expected_phrase in outputdef test_handlers_escape_rich_markup_in_messages(self, console: Console) -> None:diff --git a/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.py b/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.pyindex 973f2c6d8..6057bf287 100644--- a/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.py+++ b/tests/unit/pipelex/cli/test_init_gateway_terms_overrides.py@@ -1,9 +1,14 @@-"""`pipelex init` decides "gateway enabled" on the merged backends document, and says so when a write to the base cannot take.+"""`pipelex init` decides "managed 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.+merged over it. Two consequences are pinned here: the terms prompt fires for a managed gateway backend+enabled only by an override, and declining the terms — which disables every managed backend in the base —+warns when an override still pins one on, naming the files, instead of leaving the next boot to refuse for+terms the user just declined.++The question asked is the broad one, over every Pipelex-managed gateway backend rather than+`pipelex_gateway` by name, because the terms are the Pipelex service's: a manifold pinned back on by an+override puts the installation behind them exactly as the legacy gateway does."""from __future__ import annotations@@ -14,14 +19,17 @@ from typing import TYPE_CHECKINGfrom rich.console import Console-from pipelex.cli.commands.init.backends import warn_if_gateway_pinned_by_override+from pipelex.cli.commands.init.backends import warn_if_managed_gateway_pinned_by_overridefrom pipelex.cli.commands.init.command import _check_gateway_terms_if_needed # pyright: ignore[reportPrivateUsage]+from pipelex.cogt.model_backends.backend import MANIFOLD_MODEL_SPECS_SECTIONif TYPE_CHECKING:from pytest_mock import MockerFixtureBASE_GATEWAY_OFF = "[pipelex_gateway]\nenabled = false\n"OVERRIDE_GATEWAY_ON = "[pipelex_gateway]\nenabled = true\n"+BASE_MANIFOLD_OFF = f'[pipelex_manifold]\nenabled = false\nmodel_specs_section = "{MANIFOLD_MODEL_SPECS_SECTION}"\n'+OVERRIDE_MANIFOLD_ON = "[pipelex_manifold]\nenabled = true\n"def _write_backends(config_dir: Path, *, base: str, override: str | None) -> Path:@@ -39,21 +47,30 @@ def _capturing_console() -> tuple[Console, io.StringIO]:return Console(file=buffer, force_terminal=False, width=200), buffer-class TestWarnIfGatewayPinnedByOverride:+class TestWarnIfManagedGatewayPinnedByOverride: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 warn_if_managed_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path) is Falseassert 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 warn_if_managed_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path) is Trueassert "backends_override.toml" in buffer.getvalue()assert "still enabled" in buffer.getvalue()+ assert "pipelex_gateway" in buffer.getvalue()++ def test_it_asks_the_broad_question_so_a_manifold_pinned_on_is_named_too(self, tmp_path: Path) -> None:+ """The terms are the service's, not one dialect's — a manifold override puts the install behind them."""+ backends_toml_path = _write_backends(tmp_path, base=BASE_MANIFOLD_OFF, override=OVERRIDE_MANIFOLD_ON)+ console, buffer = _capturing_console()++ assert warn_if_managed_gateway_pinned_by_override(console=console, backends_toml_path=backends_toml_path) is True+ assert "pipelex_manifold" in buffer.getvalue()class TestCheckGatewayTermsIfNeeded:diff --git a/tests/unit/pipelex/cogt/inference/test_gateway_request_limits.py b/tests/unit/pipelex/cogt/inference/test_gateway_request_limits.pynew file mode 100644index 000000000..db1c6008f--- /dev/null+++ b/tests/unit/pipelex/cogt/inference/test_gateway_request_limits.py@@ -0,0 +1,439 @@+"""The gateway's request-shape refusals, from the wire code to the rendered advice.++The Pipelex inference gateway bounds what a request may weigh and how deeply it may+nest, and refuses anything over those bounds with codes of its own: ``pig-07`` (the+body is over its byte cap, at 413), ``pig-08`` (the body's size cannot be read — a+chunked body, or an unreadable ``Content-Length`` — at 411), ``pig-10`` (a+``pipelex-storage://`` object over its cap, at 413) and ``pig-11`` (the body nests+deeper than the gateway's depth limit, at 400).++Without a class for them the Classify step falls through to the generic status+ladder, and a caller who sent something too large reads "the provider rejected the+request" rather than "the request was too large". These tests pin the whole chain:+the code is recognized, it survives every Extract hop that can carry it, it+classifies as a caller/limit error that is never retried, and the Render step says+which limit was hit.++**The code is the discriminator, not the provider.** A request reaches the gateway+through several SDKs — the Portkey substrate, plain ``httpx`` on the native routes,+and the shared Anthropic driver that Claude travels on — so the refusal arrives+under three different ``ProviderName`` values. ``pig-`` and ``pipelex_`` are both+the gateway's own code namespaces, which is why recognition keys on the code alone.++**And one failure can wear two codes.** The gateway renders a refusal in the+vocabulary of the route it arrived on, so "this file is over its cap" is ``pig-10``+on the LLM routes and ``pipelex_storage_object_too_large`` (or, for a document+fetched by URL, ``pipelex_document_too_large``) on the native ``/v1/pipelex/*``+ones. A caller cannot tell which route their extract took, so both renderings have+to classify alike.+"""++from __future__ import annotations++import json+from typing import Any++import anthropic+import httpx+import pytest+from openai import OpenAI+from portkey_ai import Portkey++from pipelex.cogt.exceptions import InferenceErrorCategory+from pipelex.cogt.inference.error_classification import (+ GatewayRequestLimit,+ ProviderErrorMetadata,+ UserActionKind,+ extract_anthropic_metadata,+ extract_gateway_metadata,+ extract_manifold_metadata,+ extract_openai_metadata,+)+from pipelex.cogt.inference.error_classify import classify_inference_error+from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error+from pipelex.cogt.inference.provider_name import ProviderName++_ORIGIN = "https://manifold.example.com"+++def _refusal_body(message: str, code: str) -> dict[str, Any]:+ """The body the gateway's ``generateApiErrorResponse`` renders, verbatim in shape.++ ``{status, message, error: {message, code}}`` — the code lives only under+ ``error.code``, and there is no ``error.type`` beside it.+ """+ beautified = f"Portkey Error: {message}. Error Code: {code}"+ return {"status": "failure", "message": beautified, "error": {"message": beautified, "code": code}}+++_BODY_TOO_LARGE_BODY = _refusal_body(+ "This request's body is 17825792 bytes, over this gateway's limit of 16777216 bytes for a body of media type application/json",+ "pig-07",+)+_LENGTH_REQUIRED_BODY = _refusal_body(+ "This gateway requires a declared Content-Length on a POST carrying a body; it does not accept a chunked body",+ "pig-08",+)+_OBJECT_TOO_LARGE_BODY = _refusal_body("The storage object is over this gateway's per-object limit", "pig-10")+_BODY_TOO_DEEP_BODY = _refusal_body("The request body nests deeper than this gateway's limit of 128 levels", "pig-11")+++def _as_the_portkey_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:+ """Build the exception through Portkey's own factory rather than by hand.++ The constructor accepts any ``body`` you give it; the SDK's factory does not —+ it sets ``body`` to ``json.loads(text)["error"]["message"]``, a string. Only the+ factory reproduces what the Extract step actually receives in production.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(body).encode(),+ headers={"content-type": "application/json"},+ )+ client = Portkey(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ return client._make_status_error_from_response(request=request, response=response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _as_the_openai_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:+ """Build the exception through the OpenAI SDK's own factory, for the same reason as above.++ This is the hop a gateway or manifold *chat* call actually takes: both plugins+ build an ``OpenAICompletionsLLMWorker`` / ``OpenAIResponsesLLMWorker`` over a+ client pointed at the service, so an LLM-route refusal is distilled by+ ``extract_openai_metadata`` and never by ``extract_gateway_metadata``.++ That hop reads ``exc.type`` before ``exc.code`` — the opposite precedence to+ the two Pipelex-service hops — and it stays that way because it is the vendor's+ hop too. It recovers the code regardless, because the gateway's fail-closed+ envelope carries a ``code`` and no ``type`` at all; pinning it here is what+ turns that into a checked property instead of a standing assumption.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(body).encode(),+ headers={"content-type": "application/json"},+ )+ client = OpenAI(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ return client._make_status_error_from_response(response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _envelope(code: str | None, *, status_code: int, provider: ProviderName = ProviderName.GATEWAY) -> ProviderErrorMetadata:+ return ProviderErrorMetadata(+ provider=provider,+ sdk_exception_type="BadRequestError",+ message="Portkey Error: refused",+ status_code=status_code,+ provider_error_code=code,+ )+++class TestTheCodeIsRecognized:+ """``gateway_request_limit`` reads the gateway's own code namespace off the envelope."""++ @pytest.mark.parametrize(+ ("code", "expected"),+ [+ ("pig-07", GatewayRequestLimit.BODY_TOO_LARGE),+ ("pig-08", GatewayRequestLimit.BODY_LENGTH_REQUIRED),+ ("pig-10", GatewayRequestLimit.OBJECT_TOO_LARGE),+ ("pig-11", GatewayRequestLimit.BODY_TOO_DEEP),+ ],+ )+ def test_each_limit_code_maps_to_its_kind(self, code: str, expected: GatewayRequestLimit) -> None:+ assert _envelope(code, status_code=413).gateway_request_limit == expected++ @pytest.mark.parametrize("code", [None, "pig-01", "pig-09", "invalid_request_error", "PIG-07", ""])+ def test_any_other_code_is_not_a_request_limit(self, code: str | None) -> None:+ """The gateway's routing and storage-resolution refusals are a different family, and so is a vendor's code."""+ assert _envelope(code, status_code=400).gateway_request_limit is None++ @pytest.mark.parametrize("provider", list(ProviderName))+ def test_the_code_is_read_whichever_provider_reported_it(self, provider: ProviderName) -> None:+ """Claude reaches the gateway on the Anthropic driver, so the refusal is not always reported as GATEWAY."""+ assert _envelope("pig-07", status_code=413, provider=provider).gateway_request_limit == GatewayRequestLimit.BODY_TOO_LARGE+++class TestTheCodeSurvivesEveryExtractHop:+ """The refusal body the gateway actually emits, through each SDK that can carry it."""++ def test_through_the_portkey_substrate(self) -> None:+ exc = _as_the_portkey_sdk_raises_it(status_code=413, body=_BODY_TOO_LARGE_BODY)++ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code == "pig-07"+ assert metadata.gateway_request_limit == GatewayRequestLimit.BODY_TOO_LARGE++ def test_the_portkey_substrate_discards_the_payload_and_the_code_survives_anyway(self) -> None:+ """The reason the hop above is built through the SDK rather than by hand.++ Portkey's ``_make_status_error_from_response`` puts the *message string* on+ ``exc.body``, never the document — so a test that hands the constructor a+ nested dict passes on a shape production never produces, while the real path+ recovers no code at all. Pinned here so it cannot quietly regress.+ """+ exc = _as_the_portkey_sdk_raises_it(status_code=413, body=_BODY_TOO_LARGE_BODY)++ assert isinstance(getattr(exc, "body", None), str)+ assert extract_gateway_metadata(exc).gateway_request_limit == GatewayRequestLimit.BODY_TOO_LARGE++ def test_the_length_rule_arrives_on_the_substrate_too(self) -> None:+ """``pig-08`` is raised by the same middleware as ``pig-07``, ahead of authentication."""+ exc = _as_the_portkey_sdk_raises_it(status_code=411, body=_LENGTH_REQUIRED_BODY)++ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code == "pig-08"+ assert metadata.gateway_request_limit == GatewayRequestLimit.BODY_LENGTH_REQUIRED++ def test_through_plain_httpx_on_the_native_routes(self) -> None:+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")+ response = httpx.Response(status_code=400, request=request, json=_BODY_TOO_DEEP_BODY)+ exc = httpx.HTTPStatusError("Client error '400 Bad Request'", request=request, response=response)++ metadata = extract_manifold_metadata(exc)++ assert metadata.provider_error_code == "pig-11"+ assert metadata.gateway_request_limit == GatewayRequestLimit.BODY_TOO_DEEP++ def test_through_the_shared_anthropic_driver(self) -> None:+ request = httpx.Request("POST", f"{_ORIGIN}/v1/messages")+ response = httpx.Response(status_code=413, request=request)+ exc = anthropic.BadRequestError(message="error", response=response, body=_OBJECT_TOO_LARGE_BODY)++ metadata = extract_anthropic_metadata(exc)++ assert metadata.provider_error_code == "pig-10"+ assert metadata.gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE++ @pytest.mark.parametrize(+ ("body", "expected"),+ [+ (_BODY_TOO_LARGE_BODY, GatewayRequestLimit.BODY_TOO_LARGE),+ (_BODY_TOO_DEEP_BODY, GatewayRequestLimit.BODY_TOO_DEEP),+ ],+ )+ def test_through_the_openai_substrate_that_carries_every_chat_call(self, body: dict[str, Any], expected: GatewayRequestLimit) -> None:+ """The hop a gateway or manifold LLM call actually takes, and the last one without a test.++ Both plugins build an ``OpenAICompletionsLLMWorker`` over a client pointed+ at the service, so a chat-route refusal is distilled by+ ``extract_openai_metadata``. That hop reads ``type`` before ``code``, which+ is right for the vendor it also serves and would throw a ``pipelex_*`` code+ away — it recovers these because the fail-closed envelope carries no+ ``type``. That is a property of the gateway's envelope, so it is checked+ here rather than assumed.+ """+ exc = _as_the_openai_sdk_raises_it(status_code=413, body=body)++ metadata = extract_openai_metadata(exc)++ assert metadata.gateway_request_limit == expected+++class TestClassification:+ """A limit refusal is a caller error the runtime must not retry."""++ @pytest.mark.parametrize(+ ("code", "status_code", "expected_limit", "expected_category", "expected_action"),+ [+ ("pig-07", 413, GatewayRequestLimit.BODY_TOO_LARGE, InferenceErrorCategory.CONTENT, UserActionKind.CHANGE_INPUT),+ (+ "pig-08",+ 411,+ GatewayRequestLimit.BODY_LENGTH_REQUIRED,+ InferenceErrorCategory.CONFIGURATION,+ UserActionKind.CONTACT_SUPPORT,+ ),+ ("pig-10", 413, GatewayRequestLimit.OBJECT_TOO_LARGE, InferenceErrorCategory.CONTENT, UserActionKind.CHANGE_INPUT),+ ("pig-11", 400, GatewayRequestLimit.BODY_TOO_DEEP, InferenceErrorCategory.CONTENT, UserActionKind.CHANGE_INPUT),+ ],+ )+ def test_each_limit_classifies_as_a_caller_error(+ self,+ code: str,+ status_code: int,+ expected_limit: GatewayRequestLimit,+ expected_category: InferenceErrorCategory,+ expected_action: UserActionKind,+ ) -> None:+ result = classify_inference_error(_envelope(code, status_code=status_code))++ assert result.gateway_request_limit == expected_limit+ assert result.category == expected_category+ assert result.user_action_kind == expected_action+ assert result.category.is_retryable is False+ assert result.is_model_not_found is False++ def test_a_413_without_the_code_is_left_to_the_status_ladder(self) -> None:+ """Only the gateway's own code names a limit; a bare 413 from a vendor is not one."""+ result = classify_inference_error(_envelope(None, status_code=413))++ assert result.gateway_request_limit is None+ assert result.category == InferenceErrorCategory.CONFIGURATION++ def test_the_411_would_otherwise_read_as_a_configuration_error_with_input_advice(self) -> None:+ """What the fall-through gave before: the generic 4xx bucket, telling the caller to revise the prompt."""+ fell_through = classify_inference_error(_envelope("something-else", status_code=411))++ assert fell_through.user_action_kind == UserActionKind.CHANGE_INPUT+++class TestRenderedAdvice:+ """Each limit gets advice naming what to do about it, not the generic rejection line."""++ @pytest.mark.parametrize(+ ("code", "status_code", "expected_phrase"),+ [+ ("pig-07", 413, "too large"),+ ("pig-08", 411, "Content-Length"),+ ("pig-10", 413, "per-file size limit"),+ ("pig-11", 400, "deeply"),+ ],+ )+ def test_the_detail_names_the_limit(self, code: str, status_code: int, expected_phrase: str) -> None:+ metadata = _envelope(code, status_code=status_code)+ classification = classify_inference_error(metadata)++ rendered = render_inference_error(+ metadata=metadata,+ classification=classification,+ family=InferenceErrorFamily.LLM,+ model_desc="claude-fake",+ model_handle="fake-handle",+ )++ assert rendered.user_action is not None+ assert expected_phrase in rendered.user_action.detail+ assert "review the prompt, parameters, and inputs" not in rendered.user_action.detail++ def test_the_two_size_limits_are_told_apart(self) -> None:+ """A body over its cap and one file over its cap need different remedies."""+ details: list[str] = []+ for code, status_code in (("pig-07", 413), ("pig-10", 413)):+ metadata = _envelope(code, status_code=status_code)+ rendered = render_inference_error(+ metadata=metadata,+ classification=classify_inference_error(metadata),+ family=InferenceErrorFamily.LLM,+ model_desc="claude-fake",+ model_handle="fake-handle",+ )+ assert rendered.user_action is not None+ details.append(rendered.user_action.detail)++ assert details[0] != details[1]+++def _native_route_refusal_body(message: str, code: str) -> dict[str, Any]:+ """The body pig's native ``/v1/pipelex/*`` routes render, verbatim in shape.++ A different envelope from the fail-closed one above, and the difference is the+ whole point of these tests: ``providerErrorResponse`` renders every refusal on+ those routes through the gateway's standard provider-error shape, which puts a+ generic ``invalid_request_error`` in ``error.type`` and the frozen contract code+ in ``error.code``. Reading ``type`` first — which is right for Anthropic, whose+ error section has no ``code`` at all — throws the code away.+ """+ return {+ "error": {"message": message, "type": "invalid_request_error", "param": None, "code": code},+ "provider": "linkup",+ }+++class TestTheSameLimitOnTheNativeRoutes:+ """The gateway renders one failure twice, and both renderings have to classify.++ ``pig-10`` is how the LLM routes say "this file is over its cap", because there+ the client speaks a provider's protocol and the gateway's own ``pig-0N`` family+ is the only vocabulary available. On ``/v1/pipelex/extract`` and+ ``/v1/pipelex/search`` the wire contract is pig's own and the same refusal is a+ ``pipelex_*`` code — one for a storage object it resolved, one for a document it+ fetched by URL. A caller cannot tell which route their extract took, so the two+ must read alike.+ """++ @pytest.mark.parametrize("code", ["pipelex_storage_object_too_large", "pipelex_document_too_large"])+ def test_a_file_over_its_cap_classifies_as_too_large(self, code: str) -> None:+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")+ response = httpx.Response(status_code=413, request=request, json=_native_route_refusal_body("over the limit", code))+ exc = httpx.HTTPStatusError("Client error '413 Payload Too Large'", request=request, response=response)++ metadata = extract_manifold_metadata(exc)+ result = classify_inference_error(metadata)++ assert metadata.provider_error_code == code+ assert result.gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE+ assert result.category == InferenceErrorCategory.CONTENT+ assert result.category.is_retryable is False++ def test_both_routes_give_the_caller_the_same_advice(self) -> None:+ """``pig-10`` and its native-route twin are one limit, so one remedy."""+ details: list[str] = []+ for metadata in (+ _envelope("pig-10", status_code=413),+ _envelope("pipelex_storage_object_too_large", status_code=413),+ ):+ rendered = render_inference_error(+ metadata=metadata,+ classification=classify_inference_error(metadata),+ family=InferenceErrorFamily.EXTRACT,+ model_desc="extractor-fake",+ model_handle="fake-handle",+ )+ assert rendered.user_action is not None+ details.append(rendered.user_action.detail)++ assert details[0] == details[1]++ def test_the_native_envelope_survives_the_portkey_substrate_too(self) -> None:+ """Where the two fixes on this branch actually meet, on one real call.++ A gateway extract or search reaches Azure Document Intelligence and Linkup+ through the chat costume, so the refusal those providers raise is rendered+ by ``providerErrorResponse`` — the ``type``-bearing native envelope — and+ then raised by Portkey's factory, which replaces the payload with the+ message string. Recovering the code needs the response fallback *and* the+ ``code``-first precedence; either one alone leaves the caller reading "the+ provider rejected the request" for a file they can simply make smaller.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ payload = _native_route_refusal_body("over the limit", "pipelex_document_too_large")+ response = httpx.Response(+ status_code=413,+ request=request,+ content=json.dumps(payload).encode(),+ headers={"content-type": "application/json"},+ )+ client = Portkey(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ exc = client._make_status_error_from_response(request=request, response=response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert isinstance(getattr(exc, "body", None), str)+ metadata = extract_gateway_metadata(exc)+ result = classify_inference_error(metadata)++ assert metadata.provider_error_code == "pipelex_document_too_large"+ assert result.gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE+ assert result.category.is_retryable is False++ def test_the_generic_type_does_not_shadow_the_contract_code(self) -> None:+ """The regression this envelope exists to pin.++ Every native-route refusal carries ``type: "invalid_request_error"`` beside+ its code. Reading ``type`` first reports that bucket as the provider error+ code for the whole ``pipelex_*`` vocabulary, so no contract code ever+ reaches the classifier — including the ones that are not limits.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")+ body = _native_route_refusal_body("that host is refused", "pipelex_document_host_refused")+ response = httpx.Response(status_code=400, request=request, json=body)+ exc = httpx.HTTPStatusError("Client error '400 Bad Request'", request=request, response=response)++ metadata = extract_manifold_metadata(exc)++ assert metadata.provider_error_code == "pipelex_document_host_refused"+ assert metadata.gateway_request_limit is Nonediff --git a/tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py b/tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.pynew file mode 100644index 000000000..49139c532--- /dev/null+++ b/tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py@@ -0,0 +1,628 @@+"""The gateway's routing refusals, from the wire code to the rendered advice.++Before a request can reach a provider the Pipelex inference gateway has to decide+*which* provider: it reads the model out of the request, looks it up in its own+routing table, and hands the call to the integration that serves it. When that+resolution fails it refuses the request itself, with codes of its own — ``pig-01``+when it serves no such model, ``pig-02`` when the model's integration is switched+off for want of a credential, ``pig-05`` when a native-protocol path names a model+another provider serves, and ``pig-06`` when a model reaches a route its provider+does not serve.++Every one of them answers HTTP 400, so without a class for them the Classify step+falls through to the status ladder's 400 arm and a caller who named a model the+deployment does not serve is told *"The provider rejected the request — review the+prompt, parameters, and inputs."* — and receives an ``LLMCompletionError`` rather+than the ``LLMModelNotFoundError`` that case has always produced when the model+deck itself cannot find a model. These tests pin the whole chain: the code is+recognized, it survives every Extract hop that can carry it, it classifies as a+configuration problem that is never retried, the Render step says which routing+decision failed and who has to change what, and both consequences of the category+that outlive this module are pinned too — the HTTP status the family now answers,+and the advice surviving the pipe layer's re-raise.++**Every member is its own wire code here**, unlike the two families beside it.+That is not an accident of the code space: grouping is by remedy in all three+families, and each of these four names a different thing that has to change.++**Only ``pig-01`` sets ``is_model_not_found``.** The flag is not a category — it+selects the family's ``*ModelNotFoundError`` class, which ``pipe_operator.py``+re-raises as a ``PipeOperatorModelAvailabilityError`` carrying the model handle.+``pig-01`` is literally "this deployment does not know that model", seen from the+gateway. For ``pig-05`` and ``pig-06`` the model exists and *is* served — it just+cannot do what was asked, or was asked over the wrong protocol — so claiming it+was not found would be false.++**``pig-02`` is the family's ``CONTACT_SUPPORT`` arm.** A switched-off integration+is the gateway operator's fact: nothing about the request causes it, none of the+caller's own credentials are at fault, and sending them shopping for another model+would hide an unset variable. The same call ``STORAGE_NOT_SERVED`` and+``BODY_LENGTH_REQUIRED`` get in the two families beside this one.++**``pig-03`` and ``pig-04`` are deliberately outside the family**, and that scope+decision is pinned below rather than left to a comment. Neither is produced today+by a client talking to a Pipelex-operated gateway: ``pig-03`` refuses client-side+routing forms that+``tests/unit/pipelex/providers/manifold/test_manifold_clients.py`` pins the+manifold clients against by name, and ``pig-04`` refuses a path the gateway does+not mount at all. Two limits on the first half, recorded beside the map rather+than implied here: that test names four headers while the gateway refuses on an+allow-list, and the gateway img-gen worker does send ``x-portkey-config``, which+Portkey's cloud reads and one of our gateways would refuse.++**``pig-05`` is mapped but unreachable from today's runtime**, which is why no+Extract hop is pinned for it. It is raised only on a native Google protocol path+(``/v1/<v1|v1alpha|v1beta>/models/<model>:generateContent`` or its+``streamGenerateContent`` twin), and no worker speaks that protocol to+the gateway: both the gateway and manifold plugins build their LLM workers on the+OpenAI substrate, and ``ManifoldNativeClient`` serves only the ``/v1/pipelex/*``+extract and search routes. The map entry costs nothing and is right the day a+native Google path is wired — but the Google Extract hop would not carry the code+even then, which the last case in ``TestTheCodeSurvivesEveryExtractHop`` pins as+the trap it is.+"""++from __future__ import annotations++import json+from typing import Any++import anthropic+import httpx+import pytest+from openai import OpenAI+from portkey_ai import Portkey++from pipelex.base_exceptions import ErrorDomain+from pipelex.cogt.exceptions import CogtError, InferenceErrorCategory, LLMCompletionError, LLMModelNotFoundError+from pipelex.cogt.inference.error_classification import (+ _GATEWAY_ROUTING_REFUSAL_BY_CODE, # pyright: ignore[reportPrivateUsage]+ GatewayRoutingRefusal,+ ProviderErrorMetadata,+ UserActionKind,+ extract_anthropic_metadata,+ extract_gateway_metadata,+ extract_google_metadata,+ extract_manifold_metadata,+ extract_openai_metadata,+)+from pipelex.cogt.inference.error_classify import classify_inference_error+from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error+from pipelex.cogt.inference.provider_name import ProviderName+from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError+from pipelex.system.pipe_run_mode import PipeRunMode++_ORIGIN = "https://manifold.example.com"++# Every code in the family, paired with the member it must reach. Reused by the+# recognition, classification and rendering cases so a code added to the map+# without an arm — or an arm added without a code — cannot pass unnoticed.+_EVERY_CODE_AND_MEMBER: list[tuple[str, GatewayRoutingRefusal]] = [+ ("pig-01", GatewayRoutingRefusal.UNKNOWN_MODEL),+ ("pig-02", GatewayRoutingRefusal.DISABLED_INTEGRATION),+ ("pig-05", GatewayRoutingRefusal.WRONG_PROTOCOL),+ ("pig-06", GatewayRoutingRefusal.UNSERVED_CAPABILITY),+]++# The same codes as a flat list, for the cases that only need the wire code.+_EVERY_CODE: list[str] = [pair[0] for pair in _EVERY_CODE_AND_MEMBER]++# Every member whose remedy is picking a different model, i.e. all of them but the+# one that means an operator never enabled the integration.+_CHANGE_MODEL_CODES: list[str] = [code for code, member in _EVERY_CODE_AND_MEMBER if member is not GatewayRoutingRefusal.DISABLED_INTEGRATION]++# The gateway's request-shape limits and its unresolvable-reference codes, for the+# three-way disjointness cases.+_REQUEST_LIMIT_CODES: list[str] = ["pig-07", "pig-08", "pig-10", "pig-11", "pipelex_storage_object_too_large", "pipelex_document_too_large"]+_UNRESOLVED_REFERENCE_CODES: list[str] = ["pig-09", "pipelex_storage_uri_invalid", "pipelex_storage_unreadable", "pipelex_document_host_refused"]++_GENERIC_ADVICE = "The provider rejected the request — review the prompt, parameters, and inputs."+_GENERIC_NOT_FOUND_ADVICE = "The requested model was not found — pick an available model."+++def _fail_closed_refusal_body(message: str, code: str) -> dict[str, Any]:+ """The body the gateway's ``generateApiErrorResponse`` renders, verbatim in shape.++ ``{status, message, error: {message, code}}`` — the code lives only under+ ``error.code``, and there is no ``error.type`` beside it. Every routing refusal+ is rendered by that one helper, on the LLM routes and the native ones alike, so+ this is the only envelope the family arrives in.+ """+ beautified = f"Portkey Error: {message}. Error Code: {code}"+ return {"status": "failure", "message": beautified, "error": {"message": beautified, "code": code}}+++_UNKNOWN_MODEL_BODY = _fail_closed_refusal_body("No model found for the request", "pig-01")+++def _as_the_portkey_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:+ """Build the exception through Portkey's own factory rather than by hand.++ The constructor accepts any ``body`` you give it; the SDK's factory does not —+ it sets ``body`` to ``json.loads(text)["error"]["message"]``, a string. Only the+ factory reproduces what the Extract step actually receives in production.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(body).encode(),+ headers={"content-type": "application/json"},+ )+ client = Portkey(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ return client._make_status_error_from_response(request=request, response=response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _as_the_openai_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:+ """Build the exception through the OpenAI SDK's own factory, for the same reason as above.++ This is the hop a gateway or manifold *chat* call actually takes: both plugins+ build an ``OpenAICompletionsLLMWorker`` / ``OpenAIResponsesLLMWorker`` over a+ client pointed at the service, so an LLM-route refusal is distilled by+ ``extract_openai_metadata`` and never by ``extract_gateway_metadata``.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(body).encode(),+ headers={"content-type": "application/json"},+ )+ client = OpenAI(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ return client._make_status_error_from_response(response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _envelope(code: str | None, *, status_code: int = 400, provider: ProviderName = ProviderName.GATEWAY) -> ProviderErrorMetadata:+ return ProviderErrorMetadata(+ provider=provider,+ sdk_exception_type="BadRequestError",+ message="Portkey Error: refused",+ status_code=status_code,+ provider_error_code=code,+ )+++def _rendered_error(metadata: ProviderErrorMetadata, *, family: InferenceErrorFamily = InferenceErrorFamily.LLM) -> CogtError:+ return render_inference_error(+ metadata=metadata,+ classification=classify_inference_error(metadata),+ family=family,+ model_desc="claude-fake",+ model_handle="fake-handle",+ )+++def _rendered_detail(metadata: ProviderErrorMetadata, *, family: InferenceErrorFamily = InferenceErrorFamily.LLM) -> str:+ rendered = _rendered_error(metadata, family=family)+ assert rendered.user_action is not None+ return rendered.user_action.detail+++class TestTheCodeIsRecognized:+ """``gateway_routing_refusal`` reads the gateway's own code namespace off the envelope."""++ @pytest.mark.parametrize(("code", "expected"), _EVERY_CODE_AND_MEMBER)+ def test_each_code_maps_to_its_member(self, code: str, expected: GatewayRoutingRefusal) -> None:+ assert _envelope(code).gateway_routing_refusal == expected++ @pytest.mark.parametrize("member", list(GatewayRoutingRefusal))+ def test_every_member_is_reachable_from_a_wire_code(self, member: GatewayRoutingRefusal) -> None:+ """A member no code reaches is dead advice — it would never render for anyone."""+ assert member in {expected for _, expected in _EVERY_CODE_AND_MEMBER}++ def test_the_table_covers_the_whole_production_map(self) -> None:+ """The other direction, which the per-code cases cannot see.++ Every case in this module walks the table above into the map. Without this+ one, a code added to the map and forgotten here would be classified and+ rendered in production and exercised by nothing.+ """+ assert set(_EVERY_CODE) == set(_GATEWAY_ROUTING_REFUSAL_BY_CODE)++ @pytest.mark.parametrize(+ "code",+ [None, "pig-07", "pig-09", "pig-11", "invalid_request_error", "PIG-01", "pipelex_storage_unreadable", "model_not_found", ""],+ )+ def test_any_other_code_is_not_a_routing_refusal(self, code: str | None) -> None:+ """The request-shape limits, the unresolvable references, and a vendor's own code are all other families."""+ assert _envelope(code).gateway_routing_refusal is None++ @pytest.mark.parametrize("provider", list(ProviderName))+ def test_the_code_is_read_whichever_provider_reported_it(self, provider: ProviderName) -> None:+ """Claude reaches the gateway on the Anthropic driver, so the refusal is not always reported as GATEWAY."""+ metadata = _envelope("pig-01", provider=provider)++ assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNKNOWN_MODEL+++class TestTheCodeSurvivesEveryExtractHop:+ """The refusal body the gateway actually emits, through each SDK that can carry it."""++ def test_through_the_portkey_substrate(self) -> None:+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=_UNKNOWN_MODEL_BODY)++ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code == "pig-01"+ assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNKNOWN_MODEL++ def test_the_portkey_substrate_discards_the_payload_and_the_code_survives_anyway(self) -> None:+ """The reason the hop above is built through the SDK rather than by hand.++ Portkey's ``_make_status_error_from_response`` puts the *message string* on+ ``exc.body``, never the document — so a test that hands the constructor a+ nested dict passes on a shape production never produces, while the real path+ recovers no code at all.+ """+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=_UNKNOWN_MODEL_BODY)++ assert isinstance(getattr(exc, "body", None), str)+ assert extract_gateway_metadata(exc).gateway_routing_refusal == GatewayRoutingRefusal.UNKNOWN_MODEL++ @pytest.mark.parametrize(("code", "expected"), _EVERY_CODE_AND_MEMBER)+ def test_through_the_openai_substrate_that_carries_every_chat_call(self, code: str, expected: GatewayRoutingRefusal) -> None:+ """The hop a gateway or manifold LLM call actually takes.++ That hop reads ``type`` before ``code``, which is right for the vendor it+ also serves — it recovers these because the fail-closed envelope carries no+ ``type`` at all. That is a property of the gateway's envelope rather than of+ the hop, so it is checked here rather than assumed.+ """+ exc = _as_the_openai_sdk_raises_it(status_code=400, body=_fail_closed_refusal_body("refused", code))++ assert extract_openai_metadata(exc).gateway_routing_refusal == expected++ def test_through_plain_httpx_on_the_native_routes(self) -> None:+ """Where ``pig-06`` is actually raised: ``/v1/pipelex/extract`` and its siblings.++ The route's model-versus-capability refusal is rendered by the same+ fail-closed helper as the LLM routes' — it is a ``pig-0N`` code, not one of+ the native routes' own ``pipelex_*`` contract codes.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")+ response = httpx.Response(status_code=400, request=request, json=_fail_closed_refusal_body("provider does not serve extract", "pig-06"))+ exc = httpx.HTTPStatusError("Client error '400 Bad Request'", request=request, response=response)++ metadata = extract_manifold_metadata(exc)++ assert metadata.provider_error_code == "pig-06"+ assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNSERVED_CAPABILITY++ def test_through_the_shared_anthropic_driver(self) -> None:+ """Claude travels on the vendor's own SDK, which recovers the code from the body it kept."""+ request = httpx.Request("POST", f"{_ORIGIN}/v1/messages")+ response = httpx.Response(status_code=400, request=request)+ exc = anthropic.BadRequestError(message="error", response=response, body=_UNKNOWN_MODEL_BODY)++ metadata = extract_anthropic_metadata(exc)++ assert metadata.provider_error_code == "pig-01"+ assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNKNOWN_MODEL++ def test_the_google_hop_would_not_carry_a_gateway_code_and_nothing_reaches_it_today(self) -> None:+ """``pig-05``'s hop, pinned as the trap it is rather than as a passing path.++ ``pig-05`` is raised only on the native Google protocol path, and no worker+ speaks that protocol to the gateway today — both service plugins build their+ LLM workers on the OpenAI substrate, and ``ManifoldNativeClient`` serves only+ the ``/v1/pipelex/*`` routes. So the map entry is correct and unreachable.++ Were that path wired, the code would still not arrive: Google's Extract hop+ reads the symbolic ``status`` a Google error carries (``RESOURCE_EXHAUSTED``+ and friends), and the gateway's envelope has no ``error.status`` — only a+ top-level ``status: "failure"``, which the hop dutifully returns as though it+ were a provider code. This asserts that, so whoever wires a native Google+ path finds the requirement stated rather than a silent misclassification.+ """++ class _GoogleApiError(Exception):+ """The shape ``extract_google_metadata`` reads: ``code`` is the HTTP status, ``details`` the raw body."""++ def __init__(self, *, details: dict[str, Any]) -> None:+ super().__init__("Portkey Error: refused. Error Code: pig-05")+ self.code = 400+ self.details = details+ self.response = None++ metadata = extract_google_metadata(_GoogleApiError(details=_fail_closed_refusal_body("wrong protocol", "pig-05")))++ assert metadata.provider_error_code == "failure"+ assert metadata.gateway_routing_refusal is None+++class TestClassification:+ """A routing refusal is a configuration problem the runtime must not retry."""++ @pytest.mark.parametrize(("code", "expected"), _EVERY_CODE_AND_MEMBER)+ def test_each_code_classifies_as_its_member_and_is_never_retried(self, code: str, expected: GatewayRoutingRefusal) -> None:+ result = classify_inference_error(_envelope(code))++ assert result.gateway_routing_refusal == expected+ assert result.category == InferenceErrorCategory.CONFIGURATION+ assert result.category.is_retryable is False+ assert result.gateway_request_limit is None+ assert result.gateway_unresolved_reference is None++ @pytest.mark.parametrize("code", _CHANGE_MODEL_CODES)+ def test_a_refusal_the_caller_can_route_around_asks_them_to_change_the_model(self, code: str) -> None:+ result = classify_inference_error(_envelope(code))++ assert result.user_action_kind == UserActionKind.CHANGE_MODEL++ def test_a_disabled_integration_is_an_operators_problem(self) -> None:+ """The credential is the gateway operator's and unset; the caller's own key is fine."""+ result = classify_inference_error(_envelope("pig-02"))++ assert result.gateway_routing_refusal == GatewayRoutingRefusal.DISABLED_INTEGRATION+ assert result.user_action_kind == UserActionKind.CONTACT_SUPPORT+ assert result.is_model_not_found is False++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_only_the_unknown_model_is_a_missing_model(self, code: str) -> None:+ """The flag selects the ``*ModelNotFoundError`` class, so setting it wrongly makes the runtime lie.++ For ``pig-05`` and ``pig-06`` the model exists and is served — it just+ cannot do what was asked, or was asked over the wrong protocol.+ """+ result = classify_inference_error(_envelope(code))++ assert result.is_model_not_found is (code == "pig-01")++ def test_a_plain_400_without_a_recognized_code_still_takes_the_status_ladder(self) -> None:+ """Only the gateway's own codes name a routing decision; a bare 400 from a vendor does not."""+ result = classify_inference_error(_envelope("something-else"))++ assert result.gateway_routing_refusal is None+ assert result.category == InferenceErrorCategory.CONTENT+ assert result.user_action_kind == UserActionKind.CHANGE_INPUT+++class TestEndToEnd:+ """The headline of the bug: what a caller actually receives, built the way production builds it."""++ def test_an_unserved_model_reaches_the_caller_as_a_model_not_found_carrying_the_handle(self) -> None:+ """Before this family it was an ``LLMCompletionError`` telling them to review their prompt.++ The handle matters as much as the class: ``pipe_operator.py`` re-raises a+ ``ModelNotFoundError`` as a ``PipeOperatorModelAvailabilityError`` carrying+ it, which is the pipe-level error a caller already gets when the deck itself+ cannot find a model.+ """+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=_UNKNOWN_MODEL_BODY)+ metadata = extract_gateway_metadata(exc)++ rendered = render_inference_error(+ metadata=metadata,+ classification=classify_inference_error(metadata),+ family=InferenceErrorFamily.LLM,+ model_desc="some-model",+ model_handle="some-handle",+ )++ assert isinstance(rendered, LLMModelNotFoundError)+ assert rendered.model_handle == "some-handle"+ assert rendered.error_category == InferenceErrorCategory.CONFIGURATION++ def test_a_wrong_protocol_refusal_does_not_claim_the_model_was_not_found(self) -> None:+ """The model exists and is served — only the protocol the runtime spoke was wrong."""+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=_fail_closed_refusal_body("served by another provider", "pig-05"))+ metadata = extract_gateway_metadata(exc)+ classification = classify_inference_error(metadata)++ rendered = render_inference_error(+ metadata=metadata,+ classification=classification,+ family=InferenceErrorFamily.LLM,+ model_desc="some-model",+ model_handle="some-handle",+ )++ assert isinstance(rendered, LLMCompletionError)+ assert not isinstance(rendered, LLMModelNotFoundError)+ assert classification.user_action_kind == UserActionKind.CHANGE_MODEL+ assert rendered.user_action is not None+ assert "not found" not in rendered.user_action.detail+++class TestRenderedAdvice:+ """Each member gets advice naming what has to change, not a generic rejection line."""++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_no_member_renders_the_generic_rejection_line(self, code: str) -> None:+ """The whole point: every one of these used to read as a prompt to revise."""+ assert _rendered_detail(_envelope(code)) != _GENERIC_ADVICE++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_no_member_renders_the_generic_action_kind_advice_either(self, code: str) -> None:+ """Branching ahead of the action kind is what this asserts.++ ``CHANGE_MODEL`` alone would render "the requested model was not found" for+ three members whose model exists, and ``CONTACT_SUPPORT`` alone would render+ "the error could not be classified" for a refusal that named itself exactly.+ """+ detail = _rendered_detail(_envelope(code))++ assert detail != _GENERIC_NOT_FOUND_ADVICE+ assert "could not be classified" not in detail++ @pytest.mark.parametrize(+ ("code", "expected_phrase"),+ [+ ("pig-01", "does not serve that model"),+ ("pig-02", "has not enabled"),+ ("pig-05", "not over the protocol"),+ ("pig-06", "does not serve that capability"),+ ],+ )+ def test_the_detail_names_the_remedy(self, code: str, expected_phrase: str) -> None:+ assert expected_phrase in _rendered_detail(_envelope(code))++ def test_the_unserved_model_and_the_wrong_protocol_are_told_apart(self) -> None:+ """A model the gateway does not serve and one it serves differently need different moves."""+ unknown = _rendered_detail(_envelope("pig-01"))+ wrong_protocol = _rendered_detail(_envelope("pig-05"))++ assert unknown != wrong_protocol+ assert "does not serve that model" in unknown+ assert "serves that model" in wrong_protocol++ def test_the_disabled_integration_blames_neither_the_prompt_nor_the_callers_key(self) -> None:+ """The distinction the ``CONTACT_SUPPORT`` ruling exists to keep.++ ``CHECK_CREDENTIALS`` would send a hosted caller to rotate a perfectly valid+ key, and ``CHANGE_MODEL`` would send them shopping for a model over an+ operator's unset variable.+ """+ detail = _rendered_detail(_envelope("pig-02"))++ assert "contact support" in detail.lower()+ assert "prompt" not in detail+ assert "pick a model" not in detail++ def test_the_deck_disagreement_refusals_name_the_deck(self) -> None:+ """Advice saying only "pick another model" would send an operator hunting for a model problem.++ The runtime picks the protocol and the route from its own deck, so these two+ usually mean the deck and the gateway's routing table disagree.+ """+ for code in ("pig-05", "pig-06"):+ assert "model deck" in _rendered_detail(_envelope(code))++ def test_an_unserved_capability_reaching_an_extract_reads_the_same(self) -> None:+ """``pig-06`` arrives on extract and search calls, so the advice must not assume an LLM family."""+ metadata = _envelope("pig-06")++ assert _rendered_detail(metadata, family=InferenceErrorFamily.EXTRACT) == _rendered_detail(metadata)+++class TestTheScopeDecisionIsPinned:+ """``pig-03`` and ``pig-04`` are routing codes the runtime deliberately does not map.++ Neither is producible by the clients the runtime ships, so the status ladder's+ reading of each is as good as any. These assert family membership only — they+ take no position on the verdict the ladder gives them, which for ``pig-04``'s+ 404 is model-not-found and wrong in kind.+ """++ @pytest.mark.parametrize(("code", "status_code"), [("pig-03", 400), ("pig-04", 404)])+ def test_the_unmapped_routing_codes_are_not_routing_refusals(self, code: str, status_code: int) -> None:+ metadata = _envelope(code, status_code=status_code)++ assert metadata.gateway_routing_refusal is None+ assert classify_inference_error(metadata).gateway_routing_refusal is None++ def test_the_unmapped_routing_codes_belong_to_no_gateway_family_at_all(self) -> None:+ """Not quietly picked up by one of the neighbouring maps either."""+ for code, status_code in (("pig-03", 400), ("pig-04", 404)):+ metadata = _envelope(code, status_code=status_code)++ assert metadata.gateway_request_limit is None+ assert metadata.gateway_unresolved_reference is None+++class TestTheThreeGatewayFamiliesDoNotShadowEachOther:+ """One bounds the request's shape, one says a reference could not be resolved, one says it could not be routed.++ All three read the same ``pig-`` namespace, so a code landing in two maps would+ silently give one family's advice to another's refusal — and the branch order in+ ``classify_inference_error`` would start to matter, which it must not.+ """++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_no_routing_code_belongs_to_another_family(self, code: str) -> None:+ metadata = _envelope(code)++ assert metadata.gateway_request_limit is None+ assert metadata.gateway_unresolved_reference is None++ @pytest.mark.parametrize("code", _REQUEST_LIMIT_CODES + _UNRESOLVED_REFERENCE_CODES)+ def test_no_other_familys_code_is_a_routing_refusal(self, code: str) -> None:+ assert _envelope(code, status_code=413).gateway_routing_refusal is None++ def test_the_three_maps_are_disjoint_as_sets(self) -> None:+ """The direction the per-code cases cannot see: a code added to two maps at once."""+ from pipelex.cogt.inference.error_classification import ( # ruff: ignore[import-outside-top-level]+ _GATEWAY_REQUEST_LIMIT_BY_CODE, # pyright: ignore[reportPrivateUsage]+ _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE, # pyright: ignore[reportPrivateUsage]+ )++ limits = set(_GATEWAY_REQUEST_LIMIT_BY_CODE)+ references = set(_GATEWAY_UNRESOLVED_REFERENCE_BY_CODE)+ routing = set(_GATEWAY_ROUTING_REFUSAL_BY_CODE)++ assert limits & references == set()+ assert limits & routing == set()+ assert references & routing == set()+++class TestWhatTheFamilyAnswersOverHTTP:+ """The category is not only advice — it decides the status an HTTP surface returns.++ ``CONFIGURATION`` implies ``ErrorDomain.CONFIG``, which+ ``error_domain_to_http_status`` renders as 500; the ``CONTENT`` these four used+ to receive implies ``INPUT`` and renders as 422. So classifying the family+ moved its HTTP answer as surely as it moved its wording, and that is the half a+ classification test cannot see. 500 is also the status outer clients retry,+ which is worth pinning precisely because "never retried" elsewhere in this+ module is a statement about ``InferenceErrorCategory.is_retryable`` inside this+ process and about nothing else.+ """++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_every_member_answers_500_rather_than_the_422_it_used_to(self, code: str) -> None:+ report = _rendered_error(_envelope(code)).to_error_report()++ assert report.error_domain == ErrorDomain.CONFIG+ assert report.http_status == 500++ def test_an_unrecognized_400_still_answers_422(self) -> None:+ """The contrast that makes the case above a change rather than a constant."""+ report = _rendered_error(_envelope("something-else")).to_error_report()++ assert report.error_domain == ErrorDomain.INPUT+ assert report.http_status == 422+++class TestTheAdviceSurvivesThePipeBoundary:+ """``pig-01`` is the one member whose error class is re-raised on the way out.++ ``pipe_operator.py`` catches ``ModelNotFoundError`` and re-raises it as a+ ``PipeOperatorModelAvailabilityError``, whose constructor takes a message, a+ handle and a stack and no user action — so the advice reaches a caller only+ because ``_enrich_error_report_from_cause`` inherits ``user_action`` and+ ``error_domain`` off the ``__cause__`` chain. That inheritance is what carries+ every word of this family's most-argued detail through the pipe layer, and+ nothing else in this module crosses that boundary to see it.+ """++ def _re_raised_as_the_pipe_operator_does(self, cause: LLMModelNotFoundError) -> PipeOperatorModelAvailabilityError:+ """Mirror ``PipeOperator``'s ``except ModelNotFoundError`` arm, ``from`` included.++ The ``from`` is the load-bearing part: without it there is no ``__cause__``+ and the enrichment this class exists to pin has nothing to read.+ """+ try:+ raise cause+ except LLMModelNotFoundError as model_not_found_error:+ try:+ raise PipeOperatorModelAvailabilityError(+ message=model_not_found_error.message,+ run_mode=PipeRunMode.LIVE,+ pipe_type="PipeLLM",+ pipe_code="some_pipe",+ pipe_stack=[],+ model_handle=model_not_found_error.model_handle,+ ) from model_not_found_error+ except PipeOperatorModelAvailabilityError as availability_error:+ return availability_error++ def test_the_unknown_model_advice_reaches_the_caller_through_the_pipe_error(self) -> None:+ rendered = _rendered_error(_envelope("pig-01"))+ assert isinstance(rendered, LLMModelNotFoundError)++ report = self._re_raised_as_the_pipe_operator_does(rendered).to_error_report()++ assert report.error_type == "PipeOperatorModelAvailabilityError"+ assert report.user_action_detail() == _rendered_detail(_envelope("pig-01"))+ assert report.error_domain == ErrorDomain.CONFIG+ assert report.http_status == 500diff --git a/tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.py b/tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.pynew file mode 100644index 000000000..c7cefaa58--- /dev/null+++ b/tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.py@@ -0,0 +1,437 @@+"""The gateway's unresolvable-reference refusals, from the wire code to the rendered advice.++A request may name a file rather than carry it — a ``pipelex-storage://`` key the+Pipelex inference gateway resolves for the caller, or a document URL it fetches on+their behalf. When it cannot turn that reference into bytes it refuses the request+itself, with codes of its own: ``pig-09`` on the LLM routes, where its ``pig-0N``+family has one fail-closed slot for "cannot resolve" and the message carries the+difference, and a named ``pipelex_*`` contract code on the native+``/v1/pipelex/*`` routes for each distinct cause.++Without a class for them the Classify step falls through to the generic status+ladder — every one of these arrives on 400 — so a caller who mistyped a storage+key, pointed at an object this deployment cannot read, or aimed a URL at a host the+SSRF guard refuses reads "the provider rejected the request — review the prompt,+parameters, and inputs". These tests pin the whole chain: the code is recognized,+it survives every Extract hop that can carry it, it classifies as a caller error+that is never retried, and the Render step says which reference failed and what to+do about it.++**Grouped by remedy, not by wire code.** Two codes share a ``GatewayUnresolvedReference``+member only when the caller's next move is the same — which is why the three+document-URL refusals are one member and ``pipelex_document_host_refused`` is its+own: the caller can act on all four, but only the host refusal has to be stated as+the deliberate security policy it is, rather than as a fault to work around.++**And one member is not the caller's at all.** ``pipelex_storage_uri_unsupported``+means no bucket is configured, so this deployment does not serve the scheme —+nothing about the inputs causes it and no input avoids it. It is the family's one+``CONTACT_SUPPORT`` arm, the same call ``BODY_LENGTH_REQUIRED`` gets among the+request limits.+"""++from __future__ import annotations++import json+from typing import Any++import anthropic+import httpx+import pytest+from openai import OpenAI+from portkey_ai import Portkey++from pipelex.cogt.exceptions import InferenceErrorCategory+from pipelex.cogt.inference.error_classification import (+ _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE, # pyright: ignore[reportPrivateUsage]+ GatewayRequestLimit,+ GatewayUnresolvedReference,+ ProviderErrorMetadata,+ UserActionKind,+ extract_anthropic_metadata,+ extract_gateway_metadata,+ extract_manifold_metadata,+ extract_openai_metadata,+)+from pipelex.cogt.inference.error_classify import classify_inference_error+from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error+from pipelex.cogt.inference.provider_name import ProviderName++_ORIGIN = "https://manifold.example.com"++# Every code in the family, paired with the member it must reach. Reused by the+# recognition, classification and rendering cases so a code added to the map+# without an arm — or an arm added without a code — cannot pass unnoticed.+_EVERY_CODE_AND_MEMBER: list[tuple[str, GatewayUnresolvedReference]] = [+ ("pig-09", GatewayUnresolvedReference.REFERENCE_UNRESOLVED),+ ("pipelex_storage_uri_invalid", GatewayUnresolvedReference.STORAGE_REFERENCE_INVALID),+ ("pipelex_storage_unreadable", GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE),+ ("pipelex_storage_uri_unsupported", GatewayUnresolvedReference.STORAGE_NOT_SERVED),+ ("pipelex_unsupported_uri_scheme", GatewayUnresolvedReference.DOCUMENT_URL_REFUSED),+ ("pipelex_document_scheme_refused", GatewayUnresolvedReference.DOCUMENT_URL_REFUSED),+ ("pipelex_document_address_refused", GatewayUnresolvedReference.DOCUMENT_URL_REFUSED),+ ("pipelex_document_redirect_refused", GatewayUnresolvedReference.DOCUMENT_URL_REFUSED),+ ("pipelex_document_host_refused", GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED),+ ("pipelex_document_unreachable", GatewayUnresolvedReference.DOCUMENT_UNREACHABLE),+ ("pipelex_document_empty", GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE),+ ("pipelex_document_unsupported_type", GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE),+ ("pipelex_document_bad_data_url", GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE),+]++# The same codes as a flat list, for the cases that only need the wire code.+_EVERY_CODE: list[str] = [pair[0] for pair in _EVERY_CODE_AND_MEMBER]++# Every code whose remedy is the caller's own, i.e. all of them but the one that+# says this deployment serves no storage at all.+_CALLER_FIXABLE_CODES: list[str] = [code for code, member in _EVERY_CODE_AND_MEMBER if member is not GatewayUnresolvedReference.STORAGE_NOT_SERVED]++_GENERIC_ADVICE = "The provider rejected the request — review the prompt, parameters, and inputs."+++def _fail_closed_refusal_body(message: str, code: str) -> dict[str, Any]:+ """The body the gateway's ``generateApiErrorResponse`` renders, verbatim in shape.++ ``{status, message, error: {message, code}}`` — the code lives only under+ ``error.code``, and there is no ``error.type`` beside it. This is how the LLM+ routes speak, so it is the envelope ``pig-09`` arrives in.+ """+ beautified = f"Portkey Error: {message}. Error Code: {code}"+ return {"status": "failure", "message": beautified, "error": {"message": beautified, "code": code}}+++def _native_route_refusal_body(message: str, code: str) -> dict[str, Any]:+ """The body pig's native ``/v1/pipelex/*`` routes render, verbatim in shape.++ ``providerErrorResponse`` puts a generic ``invalid_request_error`` in+ ``error.type`` and the frozen contract code in ``error.code``, which is why the+ two Pipelex-service Extract hops read ``code`` before ``type``. Every+ ``pipelex_*`` code in this family arrives in this envelope.+ """+ return {+ "error": {"message": message, "type": "invalid_request_error", "param": None, "code": code},+ "provider": "linkup",+ }+++_UNRESOLVED_BODY = _fail_closed_refusal_body(+ "The request refers to 'pipelex-storage://nope/missing.pdf', which this gateway cannot resolve",+ "pig-09",+)+++def _as_the_portkey_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:+ """Build the exception through Portkey's own factory rather than by hand.++ The constructor accepts any ``body`` you give it; the SDK's factory does not —+ it sets ``body`` to ``json.loads(text)["error"]["message"]``, a string. Only the+ factory reproduces what the Extract step actually receives in production.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(body).encode(),+ headers={"content-type": "application/json"},+ )+ client = Portkey(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ return client._make_status_error_from_response(request=request, response=response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _as_the_openai_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:+ """Build the exception through the OpenAI SDK's own factory, for the same reason as above.++ This is the hop a gateway or manifold *chat* call actually takes: both plugins+ build an ``OpenAICompletionsLLMWorker`` / ``OpenAIResponsesLLMWorker`` over a+ client pointed at the service, so an LLM-route refusal is distilled by+ ``extract_openai_metadata`` and never by ``extract_gateway_metadata``.+ """+ request = httpx.Request("POST", f"{_ORIGIN}/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(body).encode(),+ headers={"content-type": "application/json"},+ )+ client = OpenAI(api_key="unused-in-this-test", base_url=f"{_ORIGIN}/v1")+ return client._make_status_error_from_response(response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]+++def _envelope(code: str | None, *, status_code: int = 400, provider: ProviderName = ProviderName.GATEWAY) -> ProviderErrorMetadata:+ return ProviderErrorMetadata(+ provider=provider,+ sdk_exception_type="BadRequestError",+ message="Portkey Error: refused",+ status_code=status_code,+ provider_error_code=code,+ )+++def _rendered_detail(metadata: ProviderErrorMetadata, *, family: InferenceErrorFamily = InferenceErrorFamily.LLM) -> str:+ rendered = render_inference_error(+ metadata=metadata,+ classification=classify_inference_error(metadata),+ family=family,+ model_desc="claude-fake",+ model_handle="fake-handle",+ )+ assert rendered.user_action is not None+ return rendered.user_action.detail+++class TestTheCodeIsRecognized:+ """``gateway_unresolved_reference`` reads the gateway's own code namespace off the envelope."""++ @pytest.mark.parametrize(("code", "expected"), _EVERY_CODE_AND_MEMBER)+ def test_each_code_maps_to_its_member(self, code: str, expected: GatewayUnresolvedReference) -> None:+ assert _envelope(code).gateway_unresolved_reference == expected++ @pytest.mark.parametrize("member", list(GatewayUnresolvedReference))+ def test_every_member_is_reachable_from_a_wire_code(self, member: GatewayUnresolvedReference) -> None:+ """A member no code reaches is dead advice — it would never render for anyone."""+ assert member in {expected for _, expected in _EVERY_CODE_AND_MEMBER}++ def test_the_table_covers_the_whole_production_map(self) -> None:+ """The other direction, which the per-code cases cannot see.++ Every case in this module walks the table above into the map. Without this+ one, a code added to the map and forgotten here would be classified and+ rendered in production and exercised by nothing.+ """+ assert set(_EVERY_CODE) == set(_GATEWAY_UNRESOLVED_REFERENCE_BY_CODE)++ @pytest.mark.parametrize(+ "code",+ [None, "pig-01", "pig-07", "pig-10", "invalid_request_error", "PIG-09", "pipelex_storage_object_too_large", ""],+ )+ def test_any_other_code_is_not_an_unresolved_reference(self, code: str | None) -> None:+ """The routing codes, the request-shape limits, and a vendor's own code are all other families."""+ assert _envelope(code).gateway_unresolved_reference is None++ @pytest.mark.parametrize("provider", list(ProviderName))+ def test_the_code_is_read_whichever_provider_reported_it(self, provider: ProviderName) -> None:+ """Claude reaches the gateway on the Anthropic driver, so the refusal is not always reported as GATEWAY."""+ metadata = _envelope("pipelex_document_host_refused", provider=provider)++ assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED+++class TestTheCodeSurvivesEveryExtractHop:+ """The refusal body the gateway actually emits, through each SDK that can carry it."""++ def test_through_the_portkey_substrate(self) -> None:+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=_UNRESOLVED_BODY)++ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code == "pig-09"+ assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED++ def test_the_portkey_substrate_discards_the_payload_and_the_code_survives_anyway(self) -> None:+ """The reason the hop above is built through the SDK rather than by hand.++ Portkey's ``_make_status_error_from_response`` puts the *message string* on+ ``exc.body``, never the document — so a test that hands the constructor a+ nested dict passes on a shape production never produces, while the real path+ recovers no code at all.+ """+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=_UNRESOLVED_BODY)++ assert isinstance(getattr(exc, "body", None), str)+ assert extract_gateway_metadata(exc).gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED++ def test_the_native_envelope_survives_the_portkey_substrate_too(self) -> None:+ """A gateway extract reaches Azure Document Intelligence in the chat costume.++ The refusal is rendered by ``providerErrorResponse`` — the ``type``-bearing+ native envelope — and then raised by Portkey's factory, which replaces the+ payload with the message string. Recovering the code needs the response+ fallback *and* the ``code``-first precedence.+ """+ body = _native_route_refusal_body("that host is refused", "pipelex_document_host_refused")+ exc = _as_the_portkey_sdk_raises_it(status_code=400, body=body)++ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code == "pipelex_document_host_refused"+ assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED++ @pytest.mark.parametrize(+ ("code", "expected"),+ [+ ("pipelex_storage_uri_invalid", GatewayUnresolvedReference.STORAGE_REFERENCE_INVALID),+ ("pipelex_storage_unreadable", GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE),+ ("pipelex_document_unsupported_type", GatewayUnresolvedReference.DOCUMENT_CONTENT_UNUSABLE),+ ],+ )+ def test_through_plain_httpx_on_the_native_routes(self, code: str, expected: GatewayUnresolvedReference) -> None:+ """Where the ``pipelex_*`` codes are actually raised: ``/v1/pipelex/extract`` and its siblings."""+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")+ response = httpx.Response(status_code=400, request=request, json=_native_route_refusal_body("refused", code))+ exc = httpx.HTTPStatusError("Client error '400 Bad Request'", request=request, response=response)++ metadata = extract_manifold_metadata(exc)++ assert metadata.provider_error_code == code+ assert metadata.gateway_unresolved_reference == expected++ def test_through_the_shared_anthropic_driver(self) -> None:+ """Claude travels on the vendor's own SDK, which recovers the code from the body it kept."""+ request = httpx.Request("POST", f"{_ORIGIN}/v1/messages")+ response = httpx.Response(status_code=400, request=request)+ exc = anthropic.BadRequestError(message="error", response=response, body=_UNRESOLVED_BODY)++ metadata = extract_anthropic_metadata(exc)++ assert metadata.provider_error_code == "pig-09"+ assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED++ def test_through_the_openai_substrate_that_carries_every_chat_call(self) -> None:+ """The hop a gateway or manifold LLM call actually takes.++ That hop reads ``type`` before ``code``, which is right for the vendor it+ also serves — it recovers ``pig-09`` because the fail-closed envelope+ carries no ``type`` at all. That is a property of the gateway's envelope, so+ it is checked here rather than assumed.+ """+ exc = _as_the_openai_sdk_raises_it(status_code=400, body=_UNRESOLVED_BODY)++ metadata = extract_openai_metadata(exc)++ assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED+++class TestClassification:+ """An unresolvable reference is a caller error the runtime must not retry."""++ @pytest.mark.parametrize(("code", "expected"), _EVERY_CODE_AND_MEMBER)+ def test_each_code_classifies_as_its_member_and_is_never_retried(self, code: str, expected: GatewayUnresolvedReference) -> None:+ result = classify_inference_error(_envelope(code))++ assert result.gateway_unresolved_reference == expected+ assert result.category.is_retryable is False+ assert result.is_model_not_found is False+ assert result.gateway_request_limit is None++ @pytest.mark.parametrize("code", _CALLER_FIXABLE_CODES)+ def test_a_reference_the_caller_can_repair_asks_them_to_change_the_input(self, code: str) -> None:+ result = classify_inference_error(_envelope(code))++ assert result.category == InferenceErrorCategory.CONTENT+ assert result.user_action_kind == UserActionKind.CHANGE_INPUT++ def test_a_deployment_that_serves_no_storage_is_an_operators_problem(self) -> None:+ """No bucket configured is not something any input can avoid, so the caller is not asked to try."""+ result = classify_inference_error(_envelope("pipelex_storage_uri_unsupported"))++ assert result.gateway_unresolved_reference == GatewayUnresolvedReference.STORAGE_NOT_SERVED+ assert result.category == InferenceErrorCategory.CONFIGURATION+ assert result.user_action_kind == UserActionKind.CONTACT_SUPPORT+ assert result.category.is_retryable is False++ def test_a_plain_400_without_a_recognized_code_still_takes_the_status_ladder(self) -> None:+ """Only the gateway's own codes name a reference; a bare 400 from a vendor does not."""+ result = classify_inference_error(_envelope("something-else"))++ assert result.gateway_unresolved_reference is None+ assert result.category == InferenceErrorCategory.CONTENT+ assert result.user_action_kind == UserActionKind.CHANGE_INPUT+++class TestRenderedAdvice:+ """Each member gets advice naming what to do about the reference, not the generic rejection line."""++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_no_member_renders_the_generic_rejection_line(self, code: str) -> None:+ """The whole point: every one of these used to read as a prompt to revise."""+ assert _rendered_detail(_envelope(code)) != _GENERIC_ADVICE++ @pytest.mark.parametrize(+ ("code", "expected_phrase"),+ [+ ("pig-09", "could not be resolved"),+ ("pipelex_storage_uri_invalid", "malformed"),+ ("pipelex_storage_unreadable", "does not exist or cannot be read"),+ ("pipelex_storage_uri_unsupported", "contact support"),+ ("pipelex_unsupported_uri_scheme", "pipelex-storage:// reference"),+ ("pipelex_document_scheme_refused", "https:// URL"),+ ("pipelex_document_host_refused", "security policy"),+ ("pipelex_document_unreachable", "publicly reachable"),+ ("pipelex_document_empty", "fetched but cannot be used"),+ ],+ )+ def test_the_detail_names_the_remedy(self, code: str, expected_phrase: str) -> None:+ assert expected_phrase in _rendered_detail(_envelope(code))++ def test_the_host_refusal_is_stated_as_a_security_policy(self) -> None:+ """The distinction the whole ``DOCUMENT_HOST_REFUSED`` member exists to keep.++ The SSRF guard refused deliberately. Advice that reads as a fault to work+ around — revise the prompt, use a smaller file — sends the caller looking+ for a problem in a document that is perfectly fine.+ """+ detail = _rendered_detail(_envelope("pipelex_document_host_refused"))++ assert "security policy" in detail+ assert "prompt" not in detail+ assert "smaller" not in detail++ def test_the_unserved_scheme_does_not_ask_the_caller_to_fix_their_input(self) -> None:+ detail = _rendered_detail(_envelope("pipelex_storage_uri_unsupported"))++ assert "contact support" in detail+ assert "prompt" not in detail++ def test_the_two_storage_reference_failures_are_told_apart(self) -> None:+ """A key that is malformed and an object that is not there need different checks."""+ malformed = _rendered_detail(_envelope("pipelex_storage_uri_invalid"))+ unreadable = _rendered_detail(_envelope("pipelex_storage_unreadable"))++ assert malformed != unreadable++ def test_the_url_shape_refusals_share_one_remedy(self) -> None:+ """They are one member precisely because the caller's next move is the same."""+ details = {+ _rendered_detail(_envelope(code))+ for code in (+ "pipelex_unsupported_uri_scheme",+ "pipelex_document_scheme_refused",+ "pipelex_document_address_refused",+ "pipelex_document_redirect_refused",+ )+ }++ assert len(details) == 1++ def test_a_host_refusal_reaching_an_extract_reads_the_same(self) -> None:+ """The document-fetch codes arrive on extract calls, so the advice must not assume an LLM family."""+ metadata = _envelope("pipelex_document_host_refused")++ assert _rendered_detail(metadata, family=InferenceErrorFamily.EXTRACT) == _rendered_detail(metadata)+++class TestTheTwoGatewayFamiliesDoNotShadowEachOther:+ """One bounds the request's shape, the other says a reference could not be resolved.++ The same middleware raises ``pig-09`` and ``pig-10``, and the native routes'+ storage codes sit in one frozen contract — so the two maps are neighbours in the+ same namespace and a code landing in both would silently give one family's+ advice to the other's refusal.+ """++ @pytest.mark.parametrize("code", _EVERY_CODE)+ def test_no_unresolved_reference_code_is_also_a_request_limit(self, code: str) -> None:+ assert _envelope(code).gateway_request_limit is None++ @pytest.mark.parametrize("code", ["pig-07", "pig-08", "pig-10", "pig-11", "pipelex_storage_object_too_large", "pipelex_document_too_large"])+ def test_no_request_limit_code_is_also_an_unresolved_reference(self, code: str) -> None:+ assert _envelope(code, status_code=413).gateway_unresolved_reference is None++ def test_the_storage_codes_are_split_between_the_two_families_on_the_same_route(self) -> None:+ """Both arrive from ``/v1/pipelex/extract``, and each must reach its own family."""+ too_large = _envelope("pipelex_storage_object_too_large", status_code=413)+ unreadable = _envelope("pipelex_storage_unreadable")++ assert classify_inference_error(too_large).gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE+ assert classify_inference_error(too_large).gateway_unresolved_reference is None+ assert classify_inference_error(unreadable).gateway_unresolved_reference == GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE+ assert classify_inference_error(unreadable).gateway_request_limit is Nonediff --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 796eee455..81453b213 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@@ -141,7 +141,7 @@ class TestAStaleBackendDirectory:*,lenient: bool,library_body: str = BACKENDS_TOML,- gateway_config: GatewayConfig | None = None,+ managed_gateway_configs: dict[str, GatewayConfig] | None = None,) -> InferenceBackendLibrary:library_path = self._write_library(machine, body=library_body)library = InferenceBackendLibrary.make_empty()@@ -149,7 +149,7 @@ class TestAStaleBackendDirectory:secrets_provider=EnvSecretsProvider(),backends_library_paths=[library_path],backends_dir_path=str(self._backends_dir(machine)),- gateway_config=gateway_config,+ managed_gateway_configs=managed_gateway_configs,lenient=lenient,)return library@@ -269,7 +269,7 @@ class TestAStaleBackendDirectory:machine,lenient=False,library_body=GATEWAY_BACKENDS_TOML,- gateway_config=GatewayConfig(model_specs=GATEWAY_SERVED_SPECS, aws_region="eu-west-1"),+ managed_gateway_configs={PipelexBackend.GATEWAY: GatewayConfig(model_specs=GATEWAY_SERVED_SPECS, aws_region="eu-west-1")},)backend = library.get_inference_backend(backend_name=PipelexBackend.GATEWAY)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 b95a000f6..9e51720c0 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@@ -15,6 +15,7 @@ from pytest_mock import MockerFixturefrom pipelex import logfrom pipelex.cogt.llm.llm_job import LLMJob+from pipelex.cogt.model_backends.backend import PipelexBackendfrom pipelex.cogt.model_backends.backend_library import InferenceBackendLibraryfrom pipelex.cogt.model_backends.gateway_config import GatewayConfigfrom pipelex.cogt.model_backends.model_spec_factory import BackendModelSpecs@@ -41,7 +42,7 @@ class TestGatewayUnknownPerModelKeys:secrets_provider=EnvSecretsProvider(),backends_library_paths=[backends_library_path],backends_dir_path=str(backends_dir),- gateway_config=GatewayConfig(model_specs=model_specs, aws_region="eu-west-3"),+ managed_gateway_configs={PipelexBackend.GATEWAY: GatewayConfig(model_specs=model_specs, aws_region="eu-west-3")},)return librarydiff --git a/tests/unit/pipelex/cogt/model_backends/test_managed_backend_missing_variable.py b/tests/unit/pipelex/cogt/model_backends/test_managed_backend_missing_variable.pynew file mode 100644index 000000000..370c1949c--- /dev/null+++ b/tests/unit/pipelex/cogt/model_backends/test_managed_backend_missing_variable.py@@ -0,0 +1,138 @@+"""A backend that DECLARES a model specs section is disabled when its `${…}` variables are unset; every other backend still stops the boot.++The kit ships `[pipelex_manifold]` declared, so joining the beta is enabling it and setting two+variables rather than editing a config file. That only works if an installation that has *not*+joined boots normally, which is why such a backend whose variables are unset is disabled with a+warning naming it.++**The scoping is the point of these tests, not a detail.** The tolerance sits on a code path every+backend shares, so a global version of it would mean a user who typos `ANTHROPIC_API_KEY` stops+getting a boot failure and starts getting a silently missing backend that resurfaces much later as a+model-resolution error — a behaviour change on the Portkey-cloud path and on every direct-SDK path,+which the two-gateways work must not make.++**And the predicate is the declaration rather than managed-ness**, because the two come apart on+`pipelex_gateway`: it is handed its section by compatibility default, so keying on managed-ness+would hand it the tolerance too and lose exactly the boot failure the paragraph above protects. The+third test below is what holds those two apart.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.cogt.exceptions import InferenceBackendCredentialsError+from pipelex.cogt.model_backends.backend import MANIFOLD_MODEL_SPECS_SECTION, PipelexBackend+from pipelex.cogt.model_backends.backend_library import InferenceBackendLibrary+from pipelex.cogt.model_backends.gateway_config import GatewayConfig+from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++# A name no environment has, so the substitution fails for the reason under test rather than by luck.+UNSET_VAR = "PIPELEX_TEST_VARIABLE_THAT_IS_NEVER_SET"++MANAGED_BACKEND_TOML = f"""+[pipelex_manifold]+enabled = true+model_specs_section = "{MANIFOLD_MODEL_SPECS_SECTION}"+endpoint = "${{{UNSET_VAR}}}"+api_key = "sk-not-a-real-key"+"""++BYOK_BACKEND_TOML = f"""+[anthropic]+enabled = true+api_key = "${{{UNSET_VAR}}}"+"""++# The legacy gateway, declaring nothing: `resolve_model_specs_section` hands it a section by+# compatibility default, which is exactly why it must not inherit the tolerance along with it.+LEGACY_GATEWAY_BACKEND_TOML = f"""+[pipelex_gateway]+enabled = true+api_key = "${{{UNSET_VAR}}}"+"""+++def _load(tmp_path: Path, *, body: str, managed_gateway_configs: dict[str, GatewayConfig] | None = None) -> InferenceBackendLibrary:+ backends_dir = tmp_path / "backends"+ backends_dir.mkdir(exist_ok=True)+ library_path = tmp_path / "backends.toml"+ library_path.write_text(body, encoding="utf-8")+ library = InferenceBackendLibrary.make_empty()+ library.load(+ secrets_provider=EnvSecretsProvider(),+ backends_library_paths=[library_path],+ backends_dir_path=str(backends_dir),+ managed_gateway_configs=managed_gateway_configs,+ lenient=False,+ )+ return library+++class TestAManagedBackendMissingItsVariables:+ def test_it_is_disabled_with_a_warning_naming_the_backend_and_the_variable(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """The remedy is the warning, so it has to name what to set and where to turn it off."""+ warning = mocker.patch("pipelex.cogt.model_backends.backend_library.log.warning")++ library = _load(tmp_path, body=MANAGED_BACKEND_TOML, managed_gateway_configs={})++ assert library.get_inference_backend(backend_name=PipelexBackend.MANIFOLD) is None+ warning.assert_called_once()+ said = str(warning.call_args.args[0])+ assert PipelexBackend.MANIFOLD in said+ assert UNSET_VAR in said++ def test_a_byok_backend_missing_its_variables_still_stops_the_boot(self, tmp_path: Path) -> None:+ """Unchanged, deliberately: a typo in an API-key variable must stay loud."""+ with pytest.raises(InferenceBackendCredentialsError) as refused:+ _load(tmp_path, body=BYOK_BACKEND_TOML)++ assert refused.value.key_name == UNSET_VAR++ def test_the_legacy_gateway_missing_its_key_still_stops_the_boot(self, tmp_path: Path) -> None:+ """The Portkey-cloud path keeps today's fatal boot, and the distinction is why this test exists.++ `pipelex_gateway` declares no `model_specs_section` — it is handed one by compatibility+ default so that a `backends.toml` written before the field keeps working. That default makes+ it *managed*, and if the tolerance were scoped to managed-ness it would inherit it: an unset+ `PIPELEX_GATEWAY_API_KEY` would stop being a boot failure with a remediation message and+ become a silently missing backend that resurfaces much later as a model-resolution error.+ The tolerance is therefore scoped to a backend that *declares* its section, which the kit+ ships only for a backend it also ships disabled.+ """+ with pytest.raises(InferenceBackendCredentialsError) as refused:+ _load(+ tmp_path,+ body=LEGACY_GATEWAY_BACKEND_TOML,+ managed_gateway_configs={PipelexBackend.GATEWAY: GatewayConfig(model_specs={}, aws_region="eu-west-1")},+ )++ assert refused.value.key_name == UNSET_VAR+++class TestAManagedBackendWithNoPublishedSection:+ def test_it_is_disabled_rather_than_refused(self, tmp_path: Path) -> None:+ """The config builder already warned by name as it skipped the section; the loader just drops it.++ A mapping that was supplied and simply has no entry for this backend is the user's situation.+ The caller's omission — no mapping at all — keeps its own loud refusal, tested below.+ """+ body = MANAGED_BACKEND_TOML.replace(f"${{{UNSET_VAR}}}", "https://manifold.example.com")++ library = _load(tmp_path, body=body, managed_gateway_configs={})++ assert library.get_inference_backend(backend_name=PipelexBackend.MANIFOLD) is None++ def test_no_managed_configs_at_all_is_the_callers_error(self, tmp_path: Path) -> None:+ """Reachable only by loading the library directly without the configs the boot always builds."""+ body = MANAGED_BACKEND_TOML.replace(f"${{{UNSET_VAR}}}", "https://manifold.example.com")++ with pytest.raises(Exception, match="managed_gateway_configs"):+ _load(tmp_path, body=body, managed_gateway_configs=None)diff --git a/tests/unit/pipelex/cogt/models/test_enforce_gateway_model_membership.py b/tests/unit/pipelex/cogt/models/test_enforce_gateway_model_membership.pynew file mode 100644index 000000000..3a5c6c46c--- /dev/null+++ b/tests/unit/pipelex/cogt/models/test_enforce_gateway_model_membership.py@@ -0,0 +1,294 @@+"""The deck-integrity check for managed gateways, once there can be more than one of them.++The check answers "does the service this handle is routed to actually carry it?", and with two+services live that question only makes sense per service. Two failure shapes are what this module+pins down, because the single-gateway implementation had no way to tell them apart:++- a **union** across the sections would accept a handle routed to the manifold service purely+ because the Portkey-cloud section happens to serve it — a boot that then fails at the first call;+- the same check run twice, once per section, over the *whole* deck would demand that every deck+ handle appear in **both** sections, which no mixed routing profile can satisfy.++The routing profile is what separates them: each per-service pass looks only at the handles the+active profile sends to that service.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.cogt.config_cogt import ModelDeckConfig+from pipelex.cogt.exceptions import GatewayUnknownModelError+from pipelex.cogt.extract.extract_setting import ExtractModelChoice, ExtractSetting+from pipelex.cogt.img_gen.img_gen_job_components import Quality+from pipelex.cogt.img_gen.img_gen_setting import ImgGenModelChoice, ImgGenSetting+from pipelex.cogt.llm.llm_setting import LLMModelChoice, LLMSetting, LLMSettingChoicesDefaults+from pipelex.cogt.llm.thinking_mode import ThinkingMode+from pipelex.cogt.model_backends.backend import PipelexBackend+from pipelex.cogt.model_backends.gateway_config import GatewayConfig+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec+from pipelex.cogt.model_backends.model_type import ModelType+from pipelex.cogt.model_routing.routing_profile import RoutingProfile+from pipelex.cogt.models.model_deck import ModelDeck+from pipelex.cogt.models.model_manager import ModelManager+from pipelex.cogt.search.search_setting import SearchModelChoice, SearchSetting+from pipelex.cogt.usage.cost_category import CostCategory+from pipelex.system.pipelex_service.types import RemoteConfigSource+from pipelex.system.runtime import ProblemReaction++if TYPE_CHECKING:+ from pipelex.cogt.model_backends.model_spec_factory import BackendModelSpecs++BYOK_BACKEND = "xai"+ENABLED_BACKENDS = [PipelexBackend.GATEWAY, PipelexBackend.MANIFOLD, BYOK_BACKEND, PipelexBackend.INTERNAL]++# The handles the fixture deck advertises. Everything not matched by a route lands on the profile's+# default backend, which is the Portkey-cloud service here.+GATEWAY_HANDLE = "gpt-5"+MANIFOLD_HANDLE = "claude-4-sonnet"+BYOK_HANDLE = "grok-3"+EXTRACT_HANDLE = "doc-extract"+IMG_GEN_HANDLE = "img-1"+SEARCH_HANDLE = "web-search"+++def _specs(*model_names: str) -> BackendModelSpecs:+ """A spec map carrying exactly these model names, plus the `defaults` table the check ignores."""+ specs: dict[str, object] = {"defaults": {"model_type": "llm", "sdk": "gateway_completions"}}+ for model_name in model_names:+ specs[model_name] = {"model_id": model_name}+ return specs # pyright: ignore[reportReturnType]+++def _resolved(name: str, *, backend_name: str) -> InferenceModelSpec:+ """A handle the deck build already resolved — what `deck.inference_models` holds.++ Only the key matters to the membership check; the spec is filled in just enough to be a real+ model, and its `backend_name` records which backend the profile matched it to.+ """+ return InferenceModelSpec(+ backend_name=backend_name,+ name=name,+ sdk="gateway_completions",+ model_type=ModelType.LLM,+ model_id=name,+ costs={CostCategory.INPUT: 0.001, CostCategory.OUTPUT: 0.002},+ thinking_mode=ThinkingMode.NONE,+ max_tokens=1000,+ max_prompt_images=None,+ )+++def _make_deck(+ *,+ llm_presets: dict[str, LLMSetting],+ inference_models: dict[str, InferenceModelSpec] | None = None,+ llm_waterfalls: dict[str, list[str]] | None = None,+) -> ModelDeck:+ """A minimal real deck whose only variable part is the LLM presets, mirroring the sibling tests."""+ llm_for_text: LLMModelChoice = GATEWAY_HANDLE+ llm_for_object: LLMModelChoice = GATEWAY_HANDLE+ extract_choice_default: ExtractModelChoice = EXTRACT_HANDLE+ img_gen_choice_default: ImgGenModelChoice = IMG_GEN_HANDLE+ search_choice_default: SearchModelChoice = SEARCH_HANDLE+ return ModelDeck(+ inference_models=inference_models if inference_models is not None else {},+ # LLM+ llm_default_temperature=0.7,+ llm_aliases={},+ llm_waterfalls=llm_waterfalls if llm_waterfalls is not None else {},+ llm_presets=llm_presets,+ llm_choice_defaults=LLMSettingChoicesDefaults(+ default_temperature=0.7,+ for_text=llm_for_text,+ for_object=llm_for_object,+ ),+ # Extract+ extract_aliases={},+ extract_waterfalls={},+ extract_presets={"default": ExtractSetting(model=EXTRACT_HANDLE)},+ extract_choice_default=extract_choice_default,+ # ImgGen+ img_gen_default_quality=Quality.MEDIUM,+ img_gen_aliases={},+ img_gen_waterfalls={},+ img_gen_presets={"default": ImgGenSetting(model=IMG_GEN_HANDLE)},+ img_gen_choice_default=img_gen_choice_default,+ # Search+ search_aliases={},+ search_waterfalls={},+ search_presets={"default": SearchSetting(model=SEARCH_HANDLE)},+ search_choice_default=search_choice_default,+ model_deck_config=ModelDeckConfig(is_model_fallback_enabled=True, missing_presets_reaction=ProblemReaction.NONE),+ )+++def _make_manager(+ *,+ llm_presets: dict[str, LLMSetting] | None = None,+ inference_models: dict[str, InferenceModelSpec] | None = None,+ llm_waterfalls: dict[str, list[str]] | None = None,+) -> ModelManager:+ """A manager holding the fixture deck and the mixed routing profile, with no boot behind it."""+ manager = ModelManager()+ manager.model_deck = _make_deck(+ llm_presets=llm_presets if llm_presets is not None else {},+ inference_models=inference_models,+ llm_waterfalls=llm_waterfalls,+ )+ manager._routing_profile = RoutingProfile( # pyright: ignore[reportPrivateUsage] # ruff: ignore[private-member-access]+ name="mixed",+ description="Portkey's cloud by default, Claude through the manifold service, grok direct",+ default=PipelexBackend.GATEWAY,+ routes={"claude-*": PipelexBackend.MANIFOLD, "grok-*": BYOK_BACKEND},+ )+ return manager+++def _enforce(+ manager: ModelManager,+ *,+ gateway_specs: BackendModelSpecs,+ manifold_specs: BackendModelSpecs,+ source: RemoteConfigSource | None = RemoteConfigSource.FRESH,+) -> None:+ manager._enforce_gateway_model_membership( # pyright: ignore[reportPrivateUsage] # ruff: ignore[private-member-access]+ managed_gateway_configs={+ PipelexBackend.GATEWAY: GatewayConfig(model_specs=gateway_specs, aws_region="eu-west-3"),+ PipelexBackend.MANIFOLD: GatewayConfig(model_specs=manifold_specs),+ },+ gateway_config_source=source,+ enabled_backends=ENABLED_BACKENDS,+ )+++EVERY_DEFAULT_ROUTED_HANDLE = (GATEWAY_HANDLE, EXTRACT_HANDLE, IMG_GEN_HANDLE, SEARCH_HANDLE)+++class TestEnforceGatewayModelMembership:+ def test_each_service_carrying_what_it_is_routed_is_silent(self) -> None:+ """The control: a mixed profile where both sections carry their own share raises nothing."""+ manager = _make_manager(llm_presets={"cheap": LLMSetting(model=MANIFOLD_HANDLE, temperature=0.5)})++ _enforce(+ manager,+ gateway_specs=_specs(*EVERY_DEFAULT_ROUTED_HANDLE),+ manifold_specs=_specs(MANIFOLD_HANDLE),+ )++ def test_a_handle_absent_from_the_service_it_is_routed_to_raises_naming_that_service(self) -> None:+ """The case that must still fail loudly — and the one a union across the sections would miss.++ `claude-4-sonnet` is served by the Portkey-cloud section here, and the profile routes it to+ the manifold service, which does not carry it. Every call would fail; the boot says so.+ """+ manager = _make_manager(llm_presets={"cheap": LLMSetting(model=MANIFOLD_HANDLE, temperature=0.5)})++ with pytest.raises(GatewayUnknownModelError) as refused:+ _enforce(+ manager,+ gateway_specs=_specs(*EVERY_DEFAULT_ROUTED_HANDLE, MANIFOLD_HANDLE),+ manifold_specs=_specs(),+ )++ assert refused.value.model_name == MANIFOLD_HANDLE+ assert refused.value.backend_name == PipelexBackend.MANIFOLD+ assert PipelexBackend.MANIFOLD in str(refused.value), "with two services live, the message has to answer 'which one'"++ def test_a_handle_absent_from_the_other_service_is_not_an_error(self) -> None:+ """A handle legitimately absent from one section is normal, not a contradiction.++ This is what a per-service check run over the whole deck would break: nothing routed to the+ manifold service here, so its empty section is simply never consulted.+ """+ manager = _make_manager()++ _enforce(+ manager,+ gateway_specs=_specs(*EVERY_DEFAULT_ROUTED_HANDLE),+ manifold_specs=_specs(),+ )++ def test_a_handle_routed_to_a_byok_backend_is_not_this_checks_business(self) -> None:+ """Neither managed section carries `grok-3`, and neither is asked to: the profile sends it elsewhere.++ A handle that backend cannot serve either is the generic missing-handle path's problem, and+ it reports it against the backend that was actually asked.+ """+ manager = _make_manager(llm_presets={"fast": LLMSetting(model=BYOK_HANDLE, temperature=0.5)})++ _enforce(+ manager,+ gateway_specs=_specs(*EVERY_DEFAULT_ROUTED_HANDLE),+ manifold_specs=_specs(),+ )++ def test_no_live_source_skips_the_check_entirely(self) -> None:+ """The dummy-specs path: no provenance means there is nothing to validate against."""+ manager = _make_manager(llm_presets={"cheap": LLMSetting(model=MANIFOLD_HANDLE, temperature=0.5)})++ _enforce(manager, gateway_specs=_specs(), manifold_specs=_specs(), source=None)++ @pytest.mark.parametrize("managed_gateway_configs", [None, {}])+ def test_no_managed_config_skips_the_check_entirely(self, managed_gateway_configs: dict[str, GatewayConfig] | None) -> None:+ """A BYOK-only installation reaches this with nothing managed, and must pass straight through."""+ manager = _make_manager(llm_presets={"cheap": LLMSetting(model=MANIFOLD_HANDLE, temperature=0.5)})++ manager._enforce_gateway_model_membership( # pyright: ignore[reportPrivateUsage] # ruff: ignore[private-member-access]+ managed_gateway_configs=managed_gateway_configs,+ gateway_config_source=RemoteConfigSource.FRESH,+ enabled_backends=ENABLED_BACKENDS,+ )+++class TestAWaterfallSpansBackends:+ """A waterfall is "try in order, use whatever works" — and the order may cross backends.++ The per-service filter answers "which candidates is *this* section responsible for", which is+ the right question for the section lookup and the wrong one for `deck.inference_models`. That+ map is built by routing every handle through the *active profile* and keeping the ones whose+ matched backend has a spec, so membership in it already means "resolvable under this profile,+ whichever backend serves it" — exactly what `ModelDeck._resolve_waterfall` consults at runtime.+ """++ def test_a_waterfall_whose_working_fallback_lives_on_another_service_is_not_an_error(self) -> None:+ """The primary is absent from the service it routes to, and the fallback resolves elsewhere.++ `claude-4-sonnet` routes to the manifold service, which carries nothing; `gpt-5` routes to+ the Portkey-cloud one and is already resolved in the deck. At runtime the waterfall walks+ past the first and uses the second, so the boot has nothing to refuse.+ """+ manager = _make_manager(+ llm_presets={"premium": LLMSetting(model="~premium", temperature=0.5)},+ llm_waterfalls={"premium": [MANIFOLD_HANDLE, GATEWAY_HANDLE]},+ inference_models={GATEWAY_HANDLE: _resolved(GATEWAY_HANDLE, backend_name=PipelexBackend.GATEWAY)},+ )++ _enforce(+ manager,+ gateway_specs=_specs(*EVERY_DEFAULT_ROUTED_HANDLE),+ manifold_specs=_specs(),+ )++ def test_a_waterfall_no_backend_can_serve_still_raises(self) -> None:+ """The companion guard: widening the deck half must not make the check stop firing.++ Both entries match `claude-*` and route to the manifold service, neither is in its section,+ and nothing resolved them — so there is no fallback to walk to and the boot says so.+ """+ manager = _make_manager(+ llm_presets={"premium": LLMSetting(model="~premium", temperature=0.5)},+ llm_waterfalls={"premium": [MANIFOLD_HANDLE, "claude-9-unknown"]},+ )++ with pytest.raises(GatewayUnknownModelError) as refused:+ _enforce(+ manager,+ gateway_specs=_specs(*EVERY_DEFAULT_ROUTED_HANDLE),+ manifold_specs=_specs(),+ )++ assert refused.value.model_name == MANIFOLD_HANDLE+ assert refused.value.backend_name == PipelexBackend.MANIFOLDdiff --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.pyindex cf9925d11..b74e519dc 100644--- 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.py@@ -49,7 +49,7 @@ class TestInferenceConfigOverridesEndToEnd:models_manager = ModelManager()models_manager.setup(secrets_provider=EnvSecretsProvider(),- gateway_config=None,+ managed_gateway_configs=None,gateway_config_source=None,needs_inference=False,)diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_client_auth.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_client_auth.pynew file mode 100644index 000000000..0e1a010bf--- /dev/null+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_client_auth.py@@ -0,0 +1,92 @@+"""How the Anthropic SDK client authenticates, per backend.++The anthropic SDK carries its key in `x-api-key`. That is right for Anthropic itself and for the+Anthropic-compatible vendors, and wrong for a backend that fronts the protocol behind a gateway+which authenticates on a header of its own — the Pipelex Manifold service reads `x-pipelex-api-key`+(or an `Authorization` bearer) and never looks at `x-api-key`, so a key left in the SDK's own slot+reaches it as an anonymous request. A backend says which header carries its key with the+`auth_header` extra-config field; these tests pin both paths and the refusal.++This lives in `providers/anthropic/` rather than in the manifold package deliberately: the driver is+shared with the plain BYOK Anthropic backend and outlives the Portkey retirement. The gate is the+backend's own declaration, so a BYOK backend takes the unchanged path.++**The `base_url` here is the origin with no `/v1`, and that is the whole endpoint rule in one+assertion.** `AsyncAnthropic` defaults to `https://api.anthropic.com` and appends `/v1/messages`+itself, unlike the OpenAI and Portkey clients which expect the version segment in `base_url`. A+`/v1`-suffixed endpoint here produces `POST /v1/v1/messages`, which a gateway forwards and a+provider answers with a 200-shaped failure — the class of bug that cost spike 5 a day.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.cogt.model_backends.backend import InferenceBackend+from pipelex.plugins.model_handle import ModelHandle+from pipelex.providers.anthropic.anthropic_exceptions import AnthropicFactoryError+from pipelex.providers.anthropic.anthropic_factory import AnthropicFactory++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++_MANIFOLD_AUTH_HEADER = "x-pipelex-api-key"+_MANIFOLD_ORIGIN = "https://manifold.example.com"+++def _model_handle() -> ModelHandle:+ return ModelHandle(sdk="anthropic", backend="test_backend")+++def _patch_config(mocker: MockerFixture) -> None:+ config = mocker.MagicMock()+ config.inference.transport_max_retries = 2+ mocker.patch("pipelex.providers.anthropic.anthropic_factory.get_config", return_value=config)+++class TestAnthropicClientAuth:+ def test_plain_backend_keeps_the_key_in_the_sdk_slot(self, mocker: MockerFixture) -> None:+ _patch_config(mocker)+ mock_client = mocker.patch("pipelex.providers.anthropic.anthropic_factory.AsyncAnthropic")+ backend = InferenceBackend(name="anthropic", endpoint=None, api_key="sk-ant-test")++ AnthropicFactory.make_anthropic_client(model_handle=_model_handle(), backend=backend)++ kwargs = mock_client.call_args.kwargs+ assert kwargs["api_key"] == "sk-ant-test"+ assert "default_headers" not in kwargs++ def test_auth_header_backend_moves_the_key_into_that_header(self, mocker: MockerFixture) -> None:+ _patch_config(mocker)+ mock_client = mocker.patch("pipelex.providers.anthropic.anthropic_factory.AsyncAnthropic")+ backend = InferenceBackend(+ name="pipelex_manifold",+ endpoint=_MANIFOLD_ORIGIN,+ api_key="manifold-service-token",+ extra_config={"auth_header": _MANIFOLD_AUTH_HEADER},+ )++ AnthropicFactory.make_anthropic_client(model_handle=_model_handle(), backend=backend)++ kwargs = mock_client.call_args.kwargs+ assert kwargs["default_headers"] == {_MANIFOLD_AUTH_HEADER: "manifold-service-token"}+ # The SDK refuses an empty api_key, so the slot holds a placeholder rather than the token.+ assert kwargs["api_key"] != "manifold-service-token"+ assert kwargs["api_key"]+ # The origin, not the origin plus `/v1`: this SDK appends its own `/v1/messages`.+ assert kwargs["base_url"] == _MANIFOLD_ORIGIN++ def test_auth_header_without_a_key_is_refused(self, mocker: MockerFixture) -> None:+ _patch_config(mocker)+ mocker.patch("pipelex.providers.anthropic.anthropic_factory.AsyncAnthropic")+ backend = InferenceBackend(+ name="pipelex_manifold",+ endpoint=_MANIFOLD_ORIGIN,+ api_key=None,+ extra_config={"auth_header": _MANIFOLD_AUTH_HEADER},+ )++ with pytest.raises(AnthropicFactoryError, match="auth_header"):+ AnthropicFactory.make_anthropic_client(model_handle=_model_handle(), backend=backend)diff --git a/tests/unit/pipelex/providers/gateway/test_extract_gateway_metadata.py b/tests/unit/pipelex/providers/gateway/test_extract_gateway_metadata.pyindex dec6acda2..24dc8003d 100644--- a/tests/unit/pipelex/providers/gateway/test_extract_gateway_metadata.py+++ b/tests/unit/pipelex/providers/gateway/test_extract_gateway_metadata.py@@ -2,13 +2,20 @@Distills a Portkey/Gateway SDK exception into a ``ProviderErrorMetadata``.``APIStatusError`` subclasses carry ``status_code``, ``response`` (httpx),-and ``body`` (pre-parsed dict). ``APITimeoutError`` / ``APIConnectionError``-carry only a request; status fields come back as ``None``.+and ``body``. ``APITimeoutError`` / ``APIConnectionError`` carry only a+request; status fields come back as ``None``.++``body`` is a pre-parsed dict only on the paths that bypass Portkey's own+exception factory; the factory itself puts the message *string* there, so the+error code has to be recovered from the response. Both shapes are pinned below."""from __future__ import annotations+import json+import httpx+from portkey_ai import Portkeyfrom portkey_ai.api_resources import exceptions as portkey_excfrom pipelex.cogt.inference.error_classification import extract_gateway_metadata@@ -52,8 +59,22 @@ class TestExtractGatewayMetadata:assert metadata.retry_after_seconds == 9.0def test_extracts_provider_error_code_from_body(self) -> None:+ """``code`` is read before ``type``, which is the opposite of the vendor-facing precedence.++ The gateway is ours, and it puts the *specific* code in ``code`` and a+ generic OpenAI-shaped bucket in ``type`` — every refusal on its native+ ``/v1/pipelex/*`` routes carries ``type: "invalid_request_error"``. Reading+ ``type`` first therefore reports that one bucket for the whole contract+ vocabulary and no ``pipelex_*`` code ever reaches the classifier. Anthropic+ keeps the other precedence because its error section carries no ``code``.+ """exc = _make_status_error(400, body={"error": {"type": "invalid_request_error", "code": "missing_field"}})metadata = extract_gateway_metadata(exc)+ assert metadata.provider_error_code == "missing_field"++ def test_falls_back_to_type_when_the_body_carries_no_code(self) -> None:+ exc = _make_status_error(400, body={"error": {"type": "invalid_request_error"}})+ metadata = extract_gateway_metadata(exc)assert metadata.provider_error_code == "invalid_request_error"def test_handles_connection_error_without_response(self) -> None:@@ -63,3 +84,50 @@ class TestExtractGatewayMetadata:assert metadata.sdk_exception_type == "APIConnectionError"assert metadata.status_code is Noneassert metadata.request_id is None+++class TestTheCodeWhenPortkeyDiscardsThePayload:+ """``exc.body`` is not the payload on the SDK's own factory — the response still is."""++ @staticmethod+ def _as_the_sdk_raises_it(status_code: int, payload: dict[str, object]) -> BaseException:+ """Build the exception through Portkey's own factory, not through its constructor.++ The constructor accepts whatever ``body`` it is handed; only the factory+ reproduces the string ``body`` the Extract step actually receives.+ """+ request = httpx.Request("POST", "https://api.portkey.ai/v1/chat/completions")+ response = httpx.Response(+ status_code=status_code,+ request=request,+ content=json.dumps(payload).encode(),+ headers={"content-type": "application/json"},+ )+ client = Portkey(api_key="unused-in-this-test", base_url="https://api.portkey.ai/v1")+ return client._make_status_error_from_response(request=request, response=response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ def test_the_code_is_recovered_from_the_response_body(self) -> None:+ """Portkey sets ``body`` to ``json.loads(text)["error"]["message"]`` — a string, not the document."""+ exc = self._as_the_sdk_raises_it(400, {"error": {"message": "refused", "code": "pig-11"}})++ assert isinstance(getattr(exc, "body", None), str)+ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code == "pig-11"+ assert isinstance(metadata.body, dict)++ def test_a_response_that_is_not_json_leaves_the_code_unset(self) -> None:+ request = httpx.Request("POST", "https://api.portkey.ai/v1/chat/completions")+ response = httpx.Response(status_code=502, request=request, content=b"<html>bad gateway</html>")+ exc = portkey_exc.APIStatusError(message="error", request=request, response=response, body=None)++ metadata = extract_gateway_metadata(exc)++ assert metadata.provider_error_code is None+ assert metadata.status_code == 502++ def test_a_dict_body_still_wins_over_the_response(self) -> None:+ """The vendored-OpenAI fallback paths hand a real dict here — it must not be re-parsed away."""+ exc = _make_status_error(400, body={"error": {"code": "pig-07"}})++ assert extract_gateway_metadata(exc).provider_error_code == "pig-07"diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_clients.py b/tests/unit/pipelex/providers/manifold/test_manifold_clients.pynew file mode 100644index 000000000..d320efd5e--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_clients.py@@ -0,0 +1,137 @@+"""What each manifold client is handed at construction.++Three SDKs sit under this package and they do not agree about `base_url`: `AsyncOpenAI` and+`AsyncPortkey` both expect the version segment in it (their own defaults are+`https://api.openai.com/v1` and `https://api.portkey.ai/v1`), while `AsyncAnthropic` defaults to+`https://api.anthropic.com` and appends `/v1/messages` itself. The origin rule composes with all+three only because each factory appends what its SDK expects — so these tests read the arguments the+factory actually passed rather than trusting that it did.++The second property pinned here is negative and matters more: **nothing about routing is sent.** The+token travels in the service's own header, the OpenAI `Authorization` slot holds a placeholder the+gateway never reads, and no config id or provider name appears anywhere.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import pytest++from pipelex.cogt.model_backends.backend import InferenceBackend+from pipelex.plugins.model_handle import ModelHandle+from pipelex.providers.manifold.manifold_completions_factory import ManifoldCompletionsFactory+from pipelex.providers.manifold.manifold_constants import ManifoldSdk+from pipelex.providers.manifold.manifold_exceptions import ManifoldFactoryError+from pipelex.providers.manifold.manifold_factory import ManifoldFactory+from pipelex.providers.manifold.manifold_responses_factory import ManifoldResponsesFactory++if TYPE_CHECKING:+ from collections.abc import Mapping++ from pytest_mock import MockerFixture++_ORIGIN = "https://manifold.example.com"+_TOKEN = "manifold-service-token"+_AUTH_HEADER = "x-pipelex-api-key"++# Anything that would tell the service who should serve the model. None of it belongs on this path:+# the model id in the body is the whole of the routing decision, and the gateway refuses a client+# that tries to make it (`pig-03`).+_ROUTING_MARKERS = ("x-portkey-config", "x-portkey-provider", "x-portkey-virtual-key", "x-portkey-custom-host")+++def _backend() -> InferenceBackend:+ return InferenceBackend(name="pipelex_manifold", endpoint=_ORIGIN, api_key=_TOKEN)+++def _handle(sdk: ManifoldSdk) -> ModelHandle:+ return ModelHandle(sdk=str(sdk), backend="pipelex_manifold")+++def _patch_config(mocker: MockerFixture, module: str) -> None:+ config = mocker.MagicMock()+ config.inference.transport_max_retries = 3+ mocker.patch(f"{module}.get_config", return_value=config)+++def _assert_no_routing(kwargs: Mapping[str, Any]) -> None:+ rendered = str(kwargs).lower()+ for marker in _ROUTING_MARKERS:+ assert marker not in rendered, f"the manifold client was handed a routing marker: {marker}"+++class TestManifoldCompletionsClient:+ def test_the_client_gets_the_origin_plus_v1_and_the_token_in_the_service_header(self, mocker: MockerFixture) -> None:+ _patch_config(mocker, "pipelex.providers.manifold.manifold_completions_factory")+ mock_openai = mocker.patch("openai.AsyncOpenAI")++ ManifoldCompletionsFactory.make_openai_client_for_completions(_handle(ManifoldSdk.COMPLETIONS), backend=_backend())++ kwargs = mock_openai.call_args.kwargs+ assert kwargs["base_url"] == f"{_ORIGIN}/v1"+ assert kwargs["default_headers"] == {_AUTH_HEADER: _TOKEN}+ assert kwargs["max_retries"] == 3+ # The SDK has refused an empty api_key since 2.34.0, so the slot holds a placeholder rather+ # than the token — sending the token twice would put it somewhere the gateway does not read.+ assert kwargs["api_key"] != _TOKEN+ assert kwargs["api_key"]+ _assert_no_routing(kwargs)++ def test_a_handle_from_another_sdk_set_is_refused(self, mocker: MockerFixture) -> None:+ _patch_config(mocker, "pipelex.providers.manifold.manifold_completions_factory")+ mocker.patch("openai.AsyncOpenAI")++ with pytest.raises(ManifoldFactoryError):+ ManifoldCompletionsFactory.make_openai_client_for_completions(_handle(ManifoldSdk.RESPONSES), backend=_backend())+++class TestManifoldResponsesClient:+ def test_the_client_gets_the_origin_plus_v1_and_the_token_in_the_service_header(self, mocker: MockerFixture) -> None:+ _patch_config(mocker, "pipelex.providers.manifold.manifold_responses_factory")+ mock_openai = mocker.patch("openai.AsyncOpenAI")++ ManifoldResponsesFactory.make_openai_client_for_responses(_handle(ManifoldSdk.RESPONSES), backend=_backend())++ kwargs = mock_openai.call_args.kwargs+ assert kwargs["base_url"] == f"{_ORIGIN}/v1"+ assert kwargs["default_headers"] == {_AUTH_HEADER: _TOKEN}+ assert kwargs["api_key"] != _TOKEN+ _assert_no_routing(kwargs)++ def test_a_handle_from_another_sdk_set_is_refused(self, mocker: MockerFixture) -> None:+ _patch_config(mocker, "pipelex.providers.manifold.manifold_responses_factory")+ mocker.patch("openai.AsyncOpenAI")++ with pytest.raises(ManifoldFactoryError):+ ManifoldResponsesFactory.make_openai_client_for_responses(_handle(ManifoldSdk.COMPLETIONS), backend=_backend())+++class TestManifoldImageClient:+ def test_the_vendor_client_is_built_under_the_same_endpoint_rule(self, mocker: MockerFixture) -> None:+ """`AsyncPortkey` is a beta-only dependency of the image path, and it obeys the same rule.++ The vendor SDK's own `base_url` default is Portkey's cloud, so the value passed here is the+ whole of what keeps this client pointed at our service.+ """+ mock_portkey = mocker.patch("portkey_ai.AsyncPortkey")++ ManifoldFactory.make_portkey_client(_backend())++ kwargs = mock_portkey.call_args.kwargs+ assert kwargs["base_url"] == f"{_ORIGIN}/v1"+ assert kwargs["api_key"] == _TOKEN+ _assert_no_routing(kwargs)++ def test_debug_is_read_from_the_backend_and_from_nothing_else(self, mocker: MockerFixture) -> None:+ """One configuration block must not govern two services.++ The Portkey-path sibling routes this through the telemetry manager's `pipelex_gateway.portkey`+ knobs; reading those here would make a change meant for the cloud path silently alter the+ manifold one.+ """+ mocker.patch("portkey_ai.AsyncPortkey")+ backend = InferenceBackend(name="pipelex_manifold", endpoint=_ORIGIN, api_key=_TOKEN, extra_config={"debug": True})++ assert ManifoldFactory.is_debug_enabled(backend) is True+ assert ManifoldFactory.is_debug_enabled(_backend()) is Falsediff --git a/tests/unit/pipelex/providers/manifold/test_manifold_completions_messages.py b/tests/unit/pipelex/providers/manifold/test_manifold_completions_messages.pynew file mode 100644index 000000000..f8a8e6028--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_completions_messages.py@@ -0,0 +1,178 @@+"""`ManifoldCompletionsFactory.make_simple_messages` — the override that is a copy on purpose.++Documents travel to a Pipelex-operated gateway as a `ChatCompletionContentPartImageParam` holding a+data URL, not as the OpenAI file part the base class sends: the gateway translates that part into+whatever document format the provider it picked actually wants, and it cannot translate a file part.+The Portkey-path factory makes the same move for the same reason — it is the same gateway codebase+on the other end — and the manifold factory carries its **own copy** rather than subclassing it, so+that retiring the Portkey package stays a deletion.++**The last test here is the one that makes that duplication safe.** A copy that silently drifts from+its original is worse than either sharing or diverging deliberately, and nothing in the package+would notice: the two factories are never used in the same process. Comparing their output is the+only place the equality is stated. It imports from `providers/gateway/` — which the *package* must+not do — and that is correct for a test whose whole subject is the relationship between the two; it+is deleted along with the path it compares against.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import pytest++from pipelex.cogt.image.prompt_image import PromptImageDetail+from pipelex.providers.manifold.manifold_completions_factory import ManifoldCompletionsFactory+from pipelex.tools.misc.filetype_utils import FileType+from pipelex.tools.uri.prepared_file import PreparedFileBase64, PreparedFileHttpUrl, PreparedFileLocalPath++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++_FACTORY_NAMESPACE = "pipelex.providers.manifold.manifold_completions_factory"++_PNG_FILE_TYPE = FileType(extension="png", mime="image/png")+_PDF_FILE_TYPE = FileType(extension="pdf", mime="application/pdf")+++def _make_llm_job(+ mocker: MockerFixture,+ *,+ system_text: str | None = None,+ user_text: str | None = None,+ has_images: bool = False,+ has_documents: bool = False,+ image_detail: PromptImageDetail | None = None,+) -> Any:+ job = mocker.MagicMock()+ job.llm_prompt.system_text = system_text+ job.llm_prompt.user_text = user_text+ job.llm_prompt.user_images = [mocker.MagicMock()] if has_images else []+ job.llm_prompt.user_documents = [mocker.MagicMock()] if has_documents else []+ job.job_params.image_detail = image_detail+ return job++[email protected](loop_scope="class")+class TestManifoldCompletionsMessages:+ async def test_system_and_user_text(self, mocker: MockerFixture) -> None:+ factory = ManifoldCompletionsFactory(is_http_url_enabled=False)+ llm_job = _make_llm_job(mocker, system_text="You are concise.", user_text="Summarize this.")++ messages = await factory.make_simple_messages(llm_job=llm_job)++ assert messages == [+ {"role": "system", "content": "You are concise."},+ {"role": "user", "content": [{"type": "text", "text": "Summarize this."}]},+ ]++ async def test_a_document_travels_as_an_image_url_data_url(self, mocker: MockerFixture) -> None:+ """The whole reason this override exists, and the reason it is not the base class's."""+ factory = ManifoldCompletionsFactory(is_http_url_enabled=False)+ llm_job = _make_llm_job(mocker, user_text="Read this doc.", has_documents=True)+ prep = mocker.patch(+ f"{_FACTORY_NAMESPACE}.prep_prompt_documents",+ new_callable=mocker.AsyncMock,+ return_value=[PreparedFileBase64(base64_data="UERG", file_type=_PDF_FILE_TYPE)],+ )++ messages = await factory.make_simple_messages(llm_job=llm_job)++ # Documents are base64 whatever the factory's images setting allows: an http URL here would+ # reach the gateway as a link it does not fetch.+ prep.assert_awaited_once_with(prompt_documents=llm_job.llm_prompt.user_documents, is_http_url_enabled=False)+ assert messages == [+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "Read this doc."},+ {"type": "image_url", "image_url": {"url": "data:application/pdf;base64,UERG", "detail": "auto"}},+ ],+ },+ ]++ @pytest.mark.parametrize(+ ("image_detail", "expected_detail"),+ [(None, "auto"), (PromptImageDetail.HIGH, "high"), (PromptImageDetail.LOW, "low")],+ )+ async def test_images_become_image_url_parts_at_the_requested_detail(+ self,+ mocker: MockerFixture,+ image_detail: PromptImageDetail | None,+ expected_detail: str,+ ) -> None:+ factory = ManifoldCompletionsFactory(is_http_url_enabled=False)+ llm_job = _make_llm_job(mocker, user_text="Look at these.", has_images=True, image_detail=image_detail)+ prep = mocker.patch(+ f"{_FACTORY_NAMESPACE}.prep_prompt_images",+ new_callable=mocker.AsyncMock,+ return_value=[PreparedFileBase64(base64_data="QUJD", file_type=_PNG_FILE_TYPE)],+ )++ messages = await factory.make_simple_messages(llm_job=llm_job)++ prep.assert_awaited_once_with(prompt_images=llm_job.llm_prompt.user_images, is_http_url_enabled=False)+ assert messages == [+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "Look at these."},+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,QUJD", "detail": expected_detail}},+ ],+ },+ ]++ @pytest.mark.parametrize(+ ("prepped_document", "expected_match"),+ [+ (PreparedFileHttpUrl(url="https://docs.example/file.pdf"), "PreparedFileHttpUrl is not supported for documents"),+ (PreparedFileLocalPath(path="some/local/file.pdf"), "PreparedFileLocalPath is not supported for documents"),+ ],+ ids=["http-url-document", "local-path-document"],+ )+ async def test_a_document_that_is_not_bytes_is_refused(+ self,+ mocker: MockerFixture,+ prepped_document: PreparedFileHttpUrl | PreparedFileLocalPath,+ expected_match: str,+ ) -> None:+ factory = ManifoldCompletionsFactory(is_http_url_enabled=False)+ llm_job = _make_llm_job(mocker, user_text="text", has_documents=True)+ mocker.patch(f"{_FACTORY_NAMESPACE}.prep_prompt_documents", new_callable=mocker.AsyncMock, return_value=[prepped_document])++ with pytest.raises(TypeError, match=expected_match):+ await factory.make_simple_messages(llm_job=llm_job)++[email protected](loop_scope="class")+class TestManifoldCompletionsMessagesMatchTheGatewayPath:+ """The copy has not drifted from the original it was taken from.++ Delete this class when the Portkey path is deleted; until then it is the only statement anywhere+ that the two overrides agree, and they must, because they talk to the same gateway codebase.+ """++ async def test_both_factories_build_the_same_messages_for_the_same_prompt(self, mocker: MockerFixture) -> None:+ from pipelex.providers.gateway.gateway_completions_factory import GatewayCompletionsFactory # ruff: ignore[import-outside-top-level]++ gateway_namespace = "pipelex.providers.gateway.gateway_completions_factory"+ prepped_images = [PreparedFileBase64(base64_data="QUJD", file_type=_PNG_FILE_TYPE)]+ prepped_documents = [PreparedFileBase64(base64_data="UERG", file_type=_PDF_FILE_TYPE)]+ for namespace in (_FACTORY_NAMESPACE, gateway_namespace):+ mocker.patch(f"{namespace}.prep_prompt_images", new_callable=mocker.AsyncMock, return_value=prepped_images)+ mocker.patch(f"{namespace}.prep_prompt_documents", new_callable=mocker.AsyncMock, return_value=prepped_documents)++ def _job() -> Any:+ return _make_llm_job(+ mocker,+ system_text="You are concise.",+ user_text="Read these.",+ has_images=True,+ has_documents=True,+ image_detail=PromptImageDetail.HIGH,+ )++ manifold_messages = await ManifoldCompletionsFactory(is_http_url_enabled=False).make_simple_messages(llm_job=_job())+ gateway_messages = await GatewayCompletionsFactory(is_http_url_enabled=False).make_simple_messages(llm_job=_job())++ assert manifold_messages == gateway_messagesdiff --git a/tests/unit/pipelex/providers/manifold/test_manifold_endpoint_rule.py b/tests/unit/pipelex/providers/manifold/test_manifold_endpoint_rule.pynew file mode 100644index 000000000..e8d26357a--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_endpoint_rule.py@@ -0,0 +1,66 @@+"""The endpoint rule, and the fallback that must not exist.++The backend declares the Pipelex Manifold service's **origin** — scheme, host and port, with no+version segment — and each client appends what its own SDK expects beneath it. The rule is normative+rather than advisory because getting it wrong is not loud: a `/v1`-suffixed endpoint under the+Anthropic SDK produces `POST /v1/v1/messages`, which a gateway forwards and a provider answers with+a 200-shaped failure.++**The absent-endpoint case is the one worth a test of its own.** The Portkey-path sibling reads+`backend.endpoint or PORTKEY_GATEWAY_URL`, which is correct there — an unset endpoint means "use the+vendor's cloud". The same line on this path would mean that an empty-resolving+`PIPELEX_MANIFOLD_ENDPOINT` silently builds a client aimed at `api.portkey.ai` carrying the+*manifold* service token: a live billable request to the wrong vendor, with nothing anywhere+reporting it. There is no symptom to notice, which is why the refusal is pinned here.+"""++from __future__ import annotations++import pytest++from pipelex.cogt.model_backends.backend import InferenceBackend+from pipelex.providers.manifold.manifold_exceptions import ManifoldCredentialsError, ManifoldEndpointError+from pipelex.providers.manifold.manifold_factory import ManifoldFactory++_ORIGIN = "https://manifold.example.com"+_TOKEN = "manifold-service-token"+++def _backend(*, endpoint: str | None = _ORIGIN, api_key: str | None = _TOKEN) -> InferenceBackend:+ return InferenceBackend(name="pipelex_manifold", endpoint=endpoint, api_key=api_key)+++class TestManifoldEndpointRule:+ def test_origin_is_returned_as_declared(self) -> None:+ assert ManifoldFactory.get_origin(_backend()) == _ORIGIN++ @pytest.mark.parametrize("declared", [f"{_ORIGIN}/", f"{_ORIGIN}///", f" {_ORIGIN} "])+ def test_a_trailing_slash_or_surrounding_space_is_forgiven(self, declared: str) -> None:+ """The one shape of a correct answer a human types by accident, normalized rather than refused."""+ assert ManifoldFactory.get_origin(_backend(endpoint=declared)) == _ORIGIN++ def test_the_version_segment_is_appended_by_the_factory_not_the_operator(self) -> None:+ assert ManifoldFactory.get_base_url(_backend()) == f"{_ORIGIN}/v1"++ @pytest.mark.parametrize("declared", [None, "", " ", "/"], ids=["unset", "empty", "blank", "slash-only"])+ def test_an_absent_endpoint_is_refused_and_never_defaulted(self, declared: str | None) -> None:+ with pytest.raises(ManifoldEndpointError) as exc_info:+ ManifoldFactory.get_origin(_backend(endpoint=declared))++ # The vendor's cloud must appear nowhere in the outcome — neither as a value nor as a hint.+ assert "portkey" not in exc_info.value.message.lower()+ assert "PIPELEX_MANIFOLD_ENDPOINT" in exc_info.value.message++ def test_an_absent_api_key_is_refused_by_name(self) -> None:+ with pytest.raises(ManifoldCredentialsError, match="PIPELEX_MANIFOLD_API_KEY"):+ ManifoldFactory.get_api_key(_backend(api_key=None))++ def test_the_only_header_about_us_is_the_service_token(self) -> None:+ """One header, no routing.++ The manifold dialect says nothing on the wire about which provider should serve a model —+ the service decides that from the model id in the body and refuses a client that tries to+ say otherwise. Asserting the whole dict rather than one key is what makes a header added+ later a red test rather than a silent widening.+ """+ assert ManifoldFactory.make_auth_headers(_backend()) == {"x-pipelex-api-key": _TOKEN}diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_extract_worker.py b/tests/unit/pipelex/providers/manifold/test_manifold_extract_worker.pynew file mode 100644index 000000000..f2342e5a3--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_extract_worker.py@@ -0,0 +1,208 @@+"""The extract worker's three invisible failure modes.++**The usage translation.** The native route reports honest counts (`usage.pages`) and the runtime's+cost model is per million tokens. Untranslated, `nb_tokens_by_category` simply stays empty — no+exception, no warning — and the job reports a cost of zero. There is nothing to notice, which is why+it is pinned here against the figure the Portkey path reports for the same work.++**The withdrawn parameters.** `ExtractJobParams` carries fields the frozen contract deliberately+does not, and the gateway refuses them at *any* value including their own defaults. A worker that+reached for `model_dump()` would send `should_caption_images=false` and be refused — at request+time, in production, with a message about a parameter nobody meant to send.++**The input form.** Which one a model takes follows from what the catalog says, not from a list of+model names kept in step by hand: a web-page extractor is handed the page's own URL, everything else+is handed the bytes inline. The gateway holds no credentials for our storage, so a local path or a+`pipelex-storage://` URI must become bytes on this side.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import pytest++from pipelex.cogt.extract.exceptions import ExtractInputError+from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory+from pipelex.providers.manifold.manifold_extract_worker import MANIFOLD_UNIT_TOKENS, ManifoldExtractWorker++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++_PDF_BYTES_URL = "data:application/pdf;base64,JVBERi0xLjQK"+++def _make_worker(+ mocker: MockerFixture,+ *,+ is_web_page_supported: bool = False,+ response_body: dict[str, Any] | None = None,+) -> ManifoldExtractWorker:+ worker = object.__new__(ManifoldExtractWorker)+ model = mocker.MagicMock()+ model.model_id = "adi/prebuilt-layout"+ model.name = "azure-document-intelligence"+ model.desc = "test-manifold-extract"+ model.is_web_page_supported_for_extract = is_web_page_supported+ worker.inference_model = model+ client = mocker.MagicMock()+ client.post_json = mocker.AsyncMock(return_value=response_body if response_body is not None else {"pages": {}, "usage": {"pages": 3}})+ worker.client = client+ return worker+++def _post_json(worker: ManifoldExtractWorker) -> Any:+ """The stand-in for the native client, as `Any` so its mock attributes typecheck."""+ return worker.client.post_json+++def _make_extract_job(mocker: MockerFixture, *, document_uri: str | None = None, image_uri: str | None = None) -> Any:+ job = mocker.MagicMock()+ job.extract_input.document_uri = document_uri+ job.extract_input.image_uri = image_uri+ job.job_params.max_nb_images = None+ job.job_params.render_js = None+ job.job_params.include_raw_html = None+ job.job_report.extract_tokens_usage = None+ return job++[email protected](loop_scope="class")+class TestManifoldExtractRequestBody:+ async def test_the_withdrawn_parameters_are_absent_rather_than_sent_at_their_defaults(self, mocker: MockerFixture) -> None:+ """`should_caption_images=false` is refused by the gateway exactly as loudly as `true` is."""+ worker = _make_worker(mocker)+ mocker.patch(+ "pipelex.providers.manifold.manifold_extract_worker.make_base64_url_from_any_uri",+ new_callable=mocker.AsyncMock,+ return_value=_PDF_BYTES_URL,+ )+ mocker.patch("pipelex.providers.manifold.manifold_extract_worker.get_storage_provider")++ await worker._extract_pages(_make_extract_job(mocker, document_uri="/local/report.pdf")) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ body = _post_json(worker).call_args.kwargs["body"]+ rendered = str(body)+ for withdrawn in ("image_min_size", "should_caption_images", "should_include_page_views", "page_views_dpi"):+ assert withdrawn not in rendered, f"the withdrawn parameter '{withdrawn}' reached the wire"++ async def test_an_unset_optional_parameter_is_omitted_rather_than_sent_as_null(self, mocker: MockerFixture) -> None:+ """The gateway refuses `render_js` on a provider that cannot honour it, null included."""+ worker = _make_worker(mocker)+ mocker.patch(+ "pipelex.providers.manifold.manifold_extract_worker.make_base64_url_from_any_uri",+ new_callable=mocker.AsyncMock,+ return_value=_PDF_BYTES_URL,+ )+ mocker.patch("pipelex.providers.manifold.manifold_extract_worker.get_storage_provider")++ await worker._extract_pages(_make_extract_job(mocker, document_uri="/local/report.pdf")) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ body = _post_json(worker).call_args.kwargs["body"]+ assert body["params"] == {}+ assert body["input"] == {"document_uri": _PDF_BYTES_URL}+ assert body["model"] == "adi/prebuilt-layout"++ async def test_a_web_page_model_is_handed_the_url_itself(self, mocker: MockerFixture) -> None:+ """The gateway fetches `https:` on this path; turning the page into bytes here would fetch it twice."""+ worker = _make_worker(mocker, is_web_page_supported=True)+ fetch = mocker.patch(+ "pipelex.providers.manifold.manifold_extract_worker.make_base64_url_from_any_uri",+ new_callable=mocker.AsyncMock,+ )++ await worker._extract_pages(_make_extract_job(mocker, document_uri="https://example.com/article")) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ body = _post_json(worker).call_args.kwargs["body"]+ assert body["input"] == {"document_uri": "https://example.com/article"}+ fetch.assert_not_awaited()++ async def test_a_non_web_page_model_is_handed_the_bytes_inline(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)+ fetch = mocker.patch(+ "pipelex.providers.manifold.manifold_extract_worker.make_base64_url_from_any_uri",+ new_callable=mocker.AsyncMock,+ return_value=_PDF_BYTES_URL,+ )+ mocker.patch("pipelex.providers.manifold.manifold_extract_worker.get_storage_provider")++ await worker._extract_pages(_make_extract_job(mocker, document_uri="pipelex-storage://bucket/report.pdf")) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ body = _post_json(worker).call_args.kwargs["body"]+ assert body["input"] == {"document_uri": _PDF_BYTES_URL}+ fetch.assert_awaited_once()++ async def test_a_web_page_model_with_no_document_uri_is_refused_by_name(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker, is_web_page_supported=True)++ with pytest.raises(ExtractInputError, match="document_uri"):+ await worker._extract_pages(_make_extract_job(mocker, image_uri="file:///local/scan.png")) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ async def test_no_input_at_all_is_refused(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)+ mocker.patch("pipelex.providers.manifold.manifold_extract_worker.get_storage_provider")++ with pytest.raises(ExtractInputError):+ await worker._extract_pages(_make_extract_job(mocker)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++[email protected](loop_scope="class")+class TestManifoldExtractUsageTranslation:+ async def test_pages_become_megatokens_in_both_categories(self, mocker: MockerFixture) -> None:+ """The figure the Portkey path reports for the same work, from a different unit.++ The costume reports `usage.prompt_tokens = pages * 1_000_000`; the native route reports+ `usage.pages = N`. Both must price the same, or phase 4's mixed-profile comparison means+ nothing. Both categories are filled because that is what the abstract worker's own fallback+ produces.+ """+ worker = _make_worker(mocker)+ mocker.patch(+ "pipelex.providers.manifold.manifold_extract_worker.make_base64_url_from_any_uri",+ new_callable=mocker.AsyncMock,+ return_value=_PDF_BYTES_URL,+ )+ mocker.patch("pipelex.providers.manifold.manifold_extract_worker.get_storage_provider")+ job = _make_extract_job(mocker, document_uri="/local/report.pdf")+ usage = mocker.MagicMock()+ job.job_report.extract_tokens_usage = usage++ await worker._extract_pages(job) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert usage.nb_tokens_by_category == {+ TokenCategory.INPUT: 3 * MANIFOLD_UNIT_TOKENS,+ TokenCategory.OUTPUT: 3 * MANIFOLD_UNIT_TOKENS,+ }++ @pytest.mark.parametrize(+ "response_body",+ [+ {"pages": {}},+ {"pages": {}, "usage": None},+ {"pages": {}, "usage": {}},+ {"pages": {}, "usage": {"pages": "three"}},+ ],+ ids=["no-usage", "null-usage", "empty-usage", "non-numeric-pages"],+ )+ async def test_a_usage_block_the_route_did_not_send_leaves_the_abstract_fallback_in_charge(+ self,+ mocker: MockerFixture,+ response_body: dict[str, Any],+ ) -> None:+ """Silence here is correct: `ExtractWorkerAbstract` counts the pages it received instead."""+ worker = _make_worker(mocker, response_body=response_body)+ mocker.patch(+ "pipelex.providers.manifold.manifold_extract_worker.make_base64_url_from_any_uri",+ new_callable=mocker.AsyncMock,+ return_value=_PDF_BYTES_URL,+ )+ mocker.patch("pipelex.providers.manifold.manifold_extract_worker.get_storage_provider")+ job = _make_extract_job(mocker, document_uri="/local/report.pdf")+ usage = mocker.MagicMock()+ empty_categories: NbTokensByCategoryDict = {}+ usage.nb_tokens_by_category = empty_categories+ job.job_report.extract_tokens_usage = usage++ await worker._extract_pages(job) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert usage.nb_tokens_by_category == {}diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_img_gen_worker.py b/tests/unit/pipelex/providers/manifold/test_manifold_img_gen_worker.pynew file mode 100644index 000000000..404875a06--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_img_gen_worker.py@@ -0,0 +1,188 @@+"""The image worker's escape paths — the ones that re-bill a generation if they leak.++The HTTP request succeeds in every test here; it is the *body* that is wrong. A raw exception at+this point is neither a `PipelexError` nor annotated with the model, so it slips past the Temporal+error bridge (`convert_pipelex_errors`), gets marked retryable, and resubmits a non-idempotent image+generation — the user pays twice for one picture.++**The `JSONDecodeError` arm is the one with no symptom.** A 2xx carrying an intermediary's HTML+error page makes the SDK's own decode raise, and `json.JSONDecodeError` is not an `APIError`, so it+falls straight through the `except (portkey_exceptions.APIError, portkey_vendored_openai.APIError)`+arm that catches everything else. Nothing about the code reads as missing a case.+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++import httpx+import pytest+from portkey_ai.api_resources import exceptions as portkey_exc++from pipelex.cogt.exceptions import ImgGenGenerationError, InferenceErrorCategory+from pipelex.cogt.inference.error_classification import UserActionKind+from pipelex.providers.manifold.manifold_img_gen_worker import ManifoldImgGenWorker++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++# A one-pixel PNG, so the success path reaches the real image decoding rather than stopping earlier.+_PNG_1PX = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="++_AZURE_GPT_IMAGE_BODY = {+ "data": [{"b64_json": _PNG_1PX}],+ "size": "1024x1024",+ "output_format": "png",+ "usage": {"input_tokens": 11, "output_tokens": 22},+}+++def _make_worker(mocker: MockerFixture) -> ManifoldImgGenWorker:+ worker = object.__new__(ManifoldImgGenWorker)+ model = mocker.MagicMock()+ model.model_id = "gpt-image-1"+ model.name = "gpt-image-1"+ model.desc = "test-manifold-img-gen"+ model.rules = mocker.MagicMock()+ worker.inference_model = model+ client = mocker.MagicMock()+ client.images.generate = mocker.AsyncMock()+ client.images.edit = mocker.AsyncMock()+ worker.portkey_client = client+ return worker+++def _images(worker: ManifoldImgGenWorker) -> Any:+ """The stand-in for the vendor client's Images resource, as `Any` so its mocks typecheck."""+ return worker.portkey_client.images+++def _make_img_gen_job(mocker: MockerFixture) -> Any:+ job = mocker.MagicMock()+ job.img_gen_prompt.positive_text = "a manifold, rendered"+ job.job_report.img_gen_tokens_usage = None+ return job+++def _patch_args_factory(mocker: MockerFixture, *, args: dict[str, Any] | None = None) -> None:+ mocker.patch(+ "pipelex.providers.manifold.manifold_img_gen_worker.ImgGenArgsFactory.make_args_for_model",+ new_callable=mocker.AsyncMock,+ return_value=args if args is not None else {"prompt": "a manifold, rendered"},+ )+++# Each body is a 2xx the worker must refuse rather than let escape, with the advice it deserves:+# a shape it cannot read at all is the model's fault, a stripped image is the prompt's.+_MALFORMED_BODIES: list[tuple[dict[str, Any], UserActionKind]] = [+ ({"data": [], "size": "1024x1024", "output_format": "png"}, UserActionKind.CHANGE_MODEL),+ ({"data": [{}], "size": "1024x1024", "output_format": "png"}, UserActionKind.CHANGE_INPUT),+ ({"data": [{"b64_json": _PNG_1PX}], "size": "wide x tall", "output_format": "png"}, UserActionKind.CHANGE_MODEL),+ ({"data": [{"b64_json": _PNG_1PX}], "output_format": "png"}, UserActionKind.CHANGE_MODEL),+]+++def _make_response(mocker: MockerFixture, body: dict[str, Any]) -> Any:+ response = mocker.MagicMock()+ response.model_dump.return_value = body+ return response++[email protected](loop_scope="class")+class TestManifoldImgGenWorkerSuccess:+ async def test_an_azure_gpt_image_body_becomes_generated_images(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)+ _patch_args_factory(mocker)+ _images(worker).generate.return_value = _make_response(mocker, _AZURE_GPT_IMAGE_BODY)++ images = await worker._gen_image_list(img_gen_job=_make_img_gen_job(mocker), nb_images=1) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert len(images) == 1+ generated = images[0]+ assert generated.base64_str == _PNG_1PX+ assert generated.size is not None+ assert (generated.size.width, generated.size.height) == (1024, 1024)+ assert generated.image_format == "png"++ async def test_input_images_route_to_the_edits_endpoint(self, mocker: MockerFixture) -> None:+ """The two Images routes are not interchangeable: /images/generations rejects input images."""+ worker = _make_worker(mocker)+ _patch_args_factory(mocker, args={"prompt": "edit it", "image": [("a.png", b"\x89PNG", "image/png")]})+ _images(worker).edit.return_value = _make_response(mocker, _AZURE_GPT_IMAGE_BODY)++ await worker._gen_image_list(img_gen_job=_make_img_gen_job(mocker), nb_images=1) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ _images(worker).edit.assert_awaited_once()+ _images(worker).generate.assert_not_awaited()++ async def test_several_input_images_travel_as_a_list_not_as_repeated_bare_parts(self, mocker: MockerFixture) -> None:+ """A server handed repeated bare `image` parts keeps one and drops the rest — silently.++ The SDK serializes a list under `image` as `image[]` parts and a single file as the bare+ field, so passing the list is what makes an edit of several images an edit of several+ images rather than a plausible edit of the first.+ """+ worker = _make_worker(mocker)+ files = [("a.png", b"\x89PNG", "image/png"), ("b.png", b"\x89PNG", "image/png")]+ _patch_args_factory(mocker, args={"prompt": "edit them", "image": files})+ _images(worker).edit.return_value = _make_response(mocker, _AZURE_GPT_IMAGE_BODY)++ await worker._gen_image_list(img_gen_job=_make_img_gen_job(mocker), nb_images=2) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert _images(worker).edit.call_args.kwargs["image"] == files++[email protected](loop_scope="class")+class TestManifoldImgGenWorkerFailures:+ async def test_a_non_json_2xx_becomes_a_categorized_error(self, mocker: MockerFixture) -> None:+ """The arm with no symptom: a decode failure is not an `APIError` and catches nowhere else."""+ worker = _make_worker(mocker)+ _patch_args_factory(mocker)+ _images(worker).generate.side_effect = json.JSONDecodeError("Expecting value", "<html>", 0)++ with pytest.raises(ImgGenGenerationError) as exc_info:+ await worker._gen_image_list(img_gen_job=_make_img_gen_job(mocker), nb_images=1) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert exc_info.value.error_category is InferenceErrorCategory.UNKNOWN+ assert exc_info.value.user_action is not None+ assert exc_info.value.user_action.kind is UserActionKind.CONTACT_SUPPORT+ assert "gpt-image-1" in exc_info.value.message++ async def test_a_provider_status_error_is_classified_rather_than_raised_raw(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)+ _patch_args_factory(mocker)+ request = httpx.Request("POST", "https://manifold.example.com/v1/images/generations")+ response = httpx.Response(status_code=429, request=request, headers={"x-request-id": "mf-1"})+ _images(worker).generate.side_effect = portkey_exc.RateLimitError(+ message="http 429",+ request=request,+ response=response,+ body={},+ )++ with pytest.raises(ImgGenGenerationError) as exc_info:+ await worker._gen_image_list(img_gen_job=_make_img_gen_job(mocker), nb_images=1) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert exc_info.value.error_category is InferenceErrorCategory.TRANSIENT++ @pytest.mark.parametrize(+ ("body", "expected_kind"),+ _MALFORMED_BODIES,+ ids=["no-images", "image-without-data", "non-numeric-size", "no-size-at-all"],+ )+ async def test_a_malformed_success_body_is_wrapped_rather_than_escaping(+ self,+ mocker: MockerFixture,+ body: dict[str, Any],+ expected_kind: UserActionKind,+ ) -> None:+ worker = _make_worker(mocker)+ _patch_args_factory(mocker)+ _images(worker).generate.return_value = _make_response(mocker, body)++ with pytest.raises(ImgGenGenerationError) as exc_info:+ await worker._gen_image_list(img_gen_job=_make_img_gen_job(mocker), nb_images=1) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert exc_info.value.user_action is not None+ assert exc_info.value.user_action.kind is expected_kinddiff --git a/tests/unit/pipelex/providers/manifold/test_manifold_native_client.py b/tests/unit/pipelex/providers/manifold/test_manifold_native_client.pynew file mode 100644index 000000000..3e3aac8f2--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_native_client.py@@ -0,0 +1,127 @@+"""The request the native-route client actually builds, and the two ways a 2xx can still be wrong.++`POST /v1/pipelex/extract` and `POST /v1/pipelex/search` are not OpenAI-shaped, so they are called+with plain `httpx`. Building the request by hand is what makes the dialect's two properties readable+in a test rather than dependent on a vendor constructor's defaults: the only header about us is the+service token, and the body carries the model with nothing about routing.++The failure arm is the other half. A 2xx whose body is not JSON — an intermediary's HTML error page+is how this happens — left raw is neither a `PipelexError` nor annotated with the model, so it+escapes the Temporal error bridge (`convert_pipelex_errors`), gets marked retryable, and re-bills a+call that already reached a provider.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import httpx+import pytest++from pipelex.cogt.exceptions import CogtError+from pipelex.cogt.inference.error_render import InferenceErrorFamily+from pipelex.cogt.model_backends.backend import InferenceBackend+from pipelex.providers.manifold.manifold_exceptions import ManifoldError+from pipelex.providers.manifold.manifold_native_client import ManifoldNativeClient++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++_ORIGIN = "https://manifold.example.com"+_TOKEN = "manifold-service-token"+++def _client() -> ManifoldNativeClient:+ return ManifoldNativeClient(backend=InferenceBackend(name="pipelex_manifold", endpoint=_ORIGIN, api_key=_TOKEN))+++def _inference_model(mocker: MockerFixture) -> Any:+ model = mocker.MagicMock()+ model.name = "linkup-sourced-answer"+ model.desc = "test-manifold-search"+ return model+++def _patch_transport(mocker: MockerFixture, response: httpx.Response) -> Any:+ """Stand in for the network at the `httpx.AsyncClient.post` seam.++ Patching the SDK's own method rather than the whole client keeps `raise_for_status` and the JSON+ decoding — the two things these tests are about — running for real.+ """+ return mocker.patch.object(httpx.AsyncClient, "post", new_callable=mocker.AsyncMock, return_value=response)+++def _response(*, status_code: int = 200, json_body: Any = None, text_body: str | None = None) -> httpx.Response:+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/search")+ if text_body is not None:+ return httpx.Response(status_code=status_code, request=request, text=text_body)+ return httpx.Response(status_code=status_code, request=request, json=json_body)++[email protected](loop_scope="class")+class TestManifoldNativeClientRequest:+ async def test_the_wire_carries_one_token_header_and_a_body_with_no_routing(self, mocker: MockerFixture) -> None:+ post = _patch_transport(mocker, _response(json_body={"answer": "ok"}))++ await _client().post_json(+ route="/pipelex/search",+ body={"model": "linkup/standard", "query": "what is a manifold"},+ family=InferenceErrorFamily.SEARCH,+ inference_model=_inference_model(mocker),+ )++ assert post.call_args.args[0] == f"{_ORIGIN}/v1/pipelex/search"+ headers = post.call_args.kwargs["headers"]+ # Asserted whole: a header added later should turn this red rather than widen silently.+ assert headers == {"x-pipelex-api-key": _TOKEN, "Content-Type": "application/json"}+ assert post.call_args.kwargs["json"] == {"model": "linkup/standard", "query": "what is a manifold"}++ async def test_a_json_object_body_comes_back_as_a_dict(self, mocker: MockerFixture) -> None:+ _patch_transport(mocker, _response(json_body={"answer": "ok", "sources": []}))++ result = await _client().post_json(+ route="/pipelex/search",+ body={"model": "linkup/standard", "query": "q"},+ family=InferenceErrorFamily.SEARCH,+ inference_model=_inference_model(mocker),+ )++ assert result == {"answer": "ok", "sources": []}++[email protected](loop_scope="class")+class TestManifoldNativeClientFailures:+ async def test_a_non_json_2xx_becomes_a_pipelex_error_naming_the_model(self, mocker: MockerFixture) -> None:+ _patch_transport(mocker, _response(text_body="<html><body>502 Bad Gateway</body></html>"))++ with pytest.raises(ManifoldError) as exc_info:+ await _client().post_json(+ route="/pipelex/search",+ body={"model": "linkup/standard", "query": "q"},+ family=InferenceErrorFamily.SEARCH,+ inference_model=_inference_model(mocker),+ )++ assert "linkup-sourced-answer" in exc_info.value.message++ async def test_a_2xx_carrying_a_json_scalar_is_refused_with_what_it_was(self, mocker: MockerFixture) -> None:+ _patch_transport(mocker, _response(json_body=["not", "an", "object"]))++ with pytest.raises(ManifoldError, match="list"):+ await _client().post_json(+ route="/pipelex/search",+ body={"model": "linkup/standard", "query": "q"},+ family=InferenceErrorFamily.SEARCH,+ inference_model=_inference_model(mocker),+ )++ async def test_a_status_error_is_classified_rather_than_raised_raw(self, mocker: MockerFixture) -> None:+ _patch_transport(mocker, _response(status_code=401, json_body={"error": {"message": "bad token"}}))++ with pytest.raises(CogtError):+ await _client().post_json(+ route="/pipelex/search",+ body={"model": "linkup/standard", "query": "q"},+ family=InferenceErrorFamily.SEARCH,+ inference_model=_inference_model(mocker),+ )diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.py b/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.pynew file mode 100644index 000000000..071a80229--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.py@@ -0,0 +1,62 @@+"""What the manifold plugin claims, stated in one place.++These sdk names are a contract with a file in another repository: the catalog's `sdk` column+(`manifold_models.toml`) has to name exactly these strings, and a mismatch is not a startup error —+it is an `InferenceBackendNotFoundError` at the first request against that model, which is to say in+production, for one model, on whatever day someone first uses it. The claim is cheap to pin and+expensive to discover.++Two of the entries are worth reading rather than skimming. `(IMG_GEN, manifold_completions)` is the+same sdk name registered under a second family, because some image models answer on the Chat+Completions shape rather than on the Images API and the catalog says which by giving them+`model_type = "img_gen"` while leaving them on the default completions sdk. And `anthropic` is+**absent on purpose**: Claude reaches the manifold service over the shared Anthropic driver, which+authenticates on whichever header the backend names, so registering a manifold-specific Anthropic+sdk would be a second way to do one thing.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from pipelex.plugins.inference_backend_registry import InferenceFamily+from pipelex.plugins.registrar import PluginRegistrar+from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS+from pipelex.providers.manifold.manifold_plugin import ManifoldPlugin++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++_EXPECTED_KEYS = {+ (InferenceFamily.LLM, "manifold_completions"),+ (InferenceFamily.LLM, "manifold_responses"),+ (InferenceFamily.IMG_GEN, "manifold_img_gen"),+ (InferenceFamily.IMG_GEN, "manifold_completions"),+ (InferenceFamily.EXTRACT, "manifold_extract"),+ (InferenceFamily.SEARCH, "manifold_search"),+}+++def _registrar(mocker: MockerFixture) -> PluginRegistrar:+ return PluginRegistrar(config=mocker.MagicMock())+++class TestManifoldPluginRegistrations:+ def test_the_plugin_claims_exactly_the_manifold_sdk_set(self, mocker: MockerFixture) -> None:+ registrar = _registrar(mocker)++ ManifoldPlugin().register(registrar)++ assert set(registrar.inference_backends) == _EXPECTED_KEYS++ def test_no_anthropic_sdk_is_claimed_under_a_manifold_name(self, mocker: MockerFixture) -> None:+ """Claude travels on the shared driver; a manifold-specific one would be a second path."""+ registrar = _registrar(mocker)++ ManifoldPlugin().register(registrar)++ assert not any("anthropic" in sdk for _, sdk in registrar.inference_backends)++ def test_the_plugin_is_a_kernel_builtin(self) -> None:+ """Registered beside the gateway plugin, so a manifold-declared backend needs no plugin install."""+ assert any(isinstance(plugin, ManifoldPlugin) for plugin in KERNEL_BUILTIN_PLUGINS)diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_search_worker.py b/tests/unit/pipelex/providers/manifold/test_manifold_search_worker.pynew file mode 100644index 000000000..58e711d52--- /dev/null+++ b/tests/unit/pipelex/providers/manifold/test_manifold_search_worker.py@@ -0,0 +1,181 @@+"""The search worker's wire body and its usage translation.++The translation is the same silent failure the extract worker has, in the other unit: the route+reports `usage.searches` and the runtime prices per million, so an untranslated response leaves+`nb_tokens_by_category` empty and `linkup-standard` at `costs = { input = 0.005 }` prices nothing at+all, with no exception and no warning.++The body carries **no `depth`**: the model id is where that lives — `linkup/standard` versus+`linkup/deep` — and a second source for a decision the gateway takes from one place is a source of+disagreement rather than of flexibility.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++import pytest+from pydantic import BaseModel++from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory+from pipelex.core.stuffs.search_result_content import SearchResultContent+from pipelex.providers.manifold.manifold_exceptions import ManifoldSearchEmptyResultError, ManifoldSearchResponseError+from pipelex.providers.manifold.manifold_extract_worker import MANIFOLD_UNIT_TOKENS+from pipelex.providers.manifold.manifold_search_worker import ManifoldSearchWorker++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++_SOURCED_ANSWER = {+ "answer": "A manifold is a topological space that locally resembles Euclidean space.",+ "sources": [{"name": "Manifold", "url": "https://example.com/manifold", "snippet": "locally Euclidean"}],+ "usage": {"searches": 1},+}+++class _Capital(BaseModel):+ city: str+++def _make_worker(mocker: MockerFixture, *, response_body: dict[str, Any] | None = None) -> ManifoldSearchWorker:+ worker = object.__new__(ManifoldSearchWorker)+ model = mocker.MagicMock()+ model.model_id = "linkup/standard"+ model.name = "linkup-sourced-answer"+ model.desc = "test-manifold-search"+ worker.inference_model = model+ client = mocker.MagicMock()+ client.post_json = mocker.AsyncMock(return_value=response_body if response_body is not None else _SOURCED_ANSWER)+ worker.client = client+ return worker+++def _post_json(worker: ManifoldSearchWorker) -> Any:+ """The stand-in for the native client, as `Any` so its mock attributes typecheck."""+ return worker.client.post_json+++def _make_search_job(mocker: MockerFixture) -> Any:+ job = mocker.MagicMock()+ job.query = "what is a manifold"+ job.job_params.search_setting.include_images = False+ job.job_params.search_setting.include_inline_citations = False+ job.job_params.search_setting.max_results = 10+ job.job_params.include_domains = None+ job.job_params.exclude_domains = None+ job.job_params.from_date = None+ job.job_params.to_date = None+ job.job_report.search_tokens_usage = None+ return job++[email protected](loop_scope="class")+class TestManifoldSearchRequestBody:+ async def test_the_body_names_the_model_and_carries_no_depth(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)++ await worker._search_sourced_answer(_make_search_job(mocker)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ call = _post_json(worker).call_args.kwargs+ assert call["route"] == "/pipelex/search"+ assert call["body"]["model"] == "linkup/standard"+ assert call["body"]["query"] == "what is a manifold"+ assert "depth" not in call["body"]++ async def test_unset_optional_parameters_are_omitted_rather_than_sent_as_null(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)++ await worker._search_sourced_answer(_make_search_job(mocker)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ body = _post_json(worker).call_args.kwargs["body"]+ for absent in ("include_domains", "exclude_domains", "from_date", "to_date", "output_schema"):+ assert absent not in body++ async def test_a_structured_search_sends_the_caller_s_schema(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker, response_body={"data": {"city": "Paris"}, "sources": [], "usage": {"searches": 1}})++ result = await worker._search_structured(_make_search_job(mocker), schema=_Capital) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert result == {"city": "Paris"}+ body = _post_json(worker).call_args.kwargs["body"]+ assert body["output_schema"] == _Capital.model_json_schema()++[email protected](loop_scope="class")+class TestManifoldSearchResponse:+ async def test_a_sourced_answer_becomes_the_runtime_s_own_content(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker)++ result = await worker._search_sourced_answer(_make_search_job(mocker)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert isinstance(result, SearchResultContent)+ assert result.answer.startswith("A manifold is")+ assert [source.url for source in result.sources] == ["https://example.com/manifold"]++ async def test_a_response_with_no_answer_is_refused_rather_than_returned_empty(self, mocker: MockerFixture) -> None:+ worker = _make_worker(mocker, response_body={"sources": [], "usage": {"searches": 1}})++ with pytest.raises(ManifoldSearchResponseError):+ await worker._search_sourced_answer(_make_search_job(mocker)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ async def test_a_structured_search_that_found_nothing_says_so(self, mocker: MockerFixture) -> None:+ """The query's fault, not the model's — which is why it carries CHANGE_INPUT."""+ worker = _make_worker(mocker, response_body={"data": None, "sources": [], "usage": {"searches": 1}})++ with pytest.raises(ManifoldSearchEmptyResultError):+ await worker._search_structured(_make_search_job(mocker), schema=_Capital) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ async def test_the_usage_key_does_not_stop_the_envelope_being_recognised(self, mocker: MockerFixture) -> None:+ """The route puts `usage` beside the envelope, and it must not reach the unwrapper.++ `extract_structured_search_payload` recognises the envelope by its key set being *exactly*+ `data` and `sources`. Hand it a third key and it returns the whole body as the payload —+ which validates against an output class whose fields have defaults and yields an+ all-defaults object, with no exception and no warning. The failure has no symptom at all+ beyond a wrong answer, so it is pinned rather than left to the shape of the fixture.+ """+ worker = _make_worker(mocker, response_body={"data": {"city": "Paris"}, "sources": [], "usage": {"searches": 1}})++ result = await worker._search_structured(_make_search_job(mocker), schema=_Capital) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert result == {"city": "Paris"}+ assert "usage" not in result+ assert "sources" not in result++[email protected](loop_scope="class")+class TestManifoldSearchUsageTranslation:+ async def test_searches_become_megatokens_in_both_categories(self, mocker: MockerFixture) -> None:+ """The same cost figure the Portkey path reports, which is what makes the two comparable."""+ worker = _make_worker(mocker, response_body={**_SOURCED_ANSWER, "usage": {"searches": 2}})+ job = _make_search_job(mocker)+ usage = mocker.MagicMock()+ job.job_report.search_tokens_usage = usage++ await worker._search_sourced_answer(job) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert usage.nb_tokens_by_category == {+ TokenCategory.INPUT: 2 * MANIFOLD_UNIT_TOKENS,+ TokenCategory.OUTPUT: 2 * MANIFOLD_UNIT_TOKENS,+ }++ @pytest.mark.parametrize(+ "usage_block",+ [None, {}, {"searches": "one"}],+ ids=["null-usage", "empty-usage", "non-numeric-searches"],+ )+ async def test_a_usage_block_the_route_did_not_send_leaves_the_categories_untouched(+ self,+ mocker: MockerFixture,+ usage_block: dict[str, Any] | None,+ ) -> None:+ worker = _make_worker(mocker, response_body={**_SOURCED_ANSWER, "usage": usage_block})+ job = _make_search_job(mocker)+ usage = mocker.MagicMock()+ empty_categories: NbTokensByCategoryDict = {}+ usage.nb_tokens_by_category = empty_categories+ job.job_report.search_tokens_usage = usage++ await worker._search_sourced_answer(job) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]++ assert usage.nb_tokens_by_category == {}diff --git a/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py b/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.pyindex 7ade66148..83e44abdd 100644--- a/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py+++ b/tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py@@ -15,6 +15,7 @@ from typing import TYPE_CHECKINGimport pytest+from pipelex.cogt.model_backends.backend import LEGACY_GATEWAY_MODEL_SPECS_SECTION, PipelexBackendfrom pipelex.pipelex import Pipelexfrom pipelex.system.pipelex_service.exceptions import GatewayTermsNotAcceptedError, InferenceSetupRequiredErrorfrom pipelex.system.pipelex_service.pipelex_service_agreement import PipelexServiceAgreement, PipelexServiceOnboarding@@ -33,7 +34,10 @@ class TestGatewayTermsCheck:@pytest.fixturedef _gateway_enabled_no_config(self, mocker: MockerFixture) -> None:"""Configure mocks: gateway is enabled but no service config exists (first run)."""- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch(f"{RUNTIME_BOOT_MODULE}.load_pipelex_service_config_if_exists", return_value=None)@pytest.fixture@@ -43,7 +47,10 @@ class TestGatewayTermsCheck:agreement=PipelexServiceAgreement(terms_accepted=False),onboarding=PipelexServiceOnboarding(inference_setup_completed=True),)- mocker.patch(f"{RUNTIME_BOOT_MODULE}.is_pipelex_gateway_enabled", return_value=True)+ mocker.patch(+ f"{RUNTIME_BOOT_MODULE}.enabled_managed_gateway_sections",+ return_value={PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION},+ )mocker.patch(f"{RUNTIME_BOOT_MODULE}.load_pipelex_service_config_if_exists", return_value=config)@pytest.mark.usefixtures("_gateway_enabled_no_config")diff --git a/tests/unit/pipelex/system/pipelex_service/test_managed_gateway_backends.py b/tests/unit/pipelex/system/pipelex_service/test_managed_gateway_backends.pynew file mode 100644index 000000000..aea97f924--- /dev/null+++ b/tests/unit/pipelex/system/pipelex_service/test_managed_gateway_backends.py@@ -0,0 +1,263 @@+"""Which backends are *managed gateway* backends, and how the one artifact is sliced for them.++Three collaborating pieces, one question: a managed gateway backend takes its model specs from the+Pipelex service's published artifact rather than from a local per-backend TOML, and naming a section+is what declares it one.++- `resolve_model_specs_section` decides, per backend, whether there is a section and which;+- `enabled_managed_gateway_sections` answers it for a whole `backends.toml`, before the backend+ library can be loaded — the boot needs the answer first, because what it fetches is that load's+ input;+- `build_managed_gateway_configs` cuts the single fetched artifact into one configuration per+ managed backend, keeping them apart rather than merging them.++And the narrower question `is_pipelex_gateway_enabled` answers, which is not a special case of the+broad one and must not be folded into it — the last class here is why.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.cogt.model_backends.backend import (+ LEGACY_GATEWAY_MODEL_SPECS_SECTION,+ MANIFOLD_MODEL_SPECS_SECTION,+ PipelexBackend,+ resolve_model_specs_section,+)+from pipelex.system.pipelex_service.managed_gateway_configs import build_managed_gateway_configs+from pipelex.system.pipelex_service.pipelex_service_config import enabled_managed_gateway_sections, is_pipelex_gateway_enabled+from pipelex.system.pipelex_service.remote_config import PipelexPosthogConfig, RemoteConfig++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture+++def _remote_config(**sections: object) -> RemoteConfig:+ """The published artifact, carrying whichever model-specs sections a test hands it."""+ return RemoteConfig(+ posthog=PipelexPosthogConfig(project_api_key="", endpoint="https://dummy.example.com", is_geoip_enabled=False, is_debug_enabled=False),+ aws_region="eu-west-3",+ **sections, # pyright: ignore[reportArgumentType]+ )+++def _write_backends(tmp_path: Path, body: str) -> Path:+ """Write the base document at a config dir and return that dir, which is what the readers take.++ Both readers below take a `config_dir` and resolve the document under it — the base+ `inference/backends.toml` plus any `inference/backends_override.toml` — so a test pins a+ directory rather than a file.+ """+ inference_dir = tmp_path / "inference"+ inference_dir.mkdir(parents=True, exist_ok=True)+ (inference_dir / "backends.toml").write_text(body, encoding="utf-8")+ return tmp_path+++class TestResolveModelSpecsSection:+ def test_a_declared_section_makes_a_backend_managed(self) -> None:+ assert resolve_model_specs_section(backend_name="whatever", declared_section="some_section") == "some_section"++ def test_the_legacy_gateway_resolves_to_its_section_without_declaring_one(self) -> None:+ """`backends.toml` is the user's own file, written before the field existed and never rewritten."""+ assert resolve_model_specs_section(backend_name=PipelexBackend.GATEWAY, declared_section=None) == LEGACY_GATEWAY_MODEL_SPECS_SECTION++ def test_an_explicit_declaration_wins_even_on_that_name(self) -> None:+ assert resolve_model_specs_section(backend_name=PipelexBackend.GATEWAY, declared_section="elsewhere") == "elsewhere"++ def test_every_other_backend_reads_its_own_file(self) -> None:+ """No section means not managed, which is every BYOK backend and the internal one."""+ assert resolve_model_specs_section(backend_name="anthropic", declared_section=None) is None+ assert resolve_model_specs_section(backend_name=PipelexBackend.MANIFOLD, declared_section=None) is None+++class TestEnabledManagedGatewaySections:+ def test_it_maps_each_enabled_managed_backend_to_its_section(self, tmp_path: Path) -> None:+ config_dir = _write_backends(+ tmp_path,+ f'[pipelex_gateway]\napi_key = "pk-x"\n\n'+ f'[pipelex_manifold]\nmodel_specs_section = "{MANIFOLD_MODEL_SPECS_SECTION}"\nendpoint = "https://gw.example.com"\n\n'+ f'[anthropic]\napi_key = "sk-x"\n',+ )++ assert enabled_managed_gateway_sections(config_dir=config_dir) == {+ PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION,+ PipelexBackend.MANIFOLD: MANIFOLD_MODEL_SPECS_SECTION,+ }++ @pytest.mark.parametrize("enabled_value", ["false", "0"])+ def test_a_disabled_backend_is_absent_reading_enabled_the_way_the_loader_does(self, tmp_path: Path, enabled_value: str) -> None:+ """Truthiness, not the literal `true` — the same reading the backend library applies."""+ config_dir = _write_backends(tmp_path, f'[pipelex_gateway]\nenabled = {enabled_value}\napi_key = "pk-x"\n')++ assert enabled_managed_gateway_sections(config_dir=config_dir) == {}++ def test_a_byok_backend_is_never_managed(self, tmp_path: Path) -> None:+ config_dir = _write_backends(tmp_path, '[anthropic]\napi_key = "sk-x"\n\n[openai]\napi_key = "sk-y"\n')++ assert enabled_managed_gateway_sections(config_dir=config_dir) == {}++ def test_a_missing_file_is_no_managed_backends_rather_than_a_refusal(self, tmp_path: Path) -> None:+ assert enabled_managed_gateway_sections(config_dir=tmp_path / "absent") == {}+++class TestTheTwoQuestionsAreNotTheSameQuestion:+ """Which managed backends are live, and whether the *legacy gateway* is — the boot asks both.++ They came apart the moment a second managed backend existed, and the boot line that must keep+ asking the narrow one is the telemetry decision: the distinct id is derived from+ `PIPELEX_GATEWAY_API_KEY`, which a manifold-only installation has no reason to hold. Asked the+ broad way, such an installation is required to produce a gateway key it does not have and fails+ to boot on `GatewayApiKeyMissingError` — a refusal with nothing in it naming manifold.++ The beta's own key cannot stand in either, and that is the second half of the verdict: for the+ private beta it is one token shared by every participant, so keying on it would report a single+ indistinguishable user rather than an identity.+ """++ def test_a_manifold_only_installation_is_managed_but_is_not_the_gateway(self, tmp_path: Path) -> None:+ config_dir = _write_backends(+ tmp_path,+ f"[pipelex_gateway]\nenabled = false\n\n"+ f'[pipelex_manifold]\nmodel_specs_section = "{MANIFOLD_MODEL_SPECS_SECTION}"\nendpoint = "https://mf.example.com"\n',+ )++ assert enabled_managed_gateway_sections(config_dir=config_dir) == {PipelexBackend.MANIFOLD: MANIFOLD_MODEL_SPECS_SECTION}+ assert not is_pipelex_gateway_enabled(config_dir=config_dir)++ def test_the_common_beta_case_keeps_both(self, tmp_path: Path) -> None:+ """A participant who leaves the legacy gateway on has a real key, and manifold runs ride on it."""+ config_dir = _write_backends(+ tmp_path,+ f'[pipelex_gateway]\napi_key = "pk-x"\n\n'+ f'[pipelex_manifold]\nmodel_specs_section = "{MANIFOLD_MODEL_SPECS_SECTION}"\nendpoint = "https://mf.example.com"\n',+ )++ assert set(enabled_managed_gateway_sections(config_dir=config_dir)) == {PipelexBackend.GATEWAY, PipelexBackend.MANIFOLD}+ assert is_pipelex_gateway_enabled(config_dir=config_dir)+++class TestBuildManagedGatewayConfigs:+ def test_each_backend_gets_its_own_section_unmerged(self) -> None:+ """Two services, two spec maps: a handle one serves and the other does not is legitimate."""+ remote_config = _remote_config(+ **{+ LEGACY_GATEWAY_MODEL_SPECS_SECTION: {"gpt-5": {"model_id": "gpt-5"}},+ MANIFOLD_MODEL_SPECS_SECTION: {"claude-4-sonnet": {"model_id": "claude-4-sonnet"}},+ }+ )++ configs = build_managed_gateway_configs(+ remote_config=remote_config,+ managed_gateway_sections={+ PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION,+ PipelexBackend.MANIFOLD: MANIFOLD_MODEL_SPECS_SECTION,+ },+ )++ assert set(configs) == {PipelexBackend.GATEWAY, PipelexBackend.MANIFOLD}+ assert set(configs[PipelexBackend.GATEWAY].model_specs) == {"gpt-5"}+ assert set(configs[PipelexBackend.MANIFOLD].model_specs) == {"claude-4-sonnet"}++ def test_the_region_belongs_to_the_legacy_slice_alone(self) -> None:+ """`aws_region` is a top-level key of the artifact, and only the direct-SDK Bedrock path reads it back."""+ empty_sections: dict[str, dict[str, object]] = {LEGACY_GATEWAY_MODEL_SPECS_SECTION: {}, MANIFOLD_MODEL_SPECS_SECTION: {}}+ remote_config = _remote_config(**empty_sections)++ configs = build_managed_gateway_configs(+ remote_config=remote_config,+ managed_gateway_sections={+ PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION,+ PipelexBackend.MANIFOLD: MANIFOLD_MODEL_SPECS_SECTION,+ },+ )++ assert configs[PipelexBackend.GATEWAY].aws_region == "eu-west-3"+ assert configs[PipelexBackend.MANIFOLD].aws_region is None++ def test_a_section_the_artifact_does_not_carry_is_disabled_by_name(self, mocker: MockerFixture) -> None:+ """Disabled with a named warning, not fatal: the kit can ship a managed backend declared.++ The warning is the whole remedy here, so it has to name both the backend and the section it+ was looking for — otherwise a user who has not joined the beta reads that *something* was+ disabled and has nowhere to go.+ """+ warning = mocker.patch("pipelex.system.pipelex_service.managed_gateway_configs.log.warning")+ remote_config = _remote_config(**{LEGACY_GATEWAY_MODEL_SPECS_SECTION: {"gpt-5": {"model_id": "gpt-5"}}})++ configs = build_managed_gateway_configs(+ remote_config=remote_config,+ managed_gateway_sections={+ PipelexBackend.GATEWAY: LEGACY_GATEWAY_MODEL_SPECS_SECTION,+ PipelexBackend.MANIFOLD: MANIFOLD_MODEL_SPECS_SECTION,+ },+ )++ assert set(configs) == {PipelexBackend.GATEWAY}+ warning.assert_called_once()+ said = str(warning.call_args.args[0])+ assert PipelexBackend.MANIFOLD in said+ assert MANIFOLD_MODEL_SPECS_SECTION in said+++class TestTheSectionLookupIsConfinedToTheArtifact:+ """`model_specs_section` is text from the user's own `backends.toml`, so the lookup it drives+ must only ever reach the artifact's own content.++ A bare `getattr` on the model answers for pydantic's machinery as well, and two of those+ attributes are plain dicts — so they pass a `isinstance(..., dict)` shape check and travel on as+ if the service had published them. The failure that produces is not a refusal but a+ `GatewayConfig` built over pydantic internals, which surfaces much later as an unintelligible+ model-spec error naming neither the backend nor the mistake.+ """++ def test_a_published_section_is_found(self) -> None:+ sections: dict[str, dict[str, object]] = {+ LEGACY_GATEWAY_MODEL_SPECS_SECTION: {},+ MANIFOLD_MODEL_SPECS_SECTION: {"claude-4-sonnet": {"model_id": "claude-4-sonnet"}},+ }+ remote_config = _remote_config(**sections)++ section = remote_config.get_model_specs_section(MANIFOLD_MODEL_SPECS_SECTION)++ assert section is not None+ assert set(section) == {"claude-4-sonnet"}++ def test_the_legacy_declared_field_is_found_too(self) -> None:+ """It is a declared field rather than an extra, and both halves of the lookup must work."""+ remote_config = _remote_config(**{LEGACY_GATEWAY_MODEL_SPECS_SECTION: {"gpt-5": {"model_id": "gpt-5"}}})++ section = remote_config.get_model_specs_section(LEGACY_GATEWAY_MODEL_SPECS_SECTION)++ assert section is not None+ assert set(section) == {"gpt-5"}++ @pytest.mark.parametrize("attribute_name", ["model_config", "model_fields"])+ def test_a_pydantic_internal_is_not_a_section(self, attribute_name: str) -> None:+ """Both are real dict attributes of any v2 model, and neither is anything the service published."""+ legacy_only: dict[str, dict[str, object]] = {LEGACY_GATEWAY_MODEL_SPECS_SECTION: {}}+ remote_config = _remote_config(**legacy_only)++ # Read off the class: instance access to `model_fields` is deprecated in pydantic v2.11,+ # and the point being made is about the attribute existing as a dict at all.+ assert isinstance(getattr(RemoteConfig, attribute_name), dict)+ assert remote_config.get_model_specs_section(attribute_name) is None++ def test_a_declared_field_that_is_not_a_spec_map_is_not_a_section(self) -> None:+ """`posthog` and `aws_region` are the artifact's own content but the wrong shape."""+ legacy_only: dict[str, dict[str, object]] = {LEGACY_GATEWAY_MODEL_SPECS_SECTION: {}}+ remote_config = _remote_config(**legacy_only)++ assert remote_config.get_model_specs_section("posthog") is None+ assert remote_config.get_model_specs_section("aws_region") is None++ def test_an_unknown_name_is_simply_absent(self) -> None:+ legacy_only: dict[str, dict[str, object]] = {LEGACY_GATEWAY_MODEL_SPECS_SECTION: {}}+ remote_config = _remote_config(**legacy_only)++ assert remote_config.get_model_specs_section("no_such_section") is Nonediff --git a/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.py b/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.pyindex aa67a10f6..c917e17fa 100644--- a/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.py+++ b/tests/unit/pipelex/test_runtime_boot_backends_document_refusal.py@@ -1,9 +1,13 @@"""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.+`RuntimeBoot` asks `enabled_managed_gateway_sections` which managed gateway backends to fetch specs for 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.++The gate is read exactly once. The telemetry decision further down needs the narrower "is the legacy gateway+enabled" answer, and it reads it off the mapping this gate returned rather than asking the document again — a+second read would be a second way past the clause."""import pytest@@ -25,7 +29,7 @@ class TestRuntimeBootBackendsDocumentRefusal:"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)+ mocker.patch("pipelex.runtime_boot.enabled_managed_gateway_sections", side_effect=refusal)Pipelex.teardown_if_needed()try:diff --git a/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py b/tests/unit/pipelex/test_runtime_boot_stale_backend_error.pyindex 6c7f94e0d..bdb0c516e 100644--- a/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py+++ b/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py@@ -118,7 +118,7 @@ class TestAStaleBackendFileTheLedgerCannotFullyExplain:secrets_provider=EnvSecretsProvider(),backends_library_paths=[machine / INFERENCE_DIR_NAME / "backends.toml"],backends_dir_path=str(machine / INFERENCE_DIR_NAME / BACKENDS_DIR_NAME),- gateway_config=None,+ managed_gateway_configs=None,lenient=False,)return refused.valuediff --git a/wip/drift-contracts/dogfood-log.md b/wip/drift-contracts/dogfood-log.mdindex 5e1dbcc58..123b7619c 100644--- a/wip/drift-contracts/dogfood-log.md+++ b/wip/drift-contracts/dogfood-log.md@@ -117,5 +117,12 @@ The surviving finding is real and small: the table under "What a programmatic ca- **2026-08-18 · cli-docs · real-catch** — Triggered by `init_config` gaining a call to `ensure_config_dir_gitignore`, the fix for `pipelex migrate` dropping untracked `.bak.<stamp>` files into a user's `git status`. The catch is the plainest kind and the kind grep cannot find: `docs/tools/cli/init.md`'s **What Gets Initialized** list is a set claim about what the command creates, and a new artifact falsifies it by *absence* — searching the target for `.gitignore` returns nothing, which reads identically to "not mentioned because not relevant". Only reading the page for its quantified claims surfaces it. Worth recording that the contract also earned its keep on a claim that turned out **fine**: `agent_cli/CLAUDE.md` states that `migrate` writes only with `--yes`, and a new write on the migrate path is exactly what would falsify that — re-derived from the code (`agent_migrate_cmd` passes `dry_run = not yes`; the bare command's first pass is `dry_run=True`; both call sites guard the new write with `if not dry_run`) rather than from the guard's own docstring, which is the artifact-not-prose rule applied to a claim I had written myself minutes earlier and was therefore the least trustworthy prose in the repo.Verdict signal: this breaks `cli-docs`'s run of clean-passes, and it does so on the cheapest possible trigger — a single new call in one CLI module. The contract opened on the right thing and pointed at the right page. No narrowing to propose.- **2026-08-18 · cli-docs · real-catch** — A one-line fix to `migrate_cmd.py` (ensure the config-dir `.gitignore` on the clean early-return path) opened the contract, and the review caught the CLI page making a set claim about when you get that file that the fix had just changed — the sort of staleness that reads fine in the diff because the false sentence never mentions what falsified it.++- **2026-08-29 · cli-docs · real-catch** — Opened by the `origin/dev` merge into `feature/Two-gateways-2`: `doctor_cmd.py` moved from probing `pipelex_gateway` by name to probing every enabled managed-gateway backend, and `error_handlers.py`'s unknown-gateway-model panel gained a `Backend:` line and stopped hardcoding `pipelex_gateway` in its remediation. Neither change touched a command, flag, help text or output format, and the review targets describe `doctor` only at that level — so the change that opened the contract left nothing stale. The catch came from the skill's re-derive-the-set discipline applied anyway: enumerating every agent-CLI command module carrying a `CliOutputFormat` parameter showed the markdown-or-JSON list had rotted by omission in *both* targets, missing `migrate` in `agent_cli/CLAUDE.md` and `migrate`, `codegen types` and `codegen check` in `agent-cli.md`. Neither omission mentions the commands that falsify it, so no grep driven by the trigger diff could have found them, and each was left behind by an earlier change that this contract had already been acked over.+ Verdict signal: keep, and note the shape — the staleness this opening caught had nothing to do with the trigger that opened it. That is an argument for the contract being a periodic re-read of the targets rather than a diff-scoped one, and it is the second time on this contract that the value came from the quantified-claim sweep rather than from following the diff.+- **2026-09-03 · cli-docs · clean-pass** — opened on the doctor backend-files probe switching to a lenient load and to attribution by the error's declared backend; the targets describe doctor at the row-list level and never how that row loads or attributes, so nothing was stale.- **2026-09-03 · cli-docs · clean-pass** — reopened in the same branch's pre-landing review, when `check_models` was moved onto the same attribution helper. Worth recording that the contract reopened at all: the second edit was to the same file for the same reason, and the second review re-read the same two targets to the same verdict. That is the honest cost of a per-file digest — a contract cannot tell "the same change, continued" from a new one, and the review is cheap only because the first one had just established which claims the targets actually make. No narrowing to propose; a contract that skipped a second edit to a triggered file would be worse.++- **2026-09-03 · cli-docs · clean-pass** — Opened by the second `origin/dev` merge into `feature/Two-gateways-2`, and worth recording mostly for what the *ack file itself* does under a merge. The two branches had each acked the same contract, so `.drift/acks/cli-docs.toml` conflicted on its header while `[trigger_files]` auto-merged into the union — a shape where hand-resolving is exactly wrong, because whichever rationale you keep, the digest it records is a digest of neither tree. The only correct resolution is to re-run the review on the merged tree and let `drift-ack` rewrite digest, timestamp and table together, which is what happened here. The triggers dev brought were `doctor_cmd.py` (the backend-files probe going lenient, and both it and `check_models` attributing through the `backend_name` the loader now stamps on the error) and `run/_run_core.py` (`--save-csv` recovering the row model for an empty result by reloading the bundle, with the guard widened to `PipelexError`). Both targets came back clean, and for the same structural reason each time: they describe `doctor` at the row level and `--save-csv` at the flag level, and neither change moved a command, a flag, a message shape or an exit code. The `run.md` claims were re-derived from the code rather than from the diff — the recorded-absence sentence in particular, since it is the one quantified claim in the area and the `AbsenceRecord` arm sits directly above the block that changed.+ Verdict signal: keep. The contract's cost here was one real review, and the merge conflict on its own ack file is a small argument in its favour rather than against — the collision is what forces the review to be redone against the tree that will actually ship, where two independently-acked branches would otherwise land an unreviewed combination.diff --git a/wip/gateway-routing-refusals/plan.md b/wip/gateway-routing-refusals/plan.mdnew file mode 100644index 000000000..d0accc554--- /dev/null+++ b/wip/gateway-routing-refusals/plan.md@@ -0,0 +1,143 @@+---+status: landed+item: L-260831-9963b5+---++# Classify the gateway's routing refusals++## The bug, verified++The Pipelex inference gateway refuses a request it cannot route with a code of its own — an unknown model handle (`pig-01`), a model served by an integration that is disabled for want of a credential (`pig-02`), a model unreachable over the native protocol the path belongs to (`pig-05`), or a model whose integration does not serve the requested capability (`pig-06`). Every one of them answers HTTP 400. `classify_inference_error` has a class for the gateway's request-shape refusals and for its unresolvable-reference refusals, but none for this family, so all four fall through to the `status_code == 400` arm of the status ladder in `pipelex/cogt/inference/error_classify.py` and are read as CONTENT / CHANGE_INPUT: a caller who named a model the gateway does not serve is told *"The provider rejected the request — review the prompt, parameters, and inputs."* and receives `LLMCompletionError` rather than `LLMModelNotFoundError`.++Probed on this branch, with the exception built through Portkey's own `_make_status_error_from_response` so `exc.body` is the message string as in production:++```+pig-01: code=pig-01 category=content action=change_input model_not_found=False err=LLMCompletionError detail='The provider rejected the request — review the prompt, parameters, and inputs.'+pig-02: code=pig-02 category=content action=change_input model_not_found=False err=LLMCompletionError detail=(same)+pig-05: code=pig-05 category=content action=change_input model_not_found=False err=LLMCompletionError detail=(same)+pig-06: code=pig-06 category=content action=change_input model_not_found=False err=LLMCompletionError detail=(same)+```++The 404 arm of the status ladder already produces exactly the verdict the family deserves (CONFIGURATION / CHANGE_MODEL with `is_model_not_found` set) — the gateway simply never answers 404 for these, so the ladder cannot reach it.++Why the fix is possible now and was not when the item was filed: the item was discovered while reviewing the request-limits work, whose review ruling was not to widen that PR. Both halves of the mechanism have since landed on the branch this plan stacks on — the code-keyed family consulted ahead of the status ladder (`GatewayRequestLimit`, from the request-limits PR) and its second instance (`GatewayUnresolvedReference`, from the unresolvable-references PR), plus the Extract-hop fixes that make the gateway's code readable on every SDK path (the Portkey substrate reads the code back off the response, and the two Pipelex-service hops read `error.code` before `error.type`). This plan adds the third family on the same shape. The gateway side needs nothing: every code already exists on the wire.++## The code inventory, from the manifold source++Verified against `pipelex-manifold/src/pig/modelResolver.ts` (constants at lines 99–106) and `src/pig/proxyPolicy.ts`:++| Code | HTTP | Raised when | Who can produce it from the runtime |+|---|---|---|---|+| `pig-01` | 400 | the body names no model, or names one that no integration lists | a model deck whose handle the gateway does not serve — a stale deck, a typo in a `.mthds` file's model, or a model the deployment deliberately does not carry |+| `pig-02` | 400 | the model resolves to an integration that is disabled because a credential variable is unset | any call to a model whose integration the operator has not configured; the message names the integration and the variables to set |+| `pig-05` | 400 | a native-protocol path names a model another provider serves — today only Google's `/v1/v1beta/models/<model>:generateContent`, the path shape `nativeProtocolPaths.ts` admits | the runtime's `GoogleLLMWorker` pointed at the gateway with a model the gateway serves through a non-Google integration: a deck/gateway disagreement about which backend a model belongs to |+| `pig-06` | 400 | a model reaches a `/v1/pipelex/*` route (extract, search) that its integration's provider does not serve | an extract or search whose model resolves to an integration without that handler: again a deck/gateway disagreement, or a model named on a pipe it cannot serve |++Deliberately out of scope, and why:++| Code | HTTP | Why it stays with the status ladder |+|---|---|---|+| `pig-03` | 400 | "the client tried to route" — a refused `x-portkey-*` header, the `?model=` query form, a `@<slug>/<model>` virtual-key model, or a path and body naming different models. No client the runtime ships produces any of these; reaching it means a client bug, not a caller's or an operator's mistake. `tests/unit/pipelex/providers/manifold/test_manifold_clients.py` already pins that the manifold clients send none of the routing forms. |+| `pig-04` | 404 | "this gateway does not serve `<method> <path>`" — the proxy policy refusing a path only the catch-all could answer. Unreachable while the runtime calls only the routes the gateway mounts. Note for honesty: because it is a 404 the ladder reads it as model-not-found, which is wrong in kind — but a served-path drift is a deployment bug to surface loudly, not a verdict to soften, and no runtime client reaches it today. The pin test below asserts it is not a routing refusal, without blessing the ladder's verdict. |+| `pig-09` | 400 | "cannot resolve this reference" — already `GatewayUnresolvedReference.REFERENCE_UNRESOLVED`, CONTENT / CHANGE_INPUT. Nothing to do here; the pin test only asserts the two families stay disjoint. |++### Found on the way, filed elsewhere++Two things the inventory turned up that this plan deliberately does not carry, so the routing PR stays one decision:++- **`pig-12` is unmapped.** The manifold has since split "no bucket configured" out of `pig-09` on the LLM routes into its own code, `pig-12` at 400, and the runtime does not recognize it — so it gets the same "review your prompt" advice, and the runtime's doc still says `pig-09` folds that cause in. One map entry to `GatewayUnresolvedReference.STORAGE_NOT_SERVED`, a doc row and a test row: L-260901-0859e8.+- **The default is the real bug.** Three families in a row had to be filed because an unmapped gateway code falls through to the ladder's 400 arm and is read as a provider rejecting the prompt. A code the gateway minted for its own refusal is never that. The gateway's code namespaces (`pig-NN`, `pig_*`, `pipelex_*`) should get a default of their own that never says "review your prompt", so the next code degrades to honest advice and the per-family maps become refinements of a correct default: L-260902-b17ff6.++## The design decision: the arms++Grouping is by remedy, as in the two families already there: two codes share a member only when the caller's next move is the same. Here every member is its own code, because each names a different thing the caller or the operator has to change.++New enum `GatewayRoutingRefusal` in `error_classification.py`, beside the two existing families:++| Member | Code | Category / action | `is_model_not_found` | Advice (gist — final wording at implementation) |+|---|---|---|---|---|+| `UNKNOWN_MODEL` | `pig-01` | `CONFIGURATION` / `CHANGE_MODEL` | **set** | the inference gateway does not serve that model — pick a model this deployment serves; if the deck lists it, the deck and the gateway disagree |+| `DISABLED_INTEGRATION` | `pig-02` | `CONFIGURATION` / `CONTACT_SUPPORT` | unset | the model is served by an integration this deployment has not enabled — nothing about the request causes this; the message names the integration and, for whoever operates the gateway, the variables to set |+| `WRONG_PROTOCOL` | `pig-05` | `CONFIGURATION` / `CHANGE_MODEL` | unset | the model is reachable through the gateway, but not over the protocol the runtime used for it — the model deck names a backend for that model that the gateway serves it through a different one; correct the deck, or pick another model |+| `UNSERVED_CAPABILITY` | `pig-06` | `CONFIGURATION` / `CHANGE_MODEL` | unset | the model's integration does not serve that capability (extract, search) — pick a model whose provider does; the message names the integration, the provider and the capability |++Decisions taken, and why:++- **`CONFIGURATION` throughout, never `CONTENT`.** Nothing in the prompt, the parameters or the inputs causes any of these, and no edit to them avoids one. That is the whole bug: a caller sent to review their prompt for a model that does not exist.+- **`CHANGE_MODEL` for the three the caller can route around, and `is_model_not_found` set only for `pig-01`.** The flag is not a category: it selects the `*ModelNotFoundError` class, which `pipe_operator.py` catches and re-raises as `PipeOperatorModelAvailabilityError` carrying the model handle — the pipe-level error a caller already gets when the deck itself cannot find a model. `pig-01` is literally that case seen from the gateway. `pig-05` and `pig-06` leave the flag unset because the model *does* exist and *is* served — it cannot do what was asked, or was asked over the wrong protocol — and the render detail carries that distinction; the error class stays the family's generic failure class with the CHANGE_MODEL advice.+- **`pig-02` is `CONTACT_SUPPORT`, ruled at checkpoint 1.** The integration is disabled because the gateway operator never set its credential: nothing about the request causes it, and the deployment — not the caller — is what has to change. `CHECK_CREDENTIALS` would send a hosted caller to rotate their own valid key. `CHANGE_MODEL` was the draft's pick, on the argument that another model does get the caller past the refusal; the ruling is that a switched-off integration is the operator's fact, the same call `STORAGE_NOT_SERVED` and `BODY_LENGTH_REQUIRED` get, and the advice should say so rather than send the caller shopping for a model. The flag stays unset — the handle resolves, so it is not a model the deployment does not know — and the detail still points whoever operates the gateway at the variable the message names.+- **`pig-05` and `pig-06` are deck-vs-gateway disagreements as much as caller mistakes, and the advice says so.** The runtime picks the protocol and the route from its own model deck, so hitting either usually means the deck names a backend or a capability for a model that the gateway's routing table does not. The detail names the deck, because "pick another model" alone would leave an operator hunting for a model problem that is a config problem. `CONFIGURATION` / `CHANGE_MODEL` is still the right pair: the category is right in kind and the action is what an end caller can do.+- **Nothing in the family is retryable.** Same reasoning as the two families already there: the gateway refused before a provider saw the request, and an identical retry earns an identical refusal. `InferenceErrorCategory.CONFIGURATION` is already non-retryable.+- **The advice names no model, integration, protocol or capability.** The gateway's own message sits beside the detail and already states the specifics; repeating a guess is how advice contradicts the refusal it explains. Same principle as `_render_gateway_limit_detail`.+- **The code is the discriminator, not the provider.** As in both existing families: the refusal arrives under more than one `ProviderName` (the Portkey substrate, the OpenAI substrate that carries every chat call, plain `httpx` on the native routes, the shared Anthropic driver, and — for `pig-05` specifically — the Google driver), and `pig-` is the gateway's own namespace.++## Implementation steps++### 1. The classification family — `pipelex/cogt/inference/error_classification.py`++- Add `GatewayRoutingRefusal` (StrEnum) with the four members above, docstrings citing the wire code, the status and who can produce it, following `GatewayRequestLimit`'s style.+- Add `_GATEWAY_ROUTING_REFUSAL_BY_CODE` mapping the four codes. Matched on the code alone with no provider check, for the reason both existing maps give. The comment above it records the scope decision: `pig-03` and `pig-04` are not producible by the runtime's own clients and keep the status ladder; `pig-09` belongs to the unresolvable-reference family.+- Add a `gateway_routing_refusal` property on `ProviderErrorMetadata`, mirroring `gateway_request_limit` and `gateway_unresolved_reference`.++### 2. The classify step — `pipelex/cogt/inference/error_classify.py`++- Add `gateway_routing_refusal: GatewayRoutingRefusal | None = None` to `ClassificationResult` — a flag beside the two existing ones, same rationale: it does not change the retry decision, it lets Render name the refusal.+- Add `_classify_gateway_routing_refusal(*, refusal: GatewayRoutingRefusal)` returning `CONFIGURATION` / `CHANGE_MODEL` for `UNKNOWN_MODEL`, `WRONG_PROTOCOL` and `UNSERVED_CAPABILITY`, with `is_model_not_found=True` for `UNKNOWN_MODEL` only, and `CONFIGURATION` / `CONTACT_SUPPORT` for `DISABLED_INTEGRATION`.+- In `classify_inference_error`, branch on `metadata.gateway_routing_refusal` right after the unresolved-reference branch. The three code sets are disjoint, so the order among the three gateway branches carries no meaning; all three must run ahead of the status ladder, and none can collide with the quota rules, which fire only on 402 and 429.++### 3. The render step — `pipelex/cogt/inference/error_render.py`++- Add `_render_gateway_routing_refusal_detail(*, refusal: GatewayRoutingRefusal) -> str` with one advice string per member (gists above).+- In `_render_detail`, branch on `classification.gateway_routing_refusal` beside the two existing gateway branches, ahead of the action-kind match. Without it `pig-01` and `pig-02` would render the generic "The requested model was not found — pick an available model", which is acceptable but says nothing about the gateway, and `pig-05` / `pig-06` would render it for a model that exists.+- No new error class: `is_model_not_found` already switches to the family-specific `*ModelNotFoundError` classes. So no `generate-error-identity` / `generate-error-pages` run.++### 4. Tests — `tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py`++Mirror the unresolvable-references module's structure and docstring style, including its table-driven `_EVERY_CODE_AND_MEMBER` list and the `test_the_table_covers_the_whole_production_map` case that walks the private map:++- **The code is recognized**: each of the four codes maps to its member; `None`, the other gateway codes and a vendor code do not; recognition is provider-blind across every `ProviderName`; every member is reachable from a wire code.+- **The code survives every Extract hop**: through the Portkey substrate (built through the SDK's own factory, never the constructor — Portkey's factory puts the message string on `exc.body`, and the hop must recover the code off the response), the OpenAI substrate that carries every chat call, plain `httpx` on the native routes (`pig-06` is the one that actually arrives there), and the shared Anthropic driver. `pig-05` arrives on the Google driver; add a hop through `extract_google_metadata` if that Extract function can carry a gateway envelope, otherwise say in the module docstring why it is not pinned.+- **Classification**: every member is `CONFIGURATION` and never retryable; `DISABLED_INTEGRATION` is `CONTACT_SUPPORT` and the other three `CHANGE_MODEL`; `is_model_not_found` is set for exactly `UNKNOWN_MODEL`; a bare 400 without a recognized code still takes the status ladder.+- **End to end**: `pig-01` built through Portkey's factory renders `LLMModelNotFoundError` with `model_handle` set — the headline of the ledger item — and `pig-05` renders `LLMCompletionError` with `CHANGE_MODEL` advice that does not say the model was not found.+- **Rendered advice**: no member renders the generic "review the prompt, parameters, and inputs" line; `pig-01` and `pig-05` are told apart; `pig-02` does not mention the caller's credentials and does not tell them to pick a model.+- **The scope decision is pinned**: `pig-03` and `pig-04` are not routing refusals (`gateway_routing_refusal is None`), and `pig-09` is an unresolved reference and not a routing refusal. The pin asserts family membership only, not the ladder's verdict for `pig-03`/`pig-04`.+- **The three families do not shadow each other**: extend the existing disjointness test in the unresolvable-references module — or add a three-way one here — so a code lands in exactly one map.++### 5. Docs and changelog++- `docs/under-the-hood/error-model.md` § "The Gateway's Own Refusals": the opening paragraph says the gateway refuses "for two different reasons" — make it three, and add a third `####` half ("When the model cannot be routed") after the reference one, with the four-code table, the scope table for `pig-03` / `pig-04`, and the decisions above. Update the closing paragraph, which currently says the routing refusals "belong to neither family and classify on their status like anything else" — after this change that sentence is false and must name only the deadline outcomes. Update the two layer-model table rows to name `GatewayRoutingRefusal` and `gateway_routing_refusal`.+- `CHANGELOG.md` under `[Unreleased]` → Added: one condensed entry in the style of the two existing gateway entries.+- No config change; no spec / conformance surface touched; the manifold side is untouched.++### 6. Gate++`make agent-check`, then the full `make agent-test` (the new test module and `.test_durations` need the full run).++## Checkpoints++- **Checkpoint 1 — plan ratified (2026-09-02).** Two rulings, both recorded above: `pig-02` is `CONFIGURATION` / `CONTACT_SUPPORT` with the flag unset, not `CHANGE_MODEL`; and the `pig-12` ride-along is split out, because the item it belongs with is the default itself — an unmapped gateway code must stop reading as "review your prompt" (L-260902-b17ff6), with the `pig-12` map entry its own small item (L-260901-0859e8).+- **Checkpoint 2 — implementation landed on this branch (2026-09-02).** Steps 1–6 are done. `GatewayRoutingRefusal`, `_GATEWAY_ROUTING_REFUSAL_BY_CODE` and the `gateway_routing_refusal` property sit beside the two existing families; the Classify step gains the flag field, `_classify_gateway_routing_refusal` and a third branch ahead of the status ladder; the Render step gains `_render_gateway_routing_refusal_detail` and a third branch ahead of the action-kind match; `tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py` covers the chain; the error-model page gained a third `####` half and the closing paragraphs were corrected; the changelog entry sits beside its two siblings. Nothing in the design section changed while building it — the four arms, the `CONTACT_SUPPORT` ruling for `pig-02` and the flag on `pig-01` alone all landed as ratified. What the build added beyond the design:++ - **`pig-05` is not reachable from today's runtime at all**, which is stronger than the design's "the runtime's `GoogleLLMWorker` pointed at the gateway". No worker speaks Google's native protocol to a Pipelex-operated gateway: both `gateway_plugin.py` and `manifold_plugin.py` build their LLM workers on the OpenAI substrate, and `ManifoldNativeClient` serves only the `/v1/pipelex/*` extract and search routes. The map entry stays — it is right the day such a path is wired, and it costs nothing — but no Extract hop is pinned for it, and the module docstring and the docs page both say why.+ - **The Google Extract hop would not carry a gateway code even then, and returns a wrong one.** `_google_provider_error_code_from_details` reads `error.status` and then a top-level `status`; the gateway's envelope has no `error.status` and a top-level `status: "failure"`, so the hop returns the string `"failure"` as `provider_error_code` — a value that looks like a real code. Probed, pinned as the trap it is (`test_the_google_hop_would_not_carry_a_gateway_code_and_nothing_reaches_it_today`), stated in the docs, and filed as L-260902-a8f50b to be fixed *before* any native Google path is pointed at a gateway.+ - **The three-way disjointness is asserted as sets, not only per code.** The unresolvable-references module's two-way pins stayed where they are; this module adds a set-level case over all three private maps, which is the direction a per-code table cannot see.+ - **A local environment repair, unrelated to the change**: this worktree's `.venv` carried shebangs from its former path (`_two`), so `pyright`, `pytest` and 97 other console scripts failed with `bad interpreter`. Rewritten in place; nothing in the repo changed.++ Next: open the stacked PR for review with `Closes L-260831-9963b5` in its body.++- **Checkpoint 3 — reviewed on PR #1185 (2026-09-02).** A `/review` pass over the diff, with an adversarial second read, produced five changes and one correction. Nothing about the four arms, the `CONTACT_SUPPORT` ruling or the flag placement moved; what moved is the honesty of three claims and the reach of the tests.++ - **`pig-01` is hedged, because the code covers more than the design assumed.** The gateway's body reader returns "no model" from a bare `catch` around both the JSON and the multipart read (`pipelex-manifold/src/pig/modelResolver.ts:255-270`), so a body it cannot parse earns `pig-01` alongside "this gateway serves no such model" and "the body names none" — three facts under one code. `is_model_not_found` still fires for all of them, which is right for the common case and cannot be narrowed from the code alone, so the detail now sends the reader to the gateway's own message before it sends them to the deck rather than asserting a deck-versus-gateway disagreement outright. The real fix is gateway-side and is filed as [L-260902-701614](http://localhost:4747/i/L-260902-701614), on the precedent of `pig-12` being drawn out of `pig-09`.+ - **The `pig-03` scope claim is narrowed to what its evidence supports.** "No client the runtime ships produces any of those" was too strong twice over: `test_manifold_clients.py` pins four steering headers *by name* while the gateway refuses on an allow-list, so a `portkey_ai` release sending some other `x-portkey-*` header would earn `pig-03` with that test still green; and `gateway_img_gen_worker.py` does send `x-portkey-config` on every image call, which Portkey's cloud reads and a Pipelex-operated gateway refuses — harmless while `pipelex_gateway` keeps its default endpoint (`gateway_factory.py`: `backend.endpoint or PORTKEY_GATEWAY_URL`), a client bug the day that backend names one of ours. The code stays out of the family; the sentence supporting that decision no longer overstates.+ - **The family's HTTP answer moved from 422 to 500, and now says so.** `CONFIGURATION` implies `ErrorDomain.CONFIG`, which renders as 500, where the `CONTENT` these four used to receive implies `INPUT` and renders as 422. That is the right answer in kind and the same one the status ladder's 404 arm has always given — but it puts these in server-error alerting and hands outer clients a status they retry, which is worth stating beside "never retried" (a claim about `InferenceErrorCategory.is_retryable` inside this process, and about nothing else). Documented in the error-model page and the changelog, and pinned by `TestWhatTheFamilyAnswersOverHTTP`.+ - **A correction to a finding the review raised and the code refuted.** The advice for `pig-01` was reported lost at the pipe boundary, since `PipeOperatorModelAvailabilityError`'s constructor takes no user action. It is not: `PipelexError._enrich_error_report_from_cause` inherits `user_action` and `error_domain` off the `__cause__` chain, and `pipe_operator.py` raises `from` the original. Probed live, and now pinned by `TestTheAdviceSurvivesThePipeBoundary` — which mutation-testing shows goes red both when the category is reverted and when that enrichment line is dropped.+ - **Two doc precision fixes.** The closing "remaining codes" sentence was a closed two-item list that omitted `pig-12` (unmapped, filed as [L-260901-0859e8](http://localhost:4747/i/L-260901-0859e8)); it now names it and says what closes it. And `pig-05`'s path shape is the gateway-prefixed `/v1/<v1|v1alpha|v1beta>/models/<model>:generateContent` with a `streamGenerateContent` twin, not the bare `/v1beta` single form the comment and the page claimed.++- **Checkpoint 4 — landed (2026-09-02).** PR #1185 was squash-merged into `feature/Two-gateways-2` as `6c4b834bc`, with every CI job green: the eight py3.11 test shards, the typecheck, and each lint job (agent-rules, config-sync, drift-contracts, hub layering, keyword-only, ruff + plxt). [L-260831-9963b5](http://localhost:4747/i/L-260831-9963b5) is closed `fixed` against that merge. The merge sits on the stack's own branch and has not yet reached `dev` or `main`, so nothing here is published: it travels with whatever pull request takes `feature/Two-gateways-2` onward, and the repo's open release item is [L-260828-f4e88c](http://localhost:4747/i/L-260828-f4e88c).++ The items this campaign filed stay open by design, each recorded above and none of them a loose end of this plan:++ - [L-260901-0859e8](http://localhost:4747/i/L-260901-0859e8) — the `pig-12` map entry, split out at checkpoint 1.+ - [L-260902-a8f50b](http://localhost:4747/i/L-260902-a8f50b) — the Google Extract hop returning `"failure"` as a provider error code, to be fixed before any native Google path is pointed at a gateway.+ - [L-260902-701614](http://localhost:4747/i/L-260902-701614) — the gateway-side split of `pig-01`, whose three facts under one code are why the detail is hedged rather than asserting a deck-versus-gateway disagreement.+ - [L-260902-b17ff6](http://localhost:4747/i/L-260902-b17ff6) — the default this campaign kept proving is missing: an unmapped code in the gateway's own namespaces must never degrade to "review your prompt".diff --git a/wip/gateway-unresolved-references/plan.md b/wip/gateway-unresolved-references/plan.mdnew file mode 100644index 000000000..f8d8bcb4c--- /dev/null+++ b/wip/gateway-unresolved-references/plan.md@@ -0,0 +1,140 @@+---+status: landed+item: L-260901-b0bd98+---++# Classify the gateway's "cannot resolve this reference" refusals++## The bug, verified++The inference gateway's unresolvable-reference refusals arrive at `classify_inference_error` carrying their own error codes, and nothing reads them. They fall through to the `status_code == 400` arm of the status ladder in `pipelex/cogt/inference/error_classify.py`, classify as `CONTENT` / `CHANGE_INPUT`, and render the generic *"The provider rejected the request — review the prompt, parameters, and inputs."* A caller who mistyped a `pipelex-storage://` key, pointed at an object the gateway's role may not read, or aimed a document URL at a host the SSRF guard refuses, is told to revise their prompt.++Probed on this branch — every code in the family renders the generic advice:++```+pig-09: content / change_input "The provider rejected the request — review the prompt, parameters, and inputs."+pipelex_storage_uri_invalid: content / change_input (same)+pipelex_storage_unreadable: content / change_input (same)+pipelex_storage_uri_unsupported: content / change_input (same)+pipelex_document_host_refused: content / change_input (same)+pipelex_document_unreachable: content / change_input (same)+pipelex_document_unsupported_type: content / change_input (same)+```++The structural cause: `_GATEWAY_REQUEST_LIMIT_BY_CODE` in `pipelex/cogt/inference/error_classification.py` maps only the request-shape limits (`pig-07`, `pig-08`, `pig-10`, `pig-11`, `pipelex_storage_object_too_large`, `pipelex_document_too_large`). The unresolvable-reference codes are deliberately absent — the `gateway_request_limit` property's docstring even promises they "classify on their status like anything else", which is exactly the behaviour this plan removes.++The codes are readable today because the fix that landed on this PR's branch made the two Pipelex-service Extract hops read `error.code` before `error.type` (`_pipelex_service_error_code_from_body`). Before that, all of these arrived as `invalid_request_error`. The mechanism to classify them — a code-keyed enum ahead of the status ladder, plus a dedicated render branch — already exists for the request-limit family and is the shape this work copies.++## The code inventory, from the manifold source++Verified against `pipelex-manifold/src/pig/`:++| Code | HTTP | Raised by | Meaning |+|---|---|---|---|+| `pig-09` | 400 | `modelResolver.ts` (LLM routes) | the one fail-closed slot for "cannot resolve" — every `StorageFailureReason` but `oversize`: no bucket configured, not a storage reference, no such object, an object it cannot read, a type no provider takes, or no way to hand a file to the resolved provider. The message carries the difference; the code does not. |+| `pipelex_storage_uri_invalid` | 400 | `storage/nativeRoute.ts` | the reference does not obey the key grammar (also the traversal guard) |+| `pipelex_storage_unreadable` | 400 | `storage/nativeRoute.ts` | the object is not there, or the role may not read it |+| `pipelex_storage_uri_unsupported` | 400 | `storage/nativeRoute.ts` | no bucket configured — the scheme is not served at all |+| `pipelex_document_scheme_refused` | 400 | `pipelex/documentFetch.ts` | the document URI is not an http(s) URL |+| `pipelex_document_host_refused` | 400 | `pipelex/documentFetch.ts` | the SSRF guard refuses the host — a deliberate security refusal |+| `pipelex_document_address_refused` | 400 | `pipelex/documentFetch.ts` | the resolved address is blocked (private/internal ranges) |+| `pipelex_document_redirect_refused` | 400 | `pipelex/documentFetch.ts` | the origin answered a redirect, which the gateway refuses to follow |+| `pipelex_document_unreachable` | 400 | `pipelex/documentFetch.ts` | the origin answered a non-success status |+| `pipelex_document_empty` | 400 | `pipelex/documentFetch.ts` | the document was served empty |+| `pipelex_document_unsupported_type` | 400 | `pipelex/documentFetch.ts` | the served MIME type is not one the pipeline accepts |+| `pipelex_document_bad_data_url` | 400 | `pipelex/documentFetch.ts` | a `data:` URL that cannot be decoded |++Out of scope, noted for completeness: `pig_storage_timeout` (504) and `pig_storage_client_disconnected` (499) are deadline outcomes, not reference verdicts — 504 already classifies transient via the ≥500 arm, which is right for a timeout. They stay with the status ladder.++## The design decision: the arms++This is the work the ledger item names: deciding which `UserActionKind` each member deserves, not just adding map entries. Grouping is by remedy — members share an arm only when the caller's next move is the same — mirroring how `GatewayRequestLimit` folds three codes into `OBJECT_TOO_LARGE`.++New enum `GatewayUnresolvedReference` in `error_classification.py`, beside `GatewayRequestLimit`:++| Member | Codes | Category / action | Advice (gist — final wording at implementation) |+|---|---|---|---|+| `REFERENCE_UNRESOLVED` | `pig-09` | `CONTENT` / `CHANGE_INPUT` | a file reference in the request could not be resolved — the error message names the cause; fix the reference it names. Deliberately defers to the message because the code is the LLM routes' single fail-closed slot for every storage failure but "over its cap". |+| `STORAGE_REFERENCE_INVALID` | `pipelex_storage_uri_invalid` | `CONTENT` / `CHANGE_INPUT` | the `pipelex-storage://` reference is malformed — check the key against what the upload returned |+| `STORAGE_OBJECT_UNREADABLE` | `pipelex_storage_unreadable` | `CONTENT` / `CHANGE_INPUT` | the referenced object does not exist or cannot be read — check the reference points at an object that was uploaded to this deployment |+| `STORAGE_NOT_SERVED` | `pipelex_storage_uri_unsupported` | `CONFIGURATION` / `CONTACT_SUPPORT` | this deployment does not serve `pipelex-storage://` references at all — an operator's problem, nothing about the inputs causes it |+| `DOCUMENT_URL_REFUSED` | `pipelex_document_scheme_refused`, `pipelex_document_address_refused`, `pipelex_document_redirect_refused` | `CONTENT` / `CHANGE_INPUT` | the document URL was refused before or during the fetch — use a plain public http(s) URL, and send the final URL rather than one that redirects |+| `DOCUMENT_HOST_REFUSED` | `pipelex_document_host_refused` | `CONTENT` / `CHANGE_INPUT` | the gateway refuses to fetch documents from this host — **a security policy, stated as one**: private and internal addresses are not fetchable; host the document publicly or upload it to Pipelex storage. Never "use a smaller file" or "revise the prompt". |+| `DOCUMENT_UNREACHABLE` | `pipelex_document_unreachable` | `CONTENT` / `CHANGE_INPUT` | the document could not be fetched from its URL — check that it is live and publicly reachable |+| `DOCUMENT_CONTENT_UNUSABLE` | `pipelex_document_empty`, `pipelex_document_unsupported_type`, `pipelex_document_bad_data_url` | `CONTENT` / `CHANGE_INPUT` | the document was fetched but is unusable — the message says whether it was empty, of an unsupported type, or a malformed `data:` URL |++Decisions taken, and why:++- **`STORAGE_NOT_SERVED` is the one `CONTACT_SUPPORT` arm.** The ledger item calls this out: no bucket configured is a deployment that does not serve the scheme, so telling the caller to fix their input is wrong in kind. `CONFIGURATION` category, matching `BODY_LENGTH_REQUIRED`'s precedent for "an operator's problem".+- **`DOCUMENT_HOST_REFUSED` keeps `CHANGE_INPUT` but gets its own member.** The caller *can* act (host the file elsewhere, or upload it to storage), so the action kind is right — but the advice must say the refusal is deliberate security policy, not a fault to work around. Folding it into `DOCUMENT_URL_REFUSED` would lose exactly the distinction the item exists for.+- **`address_refused` groups with the URL-shape refusals, not with `host_refused`.** Both are SSRF-guard outcomes, but `address_refused` fires on the resolved address and reads to the caller the same way as a refused scheme: this URL form is not accepted. If review prefers it beside `host_refused` under the security wording, that is a one-line regroup.+- **`DOCUMENT_UNREACHABLE` is not retried.** The origin could have been transiently down, but the gateway renders it 400, the runtime's retry would re-run a whole inference call to re-fetch a document, and the common case is a wrong URL. The advice can mention retrying manually if the host was down; the classifier does not.+- **Nothing in the family is retryable.** Same reasoning as the request limits: the gateway refused before a provider saw the request; an identical retry earns an identical refusal.+- **Every arm defers numbers and specifics to the gateway's own message.** Same principle as `_render_gateway_limit_detail`: the refusal message beside the detail already names the key, host, status, or type; repeating a guess is how advice contradicts the refusal it explains.++## Implementation steps++### 1. The classification family — `pipelex/cogt/inference/error_classification.py`++- Add `GatewayUnresolvedReference` (StrEnum) with the members above, docstrings citing the wire codes and statuses, following `GatewayRequestLimit`'s style.+- Add `_GATEWAY_UNRESOLVED_REFERENCE_BY_CODE` mapping all twelve codes. Matched on the code alone with no provider check, for the same reason as the limits map (the codes are the gateway's own namespaces; three SDK hops report three provider names).+- Add a `gateway_unresolved_reference` property on `ProviderErrorMetadata`, mirroring `gateway_request_limit`.+- **Rewrite the `gateway_request_limit` docstring's last paragraph**, which currently promises the storage codes "classify on their status like anything else" — after this change that sentence is false.++### 2. The classify step — `pipelex/cogt/inference/error_classify.py`++- Add `gateway_unresolved_reference: GatewayUnresolvedReference | None = None` to `ClassificationResult` (a flag beside `gateway_request_limit`, same rationale: it does not change the retry decision, it lets Render name the refusal).+- Add `_classify_gateway_unresolved_reference(*, reference: GatewayUnresolvedReference)` returning `CONTENT`/`CHANGE_INPUT` for every member except `STORAGE_NOT_SERVED` → `CONFIGURATION`/`CONTACT_SUPPORT`.+- In `classify_inference_error`, branch on `metadata.gateway_unresolved_reference` right after the request-limit branch — the two code sets are disjoint, both are explicit verdicts from a service we operate, and both must run ahead of the status ladder.++### 3. The render step — `pipelex/cogt/inference/error_render.py`++- Add `_render_gateway_unresolved_reference_detail(*, reference: GatewayUnresolvedReference) -> str` with one advice string per member (gists above).+- In `_render_detail`, branch on `classification.gateway_unresolved_reference` beside the existing `gateway_request_limit` branch, ahead of the action-kind match.++### 4. Tests — `tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.py`++Mirror `test_gateway_request_limits.py`'s structure and its module docstring style:++- **The code is recognized**: each of the twelve codes maps to its member; unknown codes and `None` do not; recognition is provider-blind (`GATEWAY`, `ANTHROPIC`).+- **The code survives every Extract hop**: through the Portkey substrate (including the payload-discarding SDK path), plain `httpx` on the native routes, the shared Anthropic driver, and the OpenAI substrate — reusing that module's envelope helpers where sharable.+- **Classification**: every member is `CHANGE_INPUT` except `STORAGE_NOT_SERVED` which is `CONTACT_SUPPORT`; none is transient; a plain 400 without a recognized code still takes the status ladder.+- **Rendered advice**: `DOCUMENT_HOST_REFUSED` advice names a security refusal and never suggests revising the prompt or shrinking a file; `STORAGE_NOT_SERVED` says contact support, not fix your input; the storage members are told apart from each other; no member renders the generic "review the prompt" line.+- **The two families do not shadow each other**: `pipelex_storage_object_too_large` still classifies as a request limit, `pipelex_storage_unreadable` as an unresolved reference.++### 5. Docs and changelog++- `docs/under-the-hood/error-model.md` § "The Gateway's Own Refusals": add the second family's table (code / HTTP / member / category-action / what the caller is told) after the request-limit table, and extend the surrounding prose — one refusal family bounds request shape, the other says a reference cannot be resolved. Update the layer-model table row for `error_classification.py` to name the new enum and property.+- `CHANGELOG.md` under `[Unreleased]` → Added: one condensed entry in the style of the request-limits entry.+- No new error class is introduced (no `gei`/`gep` needed); no config change; no spec/conformance surface touched.++### 6. Gate++`make agent-check`, then `make agent-test` (full — the new test module and `.test_durations` need the full run).++## Checkpoint — the implementation landed++Every step above is implemented on this branch. What was decided or discovered while building it, beyond what the design section already records:++- **The arms are exactly as designed**; review did not move `address_refused`, so it stays with the URL-shape refusals under `DOCUMENT_URL_REFUSED` and `DOCUMENT_HOST_REFUSED` keeps its own arm.+- **The two families are pinned as disjoint by a test rather than by a comment.** `TestTheTwoGatewayFamiliesDoNotShadowEachOther` walks both code sets and asserts each reaches one family and not the other, so a code added to the wrong map fails rather than silently borrowing the other family's advice. The `pipelex_storage_*` codes are the case that needs it: `object_too_large` is a limit, `unreadable` is an unresolved reference, and both arrive from the same route.+- **The test module keeps one parametrize table as its single source of codes** (`_EVERY_CODE_AND_MEMBER`), reused by the recognition, classification, rendering and disjointness cases, plus a case asserting every enum member is reachable from a wire code — a member no code reaches would be advice that never renders for anyone.+- **The docs section grew two `####` headings** rather than one long run: the existing request-limit half is now "What the request may weigh" and the new half "When a reference cannot be resolved", under the unchanged `### The Gateway's Own Refusals`. Nothing links to those anchors, so the split breaks no reference. The closing paragraph now names `pig_storage_timeout` / `pig_storage_client_disconnected` explicitly as belonging to neither family, which is where the inventory's out-of-scope note now lives in shipped documentation.++## Checkpoint — landed++Merged as pipelex#1181, *"Classify the gateway's unresolvable-reference refusals"*, squashed onto the stack trunk `feature/Two-gateways-2` — the branch this work was stacked on. Commits are named by subject rather than by hash throughout this document, because every rebase of the trunk rewrites them.++What the merge carries, against the steps above: all six are done as written. The two commits on the branch were *"classify the gateway's unresolvable-reference refusals"* (the family, the classify branch, the render branch, the test module, the docs half) and *"recognize the scheme refusal a caller actually reaches"* — the second a review correction adding `pipelex_unsupported_uri_scheme` to `DOCUMENT_URL_REFUSED` beside `pipelex_document_scheme_refused` rather than in place of it. `classifyExtractInput` runs before any fetch and admits only `https:`, `data:` and `pipelex-storage://`, so an `http://` document URL is refused there and never reaches the fetch — which means the inventory's `pipelex_document_scheme_refused`, mapped and kept, is not the code that arm actually sees in practice. The family therefore covers thirteen wire codes, not the twelve this plan's inventory table lists.++Every check on the pull request passed — typecheck, all eight test shards on py3.11, and each lint job including the drift-contract and keyword-only gates.++**Delivery.** The merge is on `feature/Two-gateways-2` only; it has reached neither `dev` nor `main`. It ships when the trunk's own pull request lands, and reaches consumers when a pipelex release is cut after that — the repo's open release item is the one that carries #1154 (`L-260828-f4e88c`), which predates this work and does not yet include it.++**Left for a person.** Nothing this campaign asked for. The neighbouring gateway family — the routing refusals `pig-01`, `pig-02`, `pig-05` and `pig-06`, which still answer 400 and so advise a caller to revise their prompt when the real fault is an unknown model handle — is open work of its own under its own ledger item (`L-260831-9963b5`), not unfinished business here.++## Out of scope++- The manifold side is untouched: every code already exists on the wire and this is purely the runtime's reading of them.+- `pig_storage_timeout` / `pig_storage_client_disconnected` stay with the status ladder (see inventory).+- Per-plan / per-tier wording for the hosted product — same deferral as `_render_gateway_limit_detail` records.diff --git a/wip/two-gateways/review-deferrals.md b/wip/two-gateways/review-deferrals.mdnew file mode 100644index 000000000..93948a4a5--- /dev/null+++ b/wip/two-gateways/review-deferrals.md@@ -0,0 +1,68 @@+---+status: active+item: L-260825-577e2d+---++# Two managed gateways — review deferrals++Items surfaced by the automated review of the pull request that introduced the manifold dialect, verified against the code and deliberately not fixed in that pull request. Each one records what is actually wrong, what the reporting bot got wrong about it, and why it waited — so the session that picks it up does not have to re-derive any of it.++## D1 — `preprocess_test_models_cmd` reads a managed backend's TOML as a catalog++`_fetch_managed_gateway_models()` omits a backend's key entirely when its remote section is absent (`pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:139-144`, a bare `continue`), so `managed_backends` is keyed by **fetch outcome** rather than by configuration. The membership test at `:179-180` then lets that backend fall through to `_extract_models_from_backend_toml` and emits its per-backend TOML as a model catalog.++That is the wrong predicate, and for a reason deeper than the report gives: for a managed backend the per-backend TOML is **never** a catalog. `pipelex/cogt/model_backends/backend_library.py:499-506` feeds that same file to `GatewayConfigMerger.merge` as *overrides* on top of the remote specs, keeping only `sdk` and `structure_method`. Reading it with `_group_handles_by_model_type` is a category error regardless of whether the backend is enabled.++Two corrections to the report, both worth carrying forward:++- **The trigger it names is unreachable for `pipelex_gateway`.** `backend_model_specs` is a required declared field on `RemoteConfig` (`pipelex/system/pipelex_service/remote_config.py:29`), so any fetch that validated carries it and the section lookup can never return `None` for the legacy gateway. The absent-section branch is reachable only for a section arriving through `extra="allow"`, which today means the manifold one.+- **The regression the pull request actually introduced is a different one.** The version before it was an unconditional `if backend_name == "pipelex_gateway": continue`; the change made that conditional on the fetch outcome. So a user who *disables* the gateway — a product-supported state, `disable_managed_gateway_backends()` in `pipelex/cli/commands/init/backends.py` — now gets `pipelex_gateway.toml` read as a catalog. Note that the fix the bot proposes would not restore this, because `enabled_managed_gateway_sections` excludes disabled backends by design.++**Why it waited.** This is a development-only fixture generator with no shipped runtime behind it. Both managed backend TOML files are comment-only today, so `_extract_models_from_backend_toml` returns empty lists for both and the emit site guards on non-empty — nothing is produced. `_generated_model_sets.py` is gitignored and `.pipelex-dev/model_availability.json` is not committed, so no artifact exhibits the bad pairing. When it does fire, the failure mode is a loud red integration test rather than a silent false pass. Decisively, the one-line fix closes only the latent absent-section half; the disabled-gateway half needs a different predicate, and fixing half a latent trap was not worth another lap of the pull request.++**What the fix looks like.** In `_fetch_managed_gateway_models`, keep the key and let the value be empty rather than skipping the backend, so membership means "this backend's TOML is an override file" rather than "the fetch produced something". Then decide separately whether a *disabled* managed backend should also be excluded from local discovery — that is the second predicate question, and this command ignores `enabled` uniformly for every ordinary backend, so changing it is a deliberate choice rather than an obvious repair.++**One trap for whoever takes it.** `tests/unit/pipelex/cli/dev/test_preprocess_test_models_cmd.py:72` currently pins the present shape, asserting that a backend whose section is absent is excluded from the returned mapping. That assertion has to be flipped, not added beside.++## D2 — managed-backend-blind user-facing strings++Several user-facing strings still name the Portkey-cloud service specifically, on paths that now serve either managed backend:++- `pipelex/cli/commands/doctor_cmd.py:1092-1094` gates on `enabled_managed_gateway_sections()` but reports the hardcoded "Pipelex Gateway is enabled but terms have not been accepted", which is wrong on a manifold-only machine.+- The terms panel itself asks about "the Pipelex Gateway terms of service" wherever it is raised, including now for a manifold-only selection.+- `AGENT_ERROR_HINTS["GatewayTermsNotAcceptedError"]` (`pipelex/cli/agent_cli/commands/agent_output.py:134`) recommends `pipelex init config` to accept the terms and suggests disabling `pipelex_gateway` — the first does not prompt, and the second is already off in the case that produces the error.+- `RemoteConfigFetcher._build_unavailable_error` (`pipelex/system/pipelex_service/remote_config_fetcher.py:196-204`) reports "Pipelex Gateway is enabled but the remote configuration is unreachable" and recommends disabling `pipelex_gateway` — reachable on a manifold-only machine whose first offline dry-run finds no cache, where the backend it names is already off.++This is the same family as the backend attribution the pull request added to `GatewayUnknownModelError`: a message that assumes there is one managed service. It was left out of that change deliberately, as a coherent wording sweep rather than something bundled into a correctness fix, and because the naming a second dialect deserves in user-facing copy is a product decision rather than a mechanical rename.++## D3 — the search worker indexes source dicts raw++`ManifoldSearchWorker._search_sourced_answer` (`pipelex/providers/manifold/manifold_search_worker.py:82-93`) checks `answer` carefully — `isinstance(answer, str)`, then a `ManifoldSearchResponseError` carrying a category and a user action — and then builds `sources` by indexing each entry directly: `source["name"]`, `source["url"]`, `source["snippet"]`, after a `cast` that asserts a shape nothing verified. A `sources` list carrying an entry that is not an object, or an object missing one of those three keys, raises a bare `KeyError` or `TypeError`.++That is precisely the failure mode `ManifoldNativeClient`'s own docstring names as the thing to avoid (`pipelex/providers/manifold/manifold_native_client.py:88-92`): an exception that is neither a `PipelexError` nor annotated with the model escapes the Temporal error bridge and is retried against a search that has already been paid for.++**Two corrections to keep in view.** This is not new and it is not manifold-specific: `GatewaySearchWorker._search_sourced_answer` (`pipelex/providers/gateway/gateway_search_worker.py:86-95`) does the identical thing, and additionally reads `result_dict["answer"]` unguarded where the manifold worker guards it. So the manifold path is strictly the better of the two, and a fix belongs to both or to a shared helper — which is also why it was not bundled into a pull request whose whole shape is "the manifold package imports nothing from the gateway one".++**Why it waited.** It needs a malformed response from our own service to fire, the pull request already raised the bar for the response fields it touched, and the honest fix is a sweep across both workers rather than a patch to the new one — which would leave the shipped path worse than the beta path.++**What the fix looks like.** A `ManifoldSearchSource` pydantic model beside the request schemas in `manifold_schemas.py`, validated per entry, with a malformed entry raising `ManifoldSearchResponseError` the way a missing `answer` already does. The gateway worker gets the same treatment against its own exception class when the sweep happens.++## D4 — init decides managed-ness by name, the boot by declaration++The boot's question is structural: a backend is a managed gateway backend when it declares a `model_specs_section` (`pipelex/cogt/model_backends/backend.py:52-68`, `resolve_model_specs_section`; the field is `InferenceBackendBlueprint.model_specs_section`, `pipelex/cogt/model_backends/backend_factory.py:19`, read off the raw `backends.toml` table with no allow-list on the name). `enabled_managed_gateway_sections` (`pipelex/system/pipelex_service/pipelex_service_config.py:78`) answers it, and both the boot's terms gate and `pipelex init agreement` (`_init_agreement`) ask it. The other init sites ask by name instead, through `MANAGED_GATEWAY_BACKEND_NAMES` (`backend.py:49`): `_check_gateway_terms_if_needed` (`pipelex/cli/commands/init/command.py:168`), `customize_backends_config`'s prompt and decline-removal (`pipelex/cli/commands/init/backends.py:152,163`), `disable_managed_gateway_backends` (`backends.py:92`), and the agent flow's `accept_gateway_terms` handling (`pipelex/cli/agent_cli/commands/init_cmd.py:221`).++The consequence, for a backend that declares a section under a name the constant does not list: the boot puts the installation behind the terms, `pipelex init agreement` prompts for them, but declining leaves that backend enabled — `disable_managed_gateway_backends` iterates the constant, so its own docstring's promise, *"has to leave no managed backend enabled"*, is not kept — and the next inference boot refuses with `GatewayTermsNotAcceptedError`. `pipelex init config` and `pipelex-agent init` prompt for nothing on such an installation while still marking inference setup complete.++A second, name-independent mismatch sits on the same lines: `get_selected_backend_keys` (`backends.py:70`) counts a backend as enabled only on a literal `enabled = true`, defaulting to disabled when the key is absent, whereas the boot reads truthiness with default-enabled (`pipelex_service_config.py:106`, and the loader it mirrors). A `[pipelex_manifold]` table with `enabled = 1`, or with no `enabled` key, is live to the boot and invisible to the init terms prompt even though its name is in the constant.++**What the reporting bot got wrong.** It said init "provides no way to accept" the terms for such a backend. `pipelex init agreement` is that way, and it asks the boot's question — pinned by `tests/unit/pipelex/cli/commands/test_init_agreement_any_managed_gateway.py`. The gap is in the disable-after-refusal path and in the two flows that prompt during setup, not in acceptance.++**Why it waited.** No product path declares a third section: the published configuration carries two, and a future one lands in this repository together with the constant. The kit template always writes literal booleans, so the truthiness mismatch bites only a hand-edited file. And the constant was the deliberate shape of the round-1 fix for callers that hold only backend names — the picker's selection, the agent request's `backends` list — so replacing it is a design change rather than a repair.++**What the fix looks like.** A helper in `init/backends.py` that derives the managed backend names from the tomlkit document the init code already holds, by applying `resolve_model_specs_section` to each table, so the four sites ask the boot's question over the same file and the constant retires from init. `get_selected_backend_keys` reads `enabled` the loader's way. The trap: make the code match `disable_managed_gateway_backends`'s docstring, not the reverse.++## Declined++### `ManifoldCompletionsFactory.make_simple_messages` duplicates the OpenAI message builder++Verified and declined. The override (`pipelex/providers/manifold/manifold_completions_factory.py:47-104`) re-states the base class's system-text, user-text and image handling to change seven lines of document encoding, and `OpenAICompletionsFactory` exposes no narrower seam for it. But it is byte-identical to `GatewayCompletionsFactory`'s override save for three comments, `PortkeyCompletionsFactory` carries a third copy on `dev`, and the module docstring (lines 3-14) records why subclassing the gateway factory was rejected: inheriting the Portkey extract parsing and header build would make retiring that package an untangling rather than a deletion. `tests/unit/pipelex/providers/manifold/test_manifold_completions_messages.py:148-178` is an explicit drift guard asserting the manifold and gateway overrides produce equal messages. A `_make_document_part` hook in `OpenAICompletionsFactory` that the three subclasses override would collapse the copies; it is a cleanup across `openai/`, `gateway/`, `portkey/` and `manifold/`, and the moment for it is the Portkey path's retirement, when two of the three copies disappear anyway.