needlepath 0.2.0__tar.gz → 0.2.1__tar.gz

{needlepath-0.2.0 → needlepath-0.2.1}/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.1] - 2026-09-03
+
+### Changed
+
+- Docs, docstrings and examples pin np-2026-08-r4. No behaviour change.
+
 ## [0.2.0] - 2026-08-07
 
 ### Added

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: needlepath
-Version: 0.2.0
+Version: 0.2.1
 Summary: Framework-free client for the Needlepath hosted context-selection service.
 Project-URL: Homepage, https://nextmoca.com
 Author: Next Moca Global, Inc.
@@ -57,7 +57,7 @@ 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"
+    operating_point="np-2026-08-r4",  # required — see "Pin the operating point"
 )
 
 result = client.select(
@@ -80,7 +80,7 @@ original context. That is the whole integration contract.
 ```python
 from needlepath import AsyncNeedlepathClient
 
-async with AsyncNeedlepathClient(operating_point="np-2026-07-r2") as client:
+async with AsyncNeedlepathClient(operating_point="np-2026-08-r4") as client:
     result = await client.select(records=..., task=..., max_context_tokens=4000)
 ```
 
@@ -88,6 +88,41 @@ 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.
 
+### R4 trace and outcome attribution
+
+Pin `np-2026-08-r4` and opt into the metadata-only trace when you need to
+inspect record dispositions:
+
+```python
+result = client.select(
+    records=records,
+    task=TaskSpec(prompt=question),
+    max_context_tokens=4000,
+    return_trace=True,
+)
+
+if result.response and result.response.selection_trace:
+    for item in result.response.selection_trace.records:
+        print(item.record_id, item.disposition, item.reason)
+```
+
+The hosted response also supplies `result.selection_id`, a server-issued id
+separate from your request id. Report downstream quality after the model call:
+
+```python
+if result.selection_id:
+    client.report_outcome(
+        result.selection_id,
+        task_success=True,
+        context_sufficient=True,
+        evaluation_source="application",
+    )
+```
+
+`report_outcome()` is idempotent and independently retryable. It can raise on a
+callback failure; that never changes `select()` or the context already returned.
+Do not send prompts, context, model output, answers, or free-form notes.
+
 ## Configuration
 
 | Argument | Environment | Default |
@@ -130,6 +165,7 @@ if not result.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 |
+| `escalated` | no | the engine declined: full context over capacity. **Charged at the full rate**, unlike a free stand-down |
 | `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` |
@@ -158,7 +194,7 @@ 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
+Labels are immutable: `np-2026-08-r4` 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.
 
@@ -176,7 +212,7 @@ that passes at 5.99 MB can still be rejected upstream. Lower
 ### 4. Shadow mode is a one-line switch
 
 ```python
-client = NeedlepathClient(operating_point="np-2026-07-r2", shadow=True)
+client = NeedlepathClient(operating_point="np-2026-08-r4", shadow=True)
 ```
 
 The call is made exactly as a live call would be — same body, same billing, same
@@ -228,7 +264,7 @@ string stays on `result.response.selection_error`.
 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)
+client = NeedlepathClient(operating_point="np-2026-08-r4", transport=transport)
 ```
 
 `needlepath.testing` is public API, not a private helper. Every rule above is a

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

@@ -28,7 +28,7 @@ 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"
+    operating_point="np-2026-08-r4",  # required — see "Pin the operating point"
 )
 
 result = client.select(
@@ -51,7 +51,7 @@ original context. That is the whole integration contract.
 ```python
 from needlepath import AsyncNeedlepathClient
 
-async with AsyncNeedlepathClient(operating_point="np-2026-07-r2") as client:
+async with AsyncNeedlepathClient(operating_point="np-2026-08-r4") as client:
     result = await client.select(records=..., task=..., max_context_tokens=4000)
 ```
 
@@ -59,6 +59,41 @@ 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.
 
+### R4 trace and outcome attribution
+
+Pin `np-2026-08-r4` and opt into the metadata-only trace when you need to
+inspect record dispositions:
+
+```python
+result = client.select(
+    records=records,
+    task=TaskSpec(prompt=question),
+    max_context_tokens=4000,
+    return_trace=True,
+)
+
+if result.response and result.response.selection_trace:
+    for item in result.response.selection_trace.records:
+        print(item.record_id, item.disposition, item.reason)
+```
+
+The hosted response also supplies `result.selection_id`, a server-issued id
+separate from your request id. Report downstream quality after the model call:
+
+```python
+if result.selection_id:
+    client.report_outcome(
+        result.selection_id,
+        task_success=True,
+        context_sufficient=True,
+        evaluation_source="application",
+    )
+```
+
+`report_outcome()` is idempotent and independently retryable. It can raise on a
+callback failure; that never changes `select()` or the context already returned.
+Do not send prompts, context, model output, answers, or free-form notes.
+
 ## Configuration
 
 | Argument | Environment | Default |
@@ -101,6 +136,7 @@ if not result.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 |
+| `escalated` | no | the engine declined: full context over capacity. **Charged at the full rate**, unlike a free stand-down |
 | `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` |
@@ -129,7 +165,7 @@ 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
+Labels are immutable: `np-2026-08-r4` 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.
 
@@ -147,7 +183,7 @@ that passes at 5.99 MB can still be rejected upstream. Lower
 ### 4. Shadow mode is a one-line switch
 
 ```python
-client = NeedlepathClient(operating_point="np-2026-07-r2", shadow=True)
+client = NeedlepathClient(operating_point="np-2026-08-r4", shadow=True)
 ```
 
 The call is made exactly as a live call would be — same body, same billing, same
@@ -199,7 +235,7 @@ string stays on `result.response.selection_error`.
 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)
+client = NeedlepathClient(operating_point="np-2026-08-r4", transport=transport)
 ```
 
 `needlepath.testing` is public API, not a private helper. Every rule above is a

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

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

{needlepath-0.2.0 → needlepath-0.2.1}/src/needlepath/__init__.py

@@ -2,7 +2,7 @@
 
     from needlepath import NeedlepathClient, ContextRecord, TaskSpec
 
-    client = NeedlepathClient(operating_point="np-2026-07-r2")   # key from env
+    client = NeedlepathClient(operating_point="np-2026-08-r4")   # key from env
     result = client.select(
         records=[ContextRecord(text=tool_output, kind="tool_result", id="t1")],
         task=TaskSpec(prompt=user_question),
@@ -33,10 +33,13 @@ from .client import (
     HEALTH_PATH,
     MAX_REQUEST_BYTES,
     OPERATING_POINTS_PATH,
+    OUTCOME_RETRY_STATUSES,
+    OUTCOMES_PATH,
     RETRY_STATUSES,
     SELECT_PATH,
     AsyncNeedlepathClient,
     NeedlepathClient,
+    build_outcome_report,
     build_request,
     classify,
     encode_body,
@@ -61,9 +64,13 @@ from .models import (
     ContextRequest,
     ContextResponse,
     GateSummary,
+    OutcomeReport,
+    OutcomeResponse,
     RecordKind,
     SafetySummary,
     SelectedRecord,
+    SelectionTrace,
+    SelectionTraceRecord,
     TaskSpec,
 )
 from .result import BENIGN_REASONS, Reason, SelectionResult, SelectionStats
@@ -93,6 +100,10 @@ __all__ = [
     "SelectedRecord",
     "SafetySummary",
     "GateSummary",
+    "SelectionTrace",
+    "SelectionTraceRecord",
+    "OutcomeReport",
+    "OutcomeResponse",
     "RecordKind",
     "REQUIRED_RESPONSE_FIELDS",
     # results
@@ -118,6 +129,7 @@ __all__ = [
     "default_async_transport",
     # helpers
     "build_request",
+    "build_outcome_report",
     "encode_body",
     "classify",
     "validate_response_payload",
@@ -125,12 +137,14 @@ __all__ = [
     # constants
     "DEFAULT_BASE_URL",
     "SELECT_PATH",
+    "OUTCOMES_PATH",
     "HEALTH_PATH",
     "OPERATING_POINTS_PATH",
     "MAX_REQUEST_BYTES",
     "DEFAULT_TIMEOUT_S",
     "DEFAULT_MAX_RETRIES",
     "RETRY_STATUSES",
+    "OUTCOME_RETRY_STATUSES",
     # feature flags
     "WIRE_SHADOW_MODE",
     "wire_shadow_mode_enabled",

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

@@ -42,6 +42,8 @@ from .models import (
     ContextRecord,
     ContextRequest,
     ContextResponse,
+    OutcomeReport,
+    OutcomeResponse,
     TaskSpec,
 )
 from .result import Reason, SelectionResult
@@ -65,6 +67,7 @@ from .version import __version__
 DEFAULT_BASE_URL = "https://api.nextmoca.com"
 
 SELECT_PATH = "/v1/context/select"
+OUTCOMES_PATH = "/v1/outcomes"
 HEALTH_PATH = "/v1/health"
 OPERATING_POINTS_PATH = "/v1/operating-points"
 
@@ -86,6 +89,7 @@ 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})
+OUTCOME_RETRY_STATUSES = RETRY_STATUSES | {500}
 
 #: **Not** retried, and worth saying why: a 500 from this endpoint is
 #: ``engine_error`` — a deterministic failure on this exact input. Retrying it
@@ -129,7 +133,7 @@ def _resolve_operating_point(operating_point: Optional[str]) -> str:
     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 "
+            "(e.g. 'np-2026-08-r4') 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}."
         )
@@ -185,6 +189,9 @@ def build_request(
     render: bool = True,
     render_format: str = "plain",
     return_per_record: bool = True,
+    return_trace: bool = False,
+    selection_strategy: Optional[str] = None,
+    support_contract: Optional[str] = None,
 ) -> ContextRequest:
     """Assemble a :class:`ContextRequest` with the operating point already pinned.
 
@@ -223,6 +230,9 @@ def build_request(
         render=render,
         render_format=render_format,
         return_per_record=return_per_record,
+        return_trace=return_trace,
+        selection_strategy=selection_strategy,
+        support_contract=support_contract,
     )
 
 
@@ -270,6 +280,52 @@ def validate_response_payload(payload: Any, request_id: Optional[str]) -> Contex
         raise NeedlepathContractError(f"malformed response body: {exc}") from exc
 
 
+def _header(headers: Dict[str, str], name: str) -> Optional[str]:
+    wanted = name.lower()
+    for key, value in headers.items():
+        if key.lower() == wanted and value:
+            return value
+    return None
+
+
+def build_outcome_report(
+    selection_id: str,
+    *,
+    task_success: Optional[bool] = None,
+    context_sufficient: Optional[bool] = None,
+    evaluation_source: str = "application",
+    task_latency_ms: Optional[int] = None,
+    baseline_task_latency_ms: Optional[int] = None,
+) -> OutcomeReport:
+    try:
+        return OutcomeReport(
+            selection_id=selection_id,
+            task_success=task_success,
+            context_sufficient=context_sufficient,
+            evaluation_source=evaluation_source,
+            task_latency_ms=task_latency_ms,
+            baseline_task_latency_ms=baseline_task_latency_ms,
+        )
+    except ValueError as exc:
+        raise NeedlepathConfigError(str(exc)) from exc
+
+
+def encode_outcome_body(report: OutcomeReport) -> bytes:
+    return json.dumps(report.to_wire(), separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def validate_outcome_payload(payload: Any, selection_id: str) -> OutcomeResponse:
+    if not isinstance(payload, dict):
+        raise NeedlepathContractError("outcome response is not a JSON object")
+    try:
+        response = OutcomeResponse.from_wire(payload, expected_selection_id=selection_id)
+    except (TypeError, ValueError) as exc:
+        raise NeedlepathContractError(f"malformed outcome response: {exc}") from exc
+    if not response.accepted:
+        raise NeedlepathContractError("outcome response did not acknowledge acceptance")
+    return response
+
+
 def classify(
     response: ContextResponse,
     *,
@@ -285,9 +341,10 @@ def classify(
     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.
+    That value is an open enum, and a client that branches on today's prefixes
+    is a client that breaks additively. Every decision here comes from a
+    structural field, plus one recognised value of the top-level ``outcome``
+    (see the note at that branch for why that is not the same mistake).
     """
     if response.selection_error:
         return Reason.SELECTION_ERROR
@@ -295,6 +352,15 @@ def classify(
         # 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
+    if response.outcome == "escalated":
+        # The one service-supplied enum this function reads, and it reads
+        # exactly one value from it. This is not the exhaustive matching the
+        # docstring forbids: any value we do not recognise falls through to the
+        # structural checks and gets the same answer it got before the field
+        # existed. The branch exists because escalation and a stand-down are
+        # identical on the wire apart from this field, and they are billed
+        # differently: escalation at the full rate, a stand-down free.
+        return Reason.ESCALATED
     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
@@ -449,7 +515,7 @@ class NeedlepathClient(_ClientBase):
 
         client = NeedlepathClient(
             api_key="np_live_...",              # or NEEDLEPATH_API_KEY
-            operating_point="np-2026-07-r2",    # required, and immutable
+            operating_point="np-2026-08-r4",    # required, and immutable
         )
         result = client.select(
             records=[ContextRecord(text=..., kind="tool_result", id="r1")],
@@ -464,7 +530,7 @@ class NeedlepathClient(_ClientBase):
     :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``.
+        ``np-2026-08-r4``. 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.
@@ -644,6 +710,7 @@ class NeedlepathClient(_ClientBase):
                             "a response arrived after the deadline had elapsed"
                         )
                     response = validate_response_payload(http.json(), request.request_id)
+                    response.selection_id = _header(http.headers, "x-needlepath-selection-id")
                     return response, attempts, len(body)
                 last = err
                 if http.status not in RETRY_STATUSES:
@@ -670,6 +737,67 @@ class NeedlepathClient(_ClientBase):
         last._np_bytes = len(body)  # type: ignore[attr-defined]
         raise last
 
+    def report_outcome(
+        self,
+        selection_id: str,
+        *,
+        task_success: Optional[bool] = None,
+        context_sufficient: Optional[bool] = None,
+        evaluation_source: str = "application",
+        task_latency_ms: Optional[int] = None,
+        baseline_task_latency_ms: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> OutcomeResponse:
+        """Report downstream quality for a served selection.
+
+        This call is intentionally separate from :meth:`select`: it is
+        idempotent and retryable, and any exception here cannot alter the
+        selection result already returned to the caller.
+        """
+        report = build_outcome_report(
+            selection_id,
+            task_success=task_success,
+            context_sufficient=context_sufficient,
+            evaluation_source=evaluation_source,
+            task_latency_ms=task_latency_ms,
+            baseline_task_latency_ms=baseline_task_latency_ms,
+        )
+        body = encode_outcome_body(report)
+        if len(body) > self.max_request_bytes:
+            raise NeedlepathPayloadTooLargeError(len(body), self.max_request_bytes)
+        deadline = time.monotonic() + float(timeout if timeout is not None else self.timeout)
+        last: Optional[NeedlepathError] = None
+        for attempt in range(self.max_retries + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            try:
+                http = self._transport.request(
+                    "POST",
+                    self._url(OUTCOMES_PATH),
+                    headers=self._headers(),
+                    body=body,
+                    timeout=remaining,
+                )
+                err = self._to_error(http)
+                if err is None:
+                    return validate_outcome_payload(http.json(), selection_id)
+                last = err
+                if http.status not in OUTCOME_RETRY_STATUSES:
+                    break
+                retry_after = err.retry_after
+            except (NeedlepathTransportError, NeedlepathTimeoutError) as exc:
+                last = exc
+                retry_after = None
+            if attempt >= self.max_retries:
+                break
+            delay = self._backoff.delay(attempt, retry_after, deadline - time.monotonic())
+            if delay:
+                time.sleep(delay)
+        if last is None:
+            last = NeedlepathTimeoutError("deadline elapsed before outcome report was sent")
+        raise last
+
     # ---------------------------------------------------------------- #
     # Diagnostics. These raise: they are not on any agent's hot path.
     # ---------------------------------------------------------------- #
@@ -873,6 +1001,7 @@ class AsyncNeedlepathClient(_ClientBase):
                             "a response arrived after the deadline had elapsed"
                         )
                     response = validate_response_payload(http.json(), request.request_id)
+                    response.selection_id = _header(http.headers, "x-needlepath-selection-id")
                     return response, attempts, len(body)
                 last = err
                 if http.status not in RETRY_STATUSES:
@@ -897,6 +1026,62 @@ class AsyncNeedlepathClient(_ClientBase):
         last._np_bytes = len(body)  # type: ignore[attr-defined]
         raise last
 
+    async def report_outcome(
+        self,
+        selection_id: str,
+        *,
+        task_success: Optional[bool] = None,
+        context_sufficient: Optional[bool] = None,
+        evaluation_source: str = "application",
+        task_latency_ms: Optional[int] = None,
+        baseline_task_latency_ms: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> OutcomeResponse:
+        """Asynchronous twin of :meth:`NeedlepathClient.report_outcome`."""
+        report = build_outcome_report(
+            selection_id,
+            task_success=task_success,
+            context_sufficient=context_sufficient,
+            evaluation_source=evaluation_source,
+            task_latency_ms=task_latency_ms,
+            baseline_task_latency_ms=baseline_task_latency_ms,
+        )
+        body = encode_outcome_body(report)
+        if len(body) > self.max_request_bytes:
+            raise NeedlepathPayloadTooLargeError(len(body), self.max_request_bytes)
+        deadline = time.monotonic() + float(timeout if timeout is not None else self.timeout)
+        last: Optional[NeedlepathError] = None
+        for attempt in range(self.max_retries + 1):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            try:
+                http = await self._transport.request(
+                    "POST",
+                    self._url(OUTCOMES_PATH),
+                    headers=self._headers(),
+                    body=body,
+                    timeout=remaining,
+                )
+                err = self._to_error(http)
+                if err is None:
+                    return validate_outcome_payload(http.json(), selection_id)
+                last = err
+                if http.status not in OUTCOME_RETRY_STATUSES:
+                    break
+                retry_after = err.retry_after
+            except (NeedlepathTransportError, NeedlepathTimeoutError) as exc:
+                last = exc
+                retry_after = None
+            if attempt >= self.max_retries:
+                break
+            delay = self._backoff.delay(attempt, retry_after, deadline - time.monotonic())
+            if delay:
+                await asyncio.sleep(delay)
+        if last is None:
+            last = NeedlepathTimeoutError("deadline elapsed before outcome report was sent")
+        raise last
+
     async def health(self, *, timeout: Optional[float] = None) -> Dict[str, Any]:
         return await self._aget(HEALTH_PATH, timeout)
 
@@ -994,9 +1179,7 @@ def _finish(
         reason=reason,
         # 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
-        ),
+        request_id=(request.request_id if request.request_id is not None else response.request_id),
         operating_point=operating_point,
         shadow=shadow,
         response=response,
@@ -1010,12 +1193,14 @@ def _finish(
 __all__ = [
     "DEFAULT_BASE_URL",
     "SELECT_PATH",
+    "OUTCOMES_PATH",
     "HEALTH_PATH",
     "OPERATING_POINTS_PATH",
     "MAX_REQUEST_BYTES",
     "DEFAULT_TIMEOUT_S",
     "DEFAULT_MAX_RETRIES",
     "RETRY_STATUSES",
+    "OUTCOME_RETRY_STATUSES",
     "NeedlepathClient",
     "AsyncNeedlepathClient",
     "build_request",
@@ -1023,4 +1208,7 @@ __all__ = [
     "classify",
     "validate_response_payload",
     "new_request_id",
+    "build_outcome_report",
+    "encode_outcome_body",
+    "validate_outcome_payload",
 ]