needlepath 0.2.2__tar.gz → 0.2.4__tar.gz

needlepath-0.2.4/CHANGELOG.md

@@ -0,0 +1,139 @@
+# 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.4] - 2026-11-05
+
+### Added
+
+- **`SelectionResult.protected` and `SelectionResult.applying()`.** The two
+  rules an adapter must follow once workspace protection is in force, decided
+  in the core so no adapter re-derives them. `protected` is `True` when the
+  response's `governance` forbids raw-context fallback (a blocked verdict
+  included): an adapter's own shadow flag must exempt exactly these results
+  (`shadow and not protected`), mirroring `_finish`, which keeps a protected
+  delivery applied in a shadow run. `applying()` is a context for the install
+  step: an unexpected failure inside it is re-raised as a sanitized
+  `NeedlepathGuardrailError` when the result is protected and passes through
+  to the adapter's ordinary fail-open handler otherwise.
+
+### Fixed
+
+- **A blocked result is canonicalized to an empty delivery.** `_finish` kept
+  the wire's `rendered_context` and `selected` on a `Reason.BLOCKED` result,
+  so a type-valid body that contradicted its own verdict (a render, retained
+  records with excerpts) could be forwarded by a caller reading those fields
+  or by the System One adapter. A blocked result now always exposes an empty
+  render and no selected records; the body is not rejected (the verdict is
+  the engine's word, the render is simply not delivered), and the receipt
+  keeps what the wire reported (`outcome`, `governance`, `usage`,
+  `security_action`, request id, token and record counts).
+  `to_system_one_state` mirrors the rule at the point of use: a blocked
+  result or response, however assembled, contributes no state.
+
+## [0.2.3] - 2026-11-04
+
+### Fixed
+
+- **`outcome: blocked` is applied, never passed through.** A governed
+  workspace answers a record its policy withholds with top-level
+  `outcome: "blocked"`, zero records, an empty render and a `governance`
+  block. By shape that is an empty selection, and `classify` returned
+  `EMPTY_SELECTION`, a passthrough, so every adapter delivered the withheld
+  record. `classify` now reads `blocked` first and returns `Reason.BLOCKED`,
+  an applied result with nothing to deliver: adapters install the verdict (a
+  notice, a placeholder, or no context) and never the original. Benign, not a
+  failure. A blocked verdict is enforced in shadow mode too: shadow never
+  restores a withheld record, so the result stays `reason: blocked`,
+  `applied: true` with `shadow: true`, `outcome` and `governance` on the
+  receipt.
+
+### Added
+
+- **Workspace guardrails.** `NeedlepathGuardrailError`, raised when the
+  service answers `guardrails_unavailable`, when a `governance` block is
+  malformed, or when a protected delivery (workspace policies applied,
+  raw-context fallback forbidden) cannot be applied. `guardrails_required=True`
+  on either client additionally stops on transport errors, timeouts and
+  missing enforcement evidence; it is never sent on the wire. A protected
+  delivery is applied even in shadow mode and cannot be `declined()` back to
+  the original. A blocked verdict is the exception on purpose: it is applied
+  as an empty delivery and never raises.
+- **`SelectionResult.metadata()` carries the whole receipt.** `outcome`,
+  `security_action`, `usage` and `governance` are now part of the
+  metadata-only receipt, verbatim and only when the response has them, so an
+  adapter that writes nothing but `metadata()` still shows what the engine
+  decided, what it billed and what its policies withheld.
+
+## [0.2.2] - 2026-11-03
+
+### 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`.
+
+### 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
+
+- **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.2.2 → needlepath-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: needlepath
-Version: 0.2.2
+Version: 0.2.4
 Summary: Framework-free client for the Needlepath hosted context-selection service.
 Project-URL: Homepage, https://nextmoca.com
 Author: Next Moca Global, Inc.
@@ -72,8 +72,51 @@ result = client.select(
 context = result.rendered_context if result.applied else my_original_context
 ```
 
-`select()` **never raises.** Read `result.applied`; when it is `False`, use your
-original context. That is the whole integration contract.
+Ordinary unprotected failures return `result.applied=False`, allowing your
+original context. A record your workspace policy withholds comes back as
+`result.reason == "blocked"` with `result.applied=True` and an empty
+`rendered_context`: the verdict is "deliver nothing from these records", and
+that is what you install. Workspace guardrail failures (the service could not
+enforce, or returned a protected response that cannot be applied) raise
+`NeedlepathGuardrailError`; stop the model request instead of substituting the
+original context.
+
+### Workspace guardrails
+
+The framework integrations (LangChain/LangGraph, Strands, LiteLLM and
+LlamaIndex) install a blocked verdict as a withheld notice in place of the
+record, or as no context, and let the agent continue; they propagate
+`NeedlepathGuardrailError` rather than falling back to the original.
+`guardrails_required` is a core-client option: pass a client you constructed
+with it to the integration.
+
+For a workspace with guardrails, update the SDK and construct either the sync
+or async client with `guardrails_required=True`:
+
+```python
+client = NeedlepathClient(
+    operating_point="np-2026-08-r4",
+    guardrails_required=True,
+)
+```
+
+This local fallback setting is never sent to the server and cannot disable
+workspace policies. It stops on transport errors, timeouts, invalid requests,
+and missing or malformed enforcement evidence. An authoritative admin pause
+(`enabled=False`) or active configuration with zero policies is honored.
+
+Regardless of this setting, invalid governance metadata or
+`guardrails_unavailable` raises a sanitized `NeedlepathGuardrailError`. A
+blocked response never raises: it is applied as an empty delivery
+(`reason: "blocked"`), in shadow mode too, and the receipt's `governance`
+block says what was withheld and under which policy revision.
+When the server forbids raw-context fallback, only its permitted selected
+context is applied, including in shadow mode and after engine recovery.
+`result.declined(...)` cannot restore the original context for a protected
+response. Do not catch a guardrail exception or a response rewrite error and
+continue with raw records. Existing clients
+must update and enable this setting to stop safely when an outage prevents
+the server from returning any enforcement evidence.
 
 ### Async
 
@@ -134,6 +177,7 @@ Do not send prompts, context, model output, answers, or free-form notes.
 | `max_retries` | — | `2` |
 | `max_request_bytes` | — | `6 * 1024 * 1024` |
 | `shadow` | — | `False` |
+| `guardrails_required` | — | `False` |
 
 The base URL is a **documented default, not a hard-coded one**: a durable custom
 domain replaces it, and swapping it is a config change rather than a release.
@@ -143,12 +187,13 @@ constraint; loopback is exempt so the localhost benchmark adapter still works.
 
 ## The four binding rules, and where they live
 
-### 1. Fail open, always
+### 1. Fail open for ordinary unprotected requests
 
-Timeout, 5xx, a violated contract, an empty selection, a stood-down gate — every
-one of them returns a `SelectionResult` with `applied=False`, the exception on
-`.error`, and a machine-readable `.reason`. Nothing is raised on the selection
-path.
+With the default configuration and no workspace protection evidence, a timeout,
+5xx, violated contract, empty selection, or stood-down gate returns a
+`SelectionResult` with `applied=False`, the exception on `.error`, and a
+machine-readable `.reason`. The workspace guardrail contract above takes
+precedence over these optimization fallbacks.
 
 ```python
 if not result.applied:
@@ -178,18 +223,19 @@ Treat an unrecognized reason as "do not apply". `result.failed` separates the
 error paths from the benign declines, which is the distinction that decides
 whether a passthrough deserves a `WARNING` or a `DEBUG`.
 
-The empty-selection rule is not a nicety. NEXPE-413 is the precedent: the engine
-returned an empty selection as a success, and at a framework boundary that has
-to degrade to passthrough, never to an empty context.
+An ordinary empty selection degrades to passthrough. A blocked verdict is
+applied as an empty delivery (`reason: "blocked"`, `applied=True`), never a
+passthrough and never an exception. An empty selection under workspace
+protection that is not a blocked verdict raises and must stop the model request.
 
-**`select_or_raise()` exists** for the two cases where fail-open is wrong —
-diagnostics, and a caller that is itself a benchmark and must not silently
-substitute a passthrough for a measurement. Do not use it in an adapter.
+**`select_or_raise()` exists** for diagnostics and benchmarks that must not
+silently substitute a passthrough for a measurement. Framework adapters use
+`select()` with its explicit guardrail exception contract.
 
 ### 2. Pin the operating point
 
-`operating_point` is required at construction, and this is the one failure that
-raises rather than fails open. Failing open on a bad request is degradation a
+`operating_point` is required at construction; an invalid configuration raises.
+Failing open on an ordinary unprotected bad request is degradation a
 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.
@@ -215,10 +261,14 @@ that passes at 5.99 MB can still be rejected upstream. Lower
 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
-operating point — the full response comes back and is reported, and **the
-selection is never applied**. Measure what Needlepath would have saved you;
-change nothing.
+The call is made exactly as a live call would be, with the same body, billing,
+and operating point. Ordinary unprotected selections are reported without
+being applied (`reason: "shadow"`). A blocked verdict is enforced in shadow
+mode too: shadow never restores a withheld record, so the result stays
+`reason: "blocked"`, `applied=True`, with `shadow: true`, `outcome` and
+`governance` on the receipt. A protected delivery likewise takes precedence:
+only its permitted selected context may be used, or the request stops with
+`NeedlepathGuardrailError`.
 
 `budget.mode = "shadow"` is **not on the wire yet**. `BudgetSpec.mode` on the
 published contract accepts `fixed` and `adaptive` only; adding `shadow` is a

{needlepath-0.2.2 → needlepath-0.2.4}/README.md

@@ -43,8 +43,51 @@ result = client.select(
 context = result.rendered_context if result.applied else my_original_context
 ```
 
-`select()` **never raises.** Read `result.applied`; when it is `False`, use your
-original context. That is the whole integration contract.
+Ordinary unprotected failures return `result.applied=False`, allowing your
+original context. A record your workspace policy withholds comes back as
+`result.reason == "blocked"` with `result.applied=True` and an empty
+`rendered_context`: the verdict is "deliver nothing from these records", and
+that is what you install. Workspace guardrail failures (the service could not
+enforce, or returned a protected response that cannot be applied) raise
+`NeedlepathGuardrailError`; stop the model request instead of substituting the
+original context.
+
+### Workspace guardrails
+
+The framework integrations (LangChain/LangGraph, Strands, LiteLLM and
+LlamaIndex) install a blocked verdict as a withheld notice in place of the
+record, or as no context, and let the agent continue; they propagate
+`NeedlepathGuardrailError` rather than falling back to the original.
+`guardrails_required` is a core-client option: pass a client you constructed
+with it to the integration.
+
+For a workspace with guardrails, update the SDK and construct either the sync
+or async client with `guardrails_required=True`:
+
+```python
+client = NeedlepathClient(
+    operating_point="np-2026-08-r4",
+    guardrails_required=True,
+)
+```
+
+This local fallback setting is never sent to the server and cannot disable
+workspace policies. It stops on transport errors, timeouts, invalid requests,
+and missing or malformed enforcement evidence. An authoritative admin pause
+(`enabled=False`) or active configuration with zero policies is honored.
+
+Regardless of this setting, invalid governance metadata or
+`guardrails_unavailable` raises a sanitized `NeedlepathGuardrailError`. A
+blocked response never raises: it is applied as an empty delivery
+(`reason: "blocked"`), in shadow mode too, and the receipt's `governance`
+block says what was withheld and under which policy revision.
+When the server forbids raw-context fallback, only its permitted selected
+context is applied, including in shadow mode and after engine recovery.
+`result.declined(...)` cannot restore the original context for a protected
+response. Do not catch a guardrail exception or a response rewrite error and
+continue with raw records. Existing clients
+must update and enable this setting to stop safely when an outage prevents
+the server from returning any enforcement evidence.
 
 ### Async
 
@@ -105,6 +148,7 @@ Do not send prompts, context, model output, answers, or free-form notes.
 | `max_retries` | — | `2` |
 | `max_request_bytes` | — | `6 * 1024 * 1024` |
 | `shadow` | — | `False` |
+| `guardrails_required` | — | `False` |
 
 The base URL is a **documented default, not a hard-coded one**: a durable custom
 domain replaces it, and swapping it is a config change rather than a release.
@@ -114,12 +158,13 @@ constraint; loopback is exempt so the localhost benchmark adapter still works.
 
 ## The four binding rules, and where they live
 
-### 1. Fail open, always
+### 1. Fail open for ordinary unprotected requests
 
-Timeout, 5xx, a violated contract, an empty selection, a stood-down gate — every
-one of them returns a `SelectionResult` with `applied=False`, the exception on
-`.error`, and a machine-readable `.reason`. Nothing is raised on the selection
-path.
+With the default configuration and no workspace protection evidence, a timeout,
+5xx, violated contract, empty selection, or stood-down gate returns a
+`SelectionResult` with `applied=False`, the exception on `.error`, and a
+machine-readable `.reason`. The workspace guardrail contract above takes
+precedence over these optimization fallbacks.
 
 ```python
 if not result.applied:
@@ -149,18 +194,19 @@ Treat an unrecognized reason as "do not apply". `result.failed` separates the
 error paths from the benign declines, which is the distinction that decides
 whether a passthrough deserves a `WARNING` or a `DEBUG`.
 
-The empty-selection rule is not a nicety. NEXPE-413 is the precedent: the engine
-returned an empty selection as a success, and at a framework boundary that has
-to degrade to passthrough, never to an empty context.
+An ordinary empty selection degrades to passthrough. A blocked verdict is
+applied as an empty delivery (`reason: "blocked"`, `applied=True`), never a
+passthrough and never an exception. An empty selection under workspace
+protection that is not a blocked verdict raises and must stop the model request.
 
-**`select_or_raise()` exists** for the two cases where fail-open is wrong —
-diagnostics, and a caller that is itself a benchmark and must not silently
-substitute a passthrough for a measurement. Do not use it in an adapter.
+**`select_or_raise()` exists** for diagnostics and benchmarks that must not
+silently substitute a passthrough for a measurement. Framework adapters use
+`select()` with its explicit guardrail exception contract.
 
 ### 2. Pin the operating point
 
-`operating_point` is required at construction, and this is the one failure that
-raises rather than fails open. Failing open on a bad request is degradation a
+`operating_point` is required at construction; an invalid configuration raises.
+Failing open on an ordinary unprotected bad request is degradation a
 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.
@@ -186,10 +232,14 @@ that passes at 5.99 MB can still be rejected upstream. Lower
 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
-operating point — the full response comes back and is reported, and **the
-selection is never applied**. Measure what Needlepath would have saved you;
-change nothing.
+The call is made exactly as a live call would be, with the same body, billing,
+and operating point. Ordinary unprotected selections are reported without
+being applied (`reason: "shadow"`). A blocked verdict is enforced in shadow
+mode too: shadow never restores a withheld record, so the result stays
+`reason: "blocked"`, `applied=True`, with `shadow: true`, `outcome` and
+`governance` on the receipt. A protected delivery likewise takes precedence:
+only its permitted selected context may be used, or the request stops with
+`NeedlepathGuardrailError`.
 
 `budget.mode = "shadow"` is **not on the wire yet**. `BudgetSpec.mode` on the
 published contract accepts `fixed` and `adaptive` only; adding `shadow` is a

{needlepath-0.2.2 → needlepath-0.2.4}/pyproject.toml

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

{needlepath-0.2.2 → needlepath-0.2.4}/src/needlepath/__init__.py

@@ -13,10 +13,10 @@
 Three properties this package guarantees, because the framework adapters built
 on it are only as safe as it is:
 
-1. **``select`` never raises.** Timeout, 5xx, a violated contract, an empty
-   selection, a stood-down gate — all of them come back as a result with
-   ``applied=False``, the error on ``.error``, and a metadata-only summary on
-   ``.metadata()``.
+1. Ordinary unprotected failures return ``applied=False`` with recorded errors.
+   A blocked verdict is applied (``reason: blocked``, nothing delivered) and
+   never raises. Workspace protection or ``guardrails_required`` failures
+   instead raise ``NeedlepathGuardrailError``; raw-context fallback is forbidden.
 2. **The operating point is pinned in the constructor**, or construction fails.
 3. **The 6 MB payload cap is measured client-side**, before the request leaves.
 
@@ -50,6 +50,7 @@ from .errors import (
     NeedlepathConfigError,
     NeedlepathContractError,
     NeedlepathError,
+    NeedlepathGuardrailError,
     NeedlepathHTTPError,
     NeedlepathPayloadTooLargeError,
     NeedlepathTimeoutError,
@@ -87,6 +88,7 @@ from .transport import (
 from .version import __version__
 
 __all__ = [
+    "NeedlepathGuardrailError",
     "__version__",
     # clients
     "NeedlepathClient",