needlepath 0.1.0__tar.gz → 0.2.0__tar.gz

needlepath-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to the `needlepath` Python package are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-08-07
+
+### Added
+
+- **Simple text shape** (NEXPE-461): `select(text=...)` accepts a raw string as
+  the alternative to `records=`. Exactly one of the two may be passed; passing
+  both fails open client-side with a `NeedlepathConfigError` whose message
+  mirrors the server's `400 text_and_records_both_set`. The text goes on the
+  wire verbatim; the server chunks it, and each chunk comes back in
+  `selected[].record_id` as a content-hash id of the form `sha256:<16 hex>`.
+  `ContextRequest` gains an optional `text` field, omitted from the wire when
+  unset.
+
+### Changed
+
+- **`request_id` is now optional** (NEXPE-461): it is a sent-side correlation
+  id. `ContextRequest.request_id` may be `None`, in which case the key is
+  omitted from the payload and the server assigns its own id (reported on
+  `SelectionResult.request_id`). In `select()` / `build_request()`, leaving the
+  argument off still auto-generates an id as before; pass `request_id=None`
+  explicitly to omit it. The response echo check is skipped when no id was
+  sent.
+
+### Note
+
+- No breaking changes for existing callers: records requests serialize
+  byte-identically to 0.1.x, omitting `request_id` still auto-generates one,
+  and `operating_point` remains the required, immutable-label constructor
+  argument.
+
+## [0.1.1] - 2026-08-06
+
+- Default base URL moved to `https://api.nextmoca.com`; no wire-shape changes.
+
+## [0.1.0] - 2026-08-01
+
+- Initial release: fail-open `select()`, pinned operating point, client-side
+  6 MB payload guard, shadow mode, sync and async clients.

{needlepath-0.1.0 → needlepath-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: needlepath
-Version: 0.1.0
+Version: 0.2.0
 Summary: Framework-free client for the Needlepath hosted context-selection service.
 Project-URL: Homepage, https://nextmoca.com
 Author: Next Moca Global, Inc.
@@ -94,7 +94,7 @@ never blocks the event loop either way.
 |---|---|---|
 | `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` |
+| `base_url` | `NEEDLEPATH_BASE_URL` | `https://api.nextmoca.com` |
 | `timeout` | — | `10.0` s, total, retries included |
 | `max_retries` | — | `2` |
 | `max_request_bytes` | — | `6 * 1024 * 1024` |

{needlepath-0.1.0 → needlepath-0.2.0}/README.md

@@ -65,7 +65,7 @@ never blocks the event loop either way.
 |---|---|---|
 | `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` |
+| `base_url` | `NEEDLEPATH_BASE_URL` | `https://api.nextmoca.com` |
 | `timeout` | — | `10.0` s, total, retries included |
 | `max_retries` | — | `2` |
 | `max_request_bytes` | — | `6 * 1024 * 1024` |

{needlepath-0.1.0 → needlepath-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "needlepath"
-version = "0.1.0"
+version = "0.2.0"
 description = "Framework-free client for the Needlepath hosted context-selection service."
 readme = "README.md"
 requires-python = ">=3.9"

{needlepath-0.1.0 → needlepath-0.2.0}/src/needlepath/client.py

@@ -62,7 +62,7 @@ from .version import __version__
 #: 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"
+DEFAULT_BASE_URL = "https://api.nextmoca.com"
 
 SELECT_PATH = "/v1/context/select"
 HEALTH_PATH = "/v1/health"
@@ -160,13 +160,23 @@ def new_request_id() -> str:
 # --------------------------------------------------------------------------- #
 
 
+#: Sentinel default for ``request_id``: "the caller did not pass one, generate
+#: one" (NEXPE-461). It exists so that an **explicit** ``request_id=None`` can
+#: mean something different — omit the field from the payload entirely and let
+#: the server assign its own id — without changing behaviour for existing
+#: callers, for whom leaving the argument off still auto-generates.
+_AUTO_REQUEST_ID: Any = object()
+
+
 def build_request(
     *,
-    records: Sequence[ContextRecord],
+    records: Optional[Sequence[ContextRecord]] = None,
     task: TaskSpec,
     max_context_tokens: int,
     operating_point: str,
-    request_id: Optional[str] = None,
+    text: Optional[str] = None,
+    capacity_cap_tokens: Optional[int] = None,
+    request_id: Any = _AUTO_REQUEST_ID,
     max_records: Optional[int] = None,
     max_excerpt_tokens_per_record: Optional[int] = None,
     mode: str = "fixed",
@@ -176,13 +186,33 @@ def build_request(
     render_format: str = "plain",
     return_per_record: bool = True,
 ) -> ContextRequest:
-    """Assemble a :class:`ContextRequest` with the operating point already pinned."""
+    """Assemble a :class:`ContextRequest` with the operating point already pinned.
+
+    Exactly one of ``records`` / ``text`` must be provided (NEXPE-461). ``text``
+    is the simple shape: the string is sent verbatim, the server chunks it, and
+    each chunk comes back in ``selected[].record_id`` as a content-hash id of
+    the form ``sha256:<16 hex>``.
+
+    ``request_id`` is a sent-side correlation id. Leave it off to auto-generate
+    one; pass ``request_id=None`` explicitly to omit it from the payload, in
+    which case ``result.request_id`` comes back empty (echoed in the response).
+    """
+    if text is not None and records is not None:
+        raise NeedlepathConfigError(
+            "text_and_records_both_set: pass exactly one of records= or text= "
+            "(the server rejects a request carrying both with "
+            "400 text_and_records_both_set)"
+        )
+    if text is None and records is None:
+        raise NeedlepathConfigError("one of records= or text= is required")
     return ContextRequest(
-        request_id=request_id or new_request_id(),
-        records=list(records),
+        request_id=new_request_id() if request_id is _AUTO_REQUEST_ID else request_id,
+        records=list(records) if records is not None else [],
+        text=text,
         task=task,
         budget=BudgetSpec(
             max_context_tokens=max_context_tokens,
+            capacity_cap_tokens=capacity_cap_tokens,
             operating_point=operating_point,
             max_records=max_records,
             max_excerpt_tokens_per_record=max_excerpt_tokens_per_record,
@@ -203,28 +233,37 @@ def encode_body(request: ContextRequest, *, shadow: bool) -> bytes:
     guard; the JSON is otherwise identical to the published client's.
     """
     wire = request.to_wire()
+    # None means "not sent" (review finding on #296): to_wire maps it to a
+    # JSON null, which is a value, not an omission.
+    if wire.get("request_id") is None:
+        wire.pop("request_id", None)
     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:
+def validate_response_payload(payload: Any, request_id: Optional[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``.
+
+    ``request_id=None`` means the request omitted the correlation id
+    (NEXPE-461): the echo check is skipped, because the id in the response is
+    the server's own, but ``request_id`` must still be present.
     """
     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}"
-        )
+    if request_id is not None:
+        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:
@@ -447,30 +486,48 @@ class NeedlepathClient(_ClientBase):
     def select(
         self,
         *,
-        records: Sequence[ContextRecord],
+        records: Optional[Sequence[ContextRecord]] = None,
         task: TaskSpec,
         max_context_tokens: int,
-        request_id: Optional[str] = None,
+        text: Optional[str] = None,
+        request_id: Any = _AUTO_REQUEST_ID,
         shadow: Optional[bool] = None,
         require_per_record: bool = True,
         **budget_kwargs: Any,
     ) -> SelectionResult:
         """Select context. **Never raises.**
 
+        Exactly one of ``records`` / ``text`` must be provided (NEXPE-461).
+        ``text`` is the simple shape: the string goes on the wire verbatim, the
+        server chunks it, and each chunk comes back in ``selected[].record_id``
+        as a content-hash id of the form ``sha256:<16 hex>``. Passing both is
+        the client-side mirror of the server's ``400 text_and_records_both_set``
+        and fails open with a :class:`NeedlepathConfigError` on ``.error``.
+
+        ``request_id`` is a sent-side correlation id. Leave it off to
+        auto-generate one; pass ``request_id=None`` explicitly to omit it from
+        the payload, in which case ``result.request_id`` comes back empty and
+        ``result.request_id`` carries the server's.
+
         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):
+        is_shadow = self.shadow if shadow is None else bool(shadow)
+        rid_for_report = request_id if isinstance(request_id, str) else ""
+        if (text is None and records is not None and _is_empty(records)) or (
+            text is not None and records is None and len(text) == 0
+        ):
             return SelectionResult.passthrough_result(
                 Reason.NO_RECORDS,
-                request_id=request_id or "",
+                request_id=rid_for_report,
                 operating_point=self.operating_point,
-                shadow=self.shadow if shadow is None else bool(shadow),
+                shadow=is_shadow,
             )
         try:
             request = build_request(
                 records=records,
+                text=text,
                 task=task,
                 max_context_tokens=max_context_tokens,
                 operating_point=self.operating_point,
@@ -480,8 +537,9 @@ class NeedlepathClient(_ClientBase):
         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 "",
+                request_id=rid_for_report,
                 operating_point=self.operating_point,
+                shadow=is_shadow,
                 error=exc,
             )
         return self.select_request(request, shadow=shadow, require_per_record=require_per_record)
@@ -516,7 +574,7 @@ class NeedlepathClient(_ClientBase):
         except NeedlepathError as exc:
             return SelectionResult.passthrough_result(
                 _reason_for(exc),
-                request_id=request.request_id,
+                request_id=request.request_id or "",
                 operating_point=self.operating_point,
                 shadow=is_shadow,
                 error=exc,
@@ -527,7 +585,7 @@ class NeedlepathClient(_ClientBase):
         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,
+                request_id=request.request_id or "",
                 operating_point=self.operating_point,
                 shadow=is_shadow,
                 error=exc,
@@ -678,25 +736,36 @@ class AsyncNeedlepathClient(_ClientBase):
     async def select(
         self,
         *,
-        records: Sequence[ContextRecord],
+        records: Optional[Sequence[ContextRecord]] = None,
         task: TaskSpec,
         max_context_tokens: int,
-        request_id: Optional[str] = None,
+        text: Optional[str] = None,
+        request_id: Any = _AUTO_REQUEST_ID,
         shadow: Optional[bool] = None,
         require_per_record: bool = True,
         **budget_kwargs: Any,
     ) -> SelectionResult:
-        """Select context. **Never raises.**"""
-        if _is_empty(records):
+        """Select context. **Never raises.**
+
+        Behaviour is identical to :meth:`NeedlepathClient.select`, including the
+        simple ``text`` shape and the optional sent-side ``request_id``
+        (NEXPE-461) — see that docstring.
+        """
+        is_shadow = self.shadow if shadow is None else bool(shadow)
+        rid_for_report = request_id if isinstance(request_id, str) else ""
+        if (text is None and records is not None and _is_empty(records)) or (
+            text is not None and records is None and len(text) == 0
+        ):
             return SelectionResult.passthrough_result(
                 Reason.NO_RECORDS,
-                request_id=request_id or "",
+                request_id=rid_for_report,
                 operating_point=self.operating_point,
-                shadow=self.shadow if shadow is None else bool(shadow),
+                shadow=is_shadow,
             )
         try:
             request = build_request(
                 records=records,
+                text=text,
                 task=task,
                 max_context_tokens=max_context_tokens,
                 operating_point=self.operating_point,
@@ -706,8 +775,9 @@ class AsyncNeedlepathClient(_ClientBase):
         except Exception as exc:  # noqa: BLE001
             return SelectionResult.passthrough_result(
                 Reason.UNEXPECTED_ERROR,
-                request_id=request_id or "",
+                request_id=rid_for_report,
                 operating_point=self.operating_point,
+                shadow=is_shadow,
                 error=exc,
             )
         return await self.select_request(
@@ -741,7 +811,7 @@ class AsyncNeedlepathClient(_ClientBase):
         except NeedlepathError as exc:
             return SelectionResult.passthrough_result(
                 _reason_for(exc),
-                request_id=request.request_id,
+                request_id=request.request_id or "",
                 operating_point=self.operating_point,
                 shadow=is_shadow,
                 error=exc,
@@ -752,7 +822,7 @@ class AsyncNeedlepathClient(_ClientBase):
         except Exception as exc:  # noqa: BLE001
             return SelectionResult.passthrough_result(
                 Reason.UNEXPECTED_ERROR,
-                request_id=request.request_id,
+                request_id=request.request_id or "",
                 operating_point=self.operating_point,
                 shadow=is_shadow,
                 error=exc,
@@ -903,11 +973,16 @@ def _finish(
     attempts: int,
     request_bytes: int,
 ) -> SelectionResult:
+    # NEXPE-461: the simple text shape has no caller-supplied record ids — the
+    # server mints content-hash ids (sha256:<16 hex>) for its own chunks, so
+    # every selected id is unknown to us *by construction* and the
+    # unknown-selection guard must stand down rather than veto every response.
+    known_ids = None if request.text is not None else {r.id for r in request.records if r.id}
     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},
+        known_record_ids=known_ids,
     )
     # 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
@@ -917,7 +992,11 @@ def _finish(
     return SelectionResult(
         applied=(reason == Reason.OK),
         reason=reason,
-        request_id=request.request_id,
+        # When the request omitted its sent-side id (NEXPE-461), report the
+        # server-assigned one so the caller can still correlate with logs.
+        request_id=(
+            request.request_id if request.request_id is not None else response.request_id
+        ),
         operating_point=operating_point,
         shadow=shadow,
         response=response,

{needlepath-0.1.0 → needlepath-0.2.0}/src/needlepath/models.py

@@ -90,24 +90,34 @@ class ContextRecord:
     source: Optional[str] = None
     title: Optional[str] = None
     step_id: Optional[str] = None
-    importance: float = 0.0
+    # NEXPE-437: None means "the caller never annotated importance", and the
+    # field is then OMITTED from the wire so the server applies its neutral
+    # default. The old `0.0` default was sent explicitly, which the server
+    # cannot tell apart from a deliberate 0.0 -- and 0.0 stands the record
+    # down. An explicit `importance=0.0` still goes on the wire as 0.0.
+    importance: Optional[float] = None
     keywords: List[str] = field(default_factory=list)
     tags: List[str] = field(default_factory=list)
     attributes: Dict[str, Any] = field(default_factory=dict)
 
     def to_wire(self) -> Dict[str, Any]:
-        return {
+        wire = {
             "text": self.text,
             "kind": self.kind,
             "id": self.id,
             "source": self.source,
             "title": self.title,
             "step_id": self.step_id,
-            "importance": self.importance,
             "keywords": list(self.keywords),
             "tags": list(self.tags),
             "attributes": dict(self.attributes),
         }
+        # NEXPE-437: omitted, not null. The server reads importance with
+        # `float(d.get("importance", ...))`, so `null` would be a crash and
+        # an always-present key would erase the unset/explicit distinction.
+        if self.importance is not None:
+            wire["importance"] = self.importance
+        return wire
 
     @classmethod
     def from_wire(cls, d: Dict[str, Any]) -> ContextRecord:
@@ -118,7 +128,7 @@ class ContextRecord:
             source=d.get("source"),
             title=d.get("title"),
             step_id=d.get("step_id"),
-            importance=float(d.get("importance", 0.0)),
+            importance=float(d["importance"]) if d.get("importance") is not None else None,
             keywords=list(d.get("keywords", [])),
             tags=list(d.get("tags", [])),
             attributes=dict(d.get("attributes", {})),
@@ -203,6 +213,7 @@ class BudgetSpec:
     """
 
     max_context_tokens: int
+    capacity_cap_tokens: Optional[int] = None
     operating_point: Optional[str] = None
     max_records: Optional[int] = None
     max_excerpt_tokens_per_record: Optional[int] = None
@@ -213,6 +224,7 @@ class BudgetSpec:
     def to_wire(self) -> Dict[str, Any]:
         return {
             "max_context_tokens": self.max_context_tokens,
+            "capacity_cap_tokens": self.capacity_cap_tokens,
             "operating_point": self.operating_point,
             "max_records": self.max_records,
             "max_excerpt_tokens_per_record": self.max_excerpt_tokens_per_record,
@@ -226,6 +238,9 @@ class BudgetSpec:
         adaptive = d.get("adaptive")
         return cls(
             max_context_tokens=int(d["max_context_tokens"]),
+            capacity_cap_tokens=(
+                int(d["capacity_cap_tokens"]) if d.get("capacity_cap_tokens") is not None else None
+            ),
             operating_point=d.get("operating_point"),
             max_records=d.get("max_records"),
             max_excerpt_tokens_per_record=d.get("max_excerpt_tokens_per_record"),
@@ -237,35 +252,64 @@ class BudgetSpec:
 
 @dataclass
 class ContextRequest:
-    request_id: str
+    #: NEXPE-461 (0.2.0): a **sent-side correlation id**. ``None`` means the key
+    #: is OMITTED from the wire entirely — nothing is auto-generated here — and
+    #: the server assigns its own id, which comes back in the response.
+    request_id: Optional[str]
     records: List[ContextRecord]
     task: TaskSpec
     budget: BudgetSpec
     render: bool = True
     render_format: str = "plain"  # "plain" | "hybrid"
     return_per_record: bool = True
+    #: NEXPE-461 (0.2.0): the **simple shape** — raw text instead of records.
+    #: Exactly one of ``text`` / ``records`` may be set; the server rejects a
+    #: request carrying both with ``400 text_and_records_both_set``, and this
+    #: dataclass mirrors that check client-side. The text is sent verbatim; the
+    #: server chunks it, and each chunk comes back in ``selected[].record_id``
+    #: as a content-hash id of the form ``sha256:<16 hex>``.
+    text: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.text is not None and self.records:
+            raise ValueError(
+                "text_and_records_both_set: pass exactly one of records or text "
+                "(the server rejects a request carrying both with "
+                "400 text_and_records_both_set)"
+            )
 
     def to_wire(self) -> Dict[str, Any]:
-        return {
-            "request_id": self.request_id,
-            "records": [r.to_wire() for r in self.records],
-            "task": self.task.to_wire(),
-            "budget": self.budget.to_wire(),
-            "render": self.render,
-            "render_format": self.render_format,
-            "return_per_record": self.return_per_record,
-        }
+        wire: Dict[str, Any] = {}
+        # Omitted, not null, when unset: the id is sent-side-only correlation,
+        # and the simple shape omits `records` rather than sending both keys.
+        if self.request_id is not None:
+            wire["request_id"] = self.request_id
+        if self.text is not None:
+            wire["text"] = self.text
+        else:
+            wire["records"] = [r.to_wire() for r in self.records]
+        wire.update(
+            {
+                "task": self.task.to_wire(),
+                "budget": self.budget.to_wire(),
+                "render": self.render,
+                "render_format": self.render_format,
+                "return_per_record": self.return_per_record,
+            }
+        )
+        return wire
 
     @classmethod
     def from_wire(cls, d: Dict[str, Any]) -> ContextRequest:
         return cls(
-            request_id=d["request_id"],
+            request_id=d.get("request_id"),
             records=[ContextRecord.from_wire(r) for r in d.get("records", [])],
             task=TaskSpec.from_wire(d["task"]),
             budget=BudgetSpec.from_wire(d["budget"]),
             render=bool(d.get("render", True)),
             render_format=d.get("render_format", "plain"),
             return_per_record=bool(d.get("return_per_record", True)),
+            text=d.get("text"),
         )
 
 

{needlepath-0.1.0 → needlepath-0.2.0}/src/needlepath/version.py

@@ -5,6 +5,6 @@ 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"
+__version__ = "0.2.0"
 
 __all__ = ["__version__"]

{needlepath-0.1.0 → needlepath-0.2.0}/tests/test_config_and_guards.py

@@ -185,7 +185,7 @@ def test_base_url_comes_from_the_environment(monkeypatch):
 def test_the_documented_default_is_what_ships():
     from needlepath import DEFAULT_BASE_URL
 
-    assert DEFAULT_BASE_URL == "https://ayf02egtaf.execute-api.us-east-2.amazonaws.com/prod"
+    assert DEFAULT_BASE_URL == "https://api.nextmoca.com"
 
 
 # --------------------------------------------------------------------------- #

needlepath-0.2.0/tests/test_simple_shape.py

@@ -0,0 +1,251 @@
+"""NEXPE-461: the simple text shape, and the optional sent-side request_id.
+
+Two additive 0.2.0 surfaces:
+
+1. ``select(text=...)`` — raw text instead of records. The string goes on the
+   wire verbatim under ``text`` (no ``records`` key), the server chunks it, and
+   each chunk comes back in ``selected[].record_id`` as a content-hash id of
+   the form ``sha256:<16 hex>``.
+2. ``request_id=None`` — the sent-side correlation id is omitted from the
+   payload entirely; the server assigns its own. Leaving the argument off still
+   auto-generates one, so existing callers see no change.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+
+from needlepath import (
+    ContextRecord,
+    NeedlepathClient,
+    NeedlepathConfigError,
+    Reason,
+    TaskSpec,
+    build_request,
+    models,
+)
+from needlepath.client import AsyncNeedlepathClient
+from needlepath.testing import FakeAsyncTransport, FakeTransport, ok, response_payload
+
+OP = "np-2026-07-r2"
+TASK = TaskSpec(prompt="what failed?")
+TEXT = "step 1 passed\nstep 2 failed: TimeoutError\nstep 3 skipped"
+
+#: What the server actually returns for a text request: its own chunk ids.
+HASH_SELECTED = [
+    {
+        "record_id": "sha256:0123456789abcdef",
+        "kind": "external_data",
+        "score": 0.9,
+        "reason": "engage:needle",
+        "excerpt": "step 2 failed: TimeoutError",
+        "excerpt_format": "plain",
+        "selected_tokens": 12,
+    }
+]
+
+
+def _echo_with_hash_ids():
+    """Echo the sent request_id when there is one, mint one when there is not,
+    and select a content-hash chunk id either way — the live text-shape reply."""
+
+    def _respond(method, url, *, headers, body, timeout):
+        sent = json.loads(body.decode("utf-8"))
+        rid = sent.get("request_id", "srv-assigned-0001")
+        return ok(response_payload(rid, selected=HASH_SELECTED))
+
+    return _respond
+
+
+def _client(script=None):
+    transport = FakeTransport(script if script is not None else [_echo_with_hash_ids()])
+    return (
+        NeedlepathClient(
+            operating_point=OP, base_url="https://x.test", transport=transport, max_retries=0
+        ),
+        transport,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# The text shape on the wire
+# --------------------------------------------------------------------------- #
+
+
+def test_text_is_sent_verbatim_and_records_is_absent():
+    client, transport = _client()
+    result = client.select(text=TEXT, task=TASK, max_context_tokens=1000)
+    assert result.applied is True
+    body = transport.bodies[0]
+    assert body["text"] == TEXT
+    assert "records" not in body
+
+
+def test_content_hash_chunk_ids_are_applied_not_vetoed_as_unknown():
+    """The unknown-selection guard exists for records requests. A text request
+    has no caller-supplied ids at all, so server-minted sha256:<16 hex> chunk
+    ids must not read as 'a selection of ids we never sent'."""
+    client, _ = _client()
+    result = client.select(text=TEXT, task=TASK, max_context_tokens=1000)
+    assert result.applied is True
+    assert result.selected_ids == ["sha256:0123456789abcdef"]
+
+
+def test_records_requests_still_serialize_the_old_shape():
+    client, transport = _client(
+        [
+            lambda m, u, *, headers, body, timeout: ok(
+                response_payload(json.loads(body.decode())["request_id"])
+            )
+        ]
+    )
+    result = client.select(
+        records=[ContextRecord(text="a", id="r1")], task=TASK, max_context_tokens=10
+    )
+    assert result.applied is True
+    body = transport.bodies[0]
+    assert "text" not in body
+    assert body["records"][0]["text"] == "a"
+
+
+def test_empty_text_short_circuits_without_a_call():
+    client, transport = _client()
+    result = client.select(text="", task=TASK, max_context_tokens=10)
+    assert result.reason == Reason.NO_RECORDS
+    assert transport.calls == []
+
+
+# --------------------------------------------------------------------------- #
+# Exactly one of records / text
+# --------------------------------------------------------------------------- #
+
+
+def test_both_set_fails_open_with_the_server_error_name_in_the_message():
+    client, transport = _client()
+    result = client.select(
+        records=[ContextRecord(text="a", id="r1")],
+        text=TEXT,
+        task=TASK,
+        max_context_tokens=10,
+    )
+    assert result.applied is False
+    assert result.reason == Reason.UNEXPECTED_ERROR
+    assert isinstance(result.error, NeedlepathConfigError)
+    assert "text_and_records_both_set" in str(result.error)
+    assert transport.calls == [], "the mistake is caught before any bytes leave"
+
+
+def test_neither_set_fails_open_with_a_clear_message():
+    client, transport = _client()
+    result = client.select(task=TASK, max_context_tokens=10)
+    assert result.applied is False
+    assert isinstance(result.error, NeedlepathConfigError)
+    assert transport.calls == []
+
+
+def test_build_request_raises_on_both_and_on_neither():
+    with pytest.raises(NeedlepathConfigError, match="text_and_records_both_set"):
+        build_request(
+            records=[ContextRecord(text="a")],
+            text=TEXT,
+            task=TASK,
+            max_context_tokens=10,
+            operating_point=OP,
+        )
+    with pytest.raises(NeedlepathConfigError):
+        build_request(task=TASK, max_context_tokens=10, operating_point=OP)
+
+
+def test_the_model_itself_refuses_both():
+    with pytest.raises(ValueError, match="text_and_records_both_set"):
+        models.ContextRequest(
+            request_id="np-1",
+            records=[models.ContextRecord(text="a")],
+            task=TASK,
+            budget=models.BudgetSpec(max_context_tokens=10),
+            text=TEXT,
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Optional request_id
+# --------------------------------------------------------------------------- #
+
+
+def test_omitting_the_argument_still_autogenerates_a_request_id():
+    client, transport = _client()
+    result = client.select(text=TEXT, task=TASK, max_context_tokens=1000)
+    assert result.applied is True
+    assert transport.bodies[0]["request_id"].startswith("np-")
+
+
+def test_request_id_none_is_absent_from_the_payload():
+    client, transport = _client()
+    result = client.select(text=TEXT, task=TASK, max_context_tokens=1000, request_id=None)
+    assert result.applied is True
+    assert "request_id" not in transport.bodies[0]
+
+
+def test_without_a_sent_id_the_result_reports_the_server_assigned_one():
+    # A records request this time, so the server selects the caller's r1.
+    client, _ = _client(
+        [lambda m, u, *, headers, body, timeout: ok(response_payload("srv-assigned-0001"))]
+    )
+    result = client.select(
+        records=[ContextRecord(text="a", id="r1")],
+        task=TASK,
+        max_context_tokens=10,
+        request_id=None,
+    )
+    # The echo check is skipped — there is nothing to echo — and the server's
+    # own id is what the caller gets for log correlation.
+    assert result.applied is True
+    assert result.request_id == "srv-assigned-0001"
+
+
+def test_a_wire_request_without_request_id_omits_the_key():
+    request = models.ContextRequest(
+        request_id=None,
+        records=[],
+        task=TASK,
+        budget=models.BudgetSpec(max_context_tokens=10, operating_point=OP),
+        text=TEXT,
+    )
+    wire = request.to_wire()
+    assert "request_id" not in wire
+    assert wire["text"] == TEXT
+    assert "records" not in wire
+    # And the round trip is stable.
+    assert models.ContextRequest.from_wire(wire).to_wire() == wire
+
+
+# --------------------------------------------------------------------------- #
+# The async twin cannot drift
+# --------------------------------------------------------------------------- #
+
+
+def test_async_text_and_optional_request_id_behave_identically():
+    async def _run():
+        transport = FakeAsyncTransport([_echo_with_hash_ids()])
+        client = AsyncNeedlepathClient(
+            operating_point=OP, base_url="https://x.test", transport=transport, max_retries=0
+        )
+        applied = await client.select(
+            text=TEXT, task=TASK, max_context_tokens=1000, request_id=None
+        )
+        both = await client.select(
+            records=[ContextRecord(text="a")], text=TEXT, task=TASK, max_context_tokens=10
+        )
+        return transport.bodies[0], applied, both
+
+    body, applied, both = asyncio.run(_run())
+    assert body["text"] == TEXT
+    assert "records" not in body
+    assert "request_id" not in body
+    assert applied.applied is True
+    assert applied.request_id == "srv-assigned-0001"
+    assert both.applied is False
+    assert "text_and_records_both_set" in str(both.error)

{needlepath-0.1.0 → needlepath-0.2.0}/tests/test_wire_compatibility.py

@@ -5,11 +5,11 @@
 customer's dependency tree. A copy is only safe if something notices when it
 drifts, so this file notices in two ways:
 
-1. **Against literals**, always. The field sets below are transcribed from
-   ``INTERFACE.md`` as published. This runs in CI with no extra checkout.
-2. **Against ``csbench.contracts``**, when it is importable. Set ``CSBENCH_PATH``
-   to a checkout of ``context-selection-bench`` to turn it on. This is the check
-   that catches drift on the *other* side.
+1. **Against hosted v1 literals**, always. This includes additive request fields
+   already accepted by the deployed parser and OpenAPI.
+2. **Against ``csbench.contracts``**, when it is importable. The comparison is
+   exact except for explicitly listed hosted additions, so the independently
+   released public benchmark remains a compatibility baseline.
 """
 
 from __future__ import annotations
@@ -22,12 +22,13 @@ import sys
 import pytest
 
 from needlepath import models
+from needlepath.client import build_request
 
 # --------------------------------------------------------------------------- #
-# 1. Against the published field lists
+# 1. Against the hosted v1 field lists
 # --------------------------------------------------------------------------- #
 
-PUBLISHED = {
+HOSTED_WIRE_FIELDS = {
     "ContextRecord": {
         "text",
         "kind",
@@ -55,6 +56,7 @@ PUBLISHED = {
     "AdaptiveBudget": {"initial_tokens", "escalation_tokens", "allow_full_context_fallback"},
     "BudgetSpec": {
         "max_context_tokens",
+        "capacity_cap_tokens",
         "operating_point",
         "max_records",
         "max_excerpt_tokens_per_record",
@@ -70,6 +72,9 @@ PUBLISHED = {
         "render",
         "render_format",
         "return_per_record",
+        # NEXPE-461: the simple shape. Hosted v1 accepts `text` as the
+        # alternative to `records`; unset means omitted from the wire.
+        "text",
     },
     "SelectedRecord": {
         "record_id",
@@ -123,13 +128,23 @@ LOCAL_ONLY = {
     "ContextResponse": {"extra"},
 }
 
+# The hosted v1 request parser owns this additive field before the separately
+# released public benchmark contract does. Cross-checks below require exact
+# parity except for this explicit, backwards-compatible extension.
+HOSTED_ADDITIONS = {
+    "BudgetSpec": {"capacity_cap_tokens"},
+    # NEXPE-461: hosted v1 owns the simple text shape before the public
+    # benchmark contract does.
+    "ContextRequest": {"text"},
+}
+
 
-@pytest.mark.parametrize("name", sorted(PUBLISHED))
-def test_field_names_match_the_published_contract(name):
+@pytest.mark.parametrize("name", sorted(HOSTED_WIRE_FIELDS))
+def test_field_names_match_the_hosted_contract(name):
     ours = {f.name for f in dataclasses.fields(getattr(models, name))}
-    expected = PUBLISHED[name] | LOCAL_ONLY.get(name, set())
+    expected = HOSTED_WIRE_FIELDS[name] | LOCAL_ONLY.get(name, set())
     assert ours == expected, (
-        f"{name} drifted from INTERFACE.md: "
+        f"{name} drifted from the hosted v1 contract: "
         f"extra={sorted(ours - expected)} missing={sorted(expected - ours)}"
     )
 
@@ -181,15 +196,37 @@ def test_to_wire_emits_the_full_shape_including_nones():
         budget=models.BudgetSpec(max_context_tokens=100),
     )
     wire = request.to_wire()
-    assert set(wire) == PUBLISHED["ContextRequest"]
-    assert set(wire["records"][0]) == PUBLISHED["ContextRecord"]
-    assert set(wire["task"]) == PUBLISHED["TaskSpec"]
-    assert set(wire["budget"]) == PUBLISHED["BudgetSpec"]
+    # NEXPE-461: `text` follows the same omit-when-unset rule as `importance`
+    # (below) — a records request must stay byte-identical to the old shape.
+    assert set(wire) == HOSTED_WIRE_FIELDS["ContextRequest"] - {"text"}
+    # NEXPE-437: `importance` is the one deliberate exception to the
+    # full-shape rule. Unset means OMITTED from the wire, so the server can
+    # tell "never annotated" (neutral) apart from an explicit 0.0
+    # (stand-down). Every other optional stays present-as-null.
+    assert set(wire["records"][0]) == HOSTED_WIRE_FIELDS["ContextRecord"] - {"importance"}
+    assert set(wire["task"]) == HOSTED_WIRE_FIELDS["TaskSpec"]
+    assert set(wire["budget"]) == HOSTED_WIRE_FIELDS["BudgetSpec"]
     assert wire["records"][0]["source"] is None  # present, not omitted
     assert wire["budget"]["adaptive"] is None
     json.dumps(wire)  # and it is serializable
 
 
+def test_unset_importance_is_omitted_and_explicit_zero_is_sent():
+    """NEXPE-437: the wire distinguishes unannotated from deliberately 0.0."""
+    unset = models.ContextRecord(text="t").to_wire()
+    assert "importance" not in unset
+
+    explicit_zero = models.ContextRecord(text="t", importance=0.0).to_wire()
+    assert explicit_zero["importance"] == 0.0
+
+    explicit = models.ContextRecord(text="t", importance=7.5).to_wire()
+    assert explicit["importance"] == 7.5
+
+    # And from_wire preserves the same distinction on the way back in.
+    assert models.ContextRecord.from_wire({"text": "t"}).importance is None
+    assert models.ContextRecord.from_wire({"text": "t", "importance": 0.0}).importance == 0.0
+
+
 def test_unknown_response_fields_are_kept_not_rejected():
     """`/v1` is additive (API_VERSIONING.md). `usage` is already scheduled to
     arrive this way (E2), and a client that 'validates' by rejecting unknown
@@ -227,6 +264,28 @@ def test_round_trip_through_from_wire_is_stable():
     assert models.ContextRequest.from_wire(request.to_wire()).to_wire() == request.to_wire()
 
 
+def test_capacity_cap_defaults_none_and_round_trips_through_the_sdk():
+    omitted = models.BudgetSpec.from_wire({"max_context_tokens": 2})
+    assert omitted.capacity_cap_tokens is None
+    assert omitted.to_wire()["capacity_cap_tokens"] is None
+
+    explicit = models.BudgetSpec.from_wire({"max_context_tokens": 2, "capacity_cap_tokens": 100})
+    assert explicit.capacity_cap_tokens == 100
+    assert explicit.to_wire()["capacity_cap_tokens"] == 100
+
+
+def test_sdk_request_builder_emits_capacity_cap() -> None:
+    request = build_request(
+        records=[models.ContextRecord(text="context")],
+        task=models.TaskSpec(prompt="question"),
+        max_context_tokens=2,
+        capacity_cap_tokens=100,
+        operating_point="np-2026-07-r2",
+    )
+
+    assert request.to_wire()["budget"]["capacity_cap_tokens"] == 100
+
+
 # --------------------------------------------------------------------------- #
 # 2. Against csbench itself, when it is available
 # --------------------------------------------------------------------------- #
@@ -252,12 +311,12 @@ requires_csbench = pytest.mark.skipif(
 
 
 @requires_csbench
-@pytest.mark.parametrize("name", sorted(PUBLISHED))
+@pytest.mark.parametrize("name", sorted(HOSTED_WIRE_FIELDS))
 def test_matches_csbench_field_for_field(name):
     theirs = {f.name for f in dataclasses.fields(getattr(csbench_contracts, name))}
     ours = {f.name for f in dataclasses.fields(getattr(models, name))}
     ours -= LOCAL_ONLY.get(name, set())
-    assert ours == theirs
+    assert ours == theirs | HOSTED_ADDITIONS.get(name, set())
 
 
 @requires_csbench
@@ -266,22 +325,29 @@ def test_matches_csbench_required_response_fields():
 
 
 @requires_csbench
-def test_our_wire_body_is_byte_identical_to_the_published_clients():
-    """The strongest form of the claim: same inputs, same JSON."""
+def test_our_old_request_shape_is_byte_identical_to_the_published_clients():
+    """Removing the one additive field leaves the old public JSON unchanged."""
     ours = models.ContextRequest(
         request_id="np-1",
-        records=[models.ContextRecord(text="t", kind="tool_result", id="r1")],
+        records=[models.ContextRecord(text="t", kind="tool_result", id="r1", importance=0.0)],
         task=models.TaskSpec(prompt="p"),
         budget=models.BudgetSpec(max_context_tokens=100, operating_point="np-2026-07-r2"),
     )
     theirs = csbench_contracts.ContextRequest(
         request_id="np-1",
-        records=[csbench_contracts.ContextRecord(text="t", kind="tool_result", id="r1")],
+        records=[
+            csbench_contracts.ContextRecord(text="t", kind="tool_result", id="r1", importance=0.0)
+        ],
         task=csbench_contracts.TaskSpec(prompt="p"),
         budget=csbench_contracts.BudgetSpec(
             max_context_tokens=100, operating_point="np-2026-07-r2"
         ),
     )
-    assert json.dumps(ours.to_wire(), sort_keys=True) == json.dumps(
-        theirs.to_wire(), sort_keys=True
-    )
+    ours_wire = ours.to_wire()
+    assert ours_wire["budget"].pop("capacity_cap_tokens") is None
+    assert json.dumps(ours_wire, sort_keys=True) == json.dumps(theirs.to_wire(), sort_keys=True)
+
+    # An old public parser also ignores the unknown additive key instead of
+    # rejecting the request. It cannot enforce the cap; the hosted parser can.
+    public_parse = csbench_contracts.ContextRequest.from_wire(ours.to_wire())
+    assert public_parse.to_wire() == theirs.to_wire()