needlepath 0.1.0__py3-none-any.whl

needlepath/client.py

@@ -0,0 +1,947 @@
+"""The framework-free core client.
+
+Two clients, one behaviour: :class:`NeedlepathClient` (sync) and
+:class:`AsyncNeedlepathClient`. Everything that decides *what happens* lives in
+module-level helpers shared by both, so the async client cannot drift from the
+sync one — the failure mode that makes most dual-API SDKs quietly wrong.
+
+The three binding rules of §8.2 are implemented here and nowhere else:
+
+* **Fail open, always.** :meth:`NeedlepathClient.select` has no raising path.
+  Every error becomes a :class:`~needlepath.result.SelectionResult` with
+  ``applied=False`` and the exception recorded on ``.error``.
+* **Pin the operating point explicitly.** The constructor requires one.
+* **Guard the 6 MB cap client-side.** The body is measured before it is sent.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import time
+import uuid
+from typing import AbstractSet, Any, Dict, Optional, Sequence, Tuple
+from urllib.parse import urlsplit
+
+from . import features
+from .errors import (
+    NeedlepathConfigError,
+    NeedlepathContractError,
+    NeedlepathError,
+    NeedlepathHTTPError,
+    NeedlepathPayloadTooLargeError,
+    NeedlepathTimeoutError,
+    NeedlepathTransportError,
+)
+from .models import (
+    REQUIRED_RESPONSE_FIELDS,
+    AdaptiveBudget,
+    BudgetSpec,
+    ContextRecord,
+    ContextRequest,
+    ContextResponse,
+    TaskSpec,
+)
+from .result import Reason, SelectionResult
+from .transport import (
+    AsyncTransport,
+    HttpResult,
+    Transport,
+    UrllibTransport,
+    default_async_transport,
+)
+from .version import __version__
+
+# --------------------------------------------------------------------------- #
+# Documented defaults
+# --------------------------------------------------------------------------- #
+
+#: The documented default endpoint. A durable custom domain replaces this in E1's
+#: follow-through (§5, S-17a); until it exists this is the address published runs
+#: and design partners use, and it stays overridable by argument or by
+#: ``NEEDLEPATH_BASE_URL`` so that swapping it is a config change, not a release.
+DEFAULT_BASE_URL = "https://ayf02egtaf.execute-api.us-east-2.amazonaws.com/prod"
+
+SELECT_PATH = "/v1/context/select"
+HEALTH_PATH = "/v1/health"
+OPERATING_POINTS_PATH = "/v1/operating-points"
+
+#: API Gateway REST caps a request at 10 MB; Lambda caps a synchronous payload
+#: at 6 MB. 6 MB is therefore the real contract limit for one select call, and
+#: §8.2 requires the client to guard it rather than surface a platform error.
+#:
+#: Measured against the **JSON body**. The Lambda limit applies to the whole
+#: invocation payload — the API Gateway event envelope (headers, request
+#: context, base64 expansion when a body is not UTF-8-clean) sits on top of the
+#: body — so a request that passes this guard at 5.99 MB can still be rejected
+#: upstream. Lower ``max_request_bytes`` if you routinely run near the cap; the
+#: honest guard is the one that says what it does not cover.
+MAX_REQUEST_BYTES = 6 * 1024 * 1024
+
+DEFAULT_TIMEOUT_S = 10.0
+DEFAULT_MAX_RETRIES = 2
+
+#: Retried. Every one of these is a transient condition where a second attempt
+#: has a real chance of a different answer.
+RETRY_STATUSES = frozenset({429, 502, 503, 504})
+
+#: **Not** retried, and worth saying why: a 500 from this endpoint is
+#: ``engine_error`` — a deterministic failure on this exact input. Retrying it
+#: buys nothing, doubles the latency the caller waits before failing open, and
+#: spends a second billable invocation on a request that will fail identically.
+
+ENV_BASE_URL = "NEEDLEPATH_BASE_URL"
+ENV_API_KEY = "NEEDLEPATH_API_KEY"
+ENV_OPERATING_POINT = "NEEDLEPATH_OPERATING_POINT"
+
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"})
+
+
+# --------------------------------------------------------------------------- #
+# Configuration resolution — shared, so both clients resolve identically
+# --------------------------------------------------------------------------- #
+
+
+def _resolve_base_url(base_url: Optional[str]) -> str:
+    raw = base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL
+    raw = raw.strip().rstrip("/")
+    parts = urlsplit(raw)
+    if parts.scheme not in ("http", "https"):
+        raise NeedlepathConfigError(f"base_url must be http or https, got {parts.scheme!r}")
+    host = (parts.hostname or "").lower()
+    if parts.scheme == "http" and host not in _LOOPBACK_HOSTS:
+        # "TLS only" is an inherited binding constraint, not a preference
+        # (NEEDLEPATH_SAAS_DESIGN §0). Loopback is exempted because the
+        # localhost benchmark adapter is plain HTTP by design and is the seam's
+        # whole reason for existing.
+        raise NeedlepathConfigError(
+            f"base_url must use https for any non-loopback host (TLS only); got http://{host}"
+        )
+    if not host:
+        raise NeedlepathConfigError(f"base_url has no host: {raw!r}")
+    return raw
+
+
+def _resolve_operating_point(operating_point: Optional[str]) -> str:
+    value = operating_point or os.environ.get(ENV_OPERATING_POINT)
+    if not value or not value.strip():
+        raise NeedlepathConfigError(
+            "operating_point is required. Pin an immutable label explicitly "
+            "(e.g. 'np-2026-07-r2') so behaviour never shifts under you when the "
+            "service default moves; see docs/needlepath/API_VERSIONING.md. "
+            f"Pass operating_point=... or set {ENV_OPERATING_POINT}."
+        )
+    return value.strip()
+
+
+def _resolve_api_key(api_key: Optional[str]) -> Optional[str]:
+    # An explicitly-passed empty string means "no auth" (the localhost adapter);
+    # None means "look in the environment".
+    if api_key is not None:
+        return api_key.strip() or None
+    env = os.environ.get(ENV_API_KEY)
+    return env.strip() if env and env.strip() else None
+
+
+def new_request_id() -> str:
+    """A request id inside the published identifier charset.
+
+    ``[A-Za-z0-9._:-]``, at most 128 characters (§1.3). Staying inside it means
+    the endpoint never has to sanitize ours, so ``format_metrics`` comes back
+    byte-identical to a conformant caller's.
+    """
+    return "np-" + uuid.uuid4().hex
+
+
+# --------------------------------------------------------------------------- #
+# Request assembly and response classification — shared by both clients
+# --------------------------------------------------------------------------- #
+
+
+def build_request(
+    *,
+    records: Sequence[ContextRecord],
+    task: TaskSpec,
+    max_context_tokens: int,
+    operating_point: str,
+    request_id: Optional[str] = None,
+    max_records: Optional[int] = None,
+    max_excerpt_tokens_per_record: Optional[int] = None,
+    mode: str = "fixed",
+    adaptive: Optional[AdaptiveBudget] = None,
+    require_evidence_coverage: Optional[bool] = None,
+    render: bool = True,
+    render_format: str = "plain",
+    return_per_record: bool = True,
+) -> ContextRequest:
+    """Assemble a :class:`ContextRequest` with the operating point already pinned."""
+    return ContextRequest(
+        request_id=request_id or new_request_id(),
+        records=list(records),
+        task=task,
+        budget=BudgetSpec(
+            max_context_tokens=max_context_tokens,
+            operating_point=operating_point,
+            max_records=max_records,
+            max_excerpt_tokens_per_record=max_excerpt_tokens_per_record,
+            mode=mode,
+            adaptive=adaptive,
+            require_evidence_coverage=require_evidence_coverage,
+        ),
+        render=render,
+        render_format=render_format,
+        return_per_record=return_per_record,
+    )
+
+
+def encode_body(request: ContextRequest, *, shadow: bool) -> bytes:
+    """Serialize the request, applying the shadow feature flag.
+
+    Compact separators are used because every byte counts against the 6 MB
+    guard; the JSON is otherwise identical to the published client's.
+    """
+    wire = request.to_wire()
+    if shadow and features.wire_shadow_mode_enabled():
+        wire["budget"]["mode"] = features.WIRE_SHADOW_MODE_VALUE
+    return json.dumps(wire, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def validate_response_payload(payload: Any, request_id: str) -> ContextResponse:
+    """Parse and contract-check a 2xx body.
+
+    Raises :class:`NeedlepathContractError` on anything a caller cannot trust to
+    describe *this* request. Unknown fields are kept, never rejected — the
+    contract is additive under ``/v1``.
+    """
+    if not isinstance(payload, dict):
+        raise NeedlepathContractError(f"response is not a JSON object: {type(payload).__name__}")
+    missing = [f for f in REQUIRED_RESPONSE_FIELDS if f not in payload]
+    if missing:
+        raise NeedlepathContractError(f"response missing required fields: {missing}")
+    echoed = payload.get("request_id")
+    if echoed != request_id:
+        raise NeedlepathContractError(
+            f"response request_id {echoed!r} does not echo the request's {request_id!r}"
+        )
+    try:
+        return ContextResponse.from_wire(payload)
+    except (KeyError, TypeError, ValueError) as exc:
+        raise NeedlepathContractError(f"malformed response body: {exc}") from exc
+
+
+def classify(
+    response: ContextResponse,
+    *,
+    render_requested: bool = True,
+    require_per_record: bool = True,
+    known_record_ids: Optional[AbstractSet[str]] = None,
+) -> str:
+    """Decide whether a contract-valid response is safe to *apply*.
+
+    This is the NEXPE-413 rule, generalized. An empty selection returned as a
+    success is a defect at the engine boundary; at a framework boundary it must
+    degrade to passthrough, never to an empty context. So must every other way
+    the service can say "I did not select anything useful".
+
+    Note what this function does **not** do: it never reads ``gate.reason``.
+    That value is an open enum with a planned third outcome, and a client that
+    branches on today's prefixes is a client that breaks additively. Every
+    decision here comes from a structural field.
+    """
+    if response.selection_error:
+        return Reason.SELECTION_ERROR
+    if response.fallback_used:
+        # The engine stood down and is asking for the full context. Applying a
+        # fallback render would at best be a no-op and at worst a lossy one.
+        return Reason.ENGINE_FALLBACK
+    safety = response.safety
+    if safety is not None and (safety.fallback_required or not safety.selection_safe):
+        # The coverage verdict is a structural field, not the open enum: it says
+        # in as many words that this selection should not be used.
+        return Reason.SELECTION_UNSAFE
+    if response.records_selected <= 0:
+        return Reason.EMPTY_SELECTION
+    if render_requested and not response.rendered_context.strip():
+        return Reason.EMPTY_SELECTION
+    if require_per_record and not response.selected:
+        return Reason.NO_PER_RECORD_DETAIL
+    # A response whose selected ids are all unknown to us is the most destructive
+    # shape there is: an adapter that maps "not in the selection" to a
+    # placeholder would collapse EVERY record the caller sent. Refuse it here,
+    # once, rather than in each adapter.
+    if (
+        known_record_ids is not None
+        and response.selected
+        and not (response.selected_ids & set(known_record_ids))
+    ):
+        return Reason.UNKNOWN_SELECTION
+    return Reason.OK
+
+
+def _retry_after_seconds(headers: Dict[str, str]) -> Optional[float]:
+    """Parse ``Retry-After`` when it is a delta-seconds value.
+
+    HTTP-date form is deliberately not honoured: it needs a clock-skew argument
+    to be correct, and this client's backoff is already bounded by the caller's
+    deadline, so ignoring it degrades to the default backoff rather than to
+    anything wrong.
+    """
+    raw = headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        value = float(raw.strip())
+    except (TypeError, ValueError):
+        return None
+    return value if value >= 0 else None
+
+
+class _Backoff:
+    """Full-jitter exponential backoff, bounded by the caller's deadline."""
+
+    def __init__(self, base: float = 0.1, cap: float = 2.0, rng: Optional[random.Random] = None):
+        self._base = base
+        self._cap = cap
+        self._rng = rng or random.Random()
+
+    def delay(self, attempt: int, retry_after: Optional[float], remaining: float) -> float:
+        window = min(self._cap, self._base * (2**attempt))
+        wait = retry_after if retry_after is not None else self._rng.uniform(0.0, window)
+        # Leave room to actually make the next attempt.
+        return max(0.0, min(wait, max(0.0, remaining - 0.05)))
+
+
+# --------------------------------------------------------------------------- #
+# Base
+# --------------------------------------------------------------------------- #
+
+
+class _ClientBase:
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        operating_point: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT_S,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_request_bytes: int = MAX_REQUEST_BYTES,
+        shadow: bool = False,
+        user_agent_suffix: Optional[str] = None,
+    ) -> None:
+        self.base_url = _resolve_base_url(base_url)
+        self.operating_point = _resolve_operating_point(operating_point)
+        self._api_key = _resolve_api_key(api_key)
+        if timeout <= 0:
+            raise NeedlepathConfigError(f"timeout must be positive, got {timeout!r}")
+        if max_retries < 0:
+            raise NeedlepathConfigError(f"max_retries must be >= 0, got {max_retries!r}")
+        if max_request_bytes <= 0:
+            raise NeedlepathConfigError(
+                f"max_request_bytes must be positive, got {max_request_bytes!r}"
+            )
+        self.timeout = float(timeout)
+        self.max_retries = int(max_retries)
+        self.max_request_bytes = int(max_request_bytes)
+        self.shadow = bool(shadow)
+        self._user_agent = f"needlepath-python/{__version__}"
+        if user_agent_suffix:
+            self._user_agent += f" {user_agent_suffix}"
+        self._backoff = _Backoff()
+
+    # ---------------------------------------------------------------- #
+
+    def __repr__(self) -> str:
+        # The API key is never rendered. Whether one is configured is useful;
+        # its value is not, and this object ends up in tracebacks and log lines.
+        return (
+            f"{type(self).__name__}(base_url={self.base_url!r}, "
+            f"operating_point={self.operating_point!r}, "
+            f"api_key={'set' if self._api_key else 'unset'}, "
+            f"shadow={self.shadow!r})"
+        )
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "content-type": "application/json",
+            "accept": "application/json",
+            "user-agent": self._user_agent,
+        }
+        if self._api_key:
+            headers["authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _prepare(
+        self, request: ContextRequest, shadow: bool
+    ) -> Tuple[bytes, Optional[NeedlepathPayloadTooLargeError]]:
+        body = encode_body(request, shadow=shadow)
+        if len(body) > self.max_request_bytes:
+            return body, NeedlepathPayloadTooLargeError(len(body), self.max_request_bytes)
+        return body, None
+
+    @staticmethod
+    def _to_error(result: HttpResult) -> Optional[NeedlepathHTTPError]:
+        if 200 <= result.status < 300:
+            return None
+        return NeedlepathHTTPError(
+            result.status,
+            body=result.json(),
+            text=result.text(),
+            retry_after=_retry_after_seconds(result.headers),
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Sync
+# --------------------------------------------------------------------------- #
+
+
+class NeedlepathClient(_ClientBase):
+    """Synchronous client for the Needlepath hosted context-selection service.
+
+    ::
+
+        from needlepath import NeedlepathClient, ContextRecord, TaskSpec
+
+        client = NeedlepathClient(
+            api_key="np_live_...",              # or NEEDLEPATH_API_KEY
+            operating_point="np-2026-07-r2",    # required, and immutable
+        )
+        result = client.select(
+            records=[ContextRecord(text=..., kind="tool_result", id="r1")],
+            task=TaskSpec(prompt="what is the invoice total?"),
+            max_context_tokens=4000,
+        )
+        if result.applied:
+            use(result.rendered_context)
+        else:
+            use(my_original_context)          # always safe, always available
+
+    :param api_key: ``np_live_…``. Falls back to ``NEEDLEPATH_API_KEY``. Pass
+        ``""`` to send no ``Authorization`` header (the localhost adapter).
+    :param operating_point: **Required.** An immutable label such as
+        ``np-2026-07-r2``. Falls back to ``NEEDLEPATH_OPERATING_POINT``.
+    :param base_url: Defaults to :data:`DEFAULT_BASE_URL` or ``NEEDLEPATH_BASE_URL``.
+    :param timeout: Total wall-clock deadline for one :meth:`select`, retries
+        and backoff included. Not a per-attempt timeout.
+    :param max_retries: Extra attempts after the first, for transient statuses
+        and transport failures only.
+    :param shadow: Default shadow mode for this client. See
+        :mod:`needlepath.features`.
+    """
+
+    def __init__(self, *, transport: Optional[Transport] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._transport: Transport = transport or UrllibTransport()
+        self._owns_transport = transport is None
+
+    # ---------------------------------------------------------------- #
+    # The fail-open surface
+    # ---------------------------------------------------------------- #
+
+    def select(
+        self,
+        *,
+        records: Sequence[ContextRecord],
+        task: TaskSpec,
+        max_context_tokens: int,
+        request_id: Optional[str] = None,
+        shadow: Optional[bool] = None,
+        require_per_record: bool = True,
+        **budget_kwargs: Any,
+    ) -> SelectionResult:
+        """Select context. **Never raises.**
+
+        Any keyword accepted by :func:`build_request` other than ``operating_point``
+        may be passed through ``budget_kwargs`` (``max_records``, ``mode``,
+        ``adaptive``, ``render_format``, …).
+        """
+        if _is_empty(records):
+            return SelectionResult.passthrough_result(
+                Reason.NO_RECORDS,
+                request_id=request_id or "",
+                operating_point=self.operating_point,
+                shadow=self.shadow if shadow is None else bool(shadow),
+            )
+        try:
+            request = build_request(
+                records=records,
+                task=task,
+                max_context_tokens=max_context_tokens,
+                operating_point=self.operating_point,
+                request_id=request_id,
+                **budget_kwargs,
+            )
+        except Exception as exc:  # noqa: BLE001 - assembling must not be a crash path
+            return SelectionResult.passthrough_result(
+                Reason.UNEXPECTED_ERROR,
+                request_id=request_id or "",
+                operating_point=self.operating_point,
+                error=exc,
+            )
+        return self.select_request(request, shadow=shadow, require_per_record=require_per_record)
+
+    def select_request(
+        self,
+        request: ContextRequest,
+        *,
+        shadow: Optional[bool] = None,
+        require_per_record: bool = True,
+        timeout: Optional[float] = None,
+    ) -> SelectionResult:
+        """Select context from an assembled request. **Never raises.**"""
+        is_shadow = self.shadow if shadow is None else bool(shadow)
+        started = time.perf_counter()
+        try:
+            response, attempts, size = self._call(request, is_shadow, timeout)
+            # `_finish` is INSIDE the boundary on purpose. It reads fields off a
+            # body that came from a socket; a malformed one (`rendered_context`
+            # as a number, say) would otherwise raise here, outside every
+            # except-clause, and reach the caller as a crash.
+            return _finish(
+                response,
+                request=request,
+                operating_point=self.operating_point,
+                shadow=is_shadow,
+                require_per_record=require_per_record,
+                client_latency_ms=(time.perf_counter() - started) * 1000.0,
+                attempts=attempts,
+                request_bytes=size,
+            )
+        except NeedlepathError as exc:
+            return SelectionResult.passthrough_result(
+                _reason_for(exc),
+                request_id=request.request_id,
+                operating_point=self.operating_point,
+                shadow=is_shadow,
+                error=exc,
+                client_latency_ms=(time.perf_counter() - started) * 1000.0,
+                attempts=getattr(exc, "_np_attempts", 0),
+                request_bytes=getattr(exc, "_np_bytes", 0),
+            )
+        except Exception as exc:  # noqa: BLE001 - a defect here must still fail open
+            return SelectionResult.passthrough_result(
+                Reason.UNEXPECTED_ERROR,
+                request_id=request.request_id,
+                operating_point=self.operating_point,
+                shadow=is_shadow,
+                error=exc,
+                client_latency_ms=(time.perf_counter() - started) * 1000.0,
+            )
+
+    def select_or_raise(
+        self,
+        request: ContextRequest,
+        *,
+        shadow: Optional[bool] = None,
+        timeout: Optional[float] = None,
+    ) -> ContextResponse:
+        """Select context, raising on any error path.
+
+        **Not for framework adapters.** §8.2's fail-open rule is binding at a
+        framework boundary, and this method exists for the two places it does
+        not apply: diagnostics, and callers who are themselves a benchmark and
+        must not silently substitute a passthrough for a measurement.
+        """
+        response, _attempts, _size = self._call(
+            request, self.shadow if shadow is None else bool(shadow), timeout
+        )
+        return response
+
+    # ---------------------------------------------------------------- #
+
+    def _call(
+        self, request: ContextRequest, shadow: bool, timeout: Optional[float]
+    ) -> Tuple[ContextResponse, int, int]:
+        body, oversize = self._prepare(request, shadow)
+        if oversize is not None:
+            oversize._np_bytes = len(body)  # type: ignore[attr-defined]
+            raise oversize
+        deadline = time.monotonic() + float(timeout if timeout is not None else self.timeout)
+        url = self._url(SELECT_PATH)
+        headers = self._headers()
+        last: Optional[NeedlepathError] = None
+        attempts = 0
+        for attempt in range(self.max_retries + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            attempts += 1
+            try:
+                http = self._transport.request(
+                    "POST", url, headers=headers, body=body, timeout=remaining
+                )
+                err = self._to_error(http)
+                if err is None:
+                    if time.monotonic() > deadline:
+                        # Defence in depth behind the transport's own read
+                        # deadline: a response that arrives after the caller's
+                        # budget is not a response the caller asked for.
+                        raise NeedlepathTimeoutError(
+                            "a response arrived after the deadline had elapsed"
+                        )
+                    response = validate_response_payload(http.json(), request.request_id)
+                    return response, attempts, len(body)
+                last = err
+                if http.status not in RETRY_STATUSES:
+                    break
+                retry_after = err.retry_after
+            except (NeedlepathTransportError, NeedlepathTimeoutError) as exc:
+                last = exc
+                retry_after = None
+            except NeedlepathContractError as exc:
+                # A conformant server does not do this; a second attempt at the
+                # same build will not do it differently.
+                last = exc
+                break
+            if attempt >= self.max_retries:
+                break
+            delay = self._backoff.delay(attempt, retry_after, deadline - time.monotonic())
+            if delay <= 0 and deadline - time.monotonic() <= 0:
+                break
+            if delay:
+                time.sleep(delay)
+        if last is None:  # pragma: no cover - only when the deadline was already past
+            last = NeedlepathTimeoutError("deadline elapsed before any attempt was made")
+        last._np_attempts = attempts  # type: ignore[attr-defined]
+        last._np_bytes = len(body)  # type: ignore[attr-defined]
+        raise last
+
+    # ---------------------------------------------------------------- #
+    # Diagnostics. These raise: they are not on any agent's hot path.
+    # ---------------------------------------------------------------- #
+
+    def health(self, *, timeout: Optional[float] = None) -> Dict[str, Any]:
+        """``GET /v1/health``. Raises on failure."""
+        return self._get(HEALTH_PATH, timeout)
+
+    def operating_points(self, *, timeout: Optional[float] = None) -> Dict[str, Any]:
+        """``GET /v1/operating-points``. Raises on failure.
+
+        Useful once, at wire-up, to assert that the label you pinned is one the
+        endpoint actually serves. Do not call it per request.
+        """
+        return self._get(OPERATING_POINTS_PATH, timeout)
+
+    def _get(self, path: str, timeout: Optional[float]) -> Dict[str, Any]:
+        http = self._transport.request(
+            "GET",
+            self._url(path),
+            headers=self._headers(),
+            body=None,
+            timeout=float(timeout if timeout is not None else self.timeout),
+        )
+        err = self._to_error(http)
+        if err is not None:
+            raise err
+        payload = http.json()
+        if not isinstance(payload, dict):
+            raise NeedlepathContractError(f"{path} did not return a JSON object")
+        return payload
+
+    # ---------------------------------------------------------------- #
+
+    def close(self) -> None:
+        if self._owns_transport:
+            self._transport.close()
+
+    def __enter__(self) -> NeedlepathClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+# --------------------------------------------------------------------------- #
+# Async
+# --------------------------------------------------------------------------- #
+
+
+class AsyncNeedlepathClient(_ClientBase):
+    """Asynchronous twin of :class:`NeedlepathClient`.
+
+    Identical behaviour, identical results — the decision logic is the same
+    module-level functions. Uses ``httpx.AsyncClient`` when httpx is importable
+    and a worker thread otherwise, so it never blocks the event loop either way.
+    """
+
+    def __init__(self, *, transport: Optional[AsyncTransport] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._transport: AsyncTransport = transport or default_async_transport()
+        self._owns_transport = transport is None
+
+    async def select(
+        self,
+        *,
+        records: Sequence[ContextRecord],
+        task: TaskSpec,
+        max_context_tokens: int,
+        request_id: Optional[str] = None,
+        shadow: Optional[bool] = None,
+        require_per_record: bool = True,
+        **budget_kwargs: Any,
+    ) -> SelectionResult:
+        """Select context. **Never raises.**"""
+        if _is_empty(records):
+            return SelectionResult.passthrough_result(
+                Reason.NO_RECORDS,
+                request_id=request_id or "",
+                operating_point=self.operating_point,
+                shadow=self.shadow if shadow is None else bool(shadow),
+            )
+        try:
+            request = build_request(
+                records=records,
+                task=task,
+                max_context_tokens=max_context_tokens,
+                operating_point=self.operating_point,
+                request_id=request_id,
+                **budget_kwargs,
+            )
+        except Exception as exc:  # noqa: BLE001
+            return SelectionResult.passthrough_result(
+                Reason.UNEXPECTED_ERROR,
+                request_id=request_id or "",
+                operating_point=self.operating_point,
+                error=exc,
+            )
+        return await self.select_request(
+            request, shadow=shadow, require_per_record=require_per_record
+        )
+
+    async def select_request(
+        self,
+        request: ContextRequest,
+        *,
+        shadow: Optional[bool] = None,
+        require_per_record: bool = True,
+        timeout: Optional[float] = None,
+    ) -> SelectionResult:
+        """Select context from an assembled request. **Never raises.**"""
+        is_shadow = self.shadow if shadow is None else bool(shadow)
+        started = time.perf_counter()
+        try:
+            response, attempts, size = await self._call(request, is_shadow, timeout)
+            # Inside the boundary, for the same reason as the sync twin.
+            return _finish(
+                response,
+                request=request,
+                operating_point=self.operating_point,
+                shadow=is_shadow,
+                require_per_record=require_per_record,
+                client_latency_ms=(time.perf_counter() - started) * 1000.0,
+                attempts=attempts,
+                request_bytes=size,
+            )
+        except NeedlepathError as exc:
+            return SelectionResult.passthrough_result(
+                _reason_for(exc),
+                request_id=request.request_id,
+                operating_point=self.operating_point,
+                shadow=is_shadow,
+                error=exc,
+                client_latency_ms=(time.perf_counter() - started) * 1000.0,
+                attempts=getattr(exc, "_np_attempts", 0),
+                request_bytes=getattr(exc, "_np_bytes", 0),
+            )
+        except Exception as exc:  # noqa: BLE001
+            return SelectionResult.passthrough_result(
+                Reason.UNEXPECTED_ERROR,
+                request_id=request.request_id,
+                operating_point=self.operating_point,
+                shadow=is_shadow,
+                error=exc,
+                client_latency_ms=(time.perf_counter() - started) * 1000.0,
+            )
+
+    async def select_or_raise(
+        self,
+        request: ContextRequest,
+        *,
+        shadow: Optional[bool] = None,
+        timeout: Optional[float] = None,
+    ) -> ContextResponse:
+        """Select context, raising on any error path. Not for adapters."""
+        response, _attempts, _size = await self._call(
+            request, self.shadow if shadow is None else bool(shadow), timeout
+        )
+        return response
+
+    async def _call(
+        self, request: ContextRequest, shadow: bool, timeout: Optional[float]
+    ) -> Tuple[ContextResponse, int, int]:
+        body, oversize = self._prepare(request, shadow)
+        if oversize is not None:
+            oversize._np_bytes = len(body)  # type: ignore[attr-defined]
+            raise oversize
+        deadline = time.monotonic() + float(timeout if timeout is not None else self.timeout)
+        url = self._url(SELECT_PATH)
+        headers = self._headers()
+        last: Optional[NeedlepathError] = None
+        attempts = 0
+        for attempt in range(self.max_retries + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            attempts += 1
+            try:
+                http = await self._transport.request(
+                    "POST", url, headers=headers, body=body, timeout=remaining
+                )
+                err = self._to_error(http)
+                if err is None:
+                    if time.monotonic() > deadline:
+                        # Defence in depth behind the transport's own read
+                        # deadline: a response that arrives after the caller's
+                        # budget is not a response the caller asked for.
+                        raise NeedlepathTimeoutError(
+                            "a response arrived after the deadline had elapsed"
+                        )
+                    response = validate_response_payload(http.json(), request.request_id)
+                    return response, attempts, len(body)
+                last = err
+                if http.status not in RETRY_STATUSES:
+                    break
+                retry_after = err.retry_after
+            except (NeedlepathTransportError, NeedlepathTimeoutError) as exc:
+                last = exc
+                retry_after = None
+            except NeedlepathContractError as exc:
+                last = exc
+                break
+            if attempt >= self.max_retries:
+                break
+            delay = self._backoff.delay(attempt, retry_after, deadline - time.monotonic())
+            if delay <= 0 and deadline - time.monotonic() <= 0:
+                break
+            if delay:
+                await asyncio.sleep(delay)
+        if last is None:  # pragma: no cover
+            last = NeedlepathTimeoutError("deadline elapsed before any attempt was made")
+        last._np_attempts = attempts  # type: ignore[attr-defined]
+        last._np_bytes = len(body)  # type: ignore[attr-defined]
+        raise last
+
+    async def health(self, *, timeout: Optional[float] = None) -> Dict[str, Any]:
+        return await self._aget(HEALTH_PATH, timeout)
+
+    async def operating_points(self, *, timeout: Optional[float] = None) -> Dict[str, Any]:
+        return await self._aget(OPERATING_POINTS_PATH, timeout)
+
+    async def _aget(self, path: str, timeout: Optional[float]) -> Dict[str, Any]:
+        http = await self._transport.request(
+            "GET",
+            self._url(path),
+            headers=self._headers(),
+            body=None,
+            timeout=float(timeout if timeout is not None else self.timeout),
+        )
+        err = self._to_error(http)
+        if err is not None:
+            raise err
+        payload = http.json()
+        if not isinstance(payload, dict):
+            raise NeedlepathContractError(f"{path} did not return a JSON object")
+        return payload
+
+    async def aclose(self) -> None:
+        if self._owns_transport:
+            await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncNeedlepathClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+# --------------------------------------------------------------------------- #
+# Shared outcome assembly
+# --------------------------------------------------------------------------- #
+
+
+def _is_empty(records: Any) -> bool:
+    """Whether there is nothing to select over, for any sequence-ish argument.
+
+    `not records` is the obvious spelling and it raises for anything with an
+    ambiguous truth value (a numpy array, a pandas Series) — outside the
+    fail-open boundary, because it runs before the request is even built.
+    """
+    try:
+        return len(records) == 0
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _reason_for(exc: NeedlepathError) -> str:
+    if isinstance(exc, NeedlepathPayloadTooLargeError):
+        return Reason.PAYLOAD_TOO_LARGE
+    if isinstance(exc, NeedlepathTimeoutError):
+        return Reason.TIMEOUT
+    if isinstance(exc, NeedlepathTransportError):
+        return Reason.TRANSPORT_ERROR
+    if isinstance(exc, NeedlepathHTTPError):
+        return Reason.HTTP_ERROR
+    if isinstance(exc, NeedlepathContractError):
+        return Reason.CONTRACT_ERROR
+    return Reason.UNEXPECTED_ERROR
+
+
+def _finish(
+    response: ContextResponse,
+    *,
+    request: ContextRequest,
+    operating_point: str,
+    shadow: bool,
+    require_per_record: bool,
+    client_latency_ms: float,
+    attempts: int,
+    request_bytes: int,
+) -> SelectionResult:
+    reason = classify(
+        response,
+        render_requested=request.render,
+        require_per_record=require_per_record and request.return_per_record,
+        known_record_ids={r.id for r in request.records if r.id},
+    )
+    # Shadow wins over OK and *loses* to every decline: a shadow run must report
+    # the same reason a live run would have, or the shadow report predicts an
+    # invoice for selections that would never have been applied.
+    if reason == Reason.OK and shadow:
+        reason = Reason.SHADOW
+    return SelectionResult(
+        applied=(reason == Reason.OK),
+        reason=reason,
+        request_id=request.request_id,
+        operating_point=operating_point,
+        shadow=shadow,
+        response=response,
+        error=None,
+        client_latency_ms=client_latency_ms,
+        attempts=attempts,
+        request_bytes=request_bytes,
+    )
+
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "SELECT_PATH",
+    "HEALTH_PATH",
+    "OPERATING_POINTS_PATH",
+    "MAX_REQUEST_BYTES",
+    "DEFAULT_TIMEOUT_S",
+    "DEFAULT_MAX_RETRIES",
+    "RETRY_STATUSES",
+    "NeedlepathClient",
+    "AsyncNeedlepathClient",
+    "build_request",
+    "encode_body",
+    "classify",
+    "validate_response_payload",
+    "new_request_id",
+]