needlepath 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,3 +1,12 @@
+## 0.2.2
+
+### Changed
+
+- First published build carrying the `sanitized_fallback` and `blocked`
+  security-screening outcomes, `security_mode` on requests and the
+  `security_action` receipt field (see the API release notes). 0.2.1 predates
+  them and classifies a screened fallback as `selection_unsafe`.
+
 # Changelog
 
 All notable changes to the `needlepath` Python package are documented here.
@@ -5,6 +14,30 @@ 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).
 
+## [Unreleased]
+
+### Added
+
+- **System One state adapter**: `needlepath.integrations.system_one` reshapes a
+  selection into the `{state, questions}` request body that small classifier
+  models (TypeSafe's Jev, Laya) accept. `to_system_one_state()` carries every
+  record in `response.selected`, in the order returned, with the text
+  unmodified; `mode="rendered"` returns `state` as one string instead of an
+  array. `questions` travels in the shape it was passed, mapping or sequence,
+  so a `{id: question}` mapping never arrives as a list of its keys.
+  A `SelectionResult` is accepted only when it `applied`; a passthrough raises
+  `NeedlepathConfigError` naming the reason, since its response can carry a
+  selection the client declined to use. `selection_receipt()` returns
+  `request_id`, `selection_id`, `policy_version`, `tokens_saved` and `outcome`
+  as a sidecar dict, prefixed the way `SelectionResult.metadata()` prefixes its
+  keys.
+
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: needlepath
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -222,13 +258,57 @@ carry fragments of your input in an exception message — the Lambda deliberatel
 declines to log it for that reason — so only its *type* appears here. The full
 string stays on `result.response.selection_error`.
 
+## System One models (TypeSafe Jev, Laya)
+
+Small classifier models that take `{state, questions}` and answer the questions
+against the state. `needlepath.integrations.system_one` reshapes a selection
+into that request body:
+
+```python
+from needlepath.integrations.system_one import selection_receipt, to_system_one_state
+
+result = client.select(records=records, task=task, max_context_tokens=4000)
+payload = to_system_one_state(
+    # Fail open with your own records: a result that did not apply is refused.
+    result if result.applied else records,
+    questions={"refund": Noul(instructions="Is this a refund request?")},
+)
+# Sidecar metadata, not part of the body.
+receipt = selection_receipt(result)
+```
+
+`payload["state"]` is a JSON array of `{record_id, title, source, text}`, one
+entry per record in `response.selected`, **in the order the service returned
+them, with the text unmodified**. The adapter is transport only: no threshold on
+`score`, no drop for an empty excerpt, no re-sort, no deduplication, and no
+question you did not pass. `mode="rendered"` returns `state` as a single string
+instead, records joined by blank lines under a one-line `[record_id] title`
+header, for a classifier whose state argument is text.
+
+`questions` travels in the shape you pass it. `langchain-typesafe` reads a
+mapping of id to typed question (`Noul`, `Choice`, `Score`); a different
+`{state, questions}` service may read a list. Both are copied and sent
+unchanged, so a mapping never arrives as a list of its keys. A bare string is
+refused rather than iterated into single-character questions.
+
+`to_system_one_state` accepts a `SelectionResult` only when it `applied`. A
+result that did not apply is a passthrough — your own records are what has to
+be sent — and its `response` can still carry a selection the client itself
+declined to use, so passing one raises `NeedlepathConfigError` naming the
+reason. To reshape that response anyway, for an audit or a shadow report, pass
+`result.response`.
+
+`selection_receipt()` returns `request_id`, `selection_id`, `policy_version`,
+`tokens_saved` and `outcome`, prefixed the way `result.metadata()` prefixes its
+keys. Attribution travels beside the request; record text never travels in it.
+
 ## Testing your integration
 
 ```python
 from needlepath.testing import FakeTransport, response_payload, ok, error
 
 transport = FakeTransport([error(503), ok(response_payload("np-1"))])
-client = NeedlepathClient(operating_point="np-2026-07-r2", transport=transport)
+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.2}/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
@@ -193,13 +229,57 @@ carry fragments of your input in an exception message — the Lambda deliberatel
 declines to log it for that reason — so only its *type* appears here. The full
 string stays on `result.response.selection_error`.
 
+## System One models (TypeSafe Jev, Laya)
+
+Small classifier models that take `{state, questions}` and answer the questions
+against the state. `needlepath.integrations.system_one` reshapes a selection
+into that request body:
+
+```python
+from needlepath.integrations.system_one import selection_receipt, to_system_one_state
+
+result = client.select(records=records, task=task, max_context_tokens=4000)
+payload = to_system_one_state(
+    # Fail open with your own records: a result that did not apply is refused.
+    result if result.applied else records,
+    questions={"refund": Noul(instructions="Is this a refund request?")},
+)
+# Sidecar metadata, not part of the body.
+receipt = selection_receipt(result)
+```
+
+`payload["state"]` is a JSON array of `{record_id, title, source, text}`, one
+entry per record in `response.selected`, **in the order the service returned
+them, with the text unmodified**. The adapter is transport only: no threshold on
+`score`, no drop for an empty excerpt, no re-sort, no deduplication, and no
+question you did not pass. `mode="rendered"` returns `state` as a single string
+instead, records joined by blank lines under a one-line `[record_id] title`
+header, for a classifier whose state argument is text.
+
+`questions` travels in the shape you pass it. `langchain-typesafe` reads a
+mapping of id to typed question (`Noul`, `Choice`, `Score`); a different
+`{state, questions}` service may read a list. Both are copied and sent
+unchanged, so a mapping never arrives as a list of its keys. A bare string is
+refused rather than iterated into single-character questions.
+
+`to_system_one_state` accepts a `SelectionResult` only when it `applied`. A
+result that did not apply is a passthrough — your own records are what has to
+be sent — and its `response` can still carry a selection the client itself
+declined to use, so passing one raises `NeedlepathConfigError` naming the
+reason. To reshape that response anyway, for an audit or a shadow report, pass
+`result.response`.
+
+`selection_receipt()` returns `request_id`, `selection_id`, `policy_version`,
+`tokens_saved` and `outcome`, prefixed the way `result.metadata()` prefixes its
+keys. Attribution travels beside the request; record text never travels in it.
+
 ## Testing your integration
 
 ```python
 from needlepath.testing import FakeTransport, response_payload, ok, error
 
 transport = FakeTransport([error(503), ok(response_payload("np-1"))])
-client = NeedlepathClient(operating_point="np-2026-07-r2", transport=transport)
+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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "needlepath"
-version = "0.2.0"
+version = "0.2.2"
 description = "Framework-free client for the Needlepath hosted context-selection service."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -52,6 +52,7 @@ packages = ["src/needlepath"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
 filterwarnings = ["error"]
 
 [tool.ruff]

{needlepath-0.2.0 → needlepath-0.2.2}/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,14 @@ from .models import (
     ContextRequest,
     ContextResponse,
     GateSummary,
+    OutcomeReport,
+    OutcomeResponse,
     RecordKind,
     SafetySummary,
+    SecurityMode,
     SelectedRecord,
+    SelectionTrace,
+    SelectionTraceRecord,
     TaskSpec,
 )
 from .result import BENIGN_REASONS, Reason, SelectionResult, SelectionStats
@@ -93,7 +101,12 @@ __all__ = [
     "SelectedRecord",
     "SafetySummary",
     "GateSummary",
+    "SelectionTrace",
+    "SelectionTraceRecord",
+    "OutcomeReport",
+    "OutcomeResponse",
     "RecordKind",
+    "SecurityMode",
     "REQUIRED_RESPONSE_FIELDS",
     # results
     "SelectionResult",
@@ -118,6 +131,7 @@ __all__ = [
     "default_async_transport",
     # helpers
     "build_request",
+    "build_outcome_report",
     "encode_body",
     "classify",
     "validate_response_payload",
@@ -125,12 +139,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",