Add 0079 OpenAI-compatible embeddings wire mapping (#211)

Add the retrieval-provider 0079 OpenAI-compatible embeddings wire
mapping (section 8.3) over the existing OpenAIEmbeddingProvider.
input_type flows into EmbeddingEvent.request_params but is a wire no-op
on OpenAI's symmetric /v1/embeddings; for an asymmetric model behind a
compatible endpoint, a bound client-side query_prefix / document_prefix
prepends to the input per input_type. dimensions maps to the wire
dimensions field, and base_url now defaults to https://api.openai.com
per the spec (it was previously required).

Single-source the client-side prefix rule and its application in
retrieval/_events.py (client_side_prefix + apply_client_side_prefix),
adopted by both OpenAI and TEI. Un-defer conformance fixtures 023-027,
read an openai_embedding_provider block in the harness, and assert the
request origin against the bound base_url so the override fixture
verifies routing. Env-gated live tests cover embed, dimensions, and
Matryoshka truncation.

Author: chris-colinsky

conformance.toml

@@ -786,10 +786,12 @@ since = "0.16.0"
 note = "Retrieval-provider Jina hosted wire mapping (§8 / §8.2) -- a §8 mapping in the family established by 0077. Two bundled providers ship, distinct instances (one model each) sharing the hosted endpoint: base_url defaults to https://api.jina.ai (origin only; the provider appends /v1/embeddings / /v1/rerank), and the required api_key is sent as Authorization: Bearer <key> (§8.2 *Construction*). JinaEmbeddingProvider posts POST {base_url}/v1/embeddings with {model, input, task?, dimensions?, truncate: false} -- input_type is realized as Jina's native `task` per the closed set (query -> retrieval.query, document -> retrieval.passage); absent input_type omits `task` (the symmetric default), and an unrecognized input_type is a pre-send provider_invalid_request (§7, no request issued). dimensions -> Jina's dimensions (Matryoshka) when set; truncate: false is sent explicitly (fail-loud). It parses the object envelope {model, usage: {total_tokens}, data: [{index, embedding}]}, orders the vectors by data[i].index into input order, and maps usage.total_tokens -> EmbeddingUsage.input_tokens (Jina reports usage, unlike TEI's null -- a record when the body surfaces it, never fabricated). JinaRerankProvider posts POST {base_url}/v1/rerank with {model, query, documents, top_n?, return_documents, truncation: false} -- documents maps directly onto the string array (no per-document wrapping), top_n <- top_k (omitted when None), and return_documents is sent EXPLICITLY (Jina's wire default is true but OA's is False, §2, so the mapping sends the resolved OA value). truncation: false is sent explicitly (fail-loud). It parses {model, usage: {total_tokens}, results: [{index, relevance_score, document?}]} (Cohere-shaped relevance_score), reads the document echo only when present (never auto-filled), sorts by relevance_score descending, enforces the §6 invariants (valid index, no duplicate, len(results) <= top_k), and maps usage.total_tokens -> RerankUsage.input_tokens with search_units null (Jina meters by tokens). raw is the verbatim response dict on both surfaces. Errors map per §8.2: 401/403 -> provider_authentication, 429 -> provider_rate_limit (NOT provider_unavailable), 404 -> provider_invalid_model, 422 (over-length / malformed) -> provider_invalid_request, else -> provider_unavailable. Jina enforces no per-call embed cap (server-side batching), so there is no client-side chunk-and-stitch. Both providers dispatch the typed EmbeddingEvent / RerankEvent (graph-engine §6) per call, mutually exclusive with the failure variant; input_type flows into EmbeddingEvent.request_params with absence-is-meaningful semantics, and RerankEvent.output_results is populated unconditionally on success (proposal 0089). genai_system = 'jina'. Conformance fixtures 018-022 pass, driven through the general wire-capture harness (0077) extended with an expected_wire_headers subset assertion locking the Authorization: Bearer <api_key> header on the outbound request."
 
 # Spec v0.74.0 (proposal 0079).  Retrieval-provider OpenAI-compatible
-# embeddings wire mapping (§8.3).  Not-yet; retrieval-provider fixtures
-# 023-027 defer with it.
+# embeddings wire mapping (§8.3), in the §8 mapping family established by
+# 0077.
 [proposals."0079"]
-status = "not-yet"
+status = "implemented"
+since = "0.16.0"
+note = "Retrieval-provider OpenAI-compatible embeddings wire mapping (§8 / §8.3) -- a §8 mapping in the family established by 0077, formalized over the OpenAIEmbeddingProvider that shipped with the embedding capability (0059). base_url defaults to https://api.openai.com (origin only; the provider appends /v1/embeddings) and is overridable for any OpenAI-compatible backend (vLLM / LocalAI / TEI's OpenAI surface) -- gen_ai.system 'openai' names the WIRE SURFACE, not the backing deployment (fixture 025); the api_key is sent as Authorization: Bearer <key> (§8.3 *Construction*). OpenAIEmbeddingProvider posts POST {base_url}/v1/embeddings with {model, input, dimensions?} -- input is always the array form (§3), and dimensions -> the wire dimensions field (Matryoshka) when set. input_type is a NO-OP on the base wire: the OpenAI /v1/embeddings wire has no query/document field, so an absent input_type is the correct symmetric default and the mapping does not error on a supplied one -- the wire body is byte-identical to the no-input_type request, input sent verbatim (fixture 026). input_type STILL flows into EmbeddingEvent.request_params with absence-is-meaningful semantics (empty when absent), decoupled from the wire body so it never leaks onto the wire. For an asymmetric model behind a compatible endpoint the construction MAY bind the §8.1 client-side query_prefix / document_prefix -- input_type then selects which prefix to prepend to each input client-side, the only way to express the query/document distinction on a wire with no input_type field (fixture 027); the un-prefixed caller intent is what reaches the event. encoding_format ('base64') rides the extras-pass-through bag (the mapping does not send it by default; OpenAI's wire default is 'float'). It parses the object envelope {object, data: [{object, index, embedding}], model, usage: {prompt_tokens, total_tokens}}, orders the vectors by data[i].index into input order, and maps usage.prompt_tokens -> EmbeddingUsage.input_tokens (total_tokens == prompt_tokens; embedding has no output tokens); response_id is null (OpenAI embeddings carry no id). Errors map per §8.3: 401/403 -> provider_authentication, 429 -> provider_rate_limit, 404 -> provider_invalid_model, 400/422 (malformed / oversized) -> provider_invalid_request, else (5xx) -> provider_unavailable. The client-side embed chunk-and-stitch over OpenAI's 2048-input cap (0092) stays out of scope here. genai_system = 'openai'. Conformance fixtures 023-027 pass, driven through the general wire-capture harness (0077) with the expected_wire_headers Authorization: Bearer assertion (0078). The §8.1 client-side prefix lookup is now a shared retrieval helper (client_side_prefix), adopted by both TEI (0077) and OpenAI."
 
 # Spec v0.75.0 (proposal 0080).  PromptGroup arity enforcement
 # (prompt-management §10 / §11 -- construct-time raise plus the new

src/openarmature/retrieval/_events.py

@@ -62,6 +62,52 @@ def normalize_base_url(base_url: str, *, guard_prefix: str) -> str:
     return normalized
 
 
+# retrieval-provider §8.1 client-side prefix rule, reused by §8.3: input_type
+# "query" selects query_prefix, "document" selects document_prefix; any other
+# value (including None / absent) selects no prefix -- the symmetric default.
+def client_side_prefix(
+    input_type: str | None,
+    *,
+    query_prefix: str | None,
+    document_prefix: str | None,
+) -> str | None:
+    """Return the client-side prefix for ``input_type``, or ``None``.
+
+    ``"query"`` maps to ``query_prefix``, ``"document"`` to ``document_prefix``;
+    any other value (including ``None``) maps to ``None`` (no prefix).
+    """
+    if input_type == "query":
+        return query_prefix
+    if input_type == "document":
+        return document_prefix
+    return None
+
+
+# Apply the §8.1 client-side prefix to an input list for input_type: prepend the
+# resolved prefix to every string, or return the list unchanged when input_type
+# resolves to no prefix. The single source of the "prefix the inputs" step
+# shared by the OpenAI (§8.3) and TEI (§8.1) embed mappings -- keeps the copy /
+# no-copy semantics from drifting between providers.
+def apply_client_side_prefix(
+    input_strings: list[str],
+    input_type: str | None,
+    *,
+    query_prefix: str | None,
+    document_prefix: str | None,
+) -> list[str]:
+    """Return ``input_strings`` prefixed per ``input_type``, or unchanged.
+
+    Resolves the prefix via :func:`client_side_prefix`; when it is ``None`` the
+    list is returned as-is (no defensive copy -- the result is only serialized
+    onto the wire), otherwise a new list with the prefix prepended to each
+    string.
+    """
+    prefix = client_side_prefix(input_type, query_prefix=query_prefix, document_prefix=document_prefix)
+    if prefix is None:
+        return input_strings
+    return [prefix + s for s in input_strings]
+
+
 def build_embedding_event(
     response: EmbeddingResponse,
     latency_ms: float,
@@ -282,9 +328,11 @@ def build_rerank_failed_event(
 
 
 __all__ = [
+    "apply_client_side_prefix",
     "build_embedding_event",
     "build_embedding_failed_event",
     "build_rerank_event",
     "build_rerank_failed_event",
+    "client_side_prefix",
     "normalize_base_url",
 ]

src/openarmature/retrieval/providers/openai.py

@@ -41,7 +41,12 @@
 )
 from openarmature.observability.correlation import current_dispatch
 
-from .._events import build_embedding_event, build_embedding_failed_event, normalize_base_url
+from .._events import (
+    apply_client_side_prefix,
+    build_embedding_event,
+    build_embedding_failed_event,
+    normalize_base_url,
+)
 from ..provider import validate_embedding_input, validate_embedding_response
 from ..response import EmbeddingResponse, EmbeddingRuntimeConfig, EmbeddingUsage
 
@@ -82,17 +87,20 @@ def _classify_embedding_http_error(resp: httpx.Response) -> LlmProviderError:
 
 # Absence-is-meaningful per observability §5.5.2: only caller-supplied keys
 # appear in the event's request_params -- "the field was not supplied for
-# this call", distinct from a supplied zero. The input_type field joins this
-# set with proposal 0079 (OpenAI-compatible input_type is its wire mapping's
-# job, not 0077's). For embedding the event-param names coincide with the
-# wire-body keys, so the same dict feeds both the event and the body.
+# this call", distinct from a supplied zero. For OpenAI, input_type joins
+# dimensions in this set (proposal 0079). input_type does NOT feed the wire
+# body verbatim -- the OpenAI wire has no query/document field, so input_type
+# is a wire no-op (realized only as a client-side prefix when one is bound),
+# and the wire body is built separately.
 def _request_params_from_config(config: EmbeddingRuntimeConfig | None) -> dict[str, Any]:
     """Extract the supplied embedding request parameters for the event."""
     if config is None:
         return {}
     out: dict[str, Any] = {}
     if config.dimensions is not None:
         out["dimensions"] = config.dimensions
+    if config.input_type is not None:
+        out["input_type"] = config.input_type
     return out
 
 
@@ -102,9 +110,16 @@ def _request_params_from_config(config: EmbeddingRuntimeConfig | None) -> dict[s
 class OpenAIEmbeddingProvider:
     """OpenAI ``/v1/embeddings`` wire-compatible embedding provider.
 
-    Construct with a base URL (host root), the bound embedding model, and
-    an optional API key + transport. ``embed()`` posts to
-    ``/v1/embeddings``.
+    Construct with the bound embedding model and an optional API key +
+    transport. ``base_url`` is the host root and defaults to the OpenAI
+    origin (``https://api.openai.com``), overridable for any OpenAI-compatible
+    backend. ``embed()`` posts to ``/v1/embeddings``.
+
+    The optional ``query_prefix`` / ``document_prefix`` bind the client-side
+    asymmetric prefixes -- off by default (pure-symmetric OpenAI). When bound
+    (for an asymmetric model served behind a compatible endpoint),
+    ``input_type`` selects which prefix to prepend to each input before
+    sending, since the OpenAI wire carries no query/document field.
 
     ``ready()`` verifies the bound model per the ``readiness_probe``
     argument:
@@ -120,13 +135,15 @@ class OpenAIEmbeddingProvider:
     def __init__(
         self,
         *,
-        base_url: str,
+        base_url: str = "https://api.openai.com",
         model: str,
         api_key: str | None = None,
         transport: httpx.AsyncBaseTransport | None = None,
         timeout: float = 60.0,
         genai_system: str = "openai",
         readiness_probe: Literal["embed", "models", "both"] = "embed",
+        query_prefix: str | None = None,
+        document_prefix: str | None = None,
         populate_caller_metadata: bool = True,
     ) -> None:
         # base_url is the host root; the provider appends the /v1 routes, so
@@ -143,6 +160,11 @@ def __init__(
                 f"readiness_probe must be one of {sorted(_VALID_READINESS_PROBES)} (got {readiness_probe!r})"
             )
         self._readiness_probe = readiness_probe
+        # Optional client-side asymmetric prefixes (§8.1, reused by §8.3): the
+        # OpenAI wire has no query/document field, so input_type is realized as
+        # a prefix prepend only when these are bound. Off by default (symmetric).
+        self._query_prefix = query_prefix
+        self._document_prefix = document_prefix
         # ``genai_system`` surfaces as gen_ai.system on the embedding span.
         self._genai_system = genai_system
         self._populate_caller_metadata = populate_caller_metadata
@@ -229,10 +251,12 @@ async def embed(
         input_strings = list(input)
         request_params = _request_params_from_config(config)
         request_extras = dict(config.model_extra or {}) if config is not None else {}
+        input_type = config.input_type if config is not None else None
+        dimensions = config.dimensions if config is not None else None
         adapter_start = time.perf_counter()
         try:
             validate_embedding_input(input_strings)
-            body = self._build_request_body(input_strings, request_params, request_extras)
+            body = self._build_request_body(input_strings, input_type, dimensions, request_extras)
             try:
                 resp = await self._client.post("/v1/embeddings", json=body)
             except httpx.HTTPError as exc:
@@ -281,18 +305,38 @@ async def embed(
     def _build_request_body(
         self,
         input_strings: list[str],
-        request_params: dict[str, Any],
+        input_type: str | None,
+        dimensions: int | None,
         request_extras: dict[str, Any],
     ) -> dict[str, Any]:
-        """Build the /v1/embeddings request body."""
-        # Extras are merged FIRST so the bound model, the input list, and the
-        # declared request params always win: a caller's undeclared extra
-        # named "model" or "input" must not clobber the wire identity. The
-        # request params are the same dict the event carries (dimensions for
-        # embedding), keeping the wire body and the observed request_params
-        # provably identical. Proposal 0077's input_type maps to a per-vendor
-        # wire key at the wire layer.
-        return {**request_extras, "model": self.model, "input": input_strings, **request_params}
+        """Build the /v1/embeddings request body.
+
+        The OpenAI wire has no query/document field, so ``input_type`` is not
+        realized on the wire -- it selects a client-side ``query_prefix`` /
+        ``document_prefix`` prepend when one is bound, and is otherwise a wire
+        no-op (``input`` sent verbatim). ``dimensions`` maps to the wire
+        ``dimensions`` field (Matryoshka) when set.
+        """
+        # input_type is realized as a client-side prefix (§8.1, reused by §8.3):
+        # the OpenAI wire has NO query/document/input_type/task field, so an
+        # input_type with no bound prefix leaves the input VERBATIM (the
+        # symmetric no-op). input_type MUST NEVER land on the wire. Extras merge
+        # FIRST so the managed keys (model, input, dimensions) always win: a
+        # caller's undeclared extra named "model" or "input" must not clobber
+        # the wire identity. encoding_format ("base64") rides the extras bag as
+        # a request pass-through only -- _parse_response decodes float embeddings
+        # (not base64 strings), so a base64 response raises
+        # provider_invalid_response; base64 is not an end-to-end response format.
+        inputs = apply_client_side_prefix(
+            input_strings,
+            input_type,
+            query_prefix=self._query_prefix,
+            document_prefix=self._document_prefix,
+        )
+        body: dict[str, Any] = {**request_extras, "model": self.model, "input": inputs}
+        if dimensions is not None:
+            body["dimensions"] = dimensions
+        return body
 
     def _parse_response(
         self,

src/openarmature/retrieval/providers/tei.py

@@ -50,6 +50,7 @@
 from openarmature.observability.correlation import current_dispatch
 
 from .._events import (
+    apply_client_side_prefix,
     build_embedding_event,
     build_embedding_failed_event,
     build_rerank_event,
@@ -317,24 +318,19 @@ def _build_request_body(
             else:
                 # Client-side prefix fallback: prepend for models without
                 # configured prompts. Only "query" / "document" have prefixes.
-                prefix = self._prefix_for(input_type)
-                if prefix is not None:
-                    inputs = [prefix + s for s in inputs]
+                inputs = apply_client_side_prefix(
+                    inputs,
+                    input_type,
+                    query_prefix=self._query_prefix,
+                    document_prefix=self._document_prefix,
+                )
         body: dict[str, Any] = {**request_extras, "inputs": inputs}
         if prompt_name is not None:
             body["prompt_name"] = prompt_name
         if dimensions is not None:
             body["dimensions"] = dimensions
         return body
 
-    def _prefix_for(self, input_type: str) -> str | None:
-        """Return the client-side prefix for ``input_type``, or ``None``."""
-        if input_type == "query":
-            return self._query_prefix
-        if input_type == "document":
-            return self._document_prefix
-        return None
-
     def _parse_response(
         self,
         resp: httpx.Response,