needlepath 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,12 +1,3 @@
-## 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.
@@ -14,7 +5,48 @@ 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]
+## [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
 

{needlepath-0.2.2 → needlepath-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: needlepath
-Version: 0.2.2
+Version: 0.2.3
 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.3}/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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "needlepath"
-version = "0.2.2"
+version = "0.2.3"
 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.3}/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",