needlepath 0.1.0__py3-none-any.whl

needlepath/result.py

@@ -0,0 +1,302 @@
+"""What a selection call returns, including every way it declines to apply.
+
+The central type is :class:`SelectionResult`. It is what makes "fail open" a
+*type*, not a convention: there is no success path that returns a response and a
+failure path that raises, so an integration cannot accidentally be written to
+apply a selection that did not happen.
+
+``applied`` is the only thing an adapter needs to read. When it is ``False`` the
+original context passes through unmodified — always, for every value of
+``reason``, including the ones that are not errors at all.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .models import ContextResponse
+
+
+class Reason:
+    """Why a result was, or was not, applied. **An open enum.**
+
+    Treat an unrecognized value the way you treat ``PASSTHROUGH_*``: do not
+    apply. New reasons are added additively as the service grows outcomes, and
+    a caller that exhaustively matches this set is a caller that breaks.
+    """
+
+    #: The selection is safe to apply.
+    OK = "ok"
+
+    # --- not errors: the service or the caller asked us not to apply --------
+    #: Shadow mode. A real call was made and is reported; nothing is applied.
+    SHADOW = "shadow"
+    #: The integration was constructed disabled (``enabled=False``).
+    DISABLED = "disabled"
+    #: There was nothing to select over — no call was made.
+    NO_RECORDS = "no_records"
+    #: Below the configured trigger; selecting would not pay. No call was made.
+    BELOW_TRIGGER = "below_trigger"
+    #: The seam does not carry a shape this adapter can select over safely.
+    #: (LiteLLM's non-chat call types, an empty message list, a system-only
+    #: history.) Not an error — a scope boundary.
+    UNSUPPORTED = "unsupported"
+    #: The service returned a selection that would not have made the context
+    #: smaller. Applying it would cost a rewrite and buy nothing.
+    NO_SAVING = "no_saving"
+
+    # --- the service ran and declined ---------------------------------------
+    #: Zero records selected. NEXPE-413's precedent: an empty selection is a
+    #: passthrough at a framework boundary, never an empty context.
+    EMPTY_SELECTION = "empty_selection"
+    #: ``fallback_used`` — the engine stood down and wants the full context.
+    ENGINE_FALLBACK = "engine_fallback"
+    #: The response carried a ``selection_error``.
+    SELECTION_ERROR = "selection_error"
+    #: ``return_per_record`` detail was required by the caller and absent.
+    NO_PER_RECORD_DETAIL = "no_per_record_detail"
+    #: The response selected records, but **none of them are ones we sent**.
+    #: Applying it would treat every record the caller gave us as unselected —
+    #: i.e. collapse the entire context. A passthrough, not a selection.
+    UNKNOWN_SELECTION = "unknown_selection"
+    #: The coverage verdict says the selection is not safe to use
+    #: (``safety.fallback_required``, or ``selection_safe`` false).
+    SELECTION_UNSAFE = "selection_unsafe"
+
+    # --- error paths ---------------------------------------------------------
+    #: The serialized body exceeded the client-side size guard. No call made.
+    PAYLOAD_TOO_LARGE = "payload_too_large"
+    #: The deadline elapsed.
+    TIMEOUT = "timeout"
+    #: No HTTP response at all (DNS, connect, reset, TLS).
+    TRANSPORT_ERROR = "transport_error"
+    #: A non-2xx response.
+    HTTP_ERROR = "http_error"
+    #: A 2xx body that violates the response contract.
+    CONTRACT_ERROR = "contract_error"
+    #: A defect in this client. Recorded, never raised on the framework path.
+    UNEXPECTED_ERROR = "unexpected_error"
+
+
+#: The reasons that are *not* a failure of anything. Useful for deciding
+#: whether a warning deserves a log line at WARNING or at DEBUG.
+BENIGN_REASONS = frozenset(
+    {
+        Reason.OK,
+        Reason.SHADOW,
+        Reason.DISABLED,
+        Reason.NO_RECORDS,
+        Reason.BELOW_TRIGGER,
+        Reason.UNSUPPORTED,
+        Reason.NO_SAVING,
+        Reason.EMPTY_SELECTION,
+        Reason.ENGINE_FALLBACK,
+        Reason.SELECTION_UNSAFE,
+    }
+)
+
+
+@dataclass(frozen=True)
+class SelectionResult:
+    """The outcome of one selection call. Never raises; always answerable."""
+
+    applied: bool
+    reason: str
+    request_id: str
+    operating_point: str
+    shadow: bool = False
+    response: Optional[ContextResponse] = None
+    error: Optional[BaseException] = None
+    client_latency_ms: float = 0.0
+    attempts: int = 0
+    #: Bytes actually put on the wire, or that would have been. Zero when no
+    #: request was built.
+    request_bytes: int = 0
+
+    # ------------------------------------------------------------------ #
+
+    @property
+    def passthrough(self) -> bool:
+        """``True`` when the caller must use its original context unmodified."""
+        return not self.applied
+
+    @property
+    def failed(self) -> bool:
+        """``True`` when something actually went wrong, as opposed to declined."""
+        return self.reason not in BENIGN_REASONS
+
+    @property
+    def error_type(self) -> Optional[str]:
+        return type(self.error).__name__ if self.error is not None else None
+
+    @property
+    def rendered_context(self) -> str:
+        """The model-facing block, or ``""`` when nothing is applicable."""
+        return self.response.rendered_context if self.response is not None else ""
+
+    @property
+    def selected_ids(self) -> List[str]:
+        if self.response is None:
+            return []
+        return [s.record_id for s in self.response.selected]
+
+    @property
+    def excerpts(self) -> Dict[str, str]:
+        """``record_id`` → excerpt. Empty unless per-record detail came back."""
+        return self.response.excerpts if self.response is not None else {}
+
+    @property
+    def tokens_saved(self) -> int:
+        return self.response.tokens_saved if self.response is not None else 0
+
+    # ------------------------------------------------------------------ #
+
+    def metadata(self, prefix: str = "needlepath") -> Dict[str, Any]:
+        """A flat, **metadata-only** dict to attach to a framework's metadata.
+
+        §8.2 asks every adapter to "emit a metadata-only warning" when it fails
+        open. This is that warning, in a shape that survives being dropped into
+        a ``ToolMessage.response_metadata``, a LiteLLM ``metadata`` blob or a
+        LlamaIndex node's ``metadata``.
+
+        **Nothing derived from record text is in here**, and that is a rule with
+        one non-obvious consequence: ``selection_error`` is built server-side as
+        ``f"{type(exc).__name__}: {exc}"`` and can therefore carry fragments of
+        the input in an exception message — the Lambda deliberately declines to
+        log it for exactly this reason. So only its *type* travels here. The
+        full string remains on ``result.response.selection_error`` for a caller
+        who wants it and knows what they are handling.
+        """
+        out: Dict[str, Any] = {
+            "applied": self.applied,
+            "reason": self.reason,
+            "shadow": self.shadow,
+            "request_id": self.request_id,
+            "operating_point": self.operating_point,
+            "client_latency_ms": round(self.client_latency_ms, 3),
+            "attempts": self.attempts,
+            "request_bytes": self.request_bytes,
+        }
+        if self.error is not None:
+            out["error_type"] = type(self.error).__name__
+            status = getattr(self.error, "status", None)
+            if status is not None:
+                out["http_status"] = status
+            code = getattr(self.error, "error_code", None)
+            if code is not None:
+                out["error_code"] = code
+        r = self.response
+        if r is not None:
+            out.update(
+                {
+                    "policy_version": r.policy_version,
+                    "tokens_before": r.tokens_before,
+                    "tokens_after": r.tokens_after,
+                    "tokens_saved": r.tokens_saved,
+                    "reduction_ratio": round(r.reduction_ratio, 6),
+                    "records_available": r.records_available,
+                    "records_selected": r.records_selected,
+                    "fallback_used": r.fallback_used,
+                    "engine_latency_ms": r.engine_latency_ms,
+                }
+            )
+            if r.selection_error:
+                # Type only — see the docstring.
+                out["selection_error_type"] = r.selection_error.split(":", 1)[0].strip()
+            if r.gate is not None:
+                out["gate_engaged"] = r.gate.engaged
+                out["gate_reason"] = r.gate.reason
+        if not prefix:
+            return out
+        return {f"{prefix}.{k}": v for k, v in out.items()}
+
+    # ------------------------------------------------------------------ #
+
+    def declined(self, reason: str) -> SelectionResult:
+        """A copy of this result that the adapter decided not to apply.
+
+        The service answered; the *adapter* declined — because the rewrite would
+        not have saved anything, or because the seam cannot carry the shape
+        safely. The response is kept so the metadata still reports what the
+        service actually said, which is what a shadow report needs.
+        """
+        return dataclasses.replace(self, applied=False, reason=reason)
+
+    @classmethod
+    def passthrough_result(
+        cls,
+        reason: str,
+        *,
+        request_id: str = "",
+        operating_point: str = "",
+        shadow: bool = False,
+        response: Optional[ContextResponse] = None,
+        error: Optional[BaseException] = None,
+        client_latency_ms: float = 0.0,
+        attempts: int = 0,
+        request_bytes: int = 0,
+    ) -> SelectionResult:
+        return cls(
+            applied=False,
+            reason=reason,
+            request_id=request_id,
+            operating_point=operating_point,
+            shadow=shadow,
+            response=response,
+            error=error,
+            client_latency_ms=client_latency_ms,
+            attempts=attempts,
+            request_bytes=request_bytes,
+        )
+
+
+@dataclass
+class SelectionStats:
+    """Counters an adapter can expose for a shadow report or a health check.
+
+    Deliberately tiny and deliberately not global: an adapter instance owns one.
+    Thread-safety is left to the caller; every field is a plain int incremented
+    under the GIL, so a lost increment under contention costs a count, never
+    correctness of the request path.
+    """
+
+    calls: int = 0
+    applied: int = 0
+    passthrough: int = 0
+    failures: int = 0
+    tokens_before: int = 0
+    tokens_after: int = 0
+    tokens_saved: int = 0
+    reasons: Dict[str, int] = field(default_factory=dict)
+
+    def record(self, result: SelectionResult) -> None:
+        self.calls += 1
+        self.reasons[result.reason] = self.reasons.get(result.reason, 0) + 1
+        if result.applied:
+            self.applied += 1
+        else:
+            self.passthrough += 1
+        if result.failed:
+            self.failures += 1
+        r = result.response
+        if r is not None:
+            self.tokens_before += r.tokens_before
+            self.tokens_after += r.tokens_after
+            self.tokens_saved += r.tokens_saved
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "calls": self.calls,
+            "applied": self.applied,
+            "passthrough": self.passthrough,
+            "failures": self.failures,
+            "tokens_before": self.tokens_before,
+            "tokens_after": self.tokens_after,
+            "tokens_saved": self.tokens_saved,
+            "reasons": dict(self.reasons),
+        }
+
+
+__all__ = ["Reason", "BENIGN_REASONS", "SelectionResult", "SelectionStats"]

needlepath/testing.py

@@ -0,0 +1,224 @@
+"""Test doubles, shipped as public API.
+
+The framework adapters in this tree test against these rather than against a
+network, and so should yours: every binding rule in §8.2 is a rule about what
+happens when the *service* misbehaves, and you cannot test that against a
+healthy service.
+
+Nothing here talks to a network. :class:`FakeTransport` is a scripted
+:class:`~needlepath.transport.Transport`; :func:`response_payload` builds a
+contract-valid response body so a test does not have to hand-write ten required
+fields to exercise one of them.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+
+from .transport import HttpResult
+
+#: Something a :class:`FakeTransport` can be scripted with: a ready result, an
+#: exception to raise, or a callable that produces one from the request.
+Scripted = Union[HttpResult, BaseException, Callable[..., HttpResult]]
+
+
+def response_payload(
+    request_id: str,
+    *,
+    rendered_context: str = "Relevant State:\n- kept",
+    selected: Optional[Sequence[Dict[str, Any]]] = None,
+    tokens_before: int = 1000,
+    tokens_after: int = 100,
+    records_available: int = 4,
+    records_selected: int = 1,
+    fallback_used: bool = False,
+    selection_error: Optional[str] = None,
+    policy_version: str = "np-2026-07-r2",
+    gate: Optional[Dict[str, Any]] = None,
+    engine_latency_ms: float = 12.0,
+    **extra: Any,
+) -> Dict[str, Any]:
+    """A contract-valid ``ContextResponse`` body.
+
+    ``**extra`` lands as unknown top-level fields, which is how you test that
+    this client tolerates the additive changes ``/v1`` is allowed to make
+    (``usage``, and whatever comes after it).
+    """
+    if selected is None and records_selected:
+        selected = [
+            {
+                "record_id": "r1",
+                "kind": "tool_result",
+                "score": 0.9,
+                "reason": "engage:needle",
+                "excerpt": "kept",
+                "excerpt_format": "plain",
+                "selected_tokens": 100,
+            }
+        ]
+    payload: Dict[str, Any] = {
+        "request_id": request_id,
+        "rendered_context": rendered_context,
+        "policy_version": policy_version,
+        "selected": list(selected or []),
+        "tokens_before": tokens_before,
+        "tokens_after": tokens_after,
+        "tokens_saved": max(0, tokens_before - tokens_after),
+        "records_available": records_available,
+        "records_selected": records_selected,
+        "fallback_used": fallback_used,
+        "selection_error": selection_error,
+        "engine_latency_ms": engine_latency_ms,
+        "budget_tokens": 4000,
+        "attempted_budget_tokens": [],
+        "reduction_ratio": (
+            (tokens_before - tokens_after) / tokens_before if tokens_before else 0.0
+        ),
+        "safety": None,
+        "gate": gate
+        if gate is not None
+        else {"engaged": True, "reason": "engage:needle", "signals": {}},
+        "format_metrics": {"context_format": "plain"},
+    }
+    payload.update(extra)
+    return payload
+
+
+def ok(payload: Dict[str, Any], status: int = 200) -> HttpResult:
+    """A JSON :class:`HttpResult`."""
+    import json
+
+    return HttpResult(
+        status=status,
+        body=json.dumps(payload).encode("utf-8"),
+        headers={"content-type": "application/json"},
+    )
+
+
+def error(status: int, code: str = "engine_error", **fields: Any) -> HttpResult:
+    """A JSON error :class:`HttpResult` in the shape the endpoint actually sends."""
+    import json
+
+    body: Dict[str, Any] = {"error": code}
+    body.update(fields)
+    return HttpResult(
+        status=status,
+        body=json.dumps(body).encode("utf-8"),
+        headers={"content-type": "application/json"},
+    )
+
+
+class FakeTransport:
+    """A scripted transport. Records every call it was asked to make.
+
+    Script entries are consumed in order. When the script runs out, the last
+    entry repeats — so ``FakeTransport([timeout_error])`` is "always times out"
+    without having to know the retry count.
+    """
+
+    def __init__(self, script: Optional[Sequence[Scripted]] = None) -> None:
+        self.script: List[Scripted] = list(script or [])
+        self.calls: List[Dict[str, Any]] = []
+        self.closed = False
+
+    # -- sync seam ----------------------------------------------------- #
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult:
+        self.calls.append(
+            {
+                "method": method,
+                "url": url,
+                "headers": dict(headers),
+                "body": body,
+                "timeout": timeout,
+            }
+        )
+        if not self.script:
+            raise AssertionError("FakeTransport called with an empty script")
+        index = min(len(self.calls) - 1, len(self.script) - 1)
+        entry = self.script[index]
+        if isinstance(entry, BaseException):
+            raise entry
+        if callable(entry):
+            return entry(method, url, headers=headers, body=body, timeout=timeout)
+        return entry
+
+    def close(self) -> None:
+        self.closed = True
+
+    # -- async seam ---------------------------------------------------- #
+
+    async def arequest(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult:
+        return self.request(method, url, headers=headers, body=body, timeout=timeout)
+
+    async def aclose(self) -> None:
+        self.closed = True
+
+    # -- helpers ------------------------------------------------------- #
+
+    @property
+    def bodies(self) -> List[Dict[str, Any]]:
+        """Every request body, parsed. The assertion surface for wire tests."""
+        import json
+
+        return [json.loads(c["body"].decode("utf-8")) for c in self.calls if c["body"]]
+
+
+class FakeAsyncTransport:
+    """The async seam over a :class:`FakeTransport`.
+
+    Separate class rather than duck-typing the sync one, because
+    ``AsyncTransport.request`` must be awaitable and ``Transport.request`` must
+    not be; one object cannot satisfy both without a lie somewhere.
+    """
+
+    def __init__(self, script: Optional[Sequence[Scripted]] = None) -> None:
+        self.inner = FakeTransport(script)
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> HttpResult:
+        return self.inner.request(method, url, headers=headers, body=body, timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self.inner.aclose()
+
+    @property
+    def calls(self) -> List[Dict[str, Any]]:
+        return self.inner.calls
+
+    @property
+    def bodies(self) -> List[Dict[str, Any]]:
+        return self.inner.bodies
+
+
+__all__ = [
+    "FakeTransport",
+    "FakeAsyncTransport",
+    "response_payload",
+    "ok",
+    "error",
+    "Scripted",
+]