Skip to content

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

feature/Manifold-generic-seams · L-261004-becac9 (#1332)

Louis Choquel341986d595ee
diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.toml
index 641cc9590..c0ebf3581 100644
--- a/.drift/acks/hub-layering-convention.toml
+++ b/.drift/acks/hub-layering-convention.toml
@@ -1,10 +1,10 @@
contract = "hub-layering-convention"
-digest = "sha256:717ab382b52b2fa43c750bd30036428fb9d363cd0a5f8e86faffb4ebc0d86f3f"
+digest = "sha256:35e4a1027244f3cc4546249c0a3b4d3937ceb5a10a20b74c536b2cc72439ea6a"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-04T14:31:48Z"
-rationale = "real-catch: runtime_hub.py's docstring dropped builder from the interpreter packages it may not name, since pipelex.builder no longer exists. docs/contribute/hub-layering.md named it in the same list and in its verification snippet's INTERPRETER set, which the closure test compares against INTERPRETER_PACKAGES, and listed builder/runner_code among the interpreter callers that supply get_concept_library(); all three now leave it out."
+reviewed_at = "2026-10-04T18:44:31Z"
+rationale = "real-catch: runtime_hub.py gained get_optional_service_error_vocabulary and its setter, the plugins' service error codes frozen at boot; hub-layering.md's plugin-registries row and its sentence on what RuntimeBoot.setup installs on the RuntimeHub now name it."
[trigger_files]
"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:2dbadcbab7d44364a7b5f1d16268b23b26700a00"
"pipelex/interpreter_hub.py" = "blob:327e75d0fbb5bdf46f6cbf06024f83840f0106d0"
-"pipelex/runtime_hub.py" = "blob:485fefa16424ad368e80a5008beab7bd5bf86305"
+"pipelex/runtime_hub.py" = "blob:05f84b9604b9f904e7df96d222b8856123ce9e91"
diff --git a/.test_durations b/.test_durations
index d3901b030..762382c63 100644
--- a/.test_durations
+++ b/.test_durations
@@ -194,6 +194,7 @@
"tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_init_warns_when_cache_write_fails": 0.0186,
"tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_init_warns_when_offline": 0.0218,
"tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_init_warns_when_offline_with_stale_cache_present": 0.028,
+ "tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_init_warns_when_the_written_cache_does_not_read_back": 0.0211,
"tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_priming_reads_backends_toml_from_target_dir": 0.1575,
"tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_priming_runs_for_a_manifold_only_installation": 0.5568,
"tests/integration/pipelex/cli/test_advisory_warning_channels.py::TestAdvisoryWarningChannels::test_agent_cli_bundle_envelope_carries_all_three_families": 0.6051,
@@ -3811,57 +3812,6 @@
"tests/unit/pipelex/cogt/inference/test_error_classification_unwrap.py::TestExtractUnderlyingSdkException::test_returns_none_when_both_paths_empty": 0.0005,
"tests/unit/pipelex/cogt/inference/test_error_classification_unwrap.py::TestExtractUnderlyingSdkException::test_returns_the_last_attempt_of_a_spent_retry_budget": 0.3906,
"tests/unit/pipelex/cogt/inference/test_error_classification_unwrap.py::TestExtractUnderlyingSdkException::test_returns_the_sdk_exception_the_wrapper_is_chained_from": 0.0819,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestClassification::test_a_412_without_a_recognized_code_still_takes_the_status_ladder": 0.0016,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestClassification::test_a_model_not_allowed_refusal_asks_for_another_model_and_is_not_a_missing_model": 0.0005,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestClassification::test_a_refusal_the_caller_can_route_around_asks_them_to_change_the_model[model_not_allowed_error]": 0.0006,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestClassification::test_each_code_classifies_as_its_member_and_is_never_retried[model_not_allowed_error-model_not_allowed]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestClassification::test_only_the_unknown_model_is_a_missing_model[model_not_allowed_error]": 0.0008,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestEndToEnd::test_a_model_not_allowed_refusal_reaches_the_caller_as_a_change_model_naming_the_handle": 0.0061,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_every_other_member_leaves_the_handle_to_the_message[pig-01]": 0.2984,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_every_other_member_leaves_the_handle_to_the_message[pig-02]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_every_other_member_leaves_the_handle_to_the_message[pig-05]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_every_other_member_leaves_the_handle_to_the_message[pig-06]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_no_member_renders_the_generic_action_kind_advice_either[model_not_allowed_error]": 0.0006,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_no_member_renders_the_generic_rejection_line[model_not_allowed_error]": 0.0018,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_the_detail_names_the_remedy[model_not_allowed_error-does not allow the model]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_the_model_not_allowed_advice_names_the_handle_and_not_the_wire_id": 0.0003,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_the_model_not_allowed_advice_offers_the_default_only_when_the_pipe_named_the_model": 0.0006,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestRenderedAdvice::test_the_model_not_allowed_advice_says_who_settles_a_deck_disagreement_on_either_gateway": 0.0006,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheAdviceSurvivesThePipeBoundary::test_the_model_not_allowed_advice_reaches_the_caller_through_the_located_failure": 0.0049,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_any_other_code_is_not_a_routing_refusal[MODEL_NOT_ALLOWED_ERROR]": 0.0002,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_any_other_code_is_not_a_routing_refusal[model_not_allowed]": 0.0003,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_each_code_maps_to_its_member[model_not_allowed_error-model_not_allowed]": 0.0829,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_every_member_is_reachable_from_a_wire_code[model_not_allowed]": 0.0003,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-anthropic]": 0.0008,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-azure]": 0.0012,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-bedrock]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-docling]": 0.0043,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-fal]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-gateway]": 0.001,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-google]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-huggingface]": 0.0014,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-linkup]": 0.0014,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-mistral]": 0.0005,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-openai]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[model_not_allowed_error-model_not_allowed-pypdfium2]": 0.0039,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-anthropic]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-azure]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-bedrock]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-docling]": 0.0009,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-fal]": 0.0019,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-gateway]": 0.3795,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-google]": 0.0003,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-huggingface]": 0.0011,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-linkup]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-mistral]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-openai]": 0.0007,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeIsRecognized::test_the_code_is_read_whichever_provider_reported_it[pig-01-unknown_model-pypdfium2]": 0.0004,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeSurvivesEveryExtractHop::test_the_model_not_allowed_refusal_through_every_hop[anthropic-driver]": 0.0178,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeSurvivesEveryExtractHop::test_the_model_not_allowed_refusal_through_every_hop[native-routes-httpx]": 0.0006,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeSurvivesEveryExtractHop::test_the_model_not_allowed_refusal_through_every_hop[openai-substrate]": 0.3114,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheCodeSurvivesEveryExtractHop::test_the_model_not_allowed_refusal_through_every_hop[portkey-substrate]": 0.0529,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestTheThreeGatewayFamiliesDoNotShadowEachOther::test_no_routing_code_belongs_to_another_family[model_not_allowed_error]": 0.0005,
- "tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py::TestWhatTheFamilyAnswersOverHTTP::test_the_model_not_allowed_refusal_answers_500_as_it_did_before": 0.0012,
"tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py::TestProviderClassificationParity::test_every_provider_name_has_an_extract_fn": 0.8455,
"tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py::TestProviderClassificationParity::test_extract_fn_populates_envelope_for_each_provider[anthropic]": 0.002,
"tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py::TestProviderClassificationParity::test_extract_fn_populates_envelope_for_each_provider[azure]": 0.0005,
@@ -13343,6 +13293,5 @@
"tests/unit/repo/test_docs_cite_nothing_private.py::TestDocsCiteNothingPrivate::test_published_docs_cite_nothing_in_the_private_workspace": 0.5197,
"tests/unit/repo/test_test_durations_paths.py::TestTestDurationsPaths::test_durations_file_is_committed_and_not_empty": 0.8507,
"tests/unit/repo/test_test_durations_paths.py::TestTestDurationsPaths::test_every_node_id_is_rooted_in_a_test_file_path": 0.0153,
- "tests/unit/repo/test_test_durations_paths.py::TestTestDurationsPaths::test_every_recorded_test_file_still_exists": 0.1253,
- "tests/integration/pipelex/cli/commands/init/test_cache_priming.py::TestCachePriming::test_init_warns_when_the_written_cache_does_not_read_back": 0.0211
+ "tests/unit/repo/test_test_durations_paths.py::TestTestDurationsPaths::test_every_recorded_test_file_still_exists": 0.1253
}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 088af6ab0..d90cef2bd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,8 +2,17 @@
## [Unreleased]
+### Added
+
+- **Service error codes, contributed by the plugin that speaks to the service**: a plugin declares each error code its gateway or hosted service emits on its own as a `ServiceErrorCode`, with its category, its user action, its advice and whether it means an unknown model, and hands them to `PluginRegistrar.add_service_error_codes`. `classify_inference_error` consults the booted plugins' codes ahead of the HTTP status ladder and `render_inference_error` renders the matched entry's advice; a code two plugins contribute fails the boot with `DuplicateServiceErrorCodeError`, and one the runtime classifies itself with `ReservedServiceErrorCodeError`.
+- **Request extras on the Anthropic worker**: `AnthropicLLMWorker` takes an optional `extras_factory`, the `BackendExtrasFactory` the OpenAI-substrate workers already take, whose headers and body additions join every text and structured call, and `AnthropicFactory.make_anthropic_client` takes an `sdk_variant`, so a plugin can register an sdk token of its own over the Anthropic protocol.
+
### Changed
+- **The completions image worker's fixed output format comes from its registration**: `OpenAICompletionsImgGenWorker` takes `fixed_output_format`, the one image format a service answers in, rather than inferring it from the backend's name; a request for another format is refused before the call, and a URL answer from a worker built without one is refused as unreadable.
+- **The Inference SPI table lists every symbol a provider plugin builds on**: `docs/under-the-hood/inference-backend-plugins.md` now publishes, one module per row, the worker contracts with their jobs and outputs, the OpenAI- and Anthropic-protocol factories and workers, the image-generation and prompt-preparation helpers, the error pipeline and the runtime accessors, and `parse_retry_after_seconds` and `error_code_from_body_code_first` become public in `pipelex.cogt.inference.error_classification` for a plugin that distils a plain-HTTP failure itself.
+- **The Anthropic worker no longer adds a backend's headers by backend name (Breaking)**: a worker built without an `extras_factory` sends nothing extra, whatever its backend, so a backend that relied on the worker adding its request headers must register its own sdk token with an extras factory and name that token in the `sdk` of its model specs, local overrides included; a model left on `anthropic` keeps answering, without those headers.
+- **The gateway refusal families leave the core classifier (Breaking)**: `GatewayRequestLimit`, `GatewayUnresolvedReference` and `GatewayRoutingRefusal`, the matching properties of `ProviderErrorMetadata` and fields of `ClassificationResult`, and `MANAGED_GATEWAY_BACKEND_NAMES` are removed; a gateway's own codes now reach `ClassificationResult.service_error_code` through the plugin that contributes them, and Portkey's `model_not_allowed_error` is read by `ProviderErrorMetadata.is_model_not_allowed` and `ClassificationResult.is_model_not_allowed`. Errors raised by the hosted-only provider plugin now report the `type` and `title` of their generic family, such as `extract-job-failure-error`, rather than pages and titles of their own.
- **The default extractors are waterfalls**: `@default-extract-document` takes the first of Azure Document Intelligence, Mistral OCR and `pypdfium2-extract-pdf` that an enabled backend serves, and `@default-extract-image` and `@default-premium` the first of the two OCR models, where all three named Azure Document Intelligence, which only the Pipelex Gateway and Pipelex Manifold serve. A `PipeExtract` step naming no model therefore runs on Manifold, on Mistral OCR with your own key, or, for a PDF, on its text layer read locally, which recovers no text from a scanned page; a project's managed `3_extract_deck.toml` takes the new aliases with `pipelex update`.
### Removed
diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.md
index 1f492a978..4981f7e9e 100644
--- a/docs/contribute/hub-layering.md
+++ b/docs/contribute/hub-layering.md
@@ -48,7 +48,7 @@ There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as a
| run mode | `is_dry_run_forced`, `resolve_run_mode_for_boot` |
| boot orchestrator | `get_boot_orchestrator` |
| tracing | `scoped_event_log`, `get_event_log_override` |
-| plugin registries | `get_inference_backend_registry`, `get_model_lister_registry`, `get_orchestrator_registry`, `get_bundle_validator_registry`, `get_storage_provider_registry`, `get_secrets_provider_registry` |
+| plugin registries | `get_inference_backend_registry`, `get_model_lister_registry`, `get_orchestrator_registry`, `get_bundle_validator_registry`, `get_storage_provider_registry`, `get_secrets_provider_registry`, `get_optional_service_error_vocabulary` |
### `pipelex/interpreter_hub.py` — library-scoped method machinery
@@ -164,7 +164,7 @@ The second split *is* the layer boundary, and the same rule of thumb divides it.
External plugins are unaffected by the mechanism/adapter split: they import `pipelex.plugins.contract` and `pipelex.plugins.registrar`, both of which stayed put. They are, however, affected by the *layer* split — they are discovered through the two `pipelex.plugins.kernel` / `pipelex.plugins.interpreter` entry-point groups, which are group identifiers rather than module paths, and a plugin declares its layer by choosing one. (Careful: `pipelex.plugins` is also the name of the kernel-layer *package* holding the mechanism, and that is the sense every other mention of it on this page carries — the declared-package list, the transitive-breach worked example, the closure-test entry points. A package name and an entry-point group are unrelated things that happen to share a spelling. The single pre-split group of that name is retired and now fails startup.)
-The registrar's slots are *ports* and they stay kernel-layer — `OrchestratorProtocol`, `BundleValidatorProtocol` and `PipeFuncExecutorFactoryFn` all live under `plugins/*_registry.py`. Only the *adapters* are interpreter-layer. That is ordinary ports-and-adapters, and it is what the layer rule's own remedy text prescribes: have the interpreter layer install it downward at boot. Where each derived registry is *installed* still follows the hub partition rather than the port's home: `RuntimeBoot.setup` puts the orchestrator, bundle-validator, backend, lister, storage and secrets registries on the `RuntimeHub`, and `Pipelex.setup` puts the `PipeFuncExecutorRegistry` on the `InterpreterHub` — the one placement flagged [above](#which-hub-does-a-new-symbol-belong-to). Since [the boot split](#where-the-boot-splits) the two installs sit in the two halves that match their hubs, so the partition is now visible in the code rather than only in this sentence.
+The registrar's slots are *ports* and they stay kernel-layer — `OrchestratorProtocol`, `BundleValidatorProtocol` and `PipeFuncExecutorFactoryFn` all live under `plugins/*_registry.py`. Only the *adapters* are interpreter-layer. That is ordinary ports-and-adapters, and it is what the layer rule's own remedy text prescribes: have the interpreter layer install it downward at boot. Where each derived registry is *installed* still follows the hub partition rather than the port's home: `RuntimeBoot.setup` puts the orchestrator, bundle-validator, backend, lister, storage and secrets registries and the service error vocabulary on the `RuntimeHub`, and `Pipelex.setup` puts the `PipeFuncExecutorRegistry` on the `InterpreterHub` — the one placement flagged [above](#which-hub-does-a-new-symbol-belong-to). Since [the boot split](#where-the-boot-splits) the two installs sit in the two halves that match their hubs, so the partition is now visible in the code rather than only in this sentence.
Composition happens where welding is legal. `pipelex/providers/builtins.py` exports `KERNEL_BUILTIN_PLUGINS`; `pipelex/interpreter_plugins/builtins.py` imports that half — downward, which the interpreter layer may do — and exports the composed `BUILTIN_PLUGINS` and `CORE_UNCONDITIONAL_PLUGIN_NAMES`. Both are **parameters** of `build_registrar`, never module globals it imports, so `plugins/discovery.py` stays kernel-layer: `pipelex.py` (the interpreter boot) and the `pipelex plugins list` diagnostic pass the composed lists in, while `runtime_boot.py` defaults to the kernel half alone. Exactly one place still answers "what are the built-in plugins" — it just lives in the layer permitted to say it.
diff --git a/docs/errors/duplicate-service-error-code-error.md b/docs/errors/duplicate-service-error-code-error.md
new file mode 100644
index 000000000..74b08ec91
--- /dev/null
+++ b/docs/errors/duplicate-service-error-code-error.md
@@ -0,0 +1,21 @@
+---
+title: "Duplicate service error code"
+description: "Reference for the `DuplicateServiceErrorCodeError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Duplicate service error code
+
+Two plugins contributed the same service error code.
+
+| Field | Value |
+|---|---|
+| `error_type` | `DuplicateServiceErrorCodeError` |
+| `title` | Duplicate service error code |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/duplicate-service-error-code-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.plugins.exceptions` |
+| Parent class | [`PluginError`](plugin-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.md
index 2175831b7..e79343532 100644
--- a/docs/errors/inference-and-providers.md
+++ b/docs/errors/inference-and-providers.md
@@ -101,13 +101,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
+- [`ManifoldCredentialsError`](manifold-credentials-error.md) — Inference backend credentials missing
+- [`ManifoldEndpointError`](manifold-endpoint-error.md) — Inference backend endpoint missing
+- [`ManifoldError`](manifold-error.md) — Inference backend error
+- [`ManifoldExtractResponseError`](manifold-extract-response-error.md) — Extract response unreadable
+- [`ManifoldFactoryError`](manifold-factory-error.md) — Inference client setup error
+- [`ManifoldSearchEmptyResultError`](manifold-search-empty-result-error.md) — Search returned no result
+- [`ManifoldSearchResponseError`](manifold-search-response-error.md) — Search response unreadable
- [`MistralExtractResponseError`](mistral-extract-response-error.md) — Mistral extract response
- [`MistralModelListingError`](mistral-model-listing-error.md) — Mistral model listing
- [`MistralPluginError`](mistral-plugin-error.md) — Mistral plugin
@@ -136,6 +136,7 @@ own page. Classes are grouped by subsystem.
- [`DuplicateOrchestratorError`](duplicate-orchestrator-error.md) — Duplicate orchestrator
- [`DuplicatePipeFuncExecutorError`](duplicate-pipe-func-executor-error.md) — Duplicate pipe func executor
- [`DuplicateSecretsProviderError`](duplicate-secrets-provider-error.md) — Duplicate secrets provider
+- [`DuplicateServiceErrorCodeError`](duplicate-service-error-code-error.md) — Duplicate service error code
- [`DuplicateStorageProviderError`](duplicate-storage-provider-error.md) — Duplicate storage provider
- [`HubSlotAlreadyClaimedError`](hub-slot-already-claimed-error.md) — Hub slot already claimed
- [`InferenceBackendNotFoundError`](inference-backend-not-found-error.md) — Inference backend not found
@@ -143,6 +144,7 @@ own page. Classes are grouped by subsystem.
- [`PluginDeclaredInMultipleGroupsError`](plugin-declared-in-multiple-groups-error.md) — Plugin declared in multiple groups
- [`PluginError`](plugin-error.md) — Plugin error
- [`PluginLayerViolationError`](plugin-layer-violation-error.md) — Plugin layer violation
+- [`ReservedServiceErrorCodeError`](reserved-service-error-code-error.md) — Reserved service error code
- [`RetiredPluginEntryPointGroupError`](retired-plugin-entry-point-group-error.md) — Retired plugin entry point group
- [`UnknownBootOrchestratorError`](unknown-boot-orchestrator-error.md) — Unknown boot orchestrator
- [`UnknownLogSinkError`](unknown-log-sink-error.md) — Unknown log sink
diff --git a/docs/errors/manifold-credentials-error.md b/docs/errors/manifold-credentials-error.md
index 9e6593aa3..a821a5075 100644
--- a/docs/errors/manifold-credentials-error.md
+++ b/docs/errors/manifold-credentials-error.md
@@ -1,17 +1,17 @@
---
-title: "Manifold credentials"
+title: "Inference backend credentials missing"
description: "Reference for the `ManifoldCredentialsError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold credentials
+# Inference backend credentials missing
| Field | Value |
|---|---|
| `error_type` | `ManifoldCredentialsError` |
-| `title` | Manifold credentials |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-credentials-error/` |
+| `title` | Inference backend credentials missing |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-credentials-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`ManifoldError`](manifold-error.md) |
diff --git a/docs/errors/manifold-endpoint-error.md b/docs/errors/manifold-endpoint-error.md
index aabc5cef3..567ec2ddd 100644
--- a/docs/errors/manifold-endpoint-error.md
+++ b/docs/errors/manifold-endpoint-error.md
@@ -1,19 +1,19 @@
---
-title: "Manifold endpoint"
+title: "Inference backend endpoint missing"
description: "Reference for the `ManifoldEndpointError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold endpoint
+# Inference backend endpoint missing
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/` |
+| `title` | Inference backend endpoint missing |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/inference-backend-credentials-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`ManifoldError`](manifold-error.md) |
diff --git a/docs/errors/manifold-error.md b/docs/errors/manifold-error.md
index 7ec333ece..0227557f3 100644
--- a/docs/errors/manifold-error.md
+++ b/docs/errors/manifold-error.md
@@ -1,17 +1,17 @@
---
-title: "Manifold"
+title: "Inference backend error"
description: "Reference for the `ManifoldError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold
+# Inference backend error
| Field | Value |
|---|---|
| `error_type` | `ManifoldError` |
-| `title` | Manifold |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-error/` |
+| `title` | Inference backend error |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/cogt-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`CogtError`](cogt-error.md) |
diff --git a/docs/errors/manifold-extract-response-error.md b/docs/errors/manifold-extract-response-error.md
index 5c04fd348..d40c3a8fa 100644
--- a/docs/errors/manifold-extract-response-error.md
+++ b/docs/errors/manifold-extract-response-error.md
@@ -1,17 +1,17 @@
---
-title: "Manifold extract response"
+title: "Extract response unreadable"
description: "Reference for the `ManifoldExtractResponseError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold extract response
+# Extract response unreadable
| Field | Value |
|---|---|
| `error_type` | `ManifoldExtractResponseError` |
-| `title` | Manifold extract response |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-extract-response-error/` |
+| `title` | Extract response unreadable |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/extract-job-failure-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`ManifoldError`](manifold-error.md) |
diff --git a/docs/errors/manifold-factory-error.md b/docs/errors/manifold-factory-error.md
index f57728087..75f462495 100644
--- a/docs/errors/manifold-factory-error.md
+++ b/docs/errors/manifold-factory-error.md
@@ -1,17 +1,17 @@
---
-title: "Manifold factory"
+title: "Inference client setup error"
description: "Reference for the `ManifoldFactoryError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold factory
+# Inference client setup error
| Field | Value |
|---|---|
| `error_type` | `ManifoldFactoryError` |
-| `title` | Manifold factory |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-factory-error/` |
+| `title` | Inference client setup error |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/cogt-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`ManifoldError`](manifold-error.md) |
diff --git a/docs/errors/manifold-search-empty-result-error.md b/docs/errors/manifold-search-empty-result-error.md
index c0acb457c..54e18a454 100644
--- a/docs/errors/manifold-search-empty-result-error.md
+++ b/docs/errors/manifold-search-empty-result-error.md
@@ -1,17 +1,17 @@
---
-title: "Manifold search empty result"
+title: "Search returned no result"
description: "Reference for the `ManifoldSearchEmptyResultError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold search empty result
+# Search returned no result
| Field | Value |
|---|---|
| `error_type` | `ManifoldSearchEmptyResultError` |
-| `title` | Manifold search empty result |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-search-empty-result-error/` |
+| `title` | Search returned no result |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/search-job-failure-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`ManifoldError`](manifold-error.md) |
diff --git a/docs/errors/manifold-search-response-error.md b/docs/errors/manifold-search-response-error.md
index 858e2e1bd..9e8508257 100644
--- a/docs/errors/manifold-search-response-error.md
+++ b/docs/errors/manifold-search-response-error.md
@@ -1,17 +1,17 @@
---
-title: "Manifold search response"
+title: "Search response unreadable"
description: "Reference for the `ManifoldSearchResponseError` Pipelex error class."
---
<!-- pipelex:generated -->
-# Manifold search response
+# Search response unreadable
| Field | Value |
|---|---|
| `error_type` | `ManifoldSearchResponseError` |
-| `title` | Manifold search response |
-| `type_uri` | `https://docs.pipelex.com/latest/errors/manifold-search-response-error/` |
+| `title` | Search response unreadable |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/search-job-failure-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.providers.manifold.manifold_exceptions` |
| Parent class | [`ManifoldError`](manifold-error.md) |
diff --git a/docs/errors/reserved-service-error-code-error.md b/docs/errors/reserved-service-error-code-error.md
new file mode 100644
index 000000000..a31aa5f9f
--- /dev/null
+++ b/docs/errors/reserved-service-error-code-error.md
@@ -0,0 +1,21 @@
+---
+title: "Reserved service error code"
+description: "Reference for the `ReservedServiceErrorCodeError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Reserved service error code
+
+A plugin contributed a service error code the runtime classifies itself.
+
+| Field | Value |
+|---|---|
+| `error_type` | `ReservedServiceErrorCodeError` |
+| `title` | Reserved service error code |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/reserved-service-error-code-error/` |
+| `error_domain` | _(inherited from parent)_ |
+| Defined in | `pipelex.plugins.exceptions` |
+| Parent class | [`PluginError`](plugin-error.md) |
+
+[Back to Error Reference](index.md)
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 2a3c516d7..ed70181d1 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -272,8 +272,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`, `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_classification.py` | Extract | `ProviderErrorMetadata`, `SDKErrorEnvelope`, `UserAction`, `UserActionKind`, the `extract_*_metadata` functions and the parsers they share (`parse_retry_after_seconds`, `error_code_from_body_code_first`), plus pure discriminators (`is_quota_exhaustion`, `is_content_policy_violation`, `is_network_error`, `is_model_not_allowed`) 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, service_error_code, is_model_not_allowed)`, consulting the booted plugins' service error vocabulary ahead of the status ladder |
| `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.
@@ -298,96 +298,21 @@ 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
+### Service Error Codes
-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`.
+Not every failure on an inference call comes from a provider. A gateway or a hosted inference service may refuse a request itself, before a model ever sees it, under error codes of its own, and those refusals arrive on statuses the ladder reads as a provider rejecting the prompt. The plugin that speaks to such a service contributes the codes it emits through `PluginRegistrar.add_service_error_codes`, each with its category, its action and its advice, and `classify_inference_error` consults that vocabulary ahead of the status ladder. The seam is described in [Service Error Codes](service-error-codes.md).
-#### What the request may weigh
+### A Model the Integration Does Not Allow
-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.
+One refusal outside any service's own namespace is classified by the runtime itself: `model_not_allowed_error`, Portkey's answer, at 412, when an integration serves the model but does not allow it for this caller, because the model is off the integration's allow-list or archived. Portkey's cloud emits it for a user's own workspace behind the `portkey` backend, and so does any gateway built on Portkey's middleware; the refusal means the same thing and calls for the same move from any of them, so it is matched on the code alone (`MODEL_NOT_ALLOWED_ERROR_CODE`). It carries its code in `error.type` with `error.code` null, and every Extract hop recovers it from there.
-| 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 |
+| Code | HTTP | Category / action | What the caller is told |
+|------|------|-------------------|-------------------------|
+| `model_not_allowed_error` | 412 | `CONFIGURATION` / `CHANGE_MODEL` | the gateway does not allow the model, named by its handle, for this account — pick another; if the pipe named it, leaving the pipe's model unset uses the default |
-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 change on the gateway's side.
-
-#### 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; and when it succeeds, the integration it lands on may still refuse a model it does not allow. `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) |
-| `model_not_allowed_error` | 412 | `MODEL_NOT_ALLOWED` | `CONFIGURATION` / `CHANGE_MODEL` | the gateway does not allow the model, named by its handle, for this account — pick another; if the pipe named it, leaving the pipe's model unset uses the default |
-
-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, with the one exception below, and nothing is ever retried. What is 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 the `pig-` members 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`. `model_not_allowed_error` fell through to the ladder's generic 4xx arm instead, which gave it the right category and the same wrong advice.
-- **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. One code is not in the `pig-` namespace: `model_not_allowed_error` is the code of the Portkey substrate the gateway is built on, answered at 412 when an integration does not allow every model and does not list this one, or lists it as archived. No model vendor uses it. Portkey's cloud emits it both for the integrations `pipelex_gateway` reaches by default and for a user's own workspace behind the `portkey` backend, and the manifold's vendored middleware emits it too. The refusal means the same thing and calls for the same move from any of them, so it is matched on the code alone like the rest. It carries its code in `error.type` with `error.code` null, and every Extract hop recovers it from there.
-- **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`, `pig-06` and `model_not_allowed_error` 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.
-- **`model_not_allowed_error` is the one member whose advice names the model.** The others defer every specific to the gateway's message, but this one's message names only the backend's wire id (`us.anthropic.claude-sonnet-4-5-20250929-v1:0`), which the method's author never wrote. So its advice names the model handle the deck resolved the pipe's model to, which `render_inference_error` already receives. Both of its hints are conditional, because the Render step cannot tell the cases apart: leaving the pipe's model unset helps only when the pipe named the refused model rather than falling back to it as the default, and a model deck that lists a model the allow-list refuses is Pipelex's to settle on the Pipelex gateway and the user's own on a Portkey workspace of theirs, which report the same provider.
-
-**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`, the `pig-` members 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. `model_not_allowed_error` is the exception: the ladder's generic 4xx arm already read its 412 as `CONFIGURATION`, so it answered 500 before the family took it in, and only its `user_action` moved.
-
-`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 manifold image path still travels on `portkey_ai`, the one client that could start sending such a header. |
-| `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` would close it.
+- **It is not a model-not-found.** The model exists and an integration serves it, only not for this caller, so `ClassificationResult.is_model_not_allowed` is set and `is_model_not_found` is not: the error stays on the family's generic failure class and carries the distinction in its advice. The ladder's generic 4xx arm would have given it the right category and advice sending the caller to edit their inputs.
+- **Its advice names the model.** The refusal's message names only the backend's wire id (`us.anthropic.claude-sonnet-4-5-20250929-v1:0`), which the method's author never wrote, so the advice names the model handle the deck resolved the pipe's model to. Both of its hints are conditional, because the Render step cannot tell the cases apart: leaving the pipe's model unset helps only when the pipe named the refused model rather than falling back to it as the default, and a model deck that lists a model the allow-list refuses is the operator's to settle on a hosted gateway and the user's own on a Portkey workspace of theirs.
+- **It answers 500 on an HTTP surface.** `InferenceErrorCategory.CONFIGURATION` implies `ErrorDomain.CONFIG`, which `error_domain_to_http_status` renders as 500: it lands in server-error alerting, and 500 is a status outer clients retry, though an outer retry earns an identical refusal.
### The `instructor` Unwrap
diff --git a/docs/under-the-hood/inference-backend-plugins.md b/docs/under-the-hood/inference-backend-plugins.md
index 939fca852..e3edd7f26 100644
--- a/docs/under-the-hood/inference-backend-plugins.md
+++ b/docs/under-the-hood/inference-backend-plugins.md
@@ -214,7 +214,9 @@ Use `pipelex plugins list` to see every discovered plugin, the entry-point group
## The Inference SPI
-What an out-of-tree backend plugin imports *is* the contract. The published surface:
+What an out-of-tree backend plugin imports *is* the contract. The published surface is listed below, one module per row, grouped by what a plugin does with it. The plugin contract and the worker contracts are what every backend plugin needs; the rest is what a plugin reaching an OpenAI- or Anthropic-compatible service, or a gateway with error codes of its own, builds on.
+
+**The plugin contract**
| Symbol | Module | Role |
|--------|--------|------|
@@ -227,10 +229,82 @@ What an out-of-tree backend plugin imports *is* the contract. The published surf
| `SdkClientRegistry` | `pipelex.plugins.sdk_client_registry` | per-handle client memoization |
| `InferenceModelSpec` | `pipelex.cogt.model_backends.model_spec` | the resolved model record |
| `InferenceBackend` | `pipelex.cogt.model_backends.backend` | the backend config record (api key, extras) |
-| `InferenceWorkerAbstract` and the `{LLM,ImgGen,Extract,Search,Judgment}WorkerAbstract` subclasses | `pipelex.cogt.…` | the worker contracts a plugin returns |
| `MissingDependencyError` | `pipelex.exceptions` | raised by `require_sdk` |
-The SPI is a documented, versioned **module/symbol list** gated by `PLUGIN_API_VERSION` — not an `__init__.py` re-export shim (the repo bans re-exports; import by full path). Anything a plugin needs to import outside this surface is a design gap to resolve, not an accident to live with.
+**The worker contracts, their jobs and their outputs**
+
+| Symbol | Module | Role |
+|--------|--------|------|
+| `InferenceWorkerAbstract` | `pipelex.cogt.inference.inference_worker_abstract` | the base of every worker a plugin returns |
+| `InferenceJobAbstract` | `pipelex.cogt.inference.inference_job_abstract` | the base of every job a worker serves |
+| `LLMWorkerAbstract` | `pipelex.cogt.llm.llm_worker_abstract` | the LLM worker contract |
+| `LLMJob` | `pipelex.cogt.llm.llm_job` | the LLM job |
+| `ImgGenWorkerAbstract` | `pipelex.cogt.img_gen.img_gen_worker_abstract` | the image-generation worker contract |
+| `ImgGenJob` | `pipelex.cogt.img_gen.img_gen_job` | the image-generation job |
+| `ImgGenJobParams` | `pipelex.cogt.img_gen.img_gen_job_components` | the image-generation job's parameters |
+| `GeneratedImageRawDetails` | `pipelex.cogt.image.generated_image` | what an image worker returns per image |
+| `ImageSize` | `pipelex.cogt.image.image_size` | an image's pixel size |
+| `ImageFormat` | `pipelex.tools.misc.image_utils` | an image's file format |
+| `ExtractWorkerAbstract` | `pipelex.cogt.extract.extract_worker_abstract` | the extraction worker contract |
+| `ExtractJob` | `pipelex.cogt.extract.extract_job` | the extraction job |
+| `ExtractOutput` | `pipelex.cogt.extract.extract_output` | what an extraction worker returns |
+| `ExtractInputError` | `pipelex.cogt.extract.exceptions` | an extraction input the worker cannot take |
+| `SearchWorkerAbstract` | `pipelex.cogt.search.search_worker_abstract` | the search worker contract |
+| `SearchJob` | `pipelex.cogt.search.search_job` | the search job |
+| `extract_structured_search_payload` | `pipelex.cogt.search.structured_search_payload` | turns a sourced answer into the structured output a search pipe asks for |
+| `SearchResultContent` | `pipelex.core.stuffs.search_result_content` | a search result |
+| `DocumentContent` | `pipelex.core.stuffs.document_content` | a source document a search result cites |
+| `JudgmentWorkerAbstract` | `pipelex.cogt.judgment.judgment_worker_abstract` | the judgment worker contract |
+| `DocGenWorkerAbstract` | `pipelex.cogt.doc_gen.doc_gen_worker_abstract` | the document-generation worker contract |
+| `NbTokensByCategoryDict`, `TokenCategory` | `pipelex.cogt.usage.token_category` | the token usage a worker reports |
+| `BaseModelTypeVar` | `pipelex.tools.typing.pydantic_utils` | the schema type variable of a structured-output signature |
+| `CogtError`, `SdkTypeError`, `ImgGenGenerationError`, `ImgGenParameterError`, `InferenceErrorCategory` | `pipelex.cogt.exceptions` | the inference error bases and categories a worker raises with |
+
+**Building on an OpenAI- or Anthropic-compatible service**
+
+| Symbol | Module | Role |
+|--------|--------|------|
+| `BackendExtrasFactory` | `pipelex.plugins.backend_extras_factory` | the per-request headers and body additions a worker asks its factory for |
+| `OpenAICompletionsFactory` | `pipelex.providers.openai.openai_completions_factory` | extension base for a Chat Completions service: messages, client, extras |
+| `OpenAIResponsesFactory` | `pipelex.providers.openai.openai_responses_factory` | extension base for a Responses service |
+| `OpenAICompletionsLLMWorker` | `pipelex.providers.openai.openai_completions_llm_worker` | the Chat Completions LLM worker, built with a factory |
+| `OpenAIResponsesLLMWorker` | `pipelex.providers.openai.openai_responses_llm_worker` | the Responses LLM worker, built with a factory |
+| `OpenAICompletionsImgGenWorker` | `pipelex.providers.openai.openai_completions_img_gen_worker` | the image worker over Chat Completions, built with a factory and, for a service with one, its fixed output format |
+| `AnthropicLLMWorker` | `pipelex.providers.anthropic.anthropic_llm_worker` | the Anthropic-protocol LLM worker, built with an optional extras factory |
+| `AnthropicFactory`, `AnthropicSdkVariant` | `pipelex.providers.anthropic.anthropic_factory` | the Anthropic-protocol client, for a variant named apart from the sdk token |
+| `request_with_transport_retry` | `pipelex.cogt.inference.transport_retry` | the transport retry a plain-HTTP client wraps its calls in |
+| `ImgGenArgsFactory`, `ImageFileTuple` | `pipelex.cogt.img_gen.img_gen_args_factory` | the portable image-generation arguments, mapped to an Images API |
+| `ImgGenGeminiMapping` | `pipelex.cogt.img_gen.img_gen_gemini_mapping` | the portable aspect ratio and size, mapped to Gemini's image config |
+| `AspectRatioTaxonomy` | `pipelex.cogt.img_gen.img_gen_model_rules` | the aspect-ratio vocabulary a model's rules name |
+| `prep_prompt_images` | `pipelex.cogt.image.prompt_image_utils` | prompt images, prepared for a request |
+| `PromptImageDetail` | `pipelex.cogt.image.prompt_image` | the detail level a prompt image asks for |
+| `prep_prompt_documents` | `pipelex.cogt.document.prompt_document_utils` | prompt documents, prepared for a request |
+| `PreparedFileBase64`, `PreparedFileHttpUrl`, `PreparedFileLocalPath` | `pipelex.tools.uri.prepared_file` | the forms a prepared file takes |
+| `make_base64_url_from_any_uri` | `pipelex.tools.uri.uri_base64` | a file reference, inlined as a data URL |
+
+**Errors: distilling, classifying and rendering a failure**
+
+| Symbol | Module | Role |
+|--------|--------|------|
+| `ProviderErrorMetadata`, `UserAction`, `UserActionKind` | `pipelex.cogt.inference.error_classification` | the structured failure a worker distils, and the advice it carries |
+| `parse_retry_after_seconds`, `error_code_from_body_code_first` | `pipelex.cogt.inference.error_classification` | the parsers a distiller of a plain-HTTP failure shares |
+| `extract_gateway_metadata` | `pipelex.cogt.inference.error_classification` | the distiller of a Portkey-substrate failure |
+| `ProviderName` | `pipelex.cogt.inference.provider_name` | which provider a distilled failure reports |
+| `classify_inference_error` | `pipelex.cogt.inference.error_classify` | the shared Classify step |
+| `InferenceErrorFamily`, `render_inference_error` | `pipelex.cogt.inference.error_render` | the shared Render step |
+| `ServiceErrorCode` | `pipelex.cogt.inference.service_error_vocabulary` | one error code a plugin's service emits, contributed through `PluginRegistrar.add_service_error_codes` ([Service Error Codes](service-error-codes.md)) |
+| `URLs` | `pipelex.urls` | the public error docs base a plugin error's declared type URI points under |
+
+**The runtime a worker runs in**
+
+| Symbol | Module | Role |
+|--------|--------|------|
+| `get_config` | `pipelex.config` | the runtime configuration |
+| `get_storage_provider` | `pipelex.runtime_hub` | the storage a worker reads a stored input from |
+| `JobMetadata` | `pipelex.system.job_metadata` | the run and the step a job belongs to |
+| `ReportingProtocol` | `pipelex.reporting.reporting_protocol` | where a worker reports its usage |
+
+The SPI is a documented, versioned **module/symbol list** gated by `PLUGIN_API_VERSION` — not an `__init__.py` re-export shim (the repo bans re-exports; import by full path). Anything a plugin needs to import outside this surface is a design gap to resolve, not an accident to live with: either the symbol is published here, or the plugin keeps its own copy of it. The built-in provider plugin for the hosted gateway is held to it by a test that scans its imports against this table.
---
@@ -243,6 +317,8 @@ The SPI is a documented, versioned **module/symbol list** gated by `PLUGIN_API_V
| a `pipelex.plugins.kernel` plugin registers an interpreter-layer capability | `PluginLayerViolationError` (names the capability and the group to move to) |
| duplicate `(family, sdk)` | `DuplicateInferenceBackendError` (names both plugins) |
| duplicate `sdk` model lister | `DuplicateModelListerError` (names both plugins) |
+| a service error code two plugins contribute | `DuplicateServiceErrorCodeError` (names both plugins) |
+| a service error code the runtime classifies itself | `ReservedServiceErrorCodeError` |
| `name` in `runtime.plugins.disabled` but core-unconditional | `CoreUnconditionalPluginDisabledError` |
| entry point raises while loading/registering | `BrokenPluginError` |
| lookup for an unregistered `(family, sdk)` | `InferenceBackendNotFoundError` ("… Is its plugin installed and enabled?") |
diff --git a/docs/under-the-hood/service-error-codes.md b/docs/under-the-hood/service-error-codes.md
new file mode 100644
index 000000000..00f07ad24
--- /dev/null
+++ b/docs/under-the-hood/service-error-codes.md
@@ -0,0 +1,79 @@
+---
+title: "Service Error Codes"
+description: "How a plugin contributes the error codes its gateway or hosted service emits, so the runtime classifies and explains those refusals ahead of the HTTP status ladder."
+---
+
+# Service Error Codes
+
+Not every failure on an inference call comes from a provider. A gateway, or a hosted inference service that routes to providers on the caller's behalf, may refuse a request itself, before any model sees it, under error codes of its own: a request over its size limit, a file reference it cannot resolve, a model it does not route. Those refusals arrive on statuses the [status ladder](error-model.md#worker-classification) reads as a provider rejecting the prompt, so without their codes a caller who has a reference to fix, or a deployment problem to report, is told to revise their inputs.
+
+The plugin that speaks to such a service knows its codes, so the plugin contributes them. This page describes that seam.
+
+## Contributing the codes
+
+A plugin declares each code its service emits as a `ServiceErrorCode` (`pipelex.cogt.inference.service_error_vocabulary`) and hands them to the registrar in its `register`:
+
+```python
+from pipelex.cogt.exceptions import InferenceErrorCategory
+from pipelex.cogt.inference.error_classification import UserActionKind
+from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorCode
+from pipelex.plugins.contract import PLUGIN_API_VERSION
+from pipelex.plugins.registrar import PluginRegistrar
+
+ACME_ERROR_CODES = (
+ ServiceErrorCode(
+ code="acme_body_too_large",
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail="The request was too large for the Acme gateway — send less in one call, or use smaller inputs.",
+ ),
+ ServiceErrorCode(
+ code="acme_unknown_model",
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CHANGE_MODEL,
+ detail="The Acme gateway does not serve that model — pick a model this deployment serves.",
+ is_model_not_found=True,
+ ),
+)
+
+
+class AcmePlugin:
+ name = "acme"
+ targets_api = PLUGIN_API_VERSION
+
+ def register(self, registrar: PluginRegistrar) -> None:
+ registrar.add_service_error_codes(codes=ACME_ERROR_CODES)
+ # ...and the plugin's inference backends
+```
+
+Each entry says four things about one code:
+
+| Field | Meaning |
+|-------|---------|
+| `code` | the code as the service puts it on the wire, which the worker's Extract step recovers into `ProviderErrorMetadata.provider_error_code` |
+| `category` | the `InferenceErrorCategory`, which decides whether the error is retried and the HTTP status it answers on a server |
+| `user_action_kind` | the kind of advice the caller gets |
+| `detail` | the advice itself, rendered beside the service's own message: what the caller, or whoever operates the service, should do. The service's message already names the specifics, so the advice need not repeat them |
+| `is_model_not_found` | set for a code that means the service does not know the model at all: it selects the family's `*ModelNotFoundError` class, which the pipe layer re-raises as a model-availability error carrying the model handle |
+
+## How the runtime reads them
+
+At boot, every plugin's contributions are frozen into one `ServiceErrorVocabulary` on the runtime hub. `classify_inference_error` consults it first, ahead of the quota rules and the status ladder, for any failure that reached an HTTP status: a code the vocabulary knows decides the category, the action and the model-not-found flag, and `render_inference_error` renders the entry's advice. A code nobody contributed, and every failure in a process that registered none, classifies on the status ladder as before.
+
+**Codes are matched on the code alone, with no check on the provider.** A request reaches a service through whichever SDK its protocol calls for, so the provider a failure reports does not identify the service; the code does. A plugin that contributes a code vouches that no vendor emits it, which in practice means the codes live in a namespace of the service's own.
+
+**For a code to reach the classifier, the worker's Extract step must recover it.** The vendor-facing distillers read an OpenAI-shaped error body's `type` before its `code`. A service that renders `{"error": {"type": "invalid_request_error", "code": "<specific_code>"}}` needs its distiller to read `code` first: `error_code_from_body_code_first` in `pipelex.cogt.inference.error_classification` does exactly that, and `parse_retry_after_seconds` beside it reads a `Retry-After` header, for a plugin that distils a plain-HTTP failure itself.
+
+## Fail-loud guarantees
+
+| Condition | Error |
+|-----------|-------|
+| two plugins contribute the same code | `DuplicateServiceErrorCodeError`, naming both plugins |
+| a plugin contributes a code the runtime classifies itself (`model_not_allowed_error`, see the [Error Model](error-model.md#a-model-the-integration-does-not-allow)) | `ReservedServiceErrorCodeError` |
+
+The vocabulary is a kernel-layer contribution: a plugin published under `pipelex.plugins.kernel` may contribute it, since inference errors are classified in a kernel-only boot too.
+
+## Related
+
+- [Error Model](error-model.md) — the Extract / Classify / Render pipeline the vocabulary plugs into
+- [Inference Backend Plugins](inference-backend-plugins.md) — the plugin contract and the Inference SPI
diff --git a/mkdocs.yml b/mkdocs.yml
index e14fe360a..28c37b8ec 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -348,6 +348,7 @@ plugins:
- under-the-hood/pipe-routing-and-execution.md: "Pipe Routing & Execution"
- under-the-hood/inference-backend-plugins.md: "Inference Backend Plugins"
- under-the-hood/writing-an-inference-plugin.md: "Writing an Inference Plugin"
+ - under-the-hood/service-error-codes.md: "Service Error Codes"
- under-the-hood/orchestrator-plugins.md: "Orchestrator Plugins"
- under-the-hood/storage-provider-plugins.md: "Storage Provider Plugins"
- under-the-hood/secrets-provider-plugins.md: "Secrets Provider Plugins"
@@ -600,6 +601,7 @@ nav:
- Pipe Routing & Execution: under-the-hood/pipe-routing-and-execution.md
- Inference Backend Plugins: under-the-hood/inference-backend-plugins.md
- Writing an Inference Plugin: under-the-hood/writing-an-inference-plugin.md
+ - Service Error Codes: under-the-hood/service-error-codes.md
- Orchestrator Plugins: under-the-hood/orchestrator-plugins.md
- Storage Provider Plugins: under-the-hood/storage-provider-plugins.md
- Secrets Provider Plugins: under-the-hood/secrets-provider-plugins.md
diff --git a/pipelex/cogt/inference/error_classification.py b/pipelex/cogt/inference/error_classification.py
index fceb27d1b..bc51e0828 100644
--- a/pipelex/cogt/inference/error_classification.py
+++ b/pipelex/cogt/inference/error_classification.py
@@ -45,307 +45,20 @@ _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. All but one are the gateway's ``pig-`` codes, at HTTP
- 400. ``MODEL_NOT_ALLOWED`` is keyed on the code of the Portkey substrate the
- gateway is built on, which answers it at HTTP 412 from the middleware the
- gateway vendors; Portkey's cloud answers it the same way for a caller's own
- workspace behind the ``portkey`` backend.
- """
-
- #: ``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"
- #: ``model_not_allowed_error`` at HTTP 412 — an integration serves the model
- #: but does not allow it for this caller. The substrate raises it in two
- #: cases: the integration does not allow every model and does not list this
- #: one, or it lists it as archived. The caller can pick another model; for
- #: whoever operates the gateway, it means the model deck and the integration's
- #: allow-list disagree. The gateway's message names only the backend's wire
- #: id, which the method's author never wrote, so this is the one member whose
- #: advice names the model handle the deck resolved to (see
- #: ``_render_gateway_routing_refusal_detail``).
- MODEL_NOT_ALLOWED = "model_not_allowed"
-
-
-# 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.
-#
-# **``model_not_allowed_error`` is the one code outside that namespace**, and it is
-# matched on the code alone for a reason of its own: it is the code of Portkey, the
-# substrate the gateway is built on, and no model vendor uses it. Portkey's cloud
-# emits it for a caller's own workspace behind the ``portkey`` backend, and so does
-# the middleware the manifold vendors from it. The refusal means the same thing and calls for the same
-# move whichever of them raised it, so only the advice has to hold for both. Both
-# raise sites answer 412, so checking the status too would add nothing. It arrives with
-# the code in ``type`` and ``code`` null, and every Extract hop recovers it from
-# there: the vendor-facing hops read ``type`` first, and the two Pipelex-service
-# hops fall back to 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. The manifold image path still travels
-# on ``portkey_ai``, which is the one client that could start doing so.
-# - ``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,
- "model_not_allowed_error": GatewayRoutingRefusal.MODEL_NOT_ALLOWED,
-}
+# The one error code outside any service's own namespace that the runtime classifies itself:
+# Portkey's refusal of a model an integration serves but does not allow for this caller, because the
+# model is off the integration's allow-list or archived. Portkey's cloud emits it for a caller's own
+# workspace behind the ``portkey`` backend, and so does any gateway built on Portkey's middleware. The
+# refusal means the same thing and calls for the same move whichever of them raised it, so it is
+# classified here rather than contributed by one service's plugin. Both raise sites answer 412, so
+# checking the status too would add nothing. It arrives with the code in ``type`` and ``code`` null,
+# and every Extract hop recovers it from there: the vendor-facing hops read ``type`` first, and the
+# code-first hops fall back to it.
+MODEL_NOT_ALLOWED_ERROR_CODE = "model_not_allowed_error"
+
+# The codes the runtime classifies itself, which no plugin may contribute to the service error
+# vocabulary (see ``PluginRegistrar.add_service_error_codes``).
+RUNTIME_CLASSIFIED_ERROR_CODES: frozenset[str] = frozenset({MODEL_NOT_ALLOWED_ERROR_CODE})
def _resolve_sdk_exception_type(exc: BaseException, *, status_code: int | None) -> str:
@@ -421,63 +134,14 @@ 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)
+ def is_model_not_allowed(self) -> bool:
+ """Whether an integration serves the model but does not allow it for this caller.
- @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
- 4xx arms and a caller who named a model the deployment does not serve, or
- may not use, 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``).
+ Reads ``provider_error_code`` (see ``MODEL_NOT_ALLOWED_ERROR_CODE``). Without this the
+ refusal takes the status ladder's generic 4xx arm, whose domain is right but whose action
+ sends the caller to edit their inputs.
"""
- if self.provider_error_code is None:
- return None
- return _GATEWAY_ROUTING_REFUSAL_BY_CODE.get(self.provider_error_code)
+ return self.provider_error_code == MODEL_NOT_ALLOWED_ERROR_CODE
@property
def is_content_policy_violation(self) -> bool:
@@ -715,7 +379,7 @@ def extract_underlying_sdk_exception(instructor_exc: Any) -> BaseException | Non
return None
-def _parse_retry_after_seconds(value: Any) -> float | None:
+def parse_retry_after_seconds(value: Any) -> float | None:
"""Parse a ``Retry-After`` header value into a delay in seconds.
The HTTP spec allows two forms: a non-negative number of seconds, or an
@@ -777,7 +441,7 @@ def extract_openai_metadata(exc: BaseException) -> ProviderErrorMetadata:
headers = getattr(response, "headers", None)
retry_after_seconds: float | None = None
if headers is not None:
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
body = getattr(exc, "body", None)
# OpenAI's _make_status_error pre-unwraps body["error"] onto exc.type / exc.code,
# so we read those attributes directly rather than re-parsing the body.
@@ -821,7 +485,7 @@ def extract_anthropic_metadata(exc: BaseException) -> ProviderErrorMetadata:
headers = getattr(response, "headers", None)
retry_after_seconds: float | None = None
if headers is not None:
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
body = getattr(exc, "body", None)
return ProviderErrorMetadata(
provider=ProviderName.ANTHROPIC,
@@ -851,26 +515,23 @@ 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``.
+def error_code_from_body_code_first(body: Any) -> str | None:
+ """Read the error code off an error body, preferring ``code`` over ``type``.
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.
+ the top level, which is where the 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
+ A gateway that renders its refusals in the OpenAI error shape may put its
+ *specific* code in ``code`` and a generic OpenAI-shaped bucket in ``type``:
``{"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.
+ "<specific_code>"}}``. The vendor-facing precedence is right for Anthropic,
+ whose error section carries a ``type`` and no ``code`` at all, and wrong there —
+ it replaces every specific code with ``invalid_request_error`` and the code
+ never reaches the classifier. A body carrying only ``code`` reads identically
+ through either precedence.
"""
if not isinstance(body, dict):
return None
@@ -968,7 +629,7 @@ def extract_google_metadata(exc: BaseException) -> ProviderErrorMetadata:
request_id_value = headers.get("x-goog-request-id") or headers.get("x-request-id")
if isinstance(request_id_value, str):
request_id = request_id_value
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
details = getattr(exc, "details", None)
return ProviderErrorMetadata(
provider=ProviderName.GOOGLE,
@@ -1021,7 +682,7 @@ def _build_azure_metadata(response: Any, *, sdk_exception_type: str, message: st
request_id_value = headers.get("x-ms-request-id") or headers.get("apim-request-id") or headers.get("x-request-id")
if isinstance(request_id_value, str):
request_id = request_id_value
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
body, provider_error_code = _parse_response_text_body(response)
return ProviderErrorMetadata(
provider=ProviderName.AZURE,
@@ -1054,7 +715,7 @@ def extract_fal_metadata(exc: BaseException) -> ProviderErrorMetadata:
request_id_value = response_headers.get("x-request-id") or response_headers.get("x-fal-request-id")
if isinstance(request_id_value, str):
request_id = request_id_value
- retry_after_seconds = _parse_retry_after_seconds(response_headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(response_headers.get("retry-after"))
error_type = getattr(exc, "error_type", None)
base_provider_error_code: str | None = error_type if isinstance(error_type, str) else None
response = getattr(exc, "response", None)
@@ -1093,7 +754,7 @@ def extract_huggingface_metadata(exc: BaseException) -> ProviderErrorMetadata:
headers = getattr(response, "headers", None)
retry_after_seconds: float | None = None
if headers is not None:
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
body, provider_error_code = _parse_response_text_body(response)
return ProviderErrorMetadata(
provider=ProviderName.HUGGINGFACE,
@@ -1107,98 +768,6 @@ def extract_huggingface_metadata(exc: BaseException) -> ProviderErrorMetadata:
)
-# The headers the Pipelex Manifold gateway stamps its trace id on, in the order the native routes'
-# distiller below reads them.
-#
-# Every answer a provider gave carries that id twice, with the same value under each spelling: the
-# pipelex one the dialect owns, and the inherited vendor one the gateway still emits because
-# `portkey_ai` reads it on the image path — a refusal the gateway raised before trying a provider
-# carries neither. Reading the pipelex spelling first is what makes the gateway's eventual dropping
-# of the vendor one a no-op for the native routes, at which point the second name and its lookup go
-# away. It is not a no-op for this file: `extract_gateway_metadata` carries the vendor spelling as a
-# literal of its own, and that one serves the manifold image path as well as the Portkey cloud, so
-# it can only move once the image path is off `portkey_ai`.
-#
-# They are named here rather than beside `MANIFOLD_AUTH_HEADER` in `providers/manifold/`, where the
-# dialect names the header it *sends*, because `cogt` may not import `pipelex.providers`: the edges
-# between the two are a pinned golden set, and a new one is a defect
-# (`tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py`).
-MANIFOLD_TRACE_ID_HEADER = "x-pipelex-trace-id"
-MANIFOLD_VENDOR_TRACE_ID_HEADER = "x-portkey-trace-id"
-
-
-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.
-
- **The request id is read in the manifold dialect's own spelling.** The provider's ``x-request-id``
- comes first when a provider named its call, and the gateway's trace id is the fallback for the
- answers that carried none — under ``MANIFOLD_TRACE_ID_HEADER`` before the inherited vendor
- spelling, which holds the same value and is only still read because the gateway still emits it.
- ``extract_gateway_metadata`` below keeps the vendor spelling alone, and that is not only about
- the Portkey cloud, whose trace header is not ours to rename: it also distils the *manifold
- image* failures, which still travel on ``portkey_ai``, and that SDK reads
- ``x-portkey-trace-id`` off the response itself. So the image path cannot take the pipelex
- spelling until it is ported off the SDK, and until then it is the manifold traffic that still
- depends on the vendor one.
-
- **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(MANIFOLD_TRACE_ID_HEADER) or headers.get(MANIFOLD_VENDOR_TRACE_ID_HEADER)
- 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``.
@@ -1228,9 +797,9 @@ def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata:
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"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
body: Any = getattr(exc, "body", None)
- provider_error_code = _pipelex_service_error_code_from_body(body)
+ provider_error_code = error_code_from_body_code_first(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
@@ -1238,7 +807,7 @@ def extract_gateway_metadata(exc: BaseException) -> ProviderErrorMetadata:
# 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)
+ recovered_code = error_code_from_body_code_first(recovered_body)
provider_error_code = recovered_code
if recovered_code is not None:
body = recovered_body
@@ -1277,7 +846,7 @@ def extract_mistral_metadata(exc: BaseException) -> ProviderErrorMetadata:
request_id_value = headers.get("x-request-id")
if isinstance(request_id_value, str):
request_id = request_id_value
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
raw_body = getattr(exc, "body", None)
body: Any = raw_body
provider_error_code: str | None = None
@@ -1351,7 +920,7 @@ def extract_bedrock_metadata(exc: BaseException) -> ProviderErrorMetadata:
retry_after_seconds: float | None = None
if isinstance(headers, dict):
# botocore lowercases all HTTPHeaders keys, so ``retry-after`` is the canonical lookup.
- retry_after_seconds = _parse_retry_after_seconds(cast("dict[str, Any]", headers).get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(cast("dict[str, Any]", headers).get("retry-after"))
error_code = error_section.get("Code")
provider_error_code = error_code if isinstance(error_code, str) else None
if status_code is None and provider_error_code is not None:
@@ -1449,7 +1018,7 @@ def extract_typesafe_metadata(exc: BaseException) -> ProviderErrorMetadata:
headers = getattr(exc, "headers", None)
retry_after_seconds: float | None = None
if headers is not None:
- retry_after_seconds = _parse_retry_after_seconds(headers.get("retry-after"))
+ retry_after_seconds = parse_retry_after_seconds(headers.get("retry-after"))
return ProviderErrorMetadata(
provider=ProviderName.TYPESAFE,
sdk_exception_type=type(exc).__name__,
diff --git a/pipelex/cogt/inference/error_classify.py b/pipelex/cogt/inference/error_classify.py
index 103d28ee1..36d7b60ed 100644
--- a/pipelex/cogt/inference/error_classify.py
+++ b/pipelex/cogt/inference/error_classify.py
@@ -16,13 +16,9 @@ SDK exception type name.
from pydantic import BaseModel
from pipelex.cogt.exceptions import InferenceErrorCategory
-from pipelex.cogt.inference.error_classification import (
- GatewayRequestLimit,
- GatewayRoutingRefusal,
- GatewayUnresolvedReference,
- SDKErrorEnvelope,
- UserActionKind,
-)
+from pipelex.cogt.inference.error_classification import SDKErrorEnvelope, UserActionKind
+from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorCode
+from pipelex.runtime_hub import get_optional_service_error_vocabulary
class ClassificationResult(BaseModel):
@@ -36,26 +32,16 @@ class ClassificationResult(BaseModel):
category: InferenceErrorCategory
user_action_kind: UserActionKind
is_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
+ # The service error code this refusal carried, when the service the request reached refused it
+ # itself under a code its plugin contributed (see ``service_error_vocabulary``). Like
+ # ``is_model_not_found`` this is a flag rather than a category: the entry already decided the
+ # category and the action, and it lets the Render step give the entry's own advice instead of
+ # falling back to the generic "the provider rejected the request".
+ service_error_code: ServiceErrorCode | None = None
+ # Whether an integration serves the model but does not allow it for this caller. A flag for the
+ # same reason: the model exists and is served, so it is not a model-not-found, and the Render step
+ # names the model handle the deck resolved to, which the refusal's own message does not.
+ is_model_not_allowed: bool = False
# Status-less SDK exception type names recognizable regardless of provider:
@@ -128,133 +114,6 @@ 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 the ``pig-`` members take the status ladder's
- 400 arm and read as a provider rejecting the caller's content, and
- ``MODEL_NOT_ALLOWED`` takes its generic 4xx arm, whose domain is right but whose
- action sends the caller to edit their inputs.
-
- 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 | GatewayRoutingRefusal.MODEL_NOT_ALLOWED:
- # The model exists and is served — it just cannot do what was asked, was
- # asked over a protocol its integration does not speak, or is served by
- # an integration that does not allow it for this caller. 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.
@@ -271,35 +130,32 @@ def classify_inference_error(metadata: SDKErrorEnvelope) -> ClassificationResult
if 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)
+ # A code the service contributed comes first: an explicit code from the service itself is a
+ # more specific verdict than any status bucket, and the statuses such refusals arrive on (413,
+ # 411, 400) would otherwise be read as a provider rejecting the prompt. The vocabulary is the
+ # booted plugins' (see ``service_error_vocabulary``); a process that registered none classifies
+ # on the status ladder alone.
+ vocabulary = get_optional_service_error_vocabulary()
+ if vocabulary is not None:
+ service_error_code = vocabulary.lookup(code=metadata.provider_error_code)
+ if service_error_code is not None:
+ return ClassificationResult(
+ category=service_error_code.category,
+ user_action_kind=service_error_code.user_action_kind,
+ is_model_not_found=service_error_code.is_model_not_found,
+ service_error_code=service_error_code,
+ )
- # 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. The ``pig-`` refusals arrive 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. The substrate's
- # ``model_not_allowed_error`` arrives on 412, which the ladder would send to
- # the prompt, the parameters and the inputs too.
- gateway_routing_refusal = metadata.gateway_routing_refusal
- if gateway_routing_refusal is not None:
- return _classify_gateway_routing_refusal(refusal=gateway_routing_refusal)
+ # A model an integration serves but does not allow for this caller, on the same footing. It
+ # arrives on 412, which the ladder's generic 4xx arm would send to the prompt, the parameters and
+ # the inputs. Nothing in those causes it: the model exists and is served, only not for this
+ # caller, so the flag stays unset and ``CHANGE_MODEL`` is what an end caller can do about it.
+ if metadata.is_model_not_allowed:
+ return ClassificationResult(
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CHANGE_MODEL,
+ is_model_not_allowed=True,
+ )
# Quota exhaustion is decided by the provider-aware ``is_quota_exhaustion``
# property and takes precedence over the HTTP status: providers signal it on
diff --git a/pipelex/cogt/inference/error_render.py b/pipelex/cogt/inference/error_render.py
index b5e1e5dfd..e21c1820f 100644
--- a/pipelex/cogt/inference/error_render.py
+++ b/pipelex/cogt/inference/error_render.py
@@ -23,14 +23,7 @@ from pipelex.cogt.exceptions import (
SearchJobFailureError,
SearchModelNotFoundError,
)
-from pipelex.cogt.inference.error_classification import (
- GatewayRequestLimit,
- GatewayRoutingRefusal,
- GatewayUnresolvedReference,
- SDKErrorEnvelope,
- UserAction,
- UserActionKind,
-)
+from pipelex.cogt.inference.error_classification import SDKErrorEnvelope, UserAction, UserActionKind
from pipelex.cogt.inference.error_classify import ClassificationResult
@@ -69,172 +62,36 @@ 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.
+def _render_model_not_allowed_detail(*, model_handle: str) -> str:
+ """Produce the advice for a model an integration serves but does not allow for this caller.
- **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.
+ The refusal's own message names only the backend's wire id, which the method's author never
+ wrote, so the advice names ``model_handle``, the handle the model deck resolved the pipe's model
+ to. Both halves are conditional because the Render step cannot tell the cases apart: the handle
+ may be one the pipe named or the deck's default, and leaving the model unset only helps in the
+ first case; and a deck listing a model the allow-list refuses is the gateway operator's to settle
+ on a hosted gateway, and the caller's on a Portkey workspace of their own.
"""
- 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, model_handle: str) -> str:
- """Produce the advice for a request the inference gateway refused to route.
-
- Names no 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.
-
- It names no model either, with one exception: ``MODEL_NOT_ALLOWED``, whose
- message names only the backend's wire id (``us.anthropic.claude-…``), which the
- method's author never wrote. That member's advice names ``model_handle``, the
- handle the model deck resolved the pipe's model to; every other member ignores it.
-
- 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."
- )
- case GatewayRoutingRefusal.MODEL_NOT_ALLOWED:
- # Both halves are conditional because the Render step cannot tell the
- # cases apart. The handle may be one the pipe named or the deck's
- # default, and leaving the model unset only helps in the first case. And
- # the same code comes from the Pipelex gateway and from a caller's own
- # Portkey workspace behind the ``portkey`` backend, which report the
- # same provider: a deck that lists a model the allow-list refuses is
- # Pipelex's to settle on the first and the caller's on the second.
- return (
- f"The inference gateway does not allow the model '{model_handle}' for this account — pick another model for the "
- "pipe; if the pipe named this one, leaving its model unset uses the default instead. If your model deck lists "
- "it as available, the deck and the gateway's allow-list disagree: on the Pipelex gateway, contact support; on "
- "a Portkey workspace of your own, allow the model in the integration that serves it."
- )
+ return (
+ f"The inference gateway does not allow the model '{model_handle}' for this account — pick another model for the "
+ "pipe; if the pipe named this one, leaving its model unset uses the default instead. If your model deck lists "
+ "it as available, the deck and the gateway's allow-list disagree: on a hosted gateway, contact support; on "
+ "a Portkey workspace of your own, allow the model in the integration that serves it."
+ )
def _render_detail(metadata: SDKErrorEnvelope, *, classification: ClassificationResult, model_handle: str) -> 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``, ``pig-06`` and ``model_not_allowed_error``, 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, model_handle=model_handle)
+ if classification.service_error_code is not None:
+ # Branches ahead of the action kind rather than inside it: the service's own code names the
+ # remedy more precisely than the kind does, and the kind's generic advice is often simply
+ # wrong for it — "review the prompt" for a reference to fix, "the model was not found" for a
+ # model that exists but cannot do what was asked.
+ return classification.service_error_code.detail
+ if classification.is_model_not_allowed:
+ # Same reason: ``CHANGE_MODEL`` renders "the requested model was not found", which is false
+ # for a model that exists and is served, only not for this caller.
+ return _render_model_not_allowed_detail(model_handle=model_handle)
match classification.user_action_kind:
case UserActionKind.WAIT_AND_RETRY:
if metadata.retry_after_seconds is not None:
diff --git a/pipelex/cogt/inference/service_error_vocabulary.py b/pipelex/cogt/inference/service_error_vocabulary.py
new file mode 100644
index 000000000..7f1b362ca
--- /dev/null
+++ b/pipelex/cogt/inference/service_error_vocabulary.py
@@ -0,0 +1,63 @@
+"""The error codes an inference service emits on its own, contributed by the plugin that speaks to it.
+
+A gateway or a hosted inference service may refuse a request itself, before any provider sees it,
+under codes of its own: a request over its size limit, a file reference it cannot resolve, a model it
+does not route. Those refusals arrive on statuses the status ladder reads as a provider rejecting the
+prompt, so without their codes a caller who has a reference to fix or a deployment to report is told
+to revise their inputs.
+
+The codes are the service's wire contract, so the plugin that speaks to the service owns them: it
+contributes each code with the category it falls in, the action it calls for and the advice to render,
+through `PluginRegistrar.add_service_error_codes`. Boot freezes the contributions into one
+`ServiceErrorVocabulary` on the runtime hub, which `classify_inference_error` consults ahead of the
+status ladder and whose matched entry `render_inference_error` renders.
+
+**Matched on the code alone, with no check on the provider.** A request reaches a service through
+whichever SDK its protocol calls for, so the reporting provider does not identify the service; the
+code does, and a service that contributes codes vouches that no vendor emits into them.
+"""
+
+from collections.abc import Mapping
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from pipelex.cogt.exceptions import InferenceErrorCategory
+from pipelex.cogt.inference.error_classification import UserActionKind
+
+
+class ServiceErrorCode(BaseModel):
+ """One error code a service emits, and what the runtime does about it.
+
+ `detail` is the advice rendered beside the service's own message. It names what the caller, or
+ whoever operates the service, should do; the service's message already names the specifics.
+ `is_model_not_found` selects the family's `*ModelNotFoundError` class, for a code that means the
+ service does not know the model at all.
+ """
+
+ model_config = ConfigDict(frozen=True, extra="forbid")
+
+ code: str
+ category: InferenceErrorCategory = Field(strict=False)
+ user_action_kind: UserActionKind = Field(strict=False)
+ detail: str
+ is_model_not_found: bool = False
+
+
+class ServiceErrorVocabulary:
+ """Every service error code the booted plugins contributed, keyed by code.
+
+ Built once at boot from the registrar, which has already refused a code claimed twice, so a code
+ resolves to exactly one entry.
+ """
+
+ def __init__(self, codes: Mapping[str, ServiceErrorCode]):
+ self._codes: dict[str, ServiceErrorCode] = dict(codes)
+
+ def lookup(self, *, code: str | None) -> ServiceErrorCode | None:
+ if code is None:
+ return None
+ return self._codes.get(code)
+
+ @property
+ def codes(self) -> frozenset[str]:
+ return frozenset(self._codes)
diff --git a/pipelex/cogt/model_backends/backend.py b/pipelex/cogt/model_backends/backend.py
index 85cb03b83..4ecb2cf16 100644
--- a/pipelex/cogt/model_backends/backend.py
+++ b/pipelex/cogt/model_backends/backend.py
@@ -29,16 +29,6 @@ class PipelexBackend(StrEnum):
return "Internal (software-only)"
-# 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.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.
diff --git a/pipelex/plugins/exceptions.py b/pipelex/plugins/exceptions.py
index 00f2c0727..eb46826ee 100644
--- a/pipelex/plugins/exceptions.py
+++ b/pipelex/plugins/exceptions.py
@@ -72,6 +72,33 @@ class DuplicateModelListerError(PluginError):
super().__init__(message)
+class DuplicateServiceErrorCodeError(PluginError):
+ """Two plugins contributed the same service error code."""
+
+ def __init__(self, *, code: str, first_plugin: str, second_plugin: str):
+ self.code = code
+ self.first_plugin = first_plugin
+ self.second_plugin = second_plugin
+ message = (
+ f"Service error code '{code}' is contributed by both plugin '{first_plugin}' and plugin '{second_plugin}'. "
+ f"Each code must mean one thing, so it must have a single contributor."
+ )
+ super().__init__(message)
+
+
+class ReservedServiceErrorCodeError(PluginError):
+ """A plugin contributed a service error code the runtime classifies itself."""
+
+ def __init__(self, *, code: str, plugin: str):
+ self.code = code
+ self.plugin = plugin
+ message = (
+ f"Plugin '{plugin}' contributes service error code '{code}', which the runtime already classifies itself. "
+ f"A contributed code must not compete with the runtime's own reading of it."
+ )
+ super().__init__(message)
+
+
class DuplicateOrchestratorError(PluginError):
"""Two plugins registered an orchestrator for the same orchestration mode."""
diff --git a/pipelex/plugins/registrar.py b/pipelex/plugins/registrar.py
index 394bedf29..afe832f8f 100644
--- a/pipelex/plugins/registrar.py
+++ b/pipelex/plugins/registrar.py
@@ -7,6 +7,7 @@ from pydantic import BaseModel, Field
from pipelex.base_exceptions import ErrorReport
from pipelex.cogt.doc_gen.doc_gen_format import DocGenFormat, DocGenSource, doc_gen_choice_key
+from pipelex.cogt.inference.error_classification import RUNTIME_CLASSIFIED_ERROR_CODES
from pipelex.plugins.bundle_validator_registry import BundleValidatorProtocol
from pipelex.plugins.exceptions import (
DuplicateBundleValidatorError,
@@ -19,9 +20,11 @@ from pipelex.plugins.exceptions import (
DuplicateOrchestratorError,
DuplicatePipeFuncExecutorError,
DuplicateSecretsProviderError,
+ DuplicateServiceErrorCodeError,
DuplicateStorageProviderError,
HubSlotAlreadyClaimedError,
PluginLayerViolationError,
+ ReservedServiceErrorCodeError,
)
from pipelex.plugins.inference_backend_registry import InferenceFamily, MakeWorkerFn
from pipelex.plugins.log_sink_registry import LogSinkFactoryFn
@@ -35,6 +38,9 @@ from pipelex.plugins.storage_provider_registry import StorageProviderFactoryFn
from pipelex.runtime_bridge.orchestration_mode import OrchestrationMode
if TYPE_CHECKING:
+ from collections.abc import Iterable
+
+ from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorCode
from pipelex.system.configuration.configs import PipelexConfig
@@ -170,6 +176,7 @@ class PluginRegistrar:
# Plain data, read once by ``make_model_declarations`` for the model manager to merge at boot.
self.internal_models: dict[str, dict[str, Any]] = {}
self.doc_gen_defaults: dict[tuple[DocGenFormat, DocGenSource], str] = {}
+ self.service_error_codes: dict[str, ServiceErrorCode] = {}
# Ordered list (not a type-keyed dict) because the exception types are
# resolved lazily — only ``get_http_error_mappers`` invokes the providers,
# so duplicate-by-type detection is deferred to resolution time too.
@@ -187,6 +194,7 @@ class PluginRegistrar:
self._pipe_func_executor_sources: dict[str, str] = {}
self._internal_model_sources: dict[str, str] = {}
self._doc_gen_default_sources: dict[tuple[DocGenFormat, DocGenSource], str] = {}
+ self._service_error_code_sources: dict[str, str] = {}
self._slot_sources: dict[HubSlot, str] = {}
# Reassigned per plugin by build_registrar; the floating default keeps the
# menu methods safe to call outside a registration loop (e.g. a focused unit test).
@@ -365,6 +373,29 @@ class PluginRegistrar:
),
)
+ def add_service_error_codes(self, *, codes: "Iterable[ServiceErrorCode]") -> None:
+ """Contribute the error codes a service this plugin speaks to emits on its own, and what each one means.
+
+ For a plugin whose backend is a gateway or a hosted service that refuses some requests itself,
+ before any provider sees them, under codes of its own. Boot freezes every contribution into the
+ hub's `ServiceErrorVocabulary`, which `classify_inference_error` consults ahead of the status
+ ladder: a contributed code decides the error's category, its action and its advice, whatever the
+ status it arrived on. Plain data, stored and nothing else. Fail-loud on a code another plugin
+ contributed, naming both plugins, and on a code the runtime classifies itself.
+ """
+ contributed: list[str] = []
+ for service_error_code in codes:
+ code = service_error_code.code
+ if code in RUNTIME_CLASSIFIED_ERROR_CODES:
+ raise ReservedServiceErrorCodeError(code=code, plugin=self._active.name)
+ if code in self.service_error_codes:
+ raise DuplicateServiceErrorCodeError(code=code, first_plugin=self._service_error_code_sources[code], second_plugin=self._active.name)
+ self.service_error_codes[code] = service_error_code
+ self._service_error_code_sources[code] = self._active.name
+ contributed.append(code)
+ if contributed:
+ self._active.contributions.append(f"service error codes {', '.join(contributed)}")
+
def add_pipe_func_executor(self, *, mode: str, factory: PipeFuncExecutorFactoryFn) -> None:
"""Contribute a factory for one PipeFunc execution mode, keyed by an open ``mode`` token.
diff --git a/pipelex/providers/anthropic/anthropic_factory.py b/pipelex/providers/anthropic/anthropic_factory.py
index 564c9a351..c4d919e10 100644
--- a/pipelex/providers/anthropic/anthropic_factory.py
+++ b/pipelex/providers/anthropic/anthropic_factory.py
@@ -53,12 +53,19 @@ class AnthropicFactory:
model_handle: ModelHandle,
*,
backend: InferenceBackend,
+ sdk_variant: AnthropicSdkVariant | None = None,
) -> AsyncAnthropic | AsyncAnthropicBedrock:
- try:
- sdk_variant = AnthropicSdkVariant(model_handle.sdk)
- except ValueError as exc:
- msg = f"ModelHandle '{model_handle}' is not supported by AnthropicFactory"
- raise AnthropicFactoryError(msg) from exc
+ """Build the client for the handle's sdk, or for `sdk_variant` when one is given.
+
+ `sdk_variant` is for a plugin that registers an sdk token of its own over the Anthropic protocol:
+ its token names its worker, and the variant names the client that worker speaks through.
+ """
+ if sdk_variant is None:
+ try:
+ sdk_variant = AnthropicSdkVariant(model_handle.sdk)
+ except ValueError as exc:
+ msg = f"ModelHandle '{model_handle}' is not supported by AnthropicFactory"
+ raise AnthropicFactoryError(msg) from exc
# Tier 1 transport retry: set the SDK client's retry budget explicitly from config
# instead of inheriting the silent SDK default (anthropic's own DEFAULT_MAX_RETRIES).
@@ -69,11 +76,9 @@ class AnthropicFactory:
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.
+ # its own rather than on `x-api-key`: a gateway that never looks at `x-api-key`
+ # would receive a key left in the SDK's own slot as an anonymous request. Carry it
+ # in the named header instead.
if not backend.api_key:
msg = f"Backend '{backend.name}' sets '{AnthropicExtraField.AUTH_HEADER}' but carries no api_key"
raise AnthropicFactoryError(msg)
diff --git a/pipelex/providers/anthropic/anthropic_llm_worker.py b/pipelex/providers/anthropic/anthropic_llm_worker.py
index 2216a7e00..e9e1ab346 100644
--- a/pipelex/providers/anthropic/anthropic_llm_worker.py
+++ b/pipelex/providers/anthropic/anthropic_llm_worker.py
@@ -32,10 +32,10 @@ from pipelex.cogt.llm.llm_utils import (
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
from pipelex.cogt.llm.structured_output import StructureMethod
from pipelex.cogt.llm.thinking_mode import ThinkingMode
-from pipelex.cogt.model_backends.backend import PipelexBackend
from pipelex.cogt.model_backends.constraints import ListedConstraint
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.config import get_config
+from pipelex.plugins.backend_extras_factory import BackendExtrasFactory
from pipelex.providers.anthropic.anthropic_exceptions import (
AnthropicWorkerConfigurationError,
)
@@ -43,8 +43,8 @@ from pipelex.providers.anthropic.anthropic_factory import (
AnthropicFactory,
AnthropicSdkVariant,
)
-from pipelex.providers.manifold.manifold_metadata import make_manifold_metadata_headers
from pipelex.reporting.reporting_protocol import ReportingProtocol
+from pipelex.system.telemetry.otel_constants import InferenceOutputType
from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar
if TYPE_CHECKING:
@@ -70,6 +70,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
extra_config: dict[str, Any],
inference_model: InferenceModelSpec,
reporting_delegate: ReportingProtocol | None = None,
+ extras_factory: BackendExtrasFactory | None = None,
):
LLMWorkerAbstract.__init__(
self,
@@ -77,6 +78,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
reporting_delegate=reporting_delegate,
)
self.extra_config: dict[str, Any] = extra_config
+ self.extras_factory = extras_factory
self.default_max_tokens: int = 0
if inference_model.max_tokens:
self.default_max_tokens = inference_model.max_tokens
@@ -251,7 +253,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
max_tokens=max_tokens,
thinking=thinking_params.thinking or omit,
output_config=thinking_params.output_config or omit,
- **self._request_header_kwargs(llm_job=llm_job),
+ **self._request_extras_kwargs(llm_job=llm_job, output_desc=InferenceOutputType.TEXT),
) as stream:
final_message: Message = await stream.get_final_message()
except (APIStatusError, APIConnectionError) as sdk_exc:
@@ -308,18 +310,24 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
return full_reply_content
- def _request_header_kwargs(self, *, llm_job: LLMJob) -> dict[str, Any]:
- """The per-request headers this call adds, as SDK keyword arguments: none, except behind Manifold.
+ def _request_extras_kwargs(self, *, llm_job: LLMJob, output_desc: str) -> dict[str, Any]:
+ """The per-request headers and body additions this call sends, as SDK keyword arguments.
- Claude reaches the Pipelex Manifold service over this shared driver rather than over a
- manifold sdk, so this is where the manifold dialect's `x-pipelex-metadata` header joins an
- Anthropic request — per request, because it names the job, where the token is a client
- default. Every other Anthropic backend is a direct provider SDK path and sends nothing of the
- kind: the run's identity and labels are ours to forward to our own service, not to a vendor.
+ None without an extras factory, which is every direct Anthropic and Bedrock path. A plugin that
+ reaches a service of its own over the Anthropic protocol builds this worker with a
+ `BackendExtrasFactory`, the same seam the OpenAI-substrate workers take, and its factory decides
+ per request what joins the call: a header naming the job, for instance, where the credential is
+ a client default.
"""
- if self.inference_model.backend_name != PipelexBackend.MANIFOLD:
+ if self.extras_factory is None:
return {}
- return {"extra_headers": make_manifold_metadata_headers(job_metadata=llm_job.job_metadata)}
+ extra_headers, extra_body = self.extras_factory.make_extras(self.inference_model, inference_job=llm_job, output_desc=output_desc)
+ kwargs: dict[str, Any] = {}
+ if extra_headers:
+ kwargs["extra_headers"] = extra_headers
+ if extra_body:
+ kwargs["extra_body"] = extra_body
+ return kwargs
def _structure_method_kwargs(self) -> dict[str, Any]:
"""What the structured call sends, beyond what instructor's mode sets, for the model's structure method.
@@ -377,7 +385,7 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
max_tokens=effective_max_tokens,
timeout=float(timeout_seconds), # Explicit timeout disables SDK's long-request protection
**self._structure_method_kwargs(),
- **self._request_header_kwargs(llm_job=llm_job),
+ **self._request_extras_kwargs(llm_job=llm_job, output_desc=schema.__name__),
)
except InstructorRetryException as instructor_exc:
# instructor wraps SDK exceptions during retries; recover the underlying
diff --git a/pipelex/providers/blackboxai/blackboxai_plugin.py b/pipelex/providers/blackboxai/blackboxai_plugin.py
index e56877eb2..e80a5b6e0 100644
--- a/pipelex/providers/blackboxai/blackboxai_plugin.py
+++ b/pipelex/providers/blackboxai/blackboxai_plugin.py
@@ -19,6 +19,7 @@ def _make_blackboxai_img_gen_worker(
from pipelex.providers.blackboxai.blackboxai_completions_factory import BlackboxaiCompletionsFactory # ruff: ignore[import-outside-top-level]
from pipelex.providers.openai.openai_client_factory import OpenAIClientFactory # ruff: ignore[import-outside-top-level]
from pipelex.providers.openai.openai_completions_img_gen_worker import OpenAICompletionsImgGenWorker # ruff: ignore[import-outside-top-level]
+ from pipelex.tools.misc.image_utils import ImageFormat # ruff: ignore[import-outside-top-level]
model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)
sdk_instance = sdk_clients.get_or_create(
@@ -30,6 +31,7 @@ def _make_blackboxai_img_gen_worker(
sdk_instance=sdk_instance,
inference_model=inference_model,
reporting_delegate=reporting_delegate,
+ fixed_output_format=ImageFormat.JPEG,
)
diff --git a/pipelex/providers/manifold/manifold_anthropic_extras.py b/pipelex/providers/manifold/manifold_anthropic_extras.py
new file mode 100644
index 000000000..c47de3611
--- /dev/null
+++ b/pipelex/providers/manifold/manifold_anthropic_extras.py
@@ -0,0 +1,35 @@
+"""The per-request extras of a Claude call through the Pipelex Manifold service.
+
+Claude reaches the service over the open Anthropic worker, registered here under the package's own
+`manifold_anthropic` sdk token with this factory: the worker asks it, per request, what joins the
+call, and the answer is the `x-pipelex-metadata` header naming the run and the step (see
+`manifold_metadata`). Every other Anthropic path builds the worker without a factory and sends
+nothing of the kind.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from typing_extensions import override
+
+from pipelex.plugins.backend_extras_factory import BackendExtrasFactory
+from pipelex.providers.manifold.manifold_metadata import make_manifold_metadata_headers
+
+if TYPE_CHECKING:
+ from pipelex.cogt.inference.inference_job_abstract import InferenceJobAbstract
+ from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
+
+
+class ManifoldAnthropicExtrasFactory(BackendExtrasFactory):
+ @override
+ def make_extras(
+ self, inference_model: InferenceModelSpec, *, inference_job: InferenceJobAbstract, output_desc: str
+ ) -> tuple[dict[str, str], dict[str, Any]]:
+ """The metadata header alone, and no body additions.
+
+ `inference_model` and `output_desc` are part of the shared factory signature and unused here:
+ the header names the job, not the model or the output.
+ """
+ del inference_model, output_desc
+ return make_manifold_metadata_headers(job_metadata=inference_job.job_metadata), {}
diff --git a/pipelex/providers/manifold/manifold_constants.py b/pipelex/providers/manifold/manifold_constants.py
index a64b67061..b873e9aaf 100644
--- a/pipelex/providers/manifold/manifold_constants.py
+++ b/pipelex/providers/manifold/manifold_constants.py
@@ -16,7 +16,7 @@ from enum import StrEnum
# 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
+# Anthropic client 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"
@@ -29,13 +29,9 @@ MANIFOLD_AUTH_HEADER = "x-pipelex-api-key"
# the vendor's vocabulary it does not have to.
MANIFOLD_METADATA_HEADER = "x-pipelex-metadata"
-# The gateway's response headers are named in `cogt/inference/error_classification.py`, not here.
-# `MANIFOLD_TRACE_ID_HEADER` and `MANIFOLD_VENDOR_TRACE_ID_HEADER` are the two spellings it stamps
-# its trace id on, and `extract_manifold_metadata` — the native routes' distiller, which is in
-# `cogt`, and `cogt` may not import this package — is the only reader of those two names. The vendor
-# spelling itself has a second reader that does not go through them: `extract_gateway_metadata`
-# holds it as a literal, and that is the function the manifold *image* path distils its failures
-# through, because that path still travels on `portkey_ai`. This file names what the dialect *sends*.
+# The gateway's response headers, the two spellings of its trace id, are named in
+# `manifold_error_metadata`, beside the distiller that reads them. This file names what the dialect
+# *sends*.
# 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
@@ -58,10 +54,11 @@ 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.
+ `manifold_anthropic` is the open Anthropic worker with this package's extras factory, which adds
+ the metadata header to every Claude call.
"""
+ ANTHROPIC = "manifold_anthropic"
COMPLETIONS = "manifold_completions"
RESPONSES = "manifold_responses"
IMG_GEN = "manifold_img_gen"
diff --git a/pipelex/providers/manifold/manifold_error_codes.py b/pipelex/providers/manifold/manifold_error_codes.py
new file mode 100644
index 000000000..86e2db740
--- /dev/null
+++ b/pipelex/providers/manifold/manifold_error_codes.py
@@ -0,0 +1,521 @@
+"""The Pipelex Manifold service's own error codes, contributed to the runtime's service error vocabulary.
+
+The service refuses some requests itself, before any provider sees them, under codes of its own:
+the ``pig-0N`` family on the LLM routes and the frozen ``pipelex_*`` contract codes on the native
+``/v1/pipelex/*`` routes. They group into three families by what the caller has to do — a
+request-shape limit, a reference that cannot be resolved, a request that cannot be routed — and each
+code becomes one ``ServiceErrorCode`` entry: its category, its action and its advice.
+``ManifoldPlugin.register`` contributes ``MANIFOLD_SERVICE_ERROR_CODES``, which the classifier then
+consults ahead of the status ladder.
+
+None of these is retryable: the service refused before a provider saw the request, and the identical
+request earns the identical refusal.
+"""
+
+from enum import StrEnum
+
+from pipelex.cogt.exceptions import InferenceErrorCategory
+from pipelex.cogt.inference.error_classification import UserActionKind
+from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorCode
+
+
+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 Anthropic worker 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 (more than one SDK hop reaches it, under more than one provider name), 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 ``pig-`` codes, at HTTP
+ 400, which is the contract between the two repositories — the wording of a
+ refusal is free to change, the code is not. The substrate's
+ ``model_not_allowed_error`` is a routing refusal too, but the runtime
+ classifies it itself, because Portkey's cloud answers it for a caller's own
+ workspace as well (see ``MODEL_NOT_ALLOWED_ERROR_CODE`` in core).
+ """
+
+ #: ``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
+ #: ``_routing_refusal_entry``). 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 Anthropic worker — 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. The manifold image path still travels
+# on ``portkey_ai``, which is the one client that could start doing so.
+# - ``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 _request_limit_entry(*, code: str, limit: GatewayRequestLimit) -> ServiceErrorCode:
+ """The entry for a request-shape refusal.
+
+ The advice 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 advice
+ sits beside — repeating a compiled-in guess here is how advice starts contradicting the refusal it
+ explains.
+ """
+ match limit:
+ case GatewayRequestLimit.BODY_TOO_LARGE:
+ # The caller sent more than the deployment serves — a smaller input is the whole remedy,
+ # and it is theirs to make. The same holds for the two members below.
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail="The request was too large for the inference gateway — send less in one call, or use smaller inputs.",
+ )
+ case GatewayRequestLimit.OBJECT_TOO_LARGE:
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail="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 ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail="The request nests too deeply for the inference gateway — flatten the inputs or the output structure.",
+ )
+ 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 ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CONTACT_SUPPORT,
+ detail=(
+ "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 _unresolved_reference_entry(*, code: str, reference: GatewayUnresolvedReference) -> ServiceErrorCode:
+ """The entry for a reference the gateway could not resolve.
+
+ The advice names no key, host, status or media type, for the same reason the request-limit advice
+ names no number: the gateway's own refusal message sits beside it and already states the
+ specifics. What the advice adds is what the caller should *do*, which the message does not say.
+
+ Not retryable even for ``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.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 ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CONTACT_SUPPORT,
+ detail=_unresolved_reference_detail(reference=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 its advice is where that distinction is stated.
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail=_unresolved_reference_detail(reference=reference),
+ )
+
+
+def _unresolved_reference_detail(*, reference: GatewayUnresolvedReference) -> str:
+ 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 _routing_refusal_entry(*, code: str, refusal: GatewayRoutingRefusal) -> ServiceErrorCode:
+ """The entry for a request the gateway refused to route.
+
+ Every member is ``CONFIGURATION``: nothing in the prompt, the parameters or the inputs causes any
+ of these, and no edit to them avoids one. Without the family they take the status ladder's 400
+ arm and read as a provider rejecting the caller's content.
+
+ The advice names no integration, protocol or capability: the gateway's own message sits beside it
+ and already states every specific. 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.
+ """
+ match refusal:
+ case GatewayRoutingRefusal.UNKNOWN_MODEL:
+ # The deployment does not know that model at all — which is exactly what
+ # ``is_model_not_found`` means, so this is the one member that sets it. It selects the
+ # family's ``*ModelNotFoundError`` class, which ``pipe_operator.py`` re-raises as a
+ # ``PipeOperatorModelAvailabilityError`` carrying the model handle.
+ #
+ # The advice's 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 — 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. Splitting the code is the real fix, filed on ``pipelex-manifold`` as
+ # L-260902-701614.
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CHANGE_MODEL,
+ is_model_not_found=True,
+ detail=(
+ "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:
+ # 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. ``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 handle resolved, so this is not a model the
+ # deployment does not know.
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CONTACT_SUPPORT,
+ detail=(
+ "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:
+ # The model exists and is served, just not over the protocol that was spoken — so it is not
+ # a model-not-found, and ``CHANGE_MODEL`` is still what an end caller can do about it.
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CHANGE_MODEL,
+ detail=(
+ "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:
+ # Same reading: the model exists and is served, it just cannot do what was asked.
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CHANGE_MODEL,
+ detail=(
+ "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."
+ ),
+ )
+
+
+# Every code the service emits on its own that the runtime reads, one entry each. The three families
+# are disjoint by construction — 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 — and the registrar refuses a
+# code claimed twice, so a code added to two maps fails the boot rather than picking one silently.
+MANIFOLD_SERVICE_ERROR_CODES: tuple[ServiceErrorCode, ...] = (
+ *(_request_limit_entry(code=code, limit=limit) for code, limit in _GATEWAY_REQUEST_LIMIT_BY_CODE.items()),
+ *(_unresolved_reference_entry(code=code, reference=reference) for code, reference in _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE.items()),
+ *(_routing_refusal_entry(code=code, refusal=refusal) for code, refusal in _GATEWAY_ROUTING_REFUSAL_BY_CODE.items()),
+)
diff --git a/pipelex/providers/manifold/manifold_error_metadata.py b/pipelex/providers/manifold/manifold_error_metadata.py
new file mode 100644
index 000000000..4aa44732d
--- /dev/null
+++ b/pipelex/providers/manifold/manifold_error_metadata.py
@@ -0,0 +1,91 @@
+"""How a failure on the Pipelex Manifold service's native routes is distilled into error metadata.
+
+The 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, and their failures are distilled
+here, beside the client that raises them.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, error_code_from_body_code_first, parse_retry_after_seconds
+from pipelex.cogt.inference.provider_name import ProviderName
+
+# The headers the service stamps its trace id on, in the order the distiller below reads them.
+#
+# Every answer a provider gave carries that id twice, with the same value under each spelling: the
+# pipelex one the dialect owns, and the inherited vendor one the gateway still emits because
+# `portkey_ai` reads it on the image path — a refusal the gateway raised before trying a provider
+# carries neither. Reading the pipelex spelling first is what makes the gateway's eventual dropping
+# of the vendor one a no-op for the native routes, at which point the second name and its lookup go
+# away. It is not a no-op for the image path: `extract_gateway_metadata` carries the vendor spelling
+# as a literal of its own, and the image worker distils its failures through it, so it can only move
+# once the image path is off `portkey_ai`.
+MANIFOLD_TRACE_ID_HEADER = "x-pipelex-trace-id"
+MANIFOLD_VENDOR_TRACE_ID_HEADER = "x-portkey-trace-id"
+
+
+def extract_manifold_metadata(exc: BaseException) -> ProviderErrorMetadata:
+ """Distill a raw-httpx failure against the Pipelex Manifold service into metadata.
+
+ Two exception shapes reach here:
+
+ - ``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 ``error_code_from_body_code_first``, 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.
+
+ **The request id is read in the manifold dialect's own spelling.** The provider's ``x-request-id``
+ comes first when a provider named its call, and the gateway's trace id is the fallback for the
+ answers that carried none — under ``MANIFOLD_TRACE_ID_HEADER`` before the inherited vendor
+ spelling, which holds the same value and is only still read because the gateway still emits it.
+
+ **It reports ``ProviderName.GATEWAY``**, and that is a decision rather than an oversight: the
+ service is a gateway, it phrases quota exhaustion and rate limiting the way the gateway
+ substrate does, and every ``match`` on ``ProviderName`` would need a second arm with the same
+ body to say otherwise. Which service 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(MANIFOLD_TRACE_ID_HEADER) or headers.get(MANIFOLD_VENDOR_TRACE_ID_HEADER)
+ 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 = error_code_from_body_code_first(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,
+ )
diff --git a/pipelex/providers/manifold/manifold_exceptions.py b/pipelex/providers/manifold/manifold_exceptions.py
index 3f09d121b..d4352260e 100644
--- a/pipelex/providers/manifold/manifold_exceptions.py
+++ b/pipelex/providers/manifold/manifold_exceptions.py
@@ -1,16 +1,34 @@
+"""The package's errors, each published under the page and title of its nearest generic family.
+
+A client that receives one of these in an error report reads its RFC 7807 `type` and `title`, so each
+class declares both rather than deriving them from its name: the page is the existing public one of
+the family the failure belongs to, and the title names the failure, not the component that raised it.
+Faults in the operator's configuration, a missing endpoint or credential, keep messages as precise as
+the operator needs, since they fail a boot or a worker build and never reach a client.
+"""
+
from pipelex.cogt.exceptions import CogtError
+from pipelex.urls import URLs
+
+_COGT_ERROR_PAGE = f"{URLs.error_docs_base}/cogt-error/"
+_CREDENTIALS_ERROR_PAGE = f"{URLs.error_docs_base}/inference-backend-credentials-error/"
+_EXTRACT_FAILURE_PAGE = f"{URLs.error_docs_base}/extract-job-failure-error/"
+_SEARCH_FAILURE_PAGE = f"{URLs.error_docs_base}/search-job-failure-error/"
class ManifoldError(CogtError):
- pass
+ _declared_type_uri = _COGT_ERROR_PAGE
+ _declared_title = "Inference backend error"
class ManifoldFactoryError(ManifoldError):
- pass
+ _declared_type_uri = _COGT_ERROR_PAGE
+ _declared_title = "Inference client setup error"
class ManifoldCredentialsError(ManifoldError):
- pass
+ _declared_type_uri = _CREDENTIALS_ERROR_PAGE
+ _declared_title = "Inference backend credentials missing"
class ManifoldEndpointError(ManifoldError):
@@ -21,14 +39,20 @@ class ManifoldEndpointError(ManifoldError):
silently became a vendor's public URL would carry our service token to the wrong company.
"""
+ _declared_type_uri = _CREDENTIALS_ERROR_PAGE
+ _declared_title = "Inference backend endpoint missing"
+
class ManifoldExtractResponseError(ManifoldError):
- pass
+ _declared_type_uri = _EXTRACT_FAILURE_PAGE
+ _declared_title = "Extract response unreadable"
class ManifoldSearchResponseError(ManifoldError):
- pass
+ _declared_type_uri = _SEARCH_FAILURE_PAGE
+ _declared_title = "Search response unreadable"
class ManifoldSearchEmptyResultError(ManifoldError):
- pass
+ _declared_type_uri = _SEARCH_FAILURE_PAGE
+ _declared_title = "Search returned no result"
diff --git a/pipelex/providers/manifold/manifold_extract_worker.py b/pipelex/providers/manifold/manifold_extract_worker.py
index f3fcd3a7f..7757308ff 100644
--- a/pipelex/providers/manifold/manifold_extract_worker.py
+++ b/pipelex/providers/manifold/manifold_extract_worker.py
@@ -36,9 +36,9 @@ from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCateg
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_response_errors import describe_response_validation_error
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_base64 import make_base64_url_from_any_uri
if TYPE_CHECKING:
@@ -89,7 +89,7 @@ class ManifoldExtractWorker(ExtractWorkerAbstract):
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)}"
+ msg = f"Could not parse the extraction response for model '{self.inference_model.name}': {describe_response_validation_error(exc=exc)}"
raise ManifoldExtractResponseError(msg) from exc
async def _make_request(self, *, extract_job: ExtractJob) -> ManifoldExtractRequest:
diff --git a/pipelex/providers/manifold/manifold_img_gen_worker.py b/pipelex/providers/manifold/manifold_img_gen_worker.py
index dcda5483c..85857a60f 100644
--- a/pipelex/providers/manifold/manifold_img_gen_worker.py
+++ b/pipelex/providers/manifold/manifold_img_gen_worker.py
@@ -46,8 +46,8 @@ 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_metadata import make_manifold_metadata_headers
+from pipelex.providers.manifold.manifold_response_errors import describe_response_validation_error
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
@@ -186,7 +186,8 @@ class ManifoldImgGenWorker(ImgGenWorkerAbstract):
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)}"
+ problems = describe_response_validation_error(exc=exc)
+ msg = f"Could not parse the image generation response for model '{self.inference_model.name}': {problems}"
raise ImgGenGenerationError(
msg,
error_category=InferenceErrorCategory.UNKNOWN,
diff --git a/pipelex/providers/manifold/manifold_native_client.py b/pipelex/providers/manifold/manifold_native_client.py
index ec5bee9a9..b6301fc9f 100644
--- a/pipelex/providers/manifold/manifold_native_client.py
+++ b/pipelex/providers/manifold/manifold_native_client.py
@@ -18,11 +18,11 @@ 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_error_metadata import extract_manifold_metadata
from pipelex.providers.manifold.manifold_exceptions import ManifoldError
from pipelex.providers.manifold.manifold_factory import ManifoldFactory
from pipelex.providers.manifold.manifold_metadata import make_manifold_metadata_headers
diff --git a/pipelex/providers/manifold/manifold_plugin.py b/pipelex/providers/manifold/manifold_plugin.py
index cb3df2b58..4ab527442 100644
--- a/pipelex/providers/manifold/manifold_plugin.py
+++ b/pipelex/providers/manifold/manifold_plugin.py
@@ -6,9 +6,10 @@ shape rather than on the Images API, and the catalog says which by giving them `
"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.
+Claude reaches the manifold service on ``manifold_anthropic``: the open Anthropic worker, built with
+the package's extras factory so that every call carries the metadata header, and a client that
+authenticates on whichever header the backend names. A catalog entry left on the plain ``anthropic``
+sdk would still answer, without the header.
"""
from __future__ import annotations
@@ -16,9 +17,10 @@ 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.inference_backend_registry import InferenceFamily, require_sdk
from pipelex.plugins.model_handle import ModelHandle
from pipelex.providers.manifold.manifold_constants import ManifoldSdk
+from pipelex.providers.manifold.manifold_error_codes import MANIFOLD_SERVICE_ERROR_CODES
if TYPE_CHECKING:
from pipelex.cogt.inference.inference_worker_abstract import InferenceWorkerAbstract
@@ -29,6 +31,33 @@ if TYPE_CHECKING:
from pipelex.reporting.reporting_protocol import ReportingProtocol
+def _make_manifold_anthropic_worker(
+ *,
+ inference_model: InferenceModelSpec,
+ backend: InferenceBackend,
+ sdk_clients: SdkClientRegistry,
+ reporting_delegate: ReportingProtocol | None,
+) -> InferenceWorkerAbstract:
+ require_sdk(spec="anthropic", extra="anthropic", msg="The anthropic SDK is required to reach Claude through this backend.")
+
+ from pipelex.providers.anthropic.anthropic_factory import AnthropicFactory, AnthropicSdkVariant # ruff: ignore[import-outside-top-level]
+ from pipelex.providers.anthropic.anthropic_llm_worker import AnthropicLLMWorker # ruff: ignore[import-outside-top-level]
+ from pipelex.providers.manifold.manifold_anthropic_extras import ManifoldAnthropicExtrasFactory # 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: AnthropicFactory.make_anthropic_client(model_handle=model_handle, backend=backend, sdk_variant=AnthropicSdkVariant.ANTHROPIC),
+ )
+ return AnthropicLLMWorker(
+ sdk_instance=sdk_instance,
+ extra_config=backend.extra_config,
+ inference_model=inference_model,
+ reporting_delegate=reporting_delegate,
+ extras_factory=ManifoldAnthropicExtrasFactory(),
+ )
+
+
def _make_manifold_completions_worker(
*,
inference_model: InferenceModelSpec,
@@ -84,6 +113,7 @@ def _make_manifold_completions_img_gen_worker(
) -> 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]
+ from pipelex.tools.misc.image_utils import ImageFormat # ruff: ignore[import-outside-top-level]
model_handle = ModelHandle.make_for_inference_model(inference_model=inference_model)
sdk_instance = sdk_clients.get_or_create(
@@ -95,6 +125,7 @@ def _make_manifold_completions_img_gen_worker(
sdk_instance=sdk_instance,
inference_model=inference_model,
reporting_delegate=reporting_delegate,
+ fixed_output_format=ImageFormat.PNG,
)
@@ -166,6 +197,8 @@ class ManifoldPlugin:
targets_api = PLUGIN_API_VERSION
def register(self, registrar: PluginRegistrar) -> None:
+ registrar.add_service_error_codes(codes=MANIFOLD_SERVICE_ERROR_CODES)
+ registrar.add_inference_backend(family=InferenceFamily.LLM, sdk=ManifoldSdk.ANTHROPIC, make_worker=_make_manifold_anthropic_worker)
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)
diff --git a/pipelex/providers/manifold/manifold_response_errors.py b/pipelex/providers/manifold/manifold_response_errors.py
new file mode 100644
index 000000000..6b7d2bf7f
--- /dev/null
+++ b/pipelex/providers/manifold/manifold_response_errors.py
@@ -0,0 +1,14 @@
+"""How a response body the service sent in an unexpected shape is described in an error message.
+
+A local formatter rather than core's richer validation-error analysis, which is a general-purpose
+helper rather than an extension point: a service response that fails its schema needs only which
+fields were wrong and why.
+"""
+
+from pydantic import ValidationError
+
+
+def describe_response_validation_error(*, exc: ValidationError) -> str:
+ """One `location: message` clause per error, in the order pydantic reports them."""
+ clauses = [f"{'.'.join(str(part) for part in error['loc']) or '<root>'}: {error['msg']}" for error in exc.errors()]
+ return "; ".join(clauses)
diff --git a/pipelex/providers/openai/openai_completions_img_gen_worker.py b/pipelex/providers/openai/openai_completions_img_gen_worker.py
index 333fdd382..27c0959c8 100644
--- a/pipelex/providers/openai/openai_completions_img_gen_worker.py
+++ b/pipelex/providers/openai/openai_completions_img_gen_worker.py
@@ -17,7 +17,6 @@ from pipelex.cogt.inference.error_classification import UserAction, UserActionKi
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.inference_constants import InferenceOutputType
-from pipelex.cogt.model_backends.backend import MANAGED_GATEWAY_BACKEND_NAMES
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.providers.openai.openai_completions_factory import OpenAICompletionsFactory
from pipelex.reporting.reporting_protocol import ReportingProtocol
@@ -38,8 +37,22 @@ class OpenAICompletionsImgGenWorker(ImgGenWorkerAbstract):
sdk_instance: Any,
inference_model: InferenceModelSpec,
reporting_delegate: ReportingProtocol | None = None,
+ fixed_output_format: ImageFormat | None = None,
):
+ """Build the worker.
+
+ Args:
+ openai_completions_factory: The factory building the request's messages and extras.
+ sdk_instance: The `openai.AsyncOpenAI` client to call.
+ inference_model: The model this worker serves.
+ reporting_delegate: Where inference usage is reported.
+ fixed_output_format: The one image format the service answers in, for a service that
+ normalises every image to a fixed format and may answer with a URL, from which no
+ format can be read. Whoever registers the worker for such a service passes it; a
+ request for another format is refused before the call.
+ """
super().__init__(inference_model=inference_model, reporting_delegate=reporting_delegate)
+ self.fixed_output_format = fixed_output_format
if not isinstance(sdk_instance, openai.AsyncOpenAI):
msg = f"Provided ImgGen sdk_instance is not of type openai.AsyncOpenAI: it's a '{type(sdk_instance)}'"
@@ -54,26 +67,15 @@ class OpenAICompletionsImgGenWorker(ImgGenWorkerAbstract):
img_gen_job: ImgGenJob,
) -> GeneratedImageRawDetails:
log.debug(f"Generating image with model: {self.inference_model.tag}")
- image_format: ImageFormat | None = None
- # Every Pipelex-managed gateway: 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 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)
- image_format = ImageFormat.PNG
- if self.inference_model.backend_name == "blackboxai":
- if img_gen_job.job_params.output_format and not img_gen_job.job_params.output_format.is_jpeg:
+ image_format = self.fixed_output_format
+ if image_format is not None:
+ requested_format = img_gen_job.job_params.output_format
+ if requested_format is not None and requested_format != image_format:
msg = (
- f"Completions ImgGen worker for BlackboxAI only supports JPEG output format. "
- f"Requested output format: {img_gen_job.job_params.output_format}"
+ f"Completions ImgGen worker for backend '{self.inference_model.backend_name}' only supports {image_format} output format. "
+ f"Requested output format: {requested_format}"
)
raise ImgGenParameterError(msg)
- image_format = ImageFormat.JPEG
# Build message content with optional input images
messages = await self._build_messages_with_images(img_gen_job)
@@ -123,14 +125,12 @@ class OpenAICompletionsImgGenWorker(ImgGenWorkerAbstract):
)
base64_str, base64_extracted_mime_type = extracted
elif (content := openai_message.content) and content.startswith("http"):
- # OpenAI response message is a URL, this happens with blackboxai and the Pipelex-managed gateways which have a fixed output format.
- # Otherwise we won't know what format the image is in.
+ # The response message is a URL, which only a service with a fixed output format answers with:
+ # otherwise we won't know what format the image is in.
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 a Pipelex-managed gateway "
- f"({', '.join(MANAGED_GATEWAY_BACKEND_NAMES)}). "
- f"Backend is: '{self.inference_model.backend_name}'"
+ f"The completions image response is a URL, but the worker for backend '{self.inference_model.backend_name}' "
+ f"was built with no fixed output format, so the image's format cannot be known."
)
raise ImgGenParameterError(msg)
actual_url = openai_message.content
diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.py
index 04d409db2..83c1b52b7 100644
--- a/pipelex/runtime_boot.py
+++ b/pipelex/runtime_boot.py
@@ -64,6 +64,7 @@ from pipelex.cogt.exceptions import (
RoutingProfileLibraryNotFoundError,
)
from pipelex.cogt.inference.inference_manager import InferenceManager
+from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorVocabulary
from pipelex.cogt.model_backends.backend_credentials import (
BackendCredentialsErrorMsgFactory,
)
@@ -627,6 +628,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.
# they are looked up at run time by the interpreter.
self.runtime_hub.set_inference_backend_registry(InferenceBackendRegistry(plugin_registrar.inference_backends))
self.runtime_hub.set_model_lister_registry(ModelListerRegistry(plugin_registrar.model_listers))
+ self.runtime_hub.set_service_error_vocabulary(service_error_vocabulary=ServiceErrorVocabulary(plugin_registrar.service_error_codes))
self.runtime_hub.set_orchestrator_registry(OrchestratorRegistry(plugin_registrar.orchestrators))
self.runtime_hub.set_bundle_validator_registry(BundleValidatorRegistry(plugin_registrar.bundle_validators))
storage_provider_registry = StorageProviderRegistry(plugin_registrar.storage_providers)
diff --git a/pipelex/runtime_hub.py b/pipelex/runtime_hub.py
index 485fefa16..05f84b960 100644
--- a/pipelex/runtime_hub.py
+++ b/pipelex/runtime_hub.py
@@ -59,6 +59,7 @@ if TYPE_CHECKING:
# Rich is the `cli` extra: the console is built when it is first asked for, never at import or at boot.
from rich.console import Console
+ from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorVocabulary
from pipelex.plugins.bundle_validator_registry import BundleValidatorRegistry
from pipelex.plugins.inference_backend_registry import InferenceBackendRegistry
from pipelex.plugins.model_lister_registry import ModelListerRegistry
@@ -119,6 +120,7 @@ class RuntimeHub:
self._bundle_validator_registry: BundleValidatorRegistry | None = None
self._storage_provider_registry: StorageProviderRegistry | None = None
self._secrets_provider_registry: SecretsProviderRegistry | None = None
+ self._service_error_vocabulary: ServiceErrorVocabulary | None = None
self._inference_manager: InferenceManagerProtocol
self._report_delegate: ReportingProtocol
self._content_generator: ContentGeneratorProtocol | None = None
@@ -293,6 +295,9 @@ class RuntimeHub:
def set_secrets_provider_registry(self, secrets_provider_registry: "SecretsProviderRegistry"):
self._secrets_provider_registry = secrets_provider_registry
+ def set_service_error_vocabulary(self, *, service_error_vocabulary: "ServiceErrorVocabulary"):
+ self._service_error_vocabulary = service_error_vocabulary
+
def set_inference_manager(self, inference_manager: InferenceManagerProtocol):
self._inference_manager = inference_manager
@@ -439,6 +444,9 @@ class RuntimeHub:
raise RuntimeError(msg)
return self._secrets_provider_registry
+ def get_optional_service_error_vocabulary(self) -> "ServiceErrorVocabulary | None":
+ return self._service_error_vocabulary
+
def get_inference_manager(self) -> InferenceManagerProtocol:
return self._inference_manager
@@ -551,6 +559,16 @@ def get_bundle_validator_registry() -> "BundleValidatorRegistry":
return get_runtime_hub().get_bundle_validator_registry()
+def get_optional_service_error_vocabulary() -> "ServiceErrorVocabulary | None":
+ """Non-raising by contract: the error classifier runs on paths that may precede a boot, or follow a partial one.
+
+ Covers the no-hub-at-all state and the hub booted without the plugins' contributions alike; the
+ classifier then reads every error on the status ladder alone.
+ """
+ runtime_hub = RuntimeHub.get_optional_instance()
+ return runtime_hub.get_optional_service_error_vocabulary() if runtime_hub is not None else None
+
+
def get_storage_provider_registry() -> "StorageProviderRegistry":
return get_runtime_hub().get_storage_provider_registry()
diff --git a/subject_grants.toml b/subject_grants.toml
index 8fc3b620f..ba967177b 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -1708,14 +1708,6 @@ rationale = "Predicate on the error_message; single operand."
param = "response"
rationale = "Parses the response; single operand."
-["pipelex/cogt/inference/error_classification.py::_parse_retry_after_seconds"]
-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."
@@ -1732,6 +1724,10 @@ rationale = "Extracts from the exc; single operand."
param = "body"
rationale = "Extracts/derives from the body; single operand."
+["pipelex/cogt/inference/error_classification.py::error_code_from_body_code_first"]
+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::extract_anthropic_metadata"]
param = "exc"
rationale = "Extracts from the exc; single operand."
@@ -1772,10 +1768,6 @@ 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."
@@ -1792,6 +1784,10 @@ rationale = "Extracts from the exc; single operand."
param = "instructor_exc"
rationale = "Extracts from the instructor_exc; single operand."
+["pipelex/cogt/inference/error_classification.py::parse_retry_after_seconds"]
+param = "value"
+rationale = "Parses the value; single operand."
+
["pipelex/cogt/inference/error_classify.py::_classify_statusless"]
param = "metadata"
rationale = "Classifies the metadata; single operand."
@@ -5012,6 +5008,10 @@ rationale = "Predicate on the sdk; single operand."
param = "sdk"
rationale = "Predicate on the sdk; single operand."
+["pipelex/providers/manifold/manifold_error_metadata.py::extract_manifold_metadata"]
+param = "exc"
+rationale = "Extracts from the exc; single operand."
+
["pipelex/providers/manifold/manifold_factory.py::ManifoldFactory._make_gemini_image_config"]
param = "taxonomy"
rationale = "Builds the image_config block from the Gemini aspect-ratio taxonomy; the job params and model name stay keyword-only."
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 367d9077d..86675e1d9 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -79,6 +79,7 @@ DuplicateModelListerError | Duplicate model lister | https://docs.pipelex.com/la
DuplicateOrchestratorError | Duplicate orchestrator | https://docs.pipelex.com/latest/errors/duplicate-orchestrator-error/
DuplicatePipeFuncExecutorError | Duplicate pipe func executor | https://docs.pipelex.com/latest/errors/duplicate-pipe-func-executor-error/
DuplicateSecretsProviderError | Duplicate secrets provider | https://docs.pipelex.com/latest/errors/duplicate-secrets-provider-error/
+DuplicateServiceErrorCodeError | Duplicate service error code | https://docs.pipelex.com/latest/errors/duplicate-service-error-code-error/
DuplicateStorageProviderError | Duplicate storage provider | https://docs.pipelex.com/latest/errors/duplicate-storage-provider-error/
EntryPipeAmbiguousError | Entry pipe ambiguous | https://docs.pipelex.com/latest/errors/entry-pipe-ambiguous-error/
EntryPipeNotFoundError | Entry pipe not found | https://docs.pipelex.com/latest/errors/entry-pipe-not-found-error/
@@ -163,13 +164,13 @@ LinkupSearchResponseError | Linkup search response | https://docs.pipelex.com/la
ListWhereSingularError | List where singular | https://docs.pipelex.com/latest/errors/list-where-singular-error/
LogSinkHeaderValueError | Log sink header value holds a line break | https://docs.pipelex.com/latest/errors/log-sink-header-value-error/
LogSinkVariableError | Log sink variable did not resolve | https://docs.pipelex.com/latest/errors/log-sink-variable-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/
+ManifoldCredentialsError | Inference backend credentials missing | https://docs.pipelex.com/latest/errors/inference-backend-credentials-error/
+ManifoldEndpointError | Inference backend endpoint missing | https://docs.pipelex.com/latest/errors/inference-backend-credentials-error/
+ManifoldError | Inference backend error | https://docs.pipelex.com/latest/errors/cogt-error/
+ManifoldExtractResponseError | Extract response unreadable | https://docs.pipelex.com/latest/errors/extract-job-failure-error/
+ManifoldFactoryError | Inference client setup error | https://docs.pipelex.com/latest/errors/cogt-error/
+ManifoldSearchEmptyResultError | Search returned no result | https://docs.pipelex.com/latest/errors/search-job-failure-error/
+ManifoldSearchResponseError | Search response unreadable | https://docs.pipelex.com/latest/errors/search-job-failure-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/
@@ -290,6 +291,7 @@ RemoteConfigUnavailableError | Remote config unavailable | https://docs.pipelex.
RemoteConfigValidationError | Remote config validation | https://docs.pipelex.com/latest/errors/remote-config-validation-error/
RemoteFileFetchError | Remote file could not be fetched | https://docs.pipelex.com/latest/errors/remote-file-fetch-error/
ReportingManagerError | Reporting manager | https://docs.pipelex.com/latest/errors/reporting-manager-error/
+ReservedServiceErrorCodeError | Reserved service error code | https://docs.pipelex.com/latest/errors/reserved-service-error-code-error/
RetiredPluginEntryPointGroupError | Retired plugin entry point group | https://docs.pipelex.com/latest/errors/retired-plugin-entry-point-group-error/
RoutingProfileBlueprintValueError | Routing profile blueprint value | https://docs.pipelex.com/latest/errors/routing-profile-blueprint-value-error/
RoutingProfileDisabledBackendError | Routing profile disabled backend | https://docs.pipelex.com/latest/errors/routing-profile-disabled-backend-error/
diff --git a/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py b/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py
new file mode 100644
index 000000000..4bd774855
--- /dev/null
+++ b/tests/unit/pipelex/cogt/inference/test_model_not_allowed.py
@@ -0,0 +1,342 @@
+"""A model an integration serves but does not allow for this caller, from the wire code to the rendered advice.
+
+``model_not_allowed_error`` comes from the Portkey substrate a hosted gateway is
+built on, not from any one service's own code namespace: its middleware answers it,
+at HTTP 412, when an integration serves the model but does not allow it for this
+caller, because the model is off the integration's allow-list or archived. The same
+code comes from a hosted gateway and from a user's own Portkey workspace, so the
+runtime reads it in core, through ``ProviderErrorMetadata.is_model_not_allowed``,
+rather than through a plugin's service error vocabulary.
+
+The ladder's generic 4xx arm would read a 412 as a configuration problem with the
+advice to review the prompt. 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 asks for another model and is never retried, the Render
+step names the model handle the deck resolved to, and the consequences that outlive
+this module are pinned too — the HTTP status it answers, and the advice surviving
+the pipe router's location of the failure.
+
+**Not a missing model.** The model exists and an integration serves it, only not for
+this caller, so ``is_model_not_found`` stays unset and the family keeps its failure
+class rather than its ``*ModelNotFoundError``.
+
+**The one refusal whose advice names the model.** The substrate's own message names
+only the backend's wire id, which the method's author never wrote, so the advice
+names the model handle the deck resolved the pipe's model to.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, 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 (
+ MODEL_NOT_ALLOWED_ERROR_CODE,
+ ProviderErrorMetadata,
+ UserActionKind,
+ extract_anthropic_metadata,
+ extract_gateway_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_run.exceptions import PipeRouterError
+from pipelex.providers.manifold.manifold_error_metadata import extract_manifold_metadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+_ORIGIN = "https://gateway.example.com"
+
+_GENERIC_ADVICE = "The provider rejected the request — review the prompt, parameters, and inputs."
+
+# The backend's id for the model, which is all the substrate's own message names, and
+# the handle the deck resolved the method's model to, which is the deck's own name for it.
+_MODEL_NOT_ALLOWED_WIRE_ID = "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+_MODEL_NOT_ALLOWED_HANDLE = "claude-4.5-sonnet"
+
+# The body the Portkey middleware answers with, at HTTP 412, verbatim as a run on the
+# hosted API received it. The code sits in ``type`` and ``code`` is null.
+_MODEL_NOT_ALLOWED_BODY: dict[str, Any] = {
+ "error": {
+ "message": f"Model {_MODEL_NOT_ALLOWED_WIRE_ID} is not allowed for this integration",
+ "type": "model_not_allowed_error",
+ "param": None,
+ "code": None,
+ }
+}
+
+
+def _as_the_portkey_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:
+ """Build the exception through Portkey's own factory, which keeps only the message string on ``body``."""
+ 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, the hop an LLM call on a gateway takes."""
+ 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 _as_the_anthropic_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:
+ """Build the exception through the Anthropic SDK's own factory, the hop Claude travels on.
+
+ For a status it has no subclass for, 412 among them, the factory returns a plain
+ ``APIStatusError``, which a hand-built ``BadRequestError`` would not show.
+ """
+ request = httpx.Request("POST", f"{_ORIGIN}/v1/messages")
+ response = httpx.Response(
+ status_code=status_code,
+ request=request,
+ content=json.dumps(body).encode(),
+ headers={"content-type": "application/json"},
+ )
+ client = anthropic.AsyncAnthropic(api_key="unused-in-this-test", base_url=_ORIGIN)
+ return client._make_status_error_from_response(response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+
+def _as_plain_httpx_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:
+ """The Manifold service's native ``/v1/pipelex/*`` routes, which the runtime calls over plain ``httpx``."""
+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")
+ response = httpx.Response(status_code=status_code, request=request, json=body)
+ return httpx.HTTPStatusError(f"Client error '{status_code}'", request=request, response=response)
+
+
+def _envelope(code: str | None, *, status_code: int = 412, provider: ProviderName = ProviderName.GATEWAY) -> ProviderErrorMetadata:
+ return ProviderErrorMetadata(
+ provider=provider,
+ sdk_exception_type="PreconditionFailedError",
+ message="Portkey Error: refused",
+ status_code=status_code,
+ provider_error_code=code,
+ )
+
+
+def _rendered_error(
+ metadata: ProviderErrorMetadata,
+ *,
+ family: InferenceErrorFamily = InferenceErrorFamily.LLM,
+ model_handle: str = _MODEL_NOT_ALLOWED_HANDLE,
+) -> CogtError:
+ return render_inference_error(
+ metadata=metadata,
+ classification=classify_inference_error(metadata),
+ family=family,
+ model_desc=f"{model_handle} → Model[{_MODEL_NOT_ALLOWED_WIRE_ID}]",
+ model_handle=model_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:
+ """``is_model_not_allowed`` reads the substrate's code off the envelope."""
+
+ def test_the_code_is_recognized(self) -> None:
+ assert MODEL_NOT_ALLOWED_ERROR_CODE == "model_not_allowed_error"
+ assert _envelope(MODEL_NOT_ALLOWED_ERROR_CODE).is_model_not_allowed is True
+
+ @pytest.mark.parametrize(
+ "code",
+ [None, "pig-01", "invalid_request_error", "model_not_found", "model_not_allowed", "MODEL_NOT_ALLOWED_ERROR", ""],
+ )
+ def test_any_other_code_is_not_a_model_not_allowed_refusal(self, code: str | None) -> None:
+ assert _envelope(code).is_model_not_allowed is False
+
+ @pytest.mark.parametrize("provider", list(ProviderName))
+ def test_the_code_is_read_whichever_provider_reported_it(self, provider: ProviderName) -> None:
+ """Claude reaches a gateway on the Anthropic driver, so the refusal is not always reported as GATEWAY."""
+ assert _envelope(MODEL_NOT_ALLOWED_ERROR_CODE, provider=provider).is_model_not_allowed is True
+
+
+class TestTheCodeSurvivesEveryExtractHop:
+ @pytest.mark.parametrize(
+ ("raise_it", "extract"),
+ [
+ pytest.param(_as_the_openai_sdk_raises_it, extract_openai_metadata, id="openai-substrate"),
+ pytest.param(_as_the_anthropic_sdk_raises_it, extract_anthropic_metadata, id="anthropic-driver"),
+ pytest.param(_as_the_portkey_sdk_raises_it, extract_gateway_metadata, id="portkey-substrate"),
+ pytest.param(_as_plain_httpx_raises_it, extract_manifold_metadata, id="native-routes-httpx"),
+ ],
+ )
+ def test_the_refusal_through_every_hop(
+ self,
+ raise_it: Callable[..., BaseException],
+ extract: Callable[[BaseException], ProviderErrorMetadata],
+ ) -> None:
+ """The substrate's own envelope, at 412, through each SDK's own factory.
+
+ Its code sits in ``type`` with ``code`` null. The two vendor-facing hops read
+ ``type`` first; the two Pipelex-service hops read ``code`` first and fall back
+ to ``type``, which is the fallback this case exercises.
+ """
+ exc = raise_it(status_code=412, body=_MODEL_NOT_ALLOWED_BODY)
+
+ metadata = extract(exc)
+
+ assert metadata.status_code == 412
+ assert metadata.provider_error_code == MODEL_NOT_ALLOWED_ERROR_CODE
+ assert metadata.is_model_not_allowed is True
+
+
+class TestClassification:
+ def test_it_asks_for_another_model_and_is_not_a_missing_model(self) -> None:
+ """The model exists and an integration serves it, only not for this caller.
+
+ So ``CHANGE_MODEL`` is what the caller can do, and the flag stays unset:
+ "not found" would be false.
+ """
+ result = classify_inference_error(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
+
+ assert result.is_model_not_allowed is True
+ assert result.category == InferenceErrorCategory.CONFIGURATION
+ assert result.category.is_retryable is False
+ assert result.user_action_kind == UserActionKind.CHANGE_MODEL
+ assert result.is_model_not_found is False
+ assert result.service_error_code is None
+
+ def test_a_412_without_the_code_still_takes_the_status_ladder(self) -> None:
+ """The contrast: the ladder's generic 4xx arm, which is what the refusal would otherwise read as."""
+ result = classify_inference_error(_envelope("something-else"))
+
+ assert result.is_model_not_allowed is False
+ assert result.category == InferenceErrorCategory.CONFIGURATION
+ assert result.user_action_kind == UserActionKind.CHANGE_INPUT
+
+
+class TestEndToEnd:
+ def test_it_reaches_the_caller_as_a_change_model_naming_the_handle(self) -> None:
+ """The refusal a run on the hosted API received, through the hop an LLM call on a gateway takes.
+
+ It asks for another model, names it by its handle, and stays the family's
+ failure class, since the model was found.
+ """
+ exc = _as_the_openai_sdk_raises_it(status_code=412, body=_MODEL_NOT_ALLOWED_BODY)
+ metadata = extract_openai_metadata(exc)
+
+ rendered = _rendered_error(metadata)
+
+ assert isinstance(rendered, LLMCompletionError)
+ assert not isinstance(rendered, LLMModelNotFoundError)
+ assert rendered.error_category == InferenceErrorCategory.CONFIGURATION
+ assert rendered.user_action is not None
+ assert rendered.user_action.kind == UserActionKind.CHANGE_MODEL
+ assert f"'{_MODEL_NOT_ALLOWED_HANDLE}'" in rendered.user_action.detail
+ assert rendered.user_action.detail != _GENERIC_ADVICE
+
+
+class TestRenderedAdvice:
+ def test_the_detail_names_the_remedy(self) -> None:
+ assert "does not allow the model" in _rendered_detail(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
+
+ def test_the_advice_names_the_handle_and_not_the_wire_id(self) -> None:
+ """The substrate's message names only the backend's id, which the method's author never wrote."""
+ detail = _rendered_detail(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
+
+ assert f"'{_MODEL_NOT_ALLOWED_HANDLE}'" in detail
+ assert _MODEL_NOT_ALLOWED_WIRE_ID not in detail
+ assert "pick another model" in detail
+ assert "prompt" not in detail
+
+ def test_the_advice_offers_the_default_only_when_the_pipe_named_the_model(self) -> None:
+ """The Render step cannot tell a model the pipe named from the deck's default.
+
+ When the default is the refused model, an unconditional "leave the pipe's
+ model unset" would tell the caller to do what they already did.
+ """
+ detail = _rendered_detail(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
+
+ assert "if the pipe named this one, leaving its model unset uses the default" in detail
+
+ def test_the_advice_says_who_settles_a_deck_disagreement_on_either_kind_of_gateway(self) -> None:
+ """The same code comes from a hosted gateway and from a user's own Portkey workspace.
+
+ Nothing on the wire tells them apart, so advice that only said "contact
+ support" would send the owner of a Portkey workspace to support for a setting
+ in their own dashboard.
+ """
+ detail = _rendered_detail(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
+
+ assert "model deck" in detail
+ assert "on a hosted gateway, contact support" in detail
+ assert "on a Portkey workspace of your own, allow the model in the integration that serves it" in detail
+
+ def test_the_advice_reads_the_same_on_an_extract(self) -> None:
+ metadata = _envelope(MODEL_NOT_ALLOWED_ERROR_CODE)
+
+ assert _rendered_detail(metadata, family=InferenceErrorFamily.EXTRACT) == _rendered_detail(metadata)
+
+
+class TestWhatItAnswersOverHTTP:
+ def test_it_answers_500_as_an_unrecognized_412_does(self) -> None:
+ """At its real status the refusal's answer does not move: only its advice does.
+
+ The ladder's generic 4xx arm already reads a 412 as ``CONFIGURATION``, so
+ recognizing the code changes this refusal's ``user_action`` and nothing about
+ its status.
+ """
+ report = _rendered_error(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE)).to_error_report()
+ unrecognized_report = _rendered_error(_envelope("something-else")).to_error_report()
+
+ assert report.error_domain == ErrorDomain.CONFIG
+ assert report.http_status == 500
+ assert unrecognized_report.error_domain == ErrorDomain.CONFIG
+ assert unrecognized_report.http_status == 500
+
+
+class TestTheAdviceSurvivesThePipeBoundary:
+ def test_the_advice_reaches_the_caller_through_the_located_failure(self) -> None:
+ """The failure class is not re-raised by the pipe operator, so the router's location is the boundary.
+
+ ``PipeRouterError`` reports the root fault located at the failing pipe, with
+ the classification its cause chain carries. When nothing on the chain carried
+ a user action, that report would fall back to "the message gives the cause".
+ """
+ rendered = _rendered_error(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
+ located = PipeRouterError.make_located(
+ failure=rendered,
+ run_mode=PipeRunMode.LIVE,
+ pipe_code="score_lead",
+ output_name=None,
+ pipe_stack=["score_lead"],
+ )
+ located.__cause__ = rendered
+
+ report = located.to_error_report()
+
+ assert report.error_type == "LLMCompletionError"
+ assert report.error_domain == ErrorDomain.CONFIG
+ assert report.error_category == InferenceErrorCategory.CONFIGURATION
+ assert report.retryable is False
+ assert report.user_action is not None
+ assert report.user_action.kind == UserActionKind.CHANGE_MODEL
+ assert report.user_action_detail() == _rendered_detail(_envelope(MODEL_NOT_ALLOWED_ERROR_CODE))
diff --git a/tests/unit/pipelex/cogt/inference/test_service_error_vocabulary.py b/tests/unit/pipelex/cogt/inference/test_service_error_vocabulary.py
new file mode 100644
index 000000000..209806409
--- /dev/null
+++ b/tests/unit/pipelex/cogt/inference/test_service_error_vocabulary.py
@@ -0,0 +1,160 @@
+"""The classifier reads a contributed service error code ahead of the status ladder, and the renderer gives its advice.
+
+A service that refuses a request itself does so on statuses the ladder reads as a provider rejecting
+the prompt. Its plugin's contributed code decides instead: the category, the action and the advice
+are the entry's, and a model-not-found entry selects the family's `*ModelNotFoundError`. A process
+with no vocabulary, or a code nobody contributed, falls through to the ladder unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cogt.exceptions import ExtractJobFailureError, ExtractModelNotFoundError, InferenceErrorCategory, LLMCompletionError
+from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserActionKind
+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.cogt.inference.service_error_vocabulary import ServiceErrorCode, ServiceErrorVocabulary
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+_ACCESSOR = "pipelex.cogt.inference.error_classify.get_optional_service_error_vocabulary"
+
+_TOO_LARGE = ServiceErrorCode(
+ code="svc-too-large",
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail="The request was over the service's limit — send less.",
+)
+_UNKNOWN_MODEL = ServiceErrorCode(
+ code="svc-unknown-model",
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CHANGE_MODEL,
+ detail="The service does not serve that model.",
+ is_model_not_found=True,
+)
+_NOT_CONFIGURED = ServiceErrorCode(
+ code="svc-not-configured",
+ category=InferenceErrorCategory.CONFIGURATION,
+ user_action_kind=UserActionKind.CONTACT_SUPPORT,
+ detail="The service is not configured for this — contact support.",
+)
+
+
+def _vocabulary() -> ServiceErrorVocabulary:
+ return ServiceErrorVocabulary({entry.code: entry for entry in (_TOO_LARGE, _UNKNOWN_MODEL, _NOT_CONFIGURED)})
+
+
+def _metadata(*, status_code: int | None, code: str | None, message: str = "refused") -> ProviderErrorMetadata:
+ return ProviderErrorMetadata(
+ provider=ProviderName.GATEWAY,
+ sdk_exception_type="HTTPStatusError",
+ message=message,
+ status_code=status_code,
+ provider_error_code=code,
+ )
+
+
+class TestClassification:
+ @pytest.mark.parametrize("entry", [_TOO_LARGE, _UNKNOWN_MODEL, _NOT_CONFIGURED], ids=lambda entry: entry.code)
+ def test_a_contributed_code_decides_ahead_of_the_ladder(self, mocker: MockerFixture, entry: ServiceErrorCode) -> None:
+ mocker.patch(_ACCESSOR, return_value=_vocabulary())
+
+ classification = classify_inference_error(_metadata(status_code=400, code=entry.code))
+
+ assert classification.service_error_code == entry
+ assert classification.category == entry.category
+ assert classification.user_action_kind == entry.user_action_kind
+ assert classification.is_model_not_found == entry.is_model_not_found
+
+ def test_it_runs_ahead_of_the_quota_rules(self, mocker: MockerFixture) -> None:
+ """A 402 the quota rules would call billing is the service's own refusal when it carries a contributed code."""
+ mocker.patch(_ACCESSOR, return_value=_vocabulary())
+
+ classification = classify_inference_error(_metadata(status_code=402, code=_NOT_CONFIGURED.code))
+
+ assert classification.category == InferenceErrorCategory.CONFIGURATION
+ assert classification.user_action_kind == UserActionKind.CONTACT_SUPPORT
+
+ def test_a_code_nobody_contributed_takes_the_ladder(self, mocker: MockerFixture) -> None:
+ mocker.patch(_ACCESSOR, return_value=_vocabulary())
+
+ classification = classify_inference_error(_metadata(status_code=400, code="svc-unheard-of"))
+
+ assert classification.service_error_code is None
+ assert classification.category == InferenceErrorCategory.CONTENT
+ assert classification.user_action_kind == UserActionKind.CHANGE_INPUT
+
+ @pytest.mark.parametrize("vocabulary", [None, ServiceErrorVocabulary({})], ids=["no-vocabulary", "empty-vocabulary"])
+ def test_without_the_contribution_the_ladder_reads_the_status(self, mocker: MockerFixture, vocabulary: ServiceErrorVocabulary | None) -> None:
+ mocker.patch(_ACCESSOR, return_value=vocabulary)
+
+ classification = classify_inference_error(_metadata(status_code=400, code=_NOT_CONFIGURED.code))
+
+ assert classification.service_error_code is None
+ assert classification.category == InferenceErrorCategory.CONTENT
+
+ def test_a_statusless_failure_never_reads_the_vocabulary(self, mocker: MockerFixture) -> None:
+ """A transport failure carries no code a service rendered; it stays a transient network error."""
+ accessor = mocker.patch(_ACCESSOR, return_value=_vocabulary())
+ metadata = ProviderErrorMetadata(provider=ProviderName.GATEWAY, sdk_exception_type="ConnectTimeout", message="timed out")
+
+ classification = classify_inference_error(metadata)
+
+ assert classification.category == InferenceErrorCategory.TRANSIENT
+ accessor.assert_not_called()
+
+
+class TestRendering:
+ def test_the_entry_s_advice_is_rendered(self, mocker: MockerFixture) -> None:
+ mocker.patch(_ACCESSOR, return_value=_vocabulary())
+ metadata = _metadata(status_code=413, code=_TOO_LARGE.code, message="body over 10 MB")
+
+ error = render_inference_error(
+ metadata=metadata,
+ classification=classify_inference_error(metadata),
+ family=InferenceErrorFamily.LLM,
+ model_desc="some-model",
+ model_handle="some-model",
+ )
+
+ assert isinstance(error, LLMCompletionError)
+ assert error.user_action is not None
+ assert error.user_action.detail == _TOO_LARGE.detail
+ assert error.error_category == InferenceErrorCategory.CONTENT
+ assert "body over 10 MB" in str(error)
+
+ def test_a_model_not_found_entry_selects_the_family_s_not_found_class(self, mocker: MockerFixture) -> None:
+ mocker.patch(_ACCESSOR, return_value=_vocabulary())
+ metadata = _metadata(status_code=400, code=_UNKNOWN_MODEL.code)
+
+ error = render_inference_error(
+ metadata=metadata,
+ classification=classify_inference_error(metadata),
+ family=InferenceErrorFamily.EXTRACT,
+ model_desc="some-model",
+ model_handle="some-handle",
+ )
+
+ assert isinstance(error, ExtractModelNotFoundError)
+ assert error.user_action is not None
+ assert error.user_action.detail == _UNKNOWN_MODEL.detail
+
+ def test_an_entry_without_the_flag_renders_the_failure_class(self, mocker: MockerFixture) -> None:
+ mocker.patch(_ACCESSOR, return_value=_vocabulary())
+ metadata = _metadata(status_code=400, code=_NOT_CONFIGURED.code)
+
+ error = render_inference_error(
+ metadata=metadata,
+ classification=classify_inference_error(metadata),
+ family=InferenceErrorFamily.EXTRACT,
+ model_desc="some-model",
+ model_handle="some-handle",
+ )
+
+ assert isinstance(error, ExtractJobFailureError)
+ assert not isinstance(error, ExtractModelNotFoundError)
diff --git a/tests/unit/pipelex/plugins/test_service_error_codes_seam.py b/tests/unit/pipelex/plugins/test_service_error_codes_seam.py
new file mode 100644
index 000000000..1dadd7b51
--- /dev/null
+++ b/tests/unit/pipelex/plugins/test_service_error_codes_seam.py
@@ -0,0 +1,83 @@
+"""A plugin contributes the error codes its service emits; the registrar refuses a code claimed twice or one the runtime reads itself."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, cast
+
+import pytest
+
+from pipelex.cogt.exceptions import InferenceErrorCategory
+from pipelex.cogt.inference.error_classification import MODEL_NOT_ALLOWED_ERROR_CODE, UserActionKind
+from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorCode
+from pipelex.plugins.contract import PLUGIN_API_VERSION
+from pipelex.plugins.exceptions import DuplicateServiceErrorCodeError, ReservedServiceErrorCodeError
+from pipelex.plugins.plugin_group import PluginGroup
+from pipelex.plugins.registrar import PluginOrigin, PluginRegistrar
+from pipelex.runtime_hub import get_optional_service_error_vocabulary
+
+if TYPE_CHECKING:
+ from pipelex.system.configuration.configs import PipelexConfig
+
+
+def _make_registrar() -> PluginRegistrar:
+ return PluginRegistrar(config=cast("PipelexConfig", SimpleNamespace(runtime=SimpleNamespace(plugins=SimpleNamespace(disabled=[])))))
+
+
+def _entry(code: str) -> ServiceErrorCode:
+ return ServiceErrorCode(
+ code=code,
+ category=InferenceErrorCategory.CONTENT,
+ user_action_kind=UserActionKind.CHANGE_INPUT,
+ detail=f"advice for {code}",
+ )
+
+
+class TestServiceErrorCodesSeam:
+ def test_contributed_codes_are_stored_and_attributed(self) -> None:
+ registrar = _make_registrar()
+ discovery = registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)
+
+ registrar.add_service_error_codes(codes=[_entry("svc-01"), _entry("svc-02")])
+
+ assert set(registrar.service_error_codes) == {"svc-01", "svc-02"}
+ assert registrar.service_error_codes["svc-01"].detail == "advice for svc-01"
+ assert discovery.contributions == ["service error codes svc-01, svc-02"]
+
+ def test_a_code_two_plugins_contribute_fails_naming_both(self) -> None:
+ registrar = _make_registrar()
+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)
+ registrar.add_service_error_codes(codes=[_entry("svc-01")])
+ registrar.begin_plugin(name="beta", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)
+
+ with pytest.raises(DuplicateServiceErrorCodeError) as exc_info:
+ registrar.add_service_error_codes(codes=[_entry("svc-02"), _entry("svc-01")])
+
+ assert exc_info.value.code == "svc-01"
+ assert (exc_info.value.first_plugin, exc_info.value.second_plugin) == ("alpha", "beta")
+
+ def test_a_code_the_runtime_classifies_itself_is_refused(self) -> None:
+ registrar = _make_registrar()
+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=None)
+
+ with pytest.raises(ReservedServiceErrorCodeError) as exc_info:
+ registrar.add_service_error_codes(codes=[_entry(MODEL_NOT_ALLOWED_ERROR_CODE)])
+
+ assert exc_info.value.plugin == "alpha"
+ assert not registrar.service_error_codes
+
+ def test_a_kernel_group_plugin_may_contribute(self) -> None:
+ """The vocabulary is a kernel-layer contribution: classification runs in a kernel-only boot too."""
+ registrar = _make_registrar()
+ registrar.begin_plugin(name="alpha", origin=PluginOrigin.EXTERNAL, targets_api=PLUGIN_API_VERSION, group=PluginGroup.KERNEL)
+
+ registrar.add_service_error_codes(codes=[_entry("svc-01")])
+
+ assert "svc-01" in registrar.service_error_codes
+
+ def test_boot_installs_the_contributions_on_the_hub(self) -> None:
+ """The session's boot ran every builtin; the vocabulary it froze is the one classification reads."""
+ vocabulary = get_optional_service_error_vocabulary()
+
+ assert vocabulary is not None
+ assert MODEL_NOT_ALLOWED_ERROR_CODE not in vocabulary.codes
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py
index 9bd392ad8..8a36d8274 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py
@@ -21,6 +21,7 @@ _ANTHROPIC_LEVEL_MAP: dict[str, str] = {
def _make_worker(mocker: MockerFixture, thinking_mode: ThinkingMode) -> AnthropicLLMWorker:
"""Create a minimal AnthropicLLMWorker with a mocked inference_model."""
worker = object.__new__(AnthropicLLMWorker)
+ worker.extras_factory = None
mock_model = mocker.MagicMock()
mock_model.thinking_mode = thinking_mode
mock_model.desc = "test-model"
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py
index 3fa40b535..6c20b9cab 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py
@@ -46,6 +46,8 @@ def _make_worker(mocker: MockerFixture, *, structure_method: StructureMethod) ->
mocker.patch.object(sdk_client.messages, "create", new=create)
worker = object.__new__(AnthropicLLMWorker)
+
+ worker.extras_factory = None
model = mocker.MagicMock()
model.desc = "test-model-desc"
model.model_id = "claude-test"
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py
index 7d6db8b6c..2b5b03e21 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_error_handling.py
@@ -64,6 +64,7 @@ def _make_anthropic_not_found_error(message: str) -> anthropic.NotFoundError:
def _make_worker(mocker: MockerFixture) -> AnthropicLLMWorker:
"""Create a minimal AnthropicLLMWorker with mocked internals."""
worker = object.__new__(AnthropicLLMWorker)
+ worker.extras_factory = None
mock_model = mocker.MagicMock()
mock_model.desc = "test-model-desc"
mock_model.model_id = "claude-sonnet-4-20250514"
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py
index 6e7d5d039..e23471b06 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_worker_object_error_handling.py
@@ -67,6 +67,7 @@ def _make_anthropic_not_found_error(message: str) -> anthropic.NotFoundError:
def _make_worker(mocker: MockerFixture) -> AnthropicLLMWorker:
worker = object.__new__(AnthropicLLMWorker)
+ worker.extras_factory = None
mock_model = mocker.MagicMock()
mock_model.desc = "test-model-desc"
mock_model.model_id = "claude-sonnet-4-20250514"
diff --git a/tests/unit/pipelex/providers/manifold/conftest.py b/tests/unit/pipelex/providers/manifold/conftest.py
new file mode 100644
index 000000000..99bd19843
--- /dev/null
+++ b/tests/unit/pipelex/providers/manifold/conftest.py
@@ -0,0 +1,21 @@
+"""Fixtures shared by the Manifold provider's unit tests."""
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorVocabulary
+from pipelex.providers.manifold.manifold_error_codes import MANIFOLD_SERVICE_ERROR_CODES
+
+
[email protected](autouse=True)
+def manifold_service_error_vocabulary(mocker: MockerFixture) -> ServiceErrorVocabulary:
+ """Hand the classifier the vocabulary the Manifold plugin contributes, as a booted runtime has it.
+
+ The Manifold service's own refusal codes are classified only because the plugin contributes them
+ through the service error vocabulary, so every test here classifies against exactly that
+ vocabulary, stated rather than inherited from whatever the session's boot registered. A test that
+ needs the status ladder alone patches the same accessor to return ``None``.
+ """
+ vocabulary = ServiceErrorVocabulary({entry.code: entry for entry in MANIFOLD_SERVICE_ERROR_CODES})
+ mocker.patch("pipelex.cogt.inference.error_classify.get_optional_service_error_vocabulary", return_value=vocabulary)
+ return vocabulary
diff --git a/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py b/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py
index 58b8a91c9..09a2023ce 100644
--- a/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py
+++ b/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py
@@ -16,7 +16,7 @@ from __future__ import annotations
import httpx
-from pipelex.cogt.inference.error_classification import extract_manifold_metadata
+from pipelex.providers.manifold.manifold_error_metadata import extract_manifold_metadata
_ORIGIN = "https://manifold.example.com"
diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_metadata_scope.py b/tests/unit/pipelex/providers/manifold/test_manifold_metadata_scope.py
index 144915235..e69d00297 100644
--- a/tests/unit/pipelex/providers/manifold/test_manifold_metadata_scope.py
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_metadata_scope.py
@@ -2,8 +2,9 @@
The run's identity and the host's labels are forwarded to our own gateway, which bills and logs the
call; a vendor reached directly with the caller's own key has no use for them and must not receive
-them. The shared Anthropic driver is the path most at risk, because it serves both a direct Anthropic
-backend and Claude behind Manifold from the same code.
+them. The Anthropic worker is the path most at risk, because it serves both a direct Anthropic
+backend and Claude behind Manifold from the same code: only the extras factory the manifold package
+builds it with adds the header, so a worker built without one sends nothing, whatever its backend.
"""
from __future__ import annotations
@@ -62,6 +63,7 @@ def _anthropic_worker(mocker: MockerFixture, *, sdk_client: AsyncAnthropic, back
worker = object.__new__(AnthropicLLMWorker)
worker.inference_model = _model(mocker, backend_name=backend_name)
+ worker.extras_factory = None
worker.default_max_tokens = 4096
worker.anthropic_async_client = sdk_client
worker.instructor_for_objects = from_anthropic(client=sdk_client, mode=StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS.as_instructor_mode())
@@ -104,8 +106,8 @@ class TestManifoldMetadataScope:
assert MANIFOLD_METADATA_HEADER not in extra_headers
assert "x-portkey-metadata" not in extra_headers
- @pytest.mark.parametrize("backend_name", ["anthropic", "bedrock"])
- async def test_direct_claude_sends_no_headers_on_the_text_call(self, mocker: MockerFixture, backend_name: str) -> None:
+ @pytest.mark.parametrize("backend_name", ["anthropic", "bedrock", "pipelex_manifold"])
+ async def test_a_plain_anthropic_worker_sends_no_headers_on_the_text_call(self, mocker: MockerFixture, backend_name: str) -> None:
sdk_client = AsyncAnthropic(api_key="test-key")
stream = mocker.MagicMock(side_effect=_RequestCapturedError)
mocker.patch.object(sdk_client.messages, "stream", new=stream)
@@ -116,11 +118,12 @@ class TestManifoldMetadataScope:
assert "extra_headers" not in stream.call_args.kwargs
- async def test_direct_claude_sends_no_headers_on_the_structured_call(self, mocker: MockerFixture) -> None:
+ @pytest.mark.parametrize("backend_name", ["anthropic", "pipelex_manifold"])
+ async def test_a_plain_anthropic_worker_sends_no_headers_on_the_structured_call(self, mocker: MockerFixture, backend_name: str) -> None:
sdk_client = AsyncAnthropic(api_key="test-key")
create = mocker.AsyncMock(return_value=_tool_call_message())
mocker.patch.object(sdk_client.messages, "create", new=create)
- worker = _anthropic_worker(mocker, sdk_client=sdk_client, backend_name="anthropic")
+ worker = _anthropic_worker(mocker, sdk_client=sdk_client, backend_name=backend_name)
await worker._gen_object(_llm_job(), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_metadata_sdk_paths.py b/tests/unit/pipelex/providers/manifold/test_manifold_metadata_sdk_paths.py
index 922bc06cb..40021e8b8 100644
--- a/tests/unit/pipelex/providers/manifold/test_manifold_metadata_sdk_paths.py
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_metadata_sdk_paths.py
@@ -4,7 +4,7 @@ The header differs per job, so it cannot be a client default: each path adds it
each is pinned here where the request leaves the runtime — the kwargs handed to the SDK call, or the
headers handed to `httpx` on the native routes. The paths are the OpenAI-substrate chat completions
(text, and image generation over completions) and responses, the vendor-SDK image path, the native
-extract and search routes, and Claude over the shared Anthropic driver behind the manifold backend.
+extract and search routes, and Claude over the Anthropic worker the package registers as `manifold_anthropic`.
"""
from __future__ import annotations
@@ -22,6 +22,7 @@ from pipelex.cogt.llm.llm_prompt import LLMPrompt
from pipelex.cogt.llm.structured_output import StructureMethod
from pipelex.cogt.model_backends.backend import InferenceBackend, PipelexBackend
from pipelex.providers.anthropic.anthropic_llm_worker import AnthropicLLMWorker
+from pipelex.providers.manifold.manifold_anthropic_extras import ManifoldAnthropicExtrasFactory
from pipelex.providers.manifold.manifold_completions_factory import ManifoldCompletionsFactory
from pipelex.providers.manifold.manifold_constants import MANIFOLD_METADATA_HEADER
from pipelex.providers.manifold.manifold_extract_worker import ManifoldExtractWorker
@@ -82,6 +83,7 @@ def _anthropic_worker(mocker: MockerFixture, *, sdk_client: AsyncAnthropic, back
model = _model(mocker, backend_name=backend_name, model_id="claude-test")
model.structure_method = StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS
worker.inference_model = model
+ worker.extras_factory = ManifoldAnthropicExtrasFactory()
worker.default_max_tokens = 4096
worker.instructor_for_objects = from_anthropic(client=sdk_client, mode=StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS.as_instructor_mode())
config = mocker.MagicMock()
diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.py b/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.py
index 071a80229..40697dca4 100644
--- a/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.py
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_plugin_registrations.py
@@ -9,25 +9,33 @@ 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.
+`model_type = "img_gen"` while leaving them on the default completions sdk. And Claude has a token of
+its own, `manifold_anthropic`, rather than the plain `anthropic` the open Anthropic plugin owns: it is
+the same worker built with the package's extras factory, which is what adds the metadata header.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
+from anthropic import AsyncAnthropic
+
+from pipelex.cogt.model_backends.backend import InferenceBackend
from pipelex.plugins.inference_backend_registry import InferenceFamily
+from pipelex.plugins.model_handle import ModelHandle
from pipelex.plugins.registrar import PluginRegistrar
+from pipelex.providers.anthropic.anthropic_llm_worker import AnthropicLLMWorker
from pipelex.providers.builtins import KERNEL_BUILTIN_PLUGINS
+from pipelex.providers.manifold.manifold_anthropic_extras import ManifoldAnthropicExtrasFactory
from pipelex.providers.manifold.manifold_plugin import ManifoldPlugin
if TYPE_CHECKING:
+ from collections.abc import Callable
+
from pytest_mock import MockerFixture
_EXPECTED_KEYS = {
+ (InferenceFamily.LLM, "manifold_anthropic"),
(InferenceFamily.LLM, "manifold_completions"),
(InferenceFamily.LLM, "manifold_responses"),
(InferenceFamily.IMG_GEN, "manifold_img_gen"),
@@ -37,6 +45,11 @@ _EXPECTED_KEYS = {
}
+def _build_now(*, handle: object, build: Callable[[], object]) -> object:
+ del handle
+ return build()
+
+
def _registrar(mocker: MockerFixture) -> PluginRegistrar:
return PluginRegistrar(config=mocker.MagicMock())
@@ -49,13 +62,32 @@ class TestManifoldPluginRegistrations:
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."""
+ def test_the_plain_anthropic_sdk_is_not_claimed(self, mocker: MockerFixture) -> None:
+ """The open Anthropic plugin owns `anthropic`; claiming it here would fail the boot on a duplicate."""
registrar = _registrar(mocker)
ManifoldPlugin().register(registrar)
- assert not any("anthropic" in sdk for _, sdk in registrar.inference_backends)
+ assert all(sdk.startswith("manifold_") for _, sdk in registrar.inference_backends)
+
+ def test_claude_is_built_with_the_metadata_extras_factory(self, mocker: MockerFixture) -> None:
+ registrar = _registrar(mocker)
+ ManifoldPlugin().register(registrar)
+ make_worker = registrar.inference_backends[InferenceFamily.LLM, "manifold_anthropic"]
+ model = mocker.MagicMock()
+ model.sdk = "manifold_anthropic"
+ model.max_tokens = 4096
+ model.get_instructor_mode.return_value = None
+ backend = InferenceBackend(name="pipelex_manifold", endpoint="https://manifold.example.com", api_key="token")
+ sdk_clients = mocker.MagicMock()
+ sdk_clients.get_or_create.side_effect = _build_now
+ mocker.patch.object(ModelHandle, "make_for_inference_model", return_value=mocker.MagicMock(sdk="manifold_anthropic"))
+
+ worker = make_worker(inference_model=model, backend=backend, sdk_clients=sdk_clients, reporting_delegate=None)
+
+ assert isinstance(worker, AnthropicLLMWorker)
+ assert isinstance(worker.extras_factory, ManifoldAnthropicExtrasFactory)
+ assert isinstance(worker.anthropic_async_client, AsyncAnthropic)
def test_the_plugin_is_a_kernel_builtin(self) -> None:
"""Registered beside the gateway plugin, so a manifold-declared backend needs no plugin install."""
diff --git a/tests/unit/pipelex/cogt/inference/test_gateway_request_limits.py b/tests/unit/pipelex/providers/manifold/test_manifold_request_limits.py
similarity index 81%
rename from tests/unit/pipelex/cogt/inference/test_gateway_request_limits.py
rename to tests/unit/pipelex/providers/manifold/test_manifold_request_limits.py
index db1c6008f..67f5857a3 100644
--- a/tests/unit/pipelex/cogt/inference/test_gateway_request_limits.py
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_request_limits.py
@@ -1,24 +1,29 @@
-"""The gateway's request-shape refusals, from the wire code to the rendered advice.
+"""The Manifold service'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
+The Pipelex Manifold service 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.
+These codes are the service's wire contract, so the Manifold plugin owns them: each
+is a ``GatewayRequestLimit`` member in ``manifold_error_codes``, contributed as one
+entry of the service error vocabulary that ``classify_inference_error`` consults
+ahead of the status ladder. Without that entry the Classify step falls through to
+the generic 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 in the vocabulary under the right member, 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 package's
+``conftest.py`` hands the classifier the Manifold vocabulary.
**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.
+the service's own code namespaces, which is why the vocabulary matches 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``
@@ -31,7 +36,7 @@ to classify alike.
from __future__ import annotations
import json
-from typing import Any
+from typing import TYPE_CHECKING, Any
import anthropic
import httpx
@@ -41,17 +46,25 @@ 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_classify import ClassificationResult, classify_inference_error
from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error
from pipelex.cogt.inference.provider_name import ProviderName
+from pipelex.providers.manifold.manifold_error_codes import (
+ _GATEWAY_REQUEST_LIMIT_BY_CODE, # pyright: ignore[reportPrivateUsage]
+ GatewayRequestLimit,
+)
+from pipelex.providers.manifold.manifold_error_metadata import extract_manifold_metadata
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+ from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorVocabulary
_ORIGIN = "https://manifold.example.com"
@@ -131,8 +144,18 @@ def _envelope(code: str | None, *, status_code: int, provider: ProviderName = Pr
)
+def _request_limit(code: str | None) -> GatewayRequestLimit | None:
+ """The family member a wire code names, if it names one."""
+ return _GATEWAY_REQUEST_LIMIT_BY_CODE.get(code) if code is not None else None
+
+
+def _classified_limit(result: ClassificationResult) -> GatewayRequestLimit | None:
+ """The family member the classifier matched the refusal to, read off the vocabulary entry it carries."""
+ return _request_limit(result.service_error_code.code) if result.service_error_code is not None else None
+
+
class TestTheCodeIsRecognized:
- """``gateway_request_limit`` reads the gateway's own code namespace off the envelope."""
+ """Each code is in the Manifold vocabulary, under the family member that names its limit."""
@pytest.mark.parametrize(
("code", "expected"),
@@ -143,18 +166,24 @@ class TestTheCodeIsRecognized:
("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
+ def test_each_limit_code_maps_to_its_kind(
+ self, code: str, expected: GatewayRequestLimit, manifold_service_error_vocabulary: ServiceErrorVocabulary
+ ) -> None:
+ assert _request_limit(code) == expected
+ assert manifold_service_error_vocabulary.lookup(code=code) is not None
@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
+ assert _request_limit(code) is None
+ assert _classified_limit(classify_inference_error(_envelope(code, status_code=400))) 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
+ result = classify_inference_error(_envelope("pig-07", status_code=413, provider=provider))
+
+ assert _classified_limit(result) == GatewayRequestLimit.BODY_TOO_LARGE
class TestTheCodeSurvivesEveryExtractHop:
@@ -166,7 +195,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_gateway_metadata(exc)
assert metadata.provider_error_code == "pig-07"
- assert metadata.gateway_request_limit == GatewayRequestLimit.BODY_TOO_LARGE
+ assert _request_limit(metadata.provider_error_code) == 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.
@@ -179,7 +208,7 @@ class TestTheCodeSurvivesEveryExtractHop:
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
+ assert _request_limit(extract_gateway_metadata(exc).provider_error_code) == 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."""
@@ -188,7 +217,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_gateway_metadata(exc)
assert metadata.provider_error_code == "pig-08"
- assert metadata.gateway_request_limit == GatewayRequestLimit.BODY_LENGTH_REQUIRED
+ assert _request_limit(metadata.provider_error_code) == GatewayRequestLimit.BODY_LENGTH_REQUIRED
def test_through_plain_httpx_on_the_native_routes(self) -> None:
request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")
@@ -198,7 +227,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_manifold_metadata(exc)
assert metadata.provider_error_code == "pig-11"
- assert metadata.gateway_request_limit == GatewayRequestLimit.BODY_TOO_DEEP
+ assert _request_limit(metadata.provider_error_code) == GatewayRequestLimit.BODY_TOO_DEEP
def test_through_the_shared_anthropic_driver(self) -> None:
request = httpx.Request("POST", f"{_ORIGIN}/v1/messages")
@@ -208,7 +237,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_anthropic_metadata(exc)
assert metadata.provider_error_code == "pig-10"
- assert metadata.gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE
+ assert _request_limit(metadata.provider_error_code) == GatewayRequestLimit.OBJECT_TOO_LARGE
@pytest.mark.parametrize(
("body", "expected"),
@@ -218,7 +247,7 @@ class TestTheCodeSurvivesEveryExtractHop:
],
)
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.
+ """The hop a gateway or manifold LLM call actually takes.
Both plugins build an ``OpenAICompletionsLLMWorker`` over a client pointed
at the service, so a chat-route refusal is distilled by
@@ -232,7 +261,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_openai_metadata(exc)
- assert metadata.gateway_request_limit == expected
+ assert _request_limit(metadata.provider_error_code) == expected
class TestClassification:
@@ -263,7 +292,7 @@ class TestClassification:
) -> None:
result = classify_inference_error(_envelope(code, status_code=status_code))
- assert result.gateway_request_limit == expected_limit
+ assert _classified_limit(result) == expected_limit
assert result.category == expected_category
assert result.user_action_kind == expected_action
assert result.category.is_retryable is False
@@ -273,9 +302,18 @@ class TestClassification:
"""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 _classified_limit(result) is None
assert result.category == InferenceErrorCategory.CONFIGURATION
+ def test_without_the_manifold_vocabulary_the_code_is_left_to_the_status_ladder(self, mocker: MockerFixture) -> None:
+ """The codes classify only because the plugin contributes them: a runtime without it reads the bare status."""
+ mocker.patch("pipelex.cogt.inference.error_classify.get_optional_service_error_vocabulary", return_value=None)
+
+ result = classify_inference_error(_envelope("pig-07", status_code=413))
+
+ assert result.service_error_code is None
+ assert result.user_action_kind == UserActionKind.CHANGE_INPUT
+
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))
@@ -367,7 +405,7 @@ class TestTheSameLimitOnTheNativeRoutes:
result = classify_inference_error(metadata)
assert metadata.provider_error_code == code
- assert result.gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE
+ assert _classified_limit(result) == GatewayRequestLimit.OBJECT_TOO_LARGE
assert result.category == InferenceErrorCategory.CONTENT
assert result.category.is_retryable is False
@@ -391,7 +429,7 @@ class TestTheSameLimitOnTheNativeRoutes:
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.
+ """Where the response fallback and the code-first precedence 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
@@ -417,7 +455,7 @@ class TestTheSameLimitOnTheNativeRoutes:
result = classify_inference_error(metadata)
assert metadata.provider_error_code == "pipelex_document_too_large"
- assert result.gateway_request_limit == GatewayRequestLimit.OBJECT_TOO_LARGE
+ assert _classified_limit(result) == GatewayRequestLimit.OBJECT_TOO_LARGE
assert result.category.is_retryable is False
def test_the_generic_type_does_not_shadow_the_contract_code(self) -> None:
@@ -436,4 +474,4 @@ class TestTheSameLimitOnTheNativeRoutes:
metadata = extract_manifold_metadata(exc)
assert metadata.provider_error_code == "pipelex_document_host_refused"
- assert metadata.gateway_request_limit is None
+ assert _request_limit(metadata.provider_error_code) is None
diff --git a/tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py b/tests/unit/pipelex/providers/manifold/test_manifold_routing_refusals.py
similarity index 63%
rename from tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py
rename to tests/unit/pipelex/providers/manifold/test_manifold_routing_refusals.py
index c069711bd..150aa0255 100644
--- a/tests/unit/pipelex/cogt/inference/test_gateway_routing_refusals.py
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_routing_refusals.py
@@ -1,30 +1,34 @@
-"""The gateway's routing refusals, from the wire code to the rendered advice.
+"""The Manifold service'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
+Before a request can reach a provider the Pipelex Manifold service 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. One more comes from the Portkey substrate the gateway is built on
-rather than from the ``pig-`` namespace: ``model_not_allowed_error``, which its
-middleware answers when an integration serves the model but does not allow it for
-this caller, because the model is off the integration's allow-list or archived.
-
-Every ``pig-`` code 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. ``model_not_allowed_error`` answers 412, which the
-ladder's generic 4xx arm already read as a configuration problem, but with the
-same advice to review the prompt. 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.
+does not serve.
+
+These codes are the service's wire contract, so the Manifold plugin owns them: each
+is a ``GatewayRoutingRefusal`` member in ``manifold_error_codes``, contributed as one
+entry of the service error vocabulary that ``classify_inference_error`` consults
+ahead of the status ladder (the package's ``conftest.py`` hands the classifier that
+vocabulary). Every ``pig-`` code answers HTTP 400, so without its entry 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 produces
+when the model deck itself cannot find a model. These tests pin the whole chain:
+the code is in the vocabulary under the right member, 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 answers, and the advice surviving the pipe layer's re-raise.
+
+``model_not_allowed_error``, the Portkey substrate's answer for a model an
+integration serves but does not allow for this caller, is not one of the service's
+codes and not in its vocabulary: the runtime reads it in core, and
+``tests/unit/pipelex/cogt/inference/test_model_not_allowed.py`` pins it.
**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
@@ -34,30 +38,24 @@ families, and each of these names a different thing that has to change.
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
+service. 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. The same holds for ``model_not_allowed_error``: the
-model exists and an integration serves it, only not for this caller.
-
-**``model_not_allowed_error`` is the one member whose advice names the model.**
-The rest defer every specific to the gateway's own message, but that message names
-only the backend's wire id, which the method's author never wrote. So the advice
-names the model handle the deck resolved the pipe's model to.
+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
+is the service 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
+by a client talking to a Pipelex-operated service: ``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
+manifold clients against by name, and ``pig-04`` refuses a path the service 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
+than implied here: that test names four headers while the service 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.
@@ -65,7 +63,7 @@ Portkey's cloud reads and one of our gateways would refuse.
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
+the service: 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
@@ -87,25 +85,32 @@ 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,
+ MODEL_NOT_ALLOWED_ERROR_CODE,
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_classify import ClassificationResult, 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.pipe_run.exceptions import PipeRouterError
+from pipelex.providers.manifold.manifold_error_codes import (
+ _GATEWAY_REQUEST_LIMIT_BY_CODE, # pyright: ignore[reportPrivateUsage]
+ _GATEWAY_ROUTING_REFUSAL_BY_CODE, # pyright: ignore[reportPrivateUsage]
+ _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE, # pyright: ignore[reportPrivateUsage]
+ MANIFOLD_SERVICE_ERROR_CODES,
+ GatewayRoutingRefusal,
+)
+from pipelex.providers.manifold.manifold_error_metadata import extract_manifold_metadata
from pipelex.system.pipe_run_mode import PipeRunMode
if TYPE_CHECKING:
- from collections.abc import Callable
+ from pytest_mock import MockerFixture
+
+ from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorVocabulary
_ORIGIN = "https://manifold.example.com"
@@ -117,16 +122,11 @@ _EVERY_CODE_AND_MEMBER: list[tuple[str, GatewayRoutingRefusal]] = [
("pig-02", GatewayRoutingRefusal.DISABLED_INTEGRATION),
("pig-05", GatewayRoutingRefusal.WRONG_PROTOCOL),
("pig-06", GatewayRoutingRefusal.UNSERVED_CAPABILITY),
- ("model_not_allowed_error", GatewayRoutingRefusal.MODEL_NOT_ALLOWED),
]
# 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]
-# The members the gateway renders in its own fail-closed envelope, the ``pig-`` ones.
-_FAIL_CLOSED_CODES_AND_MEMBERS: list[tuple[str, GatewayRoutingRefusal]] = [pair for pair in _EVERY_CODE_AND_MEMBER if pair[0].startswith("pig-")]
-_FAIL_CLOSED_CODES: list[str] = [pair[0] for pair in _FAIL_CLOSED_CODES_AND_MEMBERS]
-
# 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]
@@ -154,23 +154,6 @@ def _fail_closed_refusal_body(message: str, code: str) -> dict[str, Any]:
_UNKNOWN_MODEL_BODY = _fail_closed_refusal_body("No model found for the request", "pig-01")
-# The backend's id for the model, which is all the gateway's own message names, and
-# the handle the deck resolved the method's model to, which is the deck's own name for it.
-_MODEL_NOT_ALLOWED_WIRE_ID = "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
-_MODEL_NOT_ALLOWED_HANDLE = "claude-4.5-sonnet"
-
-# The body the Portkey middleware answers with, at HTTP 412, verbatim as a run on the
-# hosted API received it. Unlike the fail-closed envelope, the code sits in ``type``
-# and ``code`` is null.
-_MODEL_NOT_ALLOWED_BODY: dict[str, Any] = {
- "error": {
- "message": f"Model {_MODEL_NOT_ALLOWED_WIRE_ID} is not allowed for this integration",
- "type": "model_not_allowed_error",
- "param": None,
- "code": None,
- }
-}
-
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.
@@ -209,30 +192,6 @@ def _as_the_openai_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> B
return client._make_status_error_from_response(response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
-def _as_the_anthropic_sdk_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:
- """Build the exception through the Anthropic SDK's own factory, the hop Claude travels on.
-
- For a status it has no subclass for, 412 among them, the factory returns a plain
- ``APIStatusError``, which a hand-built ``BadRequestError`` would not show.
- """
- request = httpx.Request("POST", f"{_ORIGIN}/v1/messages")
- response = httpx.Response(
- status_code=status_code,
- request=request,
- content=json.dumps(body).encode(),
- headers={"content-type": "application/json"},
- )
- client = anthropic.AsyncAnthropic(api_key="unused-in-this-test", base_url=_ORIGIN)
- return client._make_status_error_from_response(response) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
-
-
-def _as_plain_httpx_raises_it(*, status_code: int, body: dict[str, Any]) -> BaseException:
- """The manifold's native ``/v1/pipelex/*`` routes, which the runtime calls over plain ``httpx``."""
- request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")
- response = httpx.Response(status_code=status_code, request=request, json=body)
- return httpx.HTTPStatusError(f"Client error '{status_code}'", request=request, response=response)
-
-
def _envelope(code: str | None, *, status_code: int = 400, provider: ProviderName = ProviderName.GATEWAY) -> ProviderErrorMetadata:
return ProviderErrorMetadata(
provider=provider,
@@ -243,6 +202,21 @@ def _envelope(code: str | None, *, status_code: int = 400, provider: ProviderNam
)
+def _routing_refusal(code: str | None) -> GatewayRoutingRefusal | None:
+ """The family member a wire code names, if it names one."""
+ return _GATEWAY_ROUTING_REFUSAL_BY_CODE.get(code) if code is not None else None
+
+
+def _in_another_family(code: str | None) -> bool:
+ """Whether a wire code names a request-shape limit or an unresolvable reference."""
+ return code in _GATEWAY_REQUEST_LIMIT_BY_CODE or code in _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE
+
+
+def _classified_code(result: ClassificationResult) -> str | None:
+ """The wire code of the vocabulary entry the classifier matched, if it matched one."""
+ return result.service_error_code.code if result.service_error_code is not None else None
+
+
def _rendered_error(
metadata: ProviderErrorMetadata,
*,
@@ -253,7 +227,7 @@ def _rendered_error(
metadata=metadata,
classification=classify_inference_error(metadata),
family=family,
- model_desc=f"{model_handle} → Model[{_MODEL_NOT_ALLOWED_WIRE_ID}]",
+ model_desc=f"{model_handle} → Model[some-wire-id]",
model_handle=model_handle,
)
@@ -270,11 +244,14 @@ def _rendered_detail(
class TestTheCodeIsRecognized:
- """``gateway_routing_refusal`` reads the gateway's own code namespace off the envelope."""
+ """Each code is in the Manifold vocabulary, under the family member that names the routing decision."""
@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
+ def test_each_code_maps_to_its_member(
+ self, code: str, expected: GatewayRoutingRefusal, manifold_service_error_vocabulary: ServiceErrorVocabulary
+ ) -> None:
+ assert _routing_refusal(code) == expected
+ assert manifold_service_error_vocabulary.lookup(code=code) is not None
@pytest.mark.parametrize("member", list(GatewayRoutingRefusal))
def test_every_member_is_reachable_from_a_wire_code(self, member: GatewayRoutingRefusal) -> None:
@@ -303,22 +280,27 @@ class TestTheCodeIsRecognized:
"model_not_found",
"model_not_allowed",
"MODEL_NOT_ALLOWED_ERROR",
+ MODEL_NOT_ALLOWED_ERROR_CODE,
"",
],
)
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
+ """The request-shape limits, the unresolvable references, the substrate's own refusal and a vendor's code are all other families."""
+ assert _routing_refusal(code) is None
+ assert _routing_refusal(_classified_code(classify_inference_error(_envelope(code)))) is None
+
+ def test_the_substrates_model_not_allowed_refusal_is_not_the_services_to_contribute(
+ self, manifold_service_error_vocabulary: ServiceErrorVocabulary
+ ) -> None:
+ """Core reads ``model_not_allowed_error`` itself, so the Manifold vocabulary must not claim it too."""
+ assert manifold_service_error_vocabulary.lookup(code=MODEL_NOT_ALLOWED_ERROR_CODE) is None
@pytest.mark.parametrize("provider", list(ProviderName))
- @pytest.mark.parametrize(
- ("code", "expected"), [("pig-01", GatewayRoutingRefusal.UNKNOWN_MODEL), ("model_not_allowed_error", GatewayRoutingRefusal.MODEL_NOT_ALLOWED)]
- )
- def test_the_code_is_read_whichever_provider_reported_it(self, provider: ProviderName, code: str, expected: GatewayRoutingRefusal) -> None:
- """Claude reaches the gateway on the Anthropic driver, so the refusal is not always reported as GATEWAY."""
- metadata = _envelope(code, provider=provider)
+ def test_the_code_is_read_whichever_provider_reported_it(self, provider: ProviderName) -> None:
+ """Claude reaches the service on the Anthropic driver, so the refusal is not always reported as GATEWAY."""
+ result = classify_inference_error(_envelope("pig-01", provider=provider))
- assert metadata.gateway_routing_refusal == expected
+ assert _routing_refusal(_classified_code(result)) == GatewayRoutingRefusal.UNKNOWN_MODEL
class TestTheCodeSurvivesEveryExtractHop:
@@ -330,7 +312,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_gateway_metadata(exc)
assert metadata.provider_error_code == "pig-01"
- assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNKNOWN_MODEL
+ assert _routing_refusal(metadata.provider_error_code) == 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.
@@ -343,9 +325,9 @@ class TestTheCodeSurvivesEveryExtractHop:
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
+ assert _routing_refusal(extract_gateway_metadata(exc).provider_error_code) == GatewayRoutingRefusal.UNKNOWN_MODEL
- @pytest.mark.parametrize(("code", "expected"), _FAIL_CLOSED_CODES_AND_MEMBERS)
+ @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.
@@ -356,7 +338,7 @@ class TestTheCodeSurvivesEveryExtractHop:
"""
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
+ assert _routing_refusal(extract_openai_metadata(exc).provider_error_code) == expected
def test_through_plain_httpx_on_the_native_routes(self) -> None:
"""Where ``pig-06`` is actually raised: ``/v1/pipelex/extract`` and its siblings.
@@ -372,7 +354,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_manifold_metadata(exc)
assert metadata.provider_error_code == "pig-06"
- assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNSERVED_CAPABILITY
+ assert _routing_refusal(metadata.provider_error_code) == 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."""
@@ -383,36 +365,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_anthropic_metadata(exc)
assert metadata.provider_error_code == "pig-01"
- assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.UNKNOWN_MODEL
-
- @pytest.mark.parametrize(
- ("raise_it", "extract"),
- [
- pytest.param(_as_the_openai_sdk_raises_it, extract_openai_metadata, id="openai-substrate"),
- pytest.param(_as_the_anthropic_sdk_raises_it, extract_anthropic_metadata, id="anthropic-driver"),
- pytest.param(_as_the_portkey_sdk_raises_it, extract_gateway_metadata, id="portkey-substrate"),
- pytest.param(_as_plain_httpx_raises_it, extract_manifold_metadata, id="native-routes-httpx"),
- ],
- )
- def test_the_model_not_allowed_refusal_through_every_hop(
- self,
- raise_it: Callable[..., BaseException],
- extract: Callable[[BaseException], ProviderErrorMetadata],
- ) -> None:
- """The substrate's own envelope, at 412, through each SDK's own factory.
-
- Its code sits in ``type`` with ``code`` null, the inverse of the fail-closed
- envelope. The two vendor-facing hops read ``type`` first; the two
- Pipelex-service hops read ``code`` first and fall back to ``type``, which is
- the fallback this case exercises.
- """
- exc = raise_it(status_code=412, body=_MODEL_NOT_ALLOWED_BODY)
-
- metadata = extract(exc)
-
- assert metadata.status_code == 412
- assert metadata.provider_error_code == "model_not_allowed_error"
- assert metadata.gateway_routing_refusal == GatewayRoutingRefusal.MODEL_NOT_ALLOWED
+ assert _routing_refusal(metadata.provider_error_code) == 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.
@@ -442,7 +395,7 @@ class TestTheCodeSurvivesEveryExtractHop:
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
+ assert _classified_code(classify_inference_error(metadata)) is None
class TestClassification:
@@ -452,11 +405,10 @@ class TestClassification:
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 _classified_code(result) == code
+ assert _routing_refusal(_classified_code(result)) == 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:
@@ -468,7 +420,7 @@ class TestClassification:
"""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 _routing_refusal(_classified_code(result)) == GatewayRoutingRefusal.DISABLED_INTEGRATION
assert result.user_action_kind == UserActionKind.CONTACT_SUPPORT
assert result.is_model_not_found is False
@@ -483,33 +435,22 @@ class TestClassification:
assert result.is_model_not_found is (code == "pig-01")
- def test_a_model_not_allowed_refusal_asks_for_another_model_and_is_not_a_missing_model(self) -> None:
- """The model exists and an integration serves it, only not for this caller.
-
- So ``CHANGE_MODEL`` is what the caller can do, and the flag stays unset for
- the reason it does on ``pig-05`` and ``pig-06``: "not found" would be false.
- """
- result = classify_inference_error(_envelope("model_not_allowed_error", status_code=412))
-
- assert result.gateway_routing_refusal == GatewayRoutingRefusal.MODEL_NOT_ALLOWED
- assert result.category == InferenceErrorCategory.CONFIGURATION
- assert result.category.is_retryable is False
- assert result.user_action_kind == UserActionKind.CHANGE_MODEL
- assert result.is_model_not_found is False
-
- def test_a_412_without_a_recognized_code_still_takes_the_status_ladder(self) -> None:
- """The contrast: the ladder's generic 4xx arm, which is what the refusal used to read as."""
- result = classify_inference_error(_envelope("something-else", status_code=412))
-
- assert result.gateway_routing_refusal is None
- assert result.category == InferenceErrorCategory.CONFIGURATION
- assert result.user_action_kind == UserActionKind.CHANGE_INPUT
-
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.service_error_code is None
+ assert result.category == InferenceErrorCategory.CONTENT
+ assert result.user_action_kind == UserActionKind.CHANGE_INPUT
+
+ def test_without_the_manifold_vocabulary_an_unserved_model_is_a_plain_400(self, mocker: MockerFixture) -> None:
+ """The family classifies only because the plugin contributes it: a runtime without it reads the bare status."""
+ mocker.patch("pipelex.cogt.inference.error_classify.get_optional_service_error_vocabulary", return_value=None)
+
+ result = classify_inference_error(_envelope("pig-01"))
+
+ assert result.service_error_code is None
+ assert result.is_model_not_found is False
assert result.category == InferenceErrorCategory.CONTENT
assert result.user_action_kind == UserActionKind.CHANGE_INPUT
@@ -560,32 +501,6 @@ class TestEndToEnd:
assert rendered.user_action is not None
assert "not found" not in rendered.user_action.detail
- def test_a_model_not_allowed_refusal_reaches_the_caller_as_a_change_model_naming_the_handle(self) -> None:
- """The refusal a run on the hosted API received, through the hop an LLM call on the gateway takes.
-
- It used to read "review the prompt, parameters, and inputs". It now asks for
- another model, names it by its handle, and stays the family's
- failure class, since the model was found.
- """
- exc = _as_the_openai_sdk_raises_it(status_code=412, body=_MODEL_NOT_ALLOWED_BODY)
- metadata = extract_openai_metadata(exc)
-
- rendered = render_inference_error(
- metadata=metadata,
- classification=classify_inference_error(metadata),
- family=InferenceErrorFamily.LLM,
- model_desc=f"{_MODEL_NOT_ALLOWED_HANDLE} → Model[{_MODEL_NOT_ALLOWED_WIRE_ID}]",
- model_handle=_MODEL_NOT_ALLOWED_HANDLE,
- )
-
- assert isinstance(rendered, LLMCompletionError)
- assert not isinstance(rendered, LLMModelNotFoundError)
- assert rendered.error_category == InferenceErrorCategory.CONFIGURATION
- assert rendered.user_action is not None
- assert rendered.user_action.kind == UserActionKind.CHANGE_MODEL
- assert f"'{_MODEL_NOT_ALLOWED_HANDLE}'" in rendered.user_action.detail
- assert rendered.user_action.detail != _GENERIC_ADVICE
-
class TestRenderedAdvice:
"""Each member gets advice naming what has to change, not a generic rejection line."""
@@ -615,47 +530,14 @@ class TestRenderedAdvice:
("pig-02", "has not enabled"),
("pig-05", "not over the protocol"),
("pig-06", "does not serve that capability"),
- ("model_not_allowed_error", "does not allow the model"),
],
)
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_model_not_allowed_advice_names_the_handle_and_not_the_wire_id(self) -> None:
- """The gateway's message names only the backend's id, which the method's author never wrote."""
- detail = _rendered_detail(_envelope("model_not_allowed_error", status_code=412), model_handle=_MODEL_NOT_ALLOWED_HANDLE)
-
- assert f"'{_MODEL_NOT_ALLOWED_HANDLE}'" in detail
- assert _MODEL_NOT_ALLOWED_WIRE_ID not in detail
- assert "pick another model" in detail
- assert "prompt" not in detail
-
- def test_the_model_not_allowed_advice_offers_the_default_only_when_the_pipe_named_the_model(self) -> None:
- """The Render step cannot tell a model the pipe named from the deck's default.
-
- When the default is the refused model, an unconditional "leave the pipe's
- model unset" would tell the caller to do what they already did.
- """
- detail = _rendered_detail(_envelope("model_not_allowed_error", status_code=412), model_handle=_MODEL_NOT_ALLOWED_HANDLE)
-
- assert "if the pipe named this one, leaving its model unset uses the default" in detail
-
- def test_the_model_not_allowed_advice_says_who_settles_a_deck_disagreement_on_either_gateway(self) -> None:
- """The same code comes from the Pipelex gateway and from a user's own Portkey workspace.
-
- Nothing on the wire tells them apart, so advice that only said "contact
- support" would send the owner of a Portkey workspace to Pipelex for a
- setting in their own dashboard.
- """
- detail = _rendered_detail(_envelope("model_not_allowed_error", status_code=412), model_handle=_MODEL_NOT_ALLOWED_HANDLE)
-
- assert "model deck" in detail
- assert "on the Pipelex gateway, contact support" in detail
- assert "on a Portkey workspace of your own, allow the model in the integration that serves it" in detail
-
- @pytest.mark.parametrize("code", [code for code in _EVERY_CODE if code != "model_not_allowed_error"])
- def test_every_other_member_leaves_the_handle_to_the_message(self, code: str) -> None:
- """Only the member whose gateway message names no handle the author wrote names one itself."""
+ @pytest.mark.parametrize("code", _EVERY_CODE)
+ def test_every_member_leaves_the_handle_to_the_message(self, code: str) -> None:
+ """The service's own message states every specific, so the advice names no handle of its own."""
assert "some-distinctive-handle" not in _rendered_detail(_envelope(code), model_handle="some-distinctive-handle")
def test_the_unserved_model_and_the_wrong_protocol_are_told_apart(self) -> None:
@@ -709,16 +591,13 @@ class TestTheScopeDecisionIsPinned:
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
+ assert _routing_refusal(code) is None
+ assert _classified_code(classify_inference_error(metadata)) 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
+ for code in ("pig-03", "pig-04"):
+ assert not _in_another_family(code)
class TestTheThreeGatewayFamiliesDoNotShadowEachOther:
@@ -731,22 +610,14 @@ class TestTheThreeGatewayFamiliesDoNotShadowEachOther:
@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
+ assert not _in_another_family(code)
@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
+ assert _routing_refusal(code) 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)
@@ -755,6 +626,19 @@ class TestTheThreeGatewayFamiliesDoNotShadowEachOther:
assert limits & routing == set()
assert references & routing == set()
+ def test_the_vocabulary_contributes_every_mapped_code_once(self) -> None:
+ """The contribution is the three maps and nothing else, one entry per code.
+
+ The registrar refuses a code claimed twice at boot; this states the same
+ property of the contribution itself, without a boot.
+ """
+ contributed = [entry.code for entry in MANIFOLD_SERVICE_ERROR_CODES]
+
+ assert len(contributed) == len(set(contributed))
+ assert set(contributed) == set(_GATEWAY_REQUEST_LIMIT_BY_CODE) | set(_GATEWAY_UNRESOLVED_REFERENCE_BY_CODE) | set(
+ _GATEWAY_ROUTING_REFUSAL_BY_CODE
+ )
+
class TestWhatTheFamilyAnswersOverHTTP:
"""The category is not only advice — it decides the status an HTTP surface returns.
@@ -769,27 +653,13 @@ class TestWhatTheFamilyAnswersOverHTTP:
process and about nothing else.
"""
- @pytest.mark.parametrize("code", _FAIL_CLOSED_CODES)
+ @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_the_model_not_allowed_refusal_answers_500_as_it_did_before(self) -> None:
- """At its real status the member's answer does not move: only its advice does.
-
- The ladder's generic 4xx arm already read a 412 as ``CONFIGURATION``, so the
- family changes this refusal's ``user_action`` and nothing about its status.
- """
- report = _rendered_error(_envelope("model_not_allowed_error", status_code=412)).to_error_report()
- unrecognized_report = _rendered_error(_envelope("something-else", status_code=412)).to_error_report()
-
- assert report.error_domain == ErrorDomain.CONFIG
- assert report.http_status == 500
- assert unrecognized_report.error_domain == ErrorDomain.CONFIG
- assert unrecognized_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()
@@ -810,8 +680,7 @@ class TestTheAdviceSurvivesThePipeBoundary:
nothing else in this module crosses that boundary to see it.
Every other member keeps the family's failure class, which the pipe operator
- lets through for the pipe router to locate. The last case pins that route, for
- the member a run on the hosted API reached.
+ lets through for the pipe router to locate.
"""
def _re_raised_as_the_pipe_operator_does(self, cause: LLMModelNotFoundError) -> PipeOperatorModelAvailabilityError:
@@ -845,33 +714,3 @@ class TestTheAdviceSurvivesThePipeBoundary:
assert report.user_action_detail() == _rendered_detail(_envelope("pig-01"))
assert report.error_domain == ErrorDomain.CONFIG
assert report.http_status == 500
-
- def test_the_model_not_allowed_advice_reaches_the_caller_through_the_located_failure(self) -> None:
- """The failure class is not re-raised by the pipe operator, so the router's location is the boundary.
-
- ``PipeRouterError`` reports the root fault located at the failing pipe, with
- the classification its cause chain carries. When nothing on the chain
- carried a user action, that report fell back to "the message gives the
- cause", which is what a run on the hosted API read before this member.
- """
- rendered = _rendered_error(_envelope("model_not_allowed_error", status_code=412), model_handle=_MODEL_NOT_ALLOWED_HANDLE)
- located = PipeRouterError.make_located(
- failure=rendered,
- run_mode=PipeRunMode.LIVE,
- pipe_code="score_lead",
- output_name=None,
- pipe_stack=["score_lead"],
- )
- located.__cause__ = rendered
-
- report = located.to_error_report()
-
- assert report.error_type == "LLMCompletionError"
- assert report.error_domain == ErrorDomain.CONFIG
- assert report.error_category == InferenceErrorCategory.CONFIGURATION
- assert report.retryable is False
- assert report.user_action is not None
- assert report.user_action.kind == UserActionKind.CHANGE_MODEL
- assert report.user_action_detail() == _rendered_detail(
- _envelope("model_not_allowed_error", status_code=412), model_handle=_MODEL_NOT_ALLOWED_HANDLE
- )
diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_service_error_codes_boot.py b/tests/unit/pipelex/providers/manifold/test_manifold_service_error_codes_boot.py
new file mode 100644
index 000000000..614d4f507
--- /dev/null
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_service_error_codes_boot.py
@@ -0,0 +1,20 @@
+"""The session's boot installs the Manifold service's refusal codes on the hub, where classification reads them.
+
+The package's other tests hand the classifier the Manifold vocabulary through the autouse fixture, which
+patches the classifier's binding; this one reads the hub's own accessor, which that fixture leaves alone,
+so it fails if the plugin stops contributing its codes or the boot stops installing them.
+"""
+
+from __future__ import annotations
+
+from pipelex.providers.manifold.manifold_error_codes import MANIFOLD_SERVICE_ERROR_CODES
+from pipelex.runtime_hub import get_optional_service_error_vocabulary
+
+
+class TestManifoldServiceErrorCodesBoot:
+ def test_boot_installs_every_manifold_code_on_the_hub(self) -> None:
+ vocabulary = get_optional_service_error_vocabulary()
+
+ assert vocabulary is not None
+ missing = {entry.code for entry in MANIFOLD_SERVICE_ERROR_CODES} - set(vocabulary.codes)
+ assert not missing, f"The booted vocabulary lacks Manifold codes: {sorted(missing)}"
diff --git a/tests/unit/pipelex/providers/manifold/test_manifold_spi_imports.py b/tests/unit/pipelex/providers/manifold/test_manifold_spi_imports.py
new file mode 100644
index 000000000..9840ee7a0
--- /dev/null
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_spi_imports.py
@@ -0,0 +1,76 @@
+"""The package reaches core only through the published Inference SPI.
+
+Every `pipelex.*` name the package imports, at module level, deferred or for type checking alone, must
+be a row of the SPI table in `docs/under-the-hood/inference-backend-plugins.md`, unless it is the
+package's own. Deny by default: a new import of anything else turns this red, and the fix is either to
+publish the symbol in the table, under a role that names no consumer, or to give the package its own
+copy of it. The scan is what lets the package be copied out of this repository as a plugin of its own
+and keep working against a published surface.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+_TESTS_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests")
+_REPO_ROOT = _TESTS_ROOT.parent
+_PACKAGE_DIR = _REPO_ROOT / "pipelex" / "providers" / "manifold"
+_PACKAGE_MODULE = "pipelex.providers.manifold"
+_SPI_PAGE = _REPO_ROOT / "docs" / "under-the-hood" / "inference-backend-plugins.md"
+
+_SPI_ROW = re.compile(r"^\| (?P<symbols>`[^|]+`) \| `(?P<module>[\w.]+)` \| ")
+_BACKTICKED = re.compile(r"`([A-Za-z_][\w]*)`")
+
+
+def _published_symbols() -> set[tuple[str, str]]:
+ section = _SPI_PAGE.read_text(encoding="utf-8").split("## The Inference SPI", maxsplit=1)[1].split("\n## ", maxsplit=1)[0]
+ published: set[tuple[str, str]] = set()
+ for line in section.splitlines():
+ if row := _SPI_ROW.match(line):
+ published.update((row["module"], symbol) for symbol in _BACKTICKED.findall(row["symbols"]))
+ return published
+
+
+def _core_imports() -> list[tuple[str, str, str]]:
+ """Every `(file, module, symbol)` the package imports from `pipelex` outside itself."""
+ imports: list[tuple[str, str, str]] = []
+ for path in sorted(_PACKAGE_DIR.glob("*.py")):
+ for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
+ if isinstance(node, ast.ImportFrom) and node.module is not None and node.module.split(".")[0] == "pipelex":
+ if node.module == _PACKAGE_MODULE or node.module.startswith(f"{_PACKAGE_MODULE}."):
+ continue
+ imports.extend((path.name, node.module, alias.name) for alias in node.names)
+ elif isinstance(node, ast.Import):
+ imports.extend((path.name, alias.name, "*") for alias in node.names if alias.name.split(".")[0] == "pipelex")
+ return imports
+
+
+class TestManifoldReachesCoreOnlyThroughTheSpi:
+ def test_the_spi_table_parses(self) -> None:
+ """Guards the guard: a table the regex stopped reading would let every import through."""
+ published = _published_symbols()
+
+ assert ("pipelex.plugins.registrar", "PluginRegistrar") in published
+ assert ("pipelex.cogt.inference.service_error_vocabulary", "ServiceErrorCode") in published
+
+ def test_the_package_imports_something_from_core(self) -> None:
+ """Guards the guard the other way: a scan that found nothing would pass vacuously."""
+ assert _core_imports()
+
+ def test_every_core_import_is_published(self) -> None:
+ published = _published_symbols()
+
+ unpublished = sorted(
+ f"{file}: from {module} import {symbol}" for file, module, symbol in _core_imports() if (module, symbol) not in published
+ )
+
+ assert not unpublished, "Imports outside the Inference SPI table; publish them there or copy them into the package:\n" + "\n".join(
+ unpublished
+ )
+
+ def test_no_backend_name_constant_is_imported(self) -> None:
+ """The package names its own backend; it reads no core constant that does."""
+ backend_module = "pipelex.cogt.model_backends.backend"
+ assert not [(file, symbol) for file, module, symbol in _core_imports() if module == backend_module and symbol != "InferenceBackend"]
diff --git a/tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.py b/tests/unit/pipelex/providers/manifold/test_manifold_unresolved_references.py
similarity index 82%
rename from tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.py
rename to tests/unit/pipelex/providers/manifold/test_manifold_unresolved_references.py
index c7cefaa58..0304e718e 100644
--- a/tests/unit/pipelex/cogt/inference/test_gateway_unresolved_references.py
+++ b/tests/unit/pipelex/providers/manifold/test_manifold_unresolved_references.py
@@ -1,18 +1,22 @@
-"""The gateway's unresolvable-reference refusals, from the wire code to the rendered advice.
+"""The Manifold service'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
+Pipelex Manifold service 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
+These codes are the service's wire contract, so the Manifold plugin owns them: each
+is a ``GatewayUnresolvedReference`` member in ``manifold_error_codes``, contributed
+as one entry of the service error vocabulary that ``classify_inference_error``
+consults ahead of the status ladder (the package's ``conftest.py`` hands the
+classifier that vocabulary). Without that entry 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,
+parameters, and inputs". These tests pin the whole chain: the code is in the vocabulary,
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.
@@ -33,7 +37,7 @@ request limits.
from __future__ import annotations
import json
-from typing import Any
+from typing import TYPE_CHECKING, Any
import anthropic
import httpx
@@ -43,19 +47,25 @@ 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_classify import ClassificationResult, classify_inference_error
from pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_error
from pipelex.cogt.inference.provider_name import ProviderName
+from pipelex.providers.manifold.manifold_error_codes import (
+ _GATEWAY_REQUEST_LIMIT_BY_CODE, # pyright: ignore[reportPrivateUsage]
+ _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE, # pyright: ignore[reportPrivateUsage]
+ GatewayRequestLimit,
+ GatewayUnresolvedReference,
+)
+from pipelex.providers.manifold.manifold_error_metadata import extract_manifold_metadata
+
+if TYPE_CHECKING:
+ from pipelex.cogt.inference.service_error_vocabulary import ServiceErrorVocabulary
_ORIGIN = "https://manifold.example.com"
@@ -166,6 +176,21 @@ def _envelope(code: str | None, *, status_code: int = 400, provider: ProviderNam
)
+def _unresolved_reference(code: str | None) -> GatewayUnresolvedReference | None:
+ """The family member a wire code names, if it names one."""
+ return _GATEWAY_UNRESOLVED_REFERENCE_BY_CODE.get(code) if code is not None else None
+
+
+def _request_limit(code: str | None) -> GatewayRequestLimit | None:
+ """The neighbouring family's member a wire code names, if it names one."""
+ return _GATEWAY_REQUEST_LIMIT_BY_CODE.get(code) if code is not None else None
+
+
+def _classified_code(result: ClassificationResult) -> str | None:
+ """The wire code of the vocabulary entry the classifier matched, if it matched one."""
+ return result.service_error_code.code if result.service_error_code is not None else None
+
+
def _rendered_detail(metadata: ProviderErrorMetadata, *, family: InferenceErrorFamily = InferenceErrorFamily.LLM) -> str:
rendered = render_inference_error(
metadata=metadata,
@@ -179,11 +204,14 @@ def _rendered_detail(metadata: ProviderErrorMetadata, *, family: InferenceErrorF
class TestTheCodeIsRecognized:
- """``gateway_unresolved_reference`` reads the gateway's own code namespace off the envelope."""
+ """Each code is in the Manifold vocabulary, under the family member that names its remedy."""
@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
+ def test_each_code_maps_to_its_member(
+ self, code: str, expected: GatewayUnresolvedReference, manifold_service_error_vocabulary: ServiceErrorVocabulary
+ ) -> None:
+ assert _unresolved_reference(code) == expected
+ assert manifold_service_error_vocabulary.lookup(code=code) is not None
@pytest.mark.parametrize("member", list(GatewayUnresolvedReference))
def test_every_member_is_reachable_from_a_wire_code(self, member: GatewayUnresolvedReference) -> None:
@@ -205,14 +233,15 @@ class TestTheCodeIsRecognized:
)
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
+ assert _unresolved_reference(code) is None
+ assert _unresolved_reference(_classified_code(classify_inference_error(_envelope(code)))) 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)
+ result = classify_inference_error(_envelope("pipelex_document_host_refused", provider=provider))
- assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED
+ assert _unresolved_reference(_classified_code(result)) == GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED
class TestTheCodeSurvivesEveryExtractHop:
@@ -224,7 +253,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_gateway_metadata(exc)
assert metadata.provider_error_code == "pig-09"
- assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED
+ assert _unresolved_reference(metadata.provider_error_code) == 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.
@@ -237,7 +266,7 @@ class TestTheCodeSurvivesEveryExtractHop:
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
+ assert _unresolved_reference(extract_gateway_metadata(exc).provider_error_code) == 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.
@@ -253,7 +282,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_gateway_metadata(exc)
assert metadata.provider_error_code == "pipelex_document_host_refused"
- assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED
+ assert _unresolved_reference(metadata.provider_error_code) == GatewayUnresolvedReference.DOCUMENT_HOST_REFUSED
@pytest.mark.parametrize(
("code", "expected"),
@@ -272,7 +301,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_manifold_metadata(exc)
assert metadata.provider_error_code == code
- assert metadata.gateway_unresolved_reference == expected
+ assert _unresolved_reference(metadata.provider_error_code) == 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."""
@@ -283,7 +312,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_anthropic_metadata(exc)
assert metadata.provider_error_code == "pig-09"
- assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED
+ assert _unresolved_reference(metadata.provider_error_code) == 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.
@@ -297,7 +326,7 @@ class TestTheCodeSurvivesEveryExtractHop:
metadata = extract_openai_metadata(exc)
- assert metadata.gateway_unresolved_reference == GatewayUnresolvedReference.REFERENCE_UNRESOLVED
+ assert _unresolved_reference(metadata.provider_error_code) == GatewayUnresolvedReference.REFERENCE_UNRESOLVED
class TestClassification:
@@ -307,10 +336,11 @@ class TestClassification:
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 _unresolved_reference(_classified_code(result)) == expected
assert result.category.is_retryable is False
assert result.is_model_not_found is False
- assert result.gateway_request_limit is None
+ assert _classified_code(result) == code
+ assert _request_limit(_classified_code(result)) 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:
@@ -323,7 +353,7 @@ class TestClassification:
"""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 _unresolved_reference(_classified_code(result)) == GatewayUnresolvedReference.STORAGE_NOT_SERVED
assert result.category == InferenceErrorCategory.CONFIGURATION
assert result.user_action_kind == UserActionKind.CONTACT_SUPPORT
assert result.category.is_retryable is False
@@ -332,7 +362,7 @@ class TestClassification:
"""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 _classified_code(result) is None
assert result.category == InferenceErrorCategory.CONTENT
assert result.user_action_kind == UserActionKind.CHANGE_INPUT
@@ -420,18 +450,21 @@ class TestTheTwoGatewayFamiliesDoNotShadowEachOther:
@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
+ assert _request_limit(code) 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
+ assert _unresolved_reference(code) 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 None
+ too_large_code = _classified_code(classify_inference_error(too_large))
+ unreadable_code = _classified_code(classify_inference_error(unreadable))
+
+ assert _request_limit(too_large_code) == GatewayRequestLimit.OBJECT_TOO_LARGE
+ assert _unresolved_reference(too_large_code) is None
+ assert _unresolved_reference(unreadable_code) == GatewayUnresolvedReference.STORAGE_OBJECT_UNREADABLE
+ assert _request_limit(unreadable_code) is None
diff --git a/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_error_handling.py b/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_error_handling.py
index ce70b0652..6f52234f2 100644
--- a/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_error_handling.py
+++ b/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_error_handling.py
@@ -24,6 +24,7 @@ def _make_response(status_code: int, headers: dict[str, str] | None = None) -> h
def _make_worker(mocker: MockerFixture) -> OpenAICompletionsImgGenWorker:
"""Create a minimal worker with mocked internals."""
worker = object.__new__(OpenAICompletionsImgGenWorker)
+ worker.fixed_output_format = None
mock_model = mocker.MagicMock()
mock_model.desc = "test-openai-completions-img"
mock_model.model_id = "gemini-2.5-flash-image-preview"
diff --git a/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_output_format.py b/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_output_format.py
new file mode 100644
index 000000000..689dd679c
--- /dev/null
+++ b/tests/unit/pipelex/providers/openai/test_openai_completions_img_gen_worker_output_format.py
@@ -0,0 +1,132 @@
+"""The completions image worker's fixed output format comes from whoever registers it, never from a backend name.
+
+Some services normalise every image to one format and may answer with a URL, from which no format can
+be read. The registration for such a service passes that format to the worker; the worker refuses a
+request for another one before the call, and reads a URL answer as that format. A worker built without
+one cannot interpret a URL answer, and says so.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.cogt.exceptions import ImgGenParameterError
+from pipelex.plugins.inference_backend_registry import InferenceFamily
+from pipelex.plugins.model_handle import ModelHandle
+from pipelex.plugins.registrar import PluginRegistrar
+from pipelex.providers.blackboxai.blackboxai_plugin import BlackboxaiPlugin
+from pipelex.providers.manifold.manifold_plugin import ManifoldPlugin
+from pipelex.providers.openai.openai_completions_img_gen_worker import OpenAICompletionsImgGenWorker
+from pipelex.providers.openrouter.openrouter_plugin import OpenRouterPlugin
+from pipelex.tools.misc.image_utils import ImageFormat
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+_IMAGE_URL = "https://images.example.com/generated/abc"
+
+
+def _make_worker(mocker: MockerFixture, *, fixed_output_format: ImageFormat | None) -> OpenAICompletionsImgGenWorker:
+ worker = object.__new__(OpenAICompletionsImgGenWorker)
+ worker.fixed_output_format = fixed_output_format
+ model = mocker.MagicMock()
+ model.desc = "test-completions-img"
+ model.model_id = "test-image-model"
+ model.name = "test-image-model"
+ model.backend_name = "any_backend_name"
+ model.tag = "test-tag"
+ worker.inference_model = model
+ client = mocker.MagicMock()
+ message = mocker.MagicMock(spec=["content"])
+ message.content = _IMAGE_URL
+ response = mocker.MagicMock()
+ response.choices = [mocker.MagicMock(message=message)]
+ response.usage = None
+ client.chat.completions.create = mocker.AsyncMock(return_value=response)
+ worker.openai_client = client
+ factory = mocker.MagicMock()
+ factory.make_extras.return_value = ({}, {})
+ worker.openai_completions_factory = factory
+ return worker
+
+
+def _make_job(mocker: MockerFixture, *, output_format: ImageFormat | None) -> Any:
+ job = mocker.MagicMock()
+ job.img_gen_prompt.positive_text = "a lighthouse at dusk"
+ job.img_gen_prompt.input_images = None
+ job.job_params.output_format = output_format
+ job.job_report.img_gen_tokens_usage = None
+ return job
+
+
[email protected](loop_scope="class")
+class TestFixedOutputFormat:
+ @pytest.mark.parametrize("fixed_output_format", [ImageFormat.PNG, ImageFormat.JPEG])
+ async def test_a_url_answer_is_read_as_the_fixed_format(self, mocker: MockerFixture, fixed_output_format: ImageFormat) -> None:
+ worker = _make_worker(mocker, fixed_output_format=fixed_output_format)
+
+ details = await worker._gen_image(img_gen_job=_make_job(mocker, output_format=None)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert details.actual_url == _IMAGE_URL
+ assert details.image_format == fixed_output_format
+
+ async def test_a_request_for_the_fixed_format_is_served(self, mocker: MockerFixture) -> None:
+ worker = _make_worker(mocker, fixed_output_format=ImageFormat.JPEG)
+
+ details = await worker._gen_image(img_gen_job=_make_job(mocker, output_format=ImageFormat.JPEG)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert details.image_format == ImageFormat.JPEG
+
+ @pytest.mark.parametrize(
+ ("fixed_output_format", "requested"),
+ [(ImageFormat.PNG, ImageFormat.JPEG), (ImageFormat.PNG, ImageFormat.WEBP), (ImageFormat.JPEG, ImageFormat.PNG)],
+ )
+ async def test_another_format_is_refused_before_the_call(
+ self, mocker: MockerFixture, fixed_output_format: ImageFormat, requested: ImageFormat
+ ) -> None:
+ worker = _make_worker(mocker, fixed_output_format=fixed_output_format)
+
+ with pytest.raises(ImgGenParameterError, match=f"only supports {fixed_output_format} output format"):
+ await worker._gen_image(img_gen_job=_make_job(mocker, output_format=requested)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ worker.openai_client.chat.completions.create.assert_not_called() # type: ignore[attr-defined] # pyright: ignore[reportAttributeAccessIssue]
+
+ async def test_without_a_fixed_format_a_url_answer_is_refused(self, mocker: MockerFixture) -> None:
+ worker = _make_worker(mocker, fixed_output_format=None)
+
+ with pytest.raises(ImgGenParameterError, match="no fixed output format"):
+ await worker._gen_image(img_gen_job=_make_job(mocker, output_format=None)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ async def test_without_a_fixed_format_any_format_may_be_requested(self, mocker: MockerFixture) -> None:
+ worker = _make_worker(mocker, fixed_output_format=None)
+ worker.openai_client.chat.completions.create.side_effect = RuntimeError("called") # type: ignore[attr-defined] # pyright: ignore[reportAttributeAccessIssue]
+
+ with pytest.raises(RuntimeError, match="called"):
+ await worker._gen_image(img_gen_job=_make_job(mocker, output_format=ImageFormat.WEBP)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+
+class TestEachRegistrationPassesItsFormat:
+ @pytest.mark.parametrize(
+ ("plugin", "sdk", "expected"),
+ [
+ (ManifoldPlugin(), "manifold_completions", ImageFormat.PNG),
+ (BlackboxaiPlugin(), "blackboxai_img_gen", ImageFormat.JPEG),
+ (OpenRouterPlugin(), "openrouter_img_gen", None),
+ ],
+ ids=["manifold", "blackboxai", "openrouter"],
+ )
+ def test_the_registration_builds_the_worker_with_its_format(
+ self, mocker: MockerFixture, plugin: Any, sdk: str, expected: ImageFormat | None
+ ) -> None:
+ registrar = PluginRegistrar(config=mocker.MagicMock())
+ plugin.register(registrar)
+ make_worker = registrar.inference_backends[InferenceFamily.IMG_GEN, sdk]
+ worker_class = mocker.patch("pipelex.providers.openai.openai_completions_img_gen_worker.OpenAICompletionsImgGenWorker")
+ mocker.patch.object(ModelHandle, "make_for_inference_model", return_value=mocker.MagicMock())
+ sdk_clients = mocker.MagicMock()
+
+ make_worker(inference_model=mocker.MagicMock(), backend=mocker.MagicMock(), sdk_clients=sdk_clients, reporting_delegate=None)
+
+ assert worker_class.call_args.kwargs.get("fixed_output_format") == expected
diff --git a/tests/unit/pipelex/providers/test_instructor_retry_shapes.py b/tests/unit/pipelex/providers/test_instructor_retry_shapes.py
index c312bc934..74ea60ba7 100644
--- a/tests/unit/pipelex/providers/test_instructor_retry_shapes.py
+++ b/tests/unit/pipelex/providers/test_instructor_retry_shapes.py
@@ -34,7 +34,7 @@ from tenacity import RetryError
from pipelex.base_exceptions import ErrorDomain
from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError, LLMModelNotFoundError
-from pipelex.cogt.inference.error_classification import GatewayRoutingRefusal, UserActionKind, extract_underlying_sdk_exception
+from pipelex.cogt.inference.error_classification import UserActionKind, extract_underlying_sdk_exception
from pipelex.cogt.llm.instructor_retry import make_instructor_schema_retrying
from pipelex.pipe_run.exceptions import PipeRouterError
from pipelex.providers.openai.openai_completions_llm_worker import OpenAICompletionsLLMWorker
@@ -280,7 +280,7 @@ class TestInstructorRetryShapes:
assert not isinstance(failure, LLMModelNotFoundError)
assert failure.provider_metadata is not None
assert failure.provider_metadata.status_code == 412
- assert failure.provider_metadata.gateway_routing_refusal == GatewayRoutingRefusal.MODEL_NOT_ALLOWED
+ assert failure.provider_metadata.is_model_not_allowed
located = PipeRouterError.make_located(
failure=failure,
diff --git a/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py b/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py
index 67d05d848..a2be91111 100644
--- a/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py
+++ b/tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py
@@ -1,20 +1,44 @@
"""Class-name uniqueness guard for the ``PipelexError.type_uri()`` keyspace.
-Every loaded ``PipelexError`` subclass must produce a unique ``type_uri``. A
-collision would mean two distinct error classes point at the same documentation
-page — catches future class-name reuses at CI time, not at docs-build time.
+Every loaded ``PipelexError`` subclass whose ``type_uri`` is derived from its class name must produce
+a unique one. A collision there would mean two distinct error classes kebab to the same documentation
+page by accident — this catches class-name reuses at CI time, not at docs-build time.
+
+A class that declares ``_declared_type_uri`` points at a page on purpose, usually the existing page of
+the generic family it belongs to, so it may share that page with the family's own class. What it may
+not do is point at a page that does not exist, which the second case checks.
"""
+from pathlib import Path
+
from pipelex.errors.error_pages_generator import iter_pipelex_error_subclasses
+from pipelex.urls import URLs
+
+_TESTS_ROOT = next(parent for parent in Path(__file__).resolve().parents if parent.name == "tests")
+_ERROR_PAGES_DIR = _TESTS_ROOT.parent / "docs" / "errors"
class TestPipelexErrorTypeUriUniqueness:
- def test_all_pipelex_error_subclasses_have_unique_type_uris(self) -> None:
- """Every loaded ``PipelexError`` subclass produces a unique ``type_uri``."""
+ def test_all_derived_type_uris_are_unique(self) -> None:
+ """Every loaded ``PipelexError`` subclass that derives its ``type_uri`` produces a unique one."""
seen: dict[str, str] = {}
for cls in iter_pipelex_error_subclasses():
+ if isinstance(cls.__dict__.get("_declared_type_uri"), str):
+ continue
uri = cls.type_uri()
if uri in seen and seen[uri] != cls.__name__:
msg = f"type_uri collision: {cls.__name__} and {seen[uri]} both produce {uri!r}"
raise AssertionError(msg)
seen[uri] = cls.__name__
+
+ def test_every_declared_type_uri_under_the_error_docs_names_an_existing_page(self) -> None:
+ """A declared URI that points into the error docs must land on a page that is there."""
+ missing: list[str] = []
+ for cls in iter_pipelex_error_subclasses():
+ declared = cls.__dict__.get("_declared_type_uri")
+ if not isinstance(declared, str) or not declared.startswith(f"{URLs.error_docs_base}/"):
+ continue
+ slug = declared.removeprefix(f"{URLs.error_docs_base}/").strip("/")
+ if not (_ERROR_PAGES_DIR / f"{slug}.md").is_file():
+ missing.append(f"{cls.__name__} -> {declared}")
+ assert not missing, "declared type URIs pointing at no error page:\n" + "\n".join(missing)