Move retrieval wire helpers into _wire module (#214)

Move the shared wire-mapping helpers (normalize_base_url,
client_side_prefix, apply_client_side_prefix, document_echo) out of
retrieval/_events.py into a new retrieval/_wire.py, leaving _events.py as
the observability event builders only. The providers import helpers from
_wire and event builders from _events.

_events.py had accreted these non-event helpers as the retrieval wire
mappings landed; the _wire name states what belongs there (request-body
shaping, endpoint normalization, response parsing) and what does not.
Pure refactor, no behavior change.

Author: chris-colinsky

src/openarmature/retrieval/_events.py

@@ -19,15 +19,15 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from typing import Any, cast
+from typing import Any
 
 from openarmature.graph.events import (
     EmbeddingEvent,
     EmbeddingFailedEvent,
     RerankEvent,
     RerankFailedEvent,
 )
-from openarmature.llm.errors import LlmProviderError, ProviderInvalidResponse
+from openarmature.llm.errors import LlmProviderError
 from openarmature.observability.correlation import (
     current_attempt_index,
     current_branch_name,
@@ -41,98 +41,6 @@
 from .response import EmbeddingResponse, RerankResponse
 
 
-def normalize_base_url(base_url: str, *, guard_prefix: str) -> str:
-    """Strip a trailing slash from ``base_url`` and reject a doubled version prefix.
-
-    Returns the trailing-slash-stripped host root. Raises :class:`ValueError`
-    when the stripped value already ends in ``guard_prefix`` (e.g. ``"/v1"`` /
-    ``"/v2"``).
-    """
-    # base_url is the host root; the provider appends the versioned routes
-    # itself (e.g. /v1/embeddings, /v2/rerank), so a base_url that already ends
-    # in the version prefix would produce a doubled /v1/v1 (or /v2/v2) path that
-    # 404s. Guard the footgun at construction; trailing slashes are stripped.
-    normalized = base_url.rstrip("/")
-    if normalized.endswith(guard_prefix):
-        raise ValueError(
-            f"base_url should be the host root; the provider appends the "
-            f"{guard_prefix} routes itself, so a trailing {guard_prefix} would "
-            f"produce a doubled {guard_prefix}{guard_prefix} path. Got {base_url!r}."
-        )
-    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]
-
-
-# §6 (0097): the rerank document-echo shape rule, shared by every RerankProvider
-# (Cohere / TEI / Jina). ScoredDocument.document carries the provider's string
-# echo verbatim when present, null otherwise -- never fabricated from the input
-# documents. Vendors echo it in several shapes: a bare string, a TextDoc object
-# {"text": "..."} (Jina's return_documents form), a text-less object (an
-# ImageDoc), or absent/null. Unwrap the string from a string or a TextDoc; a
-# text-less object or absent/null yields null (an empty string is present --
-# surfaced as "", not folded to null). A NON-object scalar (number / array /
-# bool -- outside the documented anyOf[string, object, null]) is wire corruption
-# and raises provider_invalid_response (§7), NOT folded to null. The verbatim
-# echo is preserved on RerankResponse.raw regardless.
-def document_echo(value: Any) -> str | None:
-    """Extract the string document echo from a rerank result's documented shapes."""
-    if value is None:
-        return None
-    if isinstance(value, str):
-        return value
-    if isinstance(value, dict):
-        text = cast("dict[str, Any]", value).get("text")
-        return text if isinstance(text, str) else None
-    raise ProviderInvalidResponse(
-        f"rerank document echo must be a string, object, or null (got {type(value).__name__})"
-    )
-
-
 def build_embedding_event(
     response: EmbeddingResponse,
     latency_ms: float,
@@ -353,12 +261,8 @@ 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",
-    "document_echo",
-    "normalize_base_url",
 ]

src/openarmature/retrieval/_wire.py

@@ -0,0 +1,115 @@
+"""Shared wire-format helpers for the retrieval reference providers.
+
+Pure, stateless primitives reused across the vendor wire mappings:
+request-body shaping (the client-side ``input_type`` prefix), endpoint
+normalization (``base_url``), and response parsing (the rerank document echo).
+Types live in ``response.py``, the observability event builders in
+``_events.py``, and the provider protocols in ``provider.py``; only the
+mapping helpers belong here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from openarmature.llm.errors import ProviderInvalidResponse
+
+
+def normalize_base_url(base_url: str, *, guard_prefix: str) -> str:
+    """Strip a trailing slash from ``base_url`` and reject a doubled version prefix.
+
+    Returns the trailing-slash-stripped host root. Raises :class:`ValueError`
+    when the stripped value already ends in ``guard_prefix`` (e.g. ``"/v1"`` /
+    ``"/v2"``).
+    """
+    # base_url is the host root; the provider appends the versioned routes
+    # itself (e.g. /v1/embeddings, /v2/rerank), so a base_url that already ends
+    # in the version prefix would produce a doubled /v1/v1 (or /v2/v2) path that
+    # 404s. Guard the footgun at construction; trailing slashes are stripped.
+    normalized = base_url.rstrip("/")
+    if normalized.endswith(guard_prefix):
+        raise ValueError(
+            f"base_url should be the host root; the provider appends the "
+            f"{guard_prefix} routes itself, so a trailing {guard_prefix} would "
+            f"produce a doubled {guard_prefix}{guard_prefix} path. Got {base_url!r}."
+        )
+    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]
+
+
+# §6 (0097): the rerank document-echo shape rule, shared by every RerankProvider
+# (Cohere / TEI / Jina). ScoredDocument.document carries the provider's string
+# echo verbatim when present, null otherwise -- never fabricated from the input
+# documents. Vendors echo it in several shapes: a bare string, a TextDoc object
+# {"text": "..."} (Jina's return_documents form), a text-less object (an
+# ImageDoc), or absent/null. Unwrap the string from a string or a TextDoc; a
+# text-less object or absent/null yields null (an empty string is present --
+# surfaced as "", not folded to null). A NON-object scalar (number / array /
+# bool -- outside the documented anyOf[string, object, null]) is wire corruption
+# and raises provider_invalid_response (§7), NOT folded to null. The verbatim
+# echo is preserved on RerankResponse.raw regardless.
+def document_echo(value: Any) -> str | None:
+    """Extract the string document echo from a rerank result's documented shapes."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        text = cast("dict[str, Any]", value).get("text")
+        return text if isinstance(text, str) else None
+    raise ProviderInvalidResponse(
+        f"rerank document echo must be a string, object, or null (got {type(value).__name__})"
+    )
+
+
+__all__ = [
+    "apply_client_side_prefix",
+    "client_side_prefix",
+    "document_echo",
+    "normalize_base_url",
+]

src/openarmature/retrieval/providers/cohere.py

@@ -44,7 +44,8 @@
 )
 from openarmature.observability.correlation import current_dispatch
 
-from .._events import build_rerank_event, build_rerank_failed_event, document_echo, normalize_base_url
+from .._events import build_rerank_event, build_rerank_failed_event
+from .._wire import document_echo, normalize_base_url
 from ..provider import validate_rerank_input, validate_rerank_response
 from ..response import RerankResponse, RerankRuntimeConfig, RerankUsage, ScoredDocument
 

src/openarmature/retrieval/providers/jina.py

@@ -61,9 +61,8 @@
     build_embedding_failed_event,
     build_rerank_event,
     build_rerank_failed_event,
-    document_echo,
-    normalize_base_url,
 )
+from .._wire import document_echo, normalize_base_url
 from ..provider import (
     validate_embedding_input,
     validate_embedding_response,

src/openarmature/retrieval/providers/openai.py

@@ -41,12 +41,8 @@
 )
 from openarmature.observability.correlation import current_dispatch
 
-from .._events import (
-    apply_client_side_prefix,
-    build_embedding_event,
-    build_embedding_failed_event,
-    normalize_base_url,
-)
+from .._events import build_embedding_event, build_embedding_failed_event
+from .._wire import apply_client_side_prefix, normalize_base_url
 from ..provider import validate_embedding_input, validate_embedding_response
 from ..response import EmbeddingResponse, EmbeddingRuntimeConfig, EmbeddingUsage
 

src/openarmature/retrieval/providers/tei.py

@@ -50,13 +50,12 @@
 from openarmature.observability.correlation import current_dispatch
 
 from .._events import (
-    apply_client_side_prefix,
     build_embedding_event,
     build_embedding_failed_event,
     build_rerank_event,
     build_rerank_failed_event,
-    document_echo,
 )
+from .._wire import apply_client_side_prefix, document_echo
 from ..provider import (
     validate_embedding_input,
     validate_embedding_response,