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-trace-id-spelling · L-260918-a332cc (#1213)

Louis Choquelc8d7f9e37cca
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd7f86265..0f77d1aab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Fixed
+
+- **A manifold error on the native routes keeps its request id under the gateway's pipelex-spelled trace header**: `extract_manifold_metadata` reads the gateway's trace id from `x-pipelex-trace-id` before the inherited `x-portkey-trace-id`, still preferring a provider's own `x-request-id` over both. The gateway emits the two spellings with the same value today, so nothing changes yet; once it drops the vendor one, such an error whose provider sent no `x-request-id` keeps a request id instead of reporting none. `extract_gateway_metadata` is unchanged and still reads the vendor spelling alone — it serves the Portkey cloud and the manifold image path, which travels on `portkey_ai` and keeps that spelling until it is ported off the SDK.
+
## [v0.60.0] - 2026-09-19
### Changed
diff --git a/pipelex/cogt/inference/error_classification.py b/pipelex/cogt/inference/error_classification.py
index b22e586f1..b88be7721 100644
--- a/pipelex/cogt/inference/error_classification.py
+++ b/pipelex/cogt/inference/error_classification.py
@@ -1072,6 +1072,26 @@ 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.
@@ -1093,6 +1113,17 @@ def extract_manifold_metadata(exc: BaseException) -> ProviderErrorMetadata:
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
@@ -1107,7 +1138,7 @@ def extract_manifold_metadata(exc: BaseException) -> ProviderErrorMetadata:
request_id: str | None = None
retry_after_seconds: float | None = None
if headers is not None:
- request_id_value = headers.get("x-request-id") or headers.get("x-portkey-trace-id")
+ 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"))
diff --git a/pipelex/providers/manifold/manifold_constants.py b/pipelex/providers/manifold/manifold_constants.py
index 3ded42917..8ecbf7cba 100644
--- a/pipelex/providers/manifold/manifold_constants.py
+++ b/pipelex/providers/manifold/manifold_constants.py
@@ -20,6 +20,14 @@ from enum import StrEnum
# `backends.toml` must spell it exactly as this constant does.
MANIFOLD_AUTH_HEADER = "x-pipelex-api-key"
+# 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 OpenAI and Portkey SDKs both expect their `base_url` to already carry the API version segment
# (`AsyncOpenAI`'s default is `https://api.openai.com/v1`, `AsyncPortkey`'s is
# `https://api.portkey.ai/v1`), and both then append their own route beneath it. The Anthropic SDK
diff --git a/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py b/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py
new file mode 100644
index 000000000..58b8a91c9
--- /dev/null
+++ b/tests/unit/pipelex/providers/manifold/test_extract_manifold_metadata.py
@@ -0,0 +1,64 @@
+"""Which header `extract_manifold_metadata` takes the request id from, and in what order.
+
+The manifold gateway stamps its trace id on every answer a provider gave, and since the header
+spellings were given a pipelex vocabulary it emits that id twice: under `x-pipelex-trace-id`, the
+spelling the dialect owns, and under `x-portkey-trace-id`, the inherited one it still carries for
+the vendor SDK on the image path. The two always hold the same value, so the precedence below is
+not about picking the better id — it is about the moment the gateway stops emitting the vendor
+spelling, after which a runtime that only knew that one would report no request id at all.
+
+`x-request-id` stays ahead of both: it is the *provider's* own id when the provider sent one, which
+is what a support conversation with that provider needs, and the gateway's trace id is the fallback
+for every answer that carried none.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from pipelex.cogt.inference.error_classification import extract_manifold_metadata
+
+_ORIGIN = "https://manifold.example.com"
+
+
+def _refusal_with_headers(headers: dict[str, str]) -> httpx.HTTPStatusError:
+ """A native-route failure as the manifold client raises it: plain httpx, no vendor SDK."""
+ request = httpx.Request("POST", f"{_ORIGIN}/v1/pipelex/extract")
+ response = httpx.Response(status_code=502, request=request, headers=headers)
+ return httpx.HTTPStatusError("Server error '502 Bad Gateway'", request=request, response=response)
+
+
+class TestTheRequestIdTheManifoldPathReports:
+ def test_reads_the_pipelex_spelled_trace_id(self) -> None:
+ """The spelling the dialect owns, alone on the response — where the gateway is heading."""
+ metadata = extract_manifold_metadata(_refusal_with_headers({"x-pipelex-trace-id": "trace-pipelex"}))
+
+ assert metadata.request_id == "trace-pipelex"
+
+ def test_prefers_the_pipelex_spelling_over_the_vendor_one(self) -> None:
+ """Both spellings on the wire is what the gateway emits today, with one value under each."""
+ headers = {"x-portkey-trace-id": "trace-vendor", "x-pipelex-trace-id": "trace-pipelex"}
+
+ metadata = extract_manifold_metadata(_refusal_with_headers(headers))
+
+ assert metadata.request_id == "trace-pipelex"
+
+ def test_still_reads_the_vendor_spelling_while_the_gateway_emits_it(self) -> None:
+ """The fallback is harmless until the gateway drops the inherited spelling, and useful until then."""
+ metadata = extract_manifold_metadata(_refusal_with_headers({"x-portkey-trace-id": "trace-vendor"}))
+
+ assert metadata.request_id == "trace-vendor"
+
+ def test_prefers_the_providers_own_request_id_over_any_trace_id(self) -> None:
+ """A provider answered and named its call; that id, not the gateway's, is the one to quote."""
+ headers = {"x-request-id": "provider-1", "x-pipelex-trace-id": "trace-pipelex", "x-portkey-trace-id": "trace-vendor"}
+
+ metadata = extract_manifold_metadata(_refusal_with_headers(headers))
+
+ assert metadata.request_id == "provider-1"
+
+ def test_reports_no_request_id_when_no_provider_was_reached(self) -> None:
+ """A refusal the gateway raised before trying a provider carries neither trace spelling."""
+ metadata = extract_manifold_metadata(_refusal_with_headers({}))
+
+ assert metadata.request_id is None