needlepath 0.1.1__tar.gz → 0.2.1__tar.gz

needlepath-0.2.1/CHANGELOG.md

@@ -0,0 +1,51 @@
+# 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.1] - 2026-09-03
+
+### Changed
+
+- Docs, docstrings and examples pin np-2026-08-r4. No behaviour change.
+
+## [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.1 → needlepath-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: needlepath
-Version: 0.1.1
+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.1.1 → 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.1.1 → needlepath-0.2.1}/pyproject.toml

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

{needlepath-0.1.1 → 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",