needlepath 0.1.0__py3-none-any.whl

needlepath/transport.py

@@ -0,0 +1,316 @@
+"""The one transport/auth seam.
+
+``ADAPTER_API_DESIGN.md`` invariant 5 and §8 both ask for a single seam so that
+localhost, the hosted endpoint, a customer VPC deployment and a future MCP
+server are the same client. That seam is :class:`Transport` / :class:`AsyncTransport`:
+a two-method protocol over ``(method, url, headers, body) -> HttpResult``.
+
+The default sync implementation is **stdlib ``urllib``**. That is a deliberate
+dependency decision, not laziness: this client is dropped into agent stacks that
+already pin ``httpx``, ``requests``, ``pydantic`` and a framework, and a core
+client that can force a resolver conflict does not get adopted. The cost is that
+we write ~60 lines of HTTP by hand; the benefit is that ``pip install needlepath``
+can never break a customer's environment.
+
+The default async implementation prefers ``httpx.AsyncClient`` when it is
+importable and otherwise runs the sync transport on a worker thread. Both are
+correct; the first is better under a proxy's concurrency (LiteLLM), which is why
+it is preferred when available rather than required.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from .errors import NeedlepathTimeoutError, NeedlepathTransportError
+
+try:  # pragma: no cover - trivial
+    from typing import Protocol
+except ImportError:  # pragma: no cover - Python < 3.8 is unsupported anyway
+    Protocol = object  # type: ignore[assignment,misc]
+
+
+@dataclass
+class HttpResult:
+    """One HTTP response, decoded no further than bytes.
+
+    ``json_body`` is parsed lazily by the client so that a transport
+    implementation never has to care about content negotiation.
+    """
+
+    status: int
+    body: bytes
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    def json(self) -> Any:
+        """Parse the body as JSON, or return ``None`` when it is not JSON."""
+        if not self.body:
+            return None
+        try:
+            return json.loads(self.body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return None
+
+    def text(self) -> str:
+        try:
+            return self.body.decode("utf-8", errors="replace")
+        except Exception:  # pragma: no cover - decode with errors= cannot raise
+            return ""
+
+
+class Transport(Protocol):  # pragma: no cover - a structural type
+    """The synchronous seam."""
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult: ...
+
+    def close(self) -> None: ...
+
+
+class AsyncTransport(Protocol):  # pragma: no cover - a structural type
+    """The asynchronous seam."""
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult: ...
+
+    async def aclose(self) -> None: ...
+
+
+# --------------------------------------------------------------------------- #
+# Sync: stdlib
+# --------------------------------------------------------------------------- #
+
+
+class UrllibTransport:
+    """Zero-dependency sync transport on ``urllib.request``.
+
+    Notes on the two things urllib gets subtly wrong for our purposes:
+
+    * ``urlopen`` raises :class:`urllib.error.HTTPError` for a non-2xx, and that
+      exception *is* a response object. We turn it back into an
+      :class:`HttpResult` — a 429 or a 413 is data this client acts on, not an
+      exceptional condition at the transport layer.
+    * ``timeout`` on ``urlopen`` is a **socket inactivity** timeout, not a
+      wall-clock deadline. A server that drips one chunk every 25 ms keeps every
+      individual read under the timeout while the whole response takes as long
+      as it likes — so an "8 s deadline" client can wait a minute. The body is
+      therefore read in chunks against a real monotonic deadline, and the
+      timeout is enforced twice: by the socket, and by the clock.
+    """
+
+    #: Body read granularity. Small enough that the deadline is checked often,
+    #: large enough that a normal response is one or two reads.
+    READ_CHUNK_BYTES = 65536
+
+    def __init__(self, *, ssl_context: Optional[ssl.SSLContext] = None) -> None:
+        self._opener = urllib.request.build_opener(
+            urllib.request.HTTPSHandler(context=ssl_context)
+            if ssl_context
+            else urllib.request.HTTPSHandler()
+        )
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult:
+        req = urllib.request.Request(url=url, data=body, method=method)
+        for name, value in headers.items():
+            req.add_header(name, value)
+        deadline = time.monotonic() + timeout
+        try:
+            with self._opener.open(req, timeout=timeout) as resp:
+                return HttpResult(
+                    status=int(resp.status),
+                    body=self._read_bounded(resp, deadline, timeout),
+                    headers={k.lower(): v for k, v in resp.headers.items()},
+                )
+        except urllib.error.HTTPError as exc:
+            # Not an error at this layer: it is a response with a status.
+            try:
+                payload = self._read_bounded(exc, deadline, timeout)
+            except NeedlepathTimeoutError:
+                raise
+            except Exception:  # pragma: no cover - a closed error body
+                payload = b""
+            finally:
+                # `HTTPError` is itself a response object and owns a socket. If
+                # the read above blew up, nothing else closes it.
+                with contextlib.suppress(Exception):
+                    exc.close()
+            return HttpResult(
+                status=int(exc.code),
+                body=payload,
+                headers={k.lower(): v for k, v in (exc.headers or {}).items()},
+            )
+        except socket.timeout as exc:
+            raise NeedlepathTimeoutError(f"request timed out after {timeout:.3f}s") from exc
+        except urllib.error.URLError as exc:
+            reason = getattr(exc, "reason", exc)
+            if isinstance(reason, socket.timeout):
+                raise NeedlepathTimeoutError(f"request timed out after {timeout:.3f}s") from exc
+            raise NeedlepathTransportError(f"{type(reason).__name__}: {reason}") from exc
+        except (OSError, ValueError, ssl.SSLError) as exc:
+            raise NeedlepathTransportError(f"{type(exc).__name__}: {exc}") from exc
+
+    def _read_bounded(self, resp: Any, deadline: float, timeout: float) -> bytes:
+        """Read a body against a wall-clock deadline, not just a socket timeout.
+
+        ``read1`` rather than ``read``, and the difference is the whole point:
+        ``read(n)`` blocks until it has ``n`` bytes or hits EOF, so for a body
+        smaller than one chunk it is a single call that blocks for the entire
+        drip — the deadline would be checked once, after the wait. ``read1``
+        returns as soon as *any* data is available, so the loop gets to look at
+        the clock between chunks.
+
+        A reader without ``read1`` (an ``HTTPError`` on some versions) falls back
+        to ``read``; the deadline is then only bounded between chunks, which is
+        still better than not at all.
+        """
+        reader = getattr(resp, "read1", None) or resp.read
+        chunks = []
+        while True:
+            if time.monotonic() > deadline:
+                raise NeedlepathTimeoutError(
+                    f"response body did not complete within {timeout:.3f}s"
+                )
+            chunk = reader(self.READ_CHUNK_BYTES)
+            if not chunk:
+                return b"".join(chunks)
+            chunks.append(chunk)
+
+    def close(self) -> None:
+        self._opener.close()
+
+
+# --------------------------------------------------------------------------- #
+# Async
+# --------------------------------------------------------------------------- #
+
+
+class ThreadedAsyncTransport:
+    """Runs a sync :class:`Transport` on the default executor.
+
+    The fallback when ``httpx`` is not installed. It costs a worker thread per
+    in-flight request, which is fine for an agent and merely adequate for a
+    proxy — hence :func:`default_async_transport` preferring ``httpx``.
+    """
+
+    def __init__(self, inner: Optional[Transport] = None) -> None:
+        self._inner: Transport = inner or UrllibTransport()
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult:
+        loop = asyncio.get_running_loop()
+
+        def _call() -> HttpResult:
+            return self._inner.request(method, url, headers=headers, body=body, timeout=timeout)
+
+        # `wait_for` gives the CALLER a real deadline even though the worker
+        # thread cannot be cancelled — it will finish and be discarded. The
+        # inner transport enforces its own deadline too, so the orphaned thread
+        # is bounded rather than indefinite.
+        try:
+            return await asyncio.wait_for(loop.run_in_executor(None, _call), timeout)
+        except asyncio.TimeoutError as exc:
+            raise NeedlepathTimeoutError(f"request timed out after {timeout:.3f}s") from exc
+
+    async def aclose(self) -> None:
+        self._inner.close()
+
+
+class HttpxAsyncTransport:
+    """Async transport on ``httpx.AsyncClient``. Used when httpx is importable."""
+
+    def __init__(self, client: Any = None) -> None:
+        import httpx  # local import: httpx is an optional dependency
+
+        self._owns_client = client is None
+        self._client = client if client is not None else httpx.AsyncClient()
+        self._httpx = httpx
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult:
+        try:
+            # httpx's `timeout` is per-operation (connect/read/write each get
+            # it), so a drip-fed body can outlive it many times over. `wait_for`
+            # is the wall-clock bound the caller actually asked for.
+            resp = await asyncio.wait_for(
+                self._client.request(method, url, headers=headers, content=body, timeout=timeout),
+                timeout,
+            )
+        except asyncio.TimeoutError as exc:
+            raise NeedlepathTimeoutError(f"request timed out after {timeout:.3f}s") from exc
+        except self._httpx.TimeoutException as exc:
+            raise NeedlepathTimeoutError(f"request timed out after {timeout:.3f}s") from exc
+        except self._httpx.HTTPError as exc:
+            raise NeedlepathTransportError(f"{type(exc).__name__}: {exc}") from exc
+        return HttpResult(
+            status=int(resp.status_code),
+            body=resp.content,
+            headers={k.lower(): v for k, v in resp.headers.items()},
+        )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+
+def default_async_transport() -> AsyncTransport:
+    """``httpx`` when it is importable, a worker thread otherwise."""
+    try:
+        return HttpxAsyncTransport()
+    except ImportError:
+        return ThreadedAsyncTransport()
+
+
+__all__ = [
+    "HttpResult",
+    "Transport",
+    "AsyncTransport",
+    "UrllibTransport",
+    "ThreadedAsyncTransport",
+    "HttpxAsyncTransport",
+    "default_async_transport",
+]

needlepath/version.py

@@ -0,0 +1,10 @@
+"""Single source of truth for the package version.
+
+Kept in a module rather than read from installed metadata so that the User-Agent
+is correct when the package is run from a source checkout, which is how every
+one of our own integration tests runs it.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

needlepath-0.1.0.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: needlepath
+Version: 0.1.0
+Summary: Framework-free client for the Needlepath hosted context-selection service.
+Project-URL: Homepage, https://nextmoca.com
+Author: Next Moca Global, Inc.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,context,context-engineering,llm,needlepath
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24; extra == 'httpx'
+Description-Content-Type: text/markdown
+
+# `needlepath` — Python client
+
+The framework-free core client for the Needlepath hosted context-selection
+service. HTTP only, zero required dependencies, one transport/auth seam.
+
+Framework integrations are **separate distributions** and depend on this one:
+
+| Distribution | Seam |
+|---|---|
+| [`needlepath-langchain`](../needlepath-langchain) | `AgentMiddleware` (`wrap_model_call`, `wrap_tool_call`) + the LangGraph recipe |
+| [`needlepath-litellm`](../needlepath-litellm) | LiteLLM **proxy** `CustomGuardrail` |
+| [`llama-index-postprocessor-needlepath`](../llama-index-postprocessor-needlepath) | `BaseNodePostprocessor` |
+
+## Install
+
+```bash
+pip install needlepath
+pip install "needlepath[httpx]"   # optional: httpx-backed async transport
+```
+
+Python 3.9+. No required runtime dependencies — the default transport is stdlib
+`urllib`, so installing this client can never move a version you already pinned.
+
+## Quickstart
+
+```python
+from needlepath import NeedlepathClient, ContextRecord, TaskSpec
+
+client = NeedlepathClient(
+    api_key="np_live_...",  # or NEEDLEPATH_API_KEY
+    operating_point="np-2026-07-r2",  # required — see "Pin the operating point"
+)
+
+result = client.select(
+    records=[
+        ContextRecord(text=tool_output, kind="tool_result", id="lookup-1"),
+        ContextRecord(text=doc, kind="external_data", id="doc-7", title="SOP"),
+    ],
+    task=TaskSpec(prompt="what is the invoice total for A-1002?"),
+    max_context_tokens=4000,
+)
+
+context = result.rendered_context if result.applied else my_original_context
+```
+
+`select()` **never raises.** Read `result.applied`; when it is `False`, use your
+original context. That is the whole integration contract.
+
+### Async
+
+```python
+from needlepath import AsyncNeedlepathClient
+
+async with AsyncNeedlepathClient(operating_point="np-2026-07-r2") as client:
+    result = await client.select(records=..., task=..., max_context_tokens=4000)
+```
+
+Identical semantics — the decision logic is literally the same functions. Uses
+`httpx.AsyncClient` when httpx is importable, a worker thread otherwise; it
+never blocks the event loop either way.
+
+## Configuration
+
+| Argument | Environment | Default |
+|---|---|---|
+| `api_key` | `NEEDLEPATH_API_KEY` | none (no `Authorization` header) |
+| `operating_point` | `NEEDLEPATH_OPERATING_POINT` | **required** |
+| `base_url` | `NEEDLEPATH_BASE_URL` | `https://ayf02egtaf.execute-api.us-east-2.amazonaws.com/prod` |
+| `timeout` | — | `10.0` s, total, retries included |
+| `max_retries` | — | `2` |
+| `max_request_bytes` | — | `6 * 1024 * 1024` |
+| `shadow` | — | `False` |
+
+The base URL is a **documented default, not a hard-coded one**: a durable custom
+domain replaces it, and swapping it is a config change rather than a release.
+
+`http://` is refused for any non-loopback host. TLS-only is an inherited binding
+constraint; loopback is exempt so the localhost benchmark adapter still works.
+
+## The four binding rules, and where they live
+
+### 1. Fail open, always
+
+Timeout, 5xx, a violated contract, an empty selection, a stood-down gate — every
+one of them returns a `SelectionResult` with `applied=False`, the exception on
+`.error`, and a machine-readable `.reason`. Nothing is raised on the selection
+path.
+
+```python
+if not result.applied:
+    log.info("needlepath passthrough", extra=result.metadata())
+    context = my_original_context
+```
+
+`result.reason` is an **open enum** (`needlepath.Reason`). Today:
+
+| reason | applied | meaning |
+|---|---|---|
+| `ok` | yes | safe to apply |
+| `shadow` | no | shadow mode — measured, deliberately not applied |
+| `disabled` | no | the integration was constructed disabled |
+| `no_records` | no | nothing to select over; no call was made |
+| `below_trigger` | no | under the configured trigger; no call was made |
+| `empty_selection` | no | zero records selected |
+| `engine_fallback` | no | `fallback_used` — the engine wants the full context |
+| `selection_error` | no | the response carried a `selection_error` |
+| `no_per_record_detail` | no | per-record detail was required and absent |
+| `payload_too_large` | no | over the client-side guard; **no call was made** |
+| `timeout` / `transport_error` / `http_error` / `contract_error` | no | error paths |
+| `unexpected_error` | no | a defect in this client — still fails open |
+
+Treat an unrecognized reason as "do not apply". `result.failed` separates the
+error paths from the benign declines, which is the distinction that decides
+whether a passthrough deserves a `WARNING` or a `DEBUG`.
+
+The empty-selection rule is not a nicety. NEXPE-413 is the precedent: the engine
+returned an empty selection as a success, and at a framework boundary that has
+to degrade to passthrough, never to an empty context.
+
+**`select_or_raise()` exists** for the two cases where fail-open is wrong —
+diagnostics, and a caller that is itself a benchmark and must not silently
+substitute a passthrough for a measurement. Do not use it in an adapter.
+
+### 2. Pin the operating point
+
+`operating_point` is required at construction, and this is the one failure that
+raises rather than fails open. Failing open on a bad request is degradation a
+customer absorbs; failing open on "no operating point was pinned" accepts
+exactly the behaviour drift the rule exists to prevent. It fails at wire-up,
+never under load.
+
+Labels are immutable: `np-2026-07-r2` means one frozen configuration forever, and
+a retune mints a new label. `client.operating_points()` lists what the endpoint
+serves — call it once at wire-up if you want the assertion, never per request.
+
+### 3. Guard the 6 MB cap client-side
+
+The serialized body is measured before it is sent. Over the guard, you get
+`reason="payload_too_large"` and **no network call**, rather than a platform
+error from the far side of the wire.
+
+The guard measures the JSON body. Lambda's 6 MB limit applies to the whole
+invocation payload — the API Gateway event envelope sits on top — so a request
+that passes at 5.99 MB can still be rejected upstream. Lower
+`max_request_bytes` if you run near the cap.
+
+### 4. Shadow mode is a one-line switch
+
+```python
+client = NeedlepathClient(operating_point="np-2026-07-r2", shadow=True)
+```
+
+The call is made exactly as a live call would be — same body, same billing, same
+operating point — the full response comes back and is reported, and **the
+selection is never applied**. Measure what Needlepath would have saved you;
+change nothing.
+
+`budget.mode = "shadow"` is **not on the wire yet**. `BudgetSpec.mode` on the
+published contract accepts `fixed` and `adaptive` only; adding `shadow` is a
+public-repo contract change (§0.1, sequenced in E7). The wire half is behind
+`needlepath.features.WIRE_SHADOW_MODE`; flip it in the same change that lands the
+field. Client-side behaviour does not change when you do — it is already correct.
+
+## Retries
+
+Retried: `429`, `502`, `503`, `504`, and transport failures. `Retry-After` is
+honoured in delta-seconds form. Backoff is full-jitter exponential, and every
+retry is bounded by the `timeout` deadline — retries can never exceed the budget
+the caller gave you.
+
+**`500` is not retried.** A 500 from this endpoint is `engine_error`: a
+deterministic failure on this exact input. Retrying buys nothing, doubles the
+latency before you fail open, and spends a second billable invocation on a
+request that will fail identically.
+
+POST is safe to retry here because the endpoint is stateless and idempotent by
+contract (`ADAPTER_API_DESIGN.md` invariant 1).
+
+## Metadata
+
+`result.metadata()` is a flat, **metadata-only** dict built for a framework's
+metadata blob:
+
+```python
+{"needlepath.applied": False, "needlepath.reason": "engine_fallback",
+ "needlepath.tokens_before": 8400, "needlepath.tokens_saved": 0,
+ "needlepath.gate_reason": "standdown:flat_gap", ...}
+```
+
+Nothing derived from record text is in it. One consequence is non-obvious:
+`selection_error` is built server-side as `f"{type(exc).__name__}: {exc}"` and can
+carry fragments of your input in an exception message — the Lambda deliberately
+declines to log it for that reason — so only its *type* appears here. The full
+string stays on `result.response.selection_error`.
+
+## Testing your integration
+
+```python
+from needlepath.testing import FakeTransport, response_payload, ok, error
+
+transport = FakeTransport([error(503), ok(response_payload("np-1"))])
+client = NeedlepathClient(operating_point="np-2026-07-r2", transport=transport)
+```
+
+`needlepath.testing` is public API, not a private helper. Every rule above is a
+rule about what happens when the service misbehaves, and you cannot test that
+against a healthy service.
+
+## Wire contract
+
+`INTERFACE.md` in `context-selection-bench` is the published contract; the
+dataclasses here are an independent implementation of it, deliberately copied
+rather than imported so a research harness never lands in a customer's
+dependency tree. `tests/test_wire_compatibility.py` asserts they have not
+drifted.
+
+Unknown response fields are kept on `response.extra`, never rejected: `/v1` is
+additive, and `usage` (E2) is already scheduled to arrive that way.
+
+The gate outcome and `reason` are an **open enum**. Nothing in this SDK branches
+on them and nothing you build on it should — a third outcome is a planned
+additive change.

needlepath-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+needlepath/__init__.py,sha256=gPl4JgYTjwa2D7BZPX79_Vo21xJTdPxCqQXPBj9Daps,3683
+needlepath/client.py,sha256=W_o_9XgV9scQB7DzPihJnAaYNiJQYloagTCLAw6gwMU,37658
+needlepath/errors.py,sha256=YElGVzDL8VBi-HMgL-LC2tJZ7_PmdOBo6CH--rHGBSs,4296
+needlepath/features.py,sha256=-W-awNrjzsTv1pHEnrdCZc5t6Y8QAwce6JYc5VzlfN4,2905
+needlepath/models.py,sha256=yAfRLWqOjkprKyR-GEmEp8eV5V-r2p_Lb6AeM9oYl7k,17342
+needlepath/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+needlepath/result.py,sha256=O3_HPH0YwoCTIL_n-hY5HGic7LSE0HUSj3Ar30dtLgw,11811
+needlepath/testing.py,sha256=8pfw9HcjagjTt98iVF3lG1QMxlh_79qOeMUoYZwhxI4,7089
+needlepath/transport.py,sha256=ZjNy9c7KyRyQGORF5uY2ft7y0l1tr05fmQDoEsuXCRY,11773
+needlepath/version.py,sha256=RMgmvDRBq67Hr7YmyQW0Fog13ihX3lePDO-sMa7jCTU,307
+needlepath-0.1.0.dist-info/METADATA,sha256=Y_puZt7TqmKPoVZ2hvBIaGl6BAJS3fR9lwTL0_iOPYo,10436
+needlepath-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+needlepath-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+needlepath-0.1.0.dist-info/RECORD,,

needlepath-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any