needlepath-langchain 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. needlepath_langchain-0.2.2/CHANGELOG.md +90 -0
  2. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/PKG-INFO +67 -3
  3. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/README.md +66 -2
  4. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/pyproject.toml +1 -1
  5. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/src/needlepath_langchain/__init__.py +1 -1
  6. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/src/needlepath_langchain/langgraph.py +11 -1
  7. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/src/needlepath_langchain/middleware.py +40 -4
  8. needlepath_langchain-0.2.2/src/needlepath_langchain/system_one.py +236 -0
  9. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/src/needlepath_langchain/version.py +1 -1
  10. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/tests/test_middleware.py +87 -0
  11. needlepath_langchain-0.2.2/tests/test_system_one_chain.py +328 -0
  12. needlepath_langchain-0.2.0/CHANGELOG.md +0 -46
  13. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/.gitignore +0 -0
  14. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/LICENSE +0 -0
  15. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/src/needlepath_langchain/_messages.py +0 -0
  16. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/src/needlepath_langchain/py.typed +0 -0
  17. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/tests/conftest.py +0 -0
  18. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/tests/test_end_to_end.py +0 -0
  19. {needlepath_langchain-0.2.0 → needlepath_langchain-0.2.2}/tests/test_langgraph_recipe.py +0 -0
@@ -0,0 +1,90 @@
1
+ # Changelog
2
+
3
+ All notable changes to the `needlepath-langchain` Python package are documented here.
4
+
5
+ ## 0.2.2
6
+
7
+ ### Fixed
8
+
9
+ - **Tool-result seam applies a `sanitized_fallback`.** The service answers a
10
+ screened tool result with one model-facing packet (`rendered_context`, the
11
+ record with the offending span removed and marked in place) and no per-record
12
+ excerpt. The seam declined that packet as `NO_SAVING` and delivered the
13
+ unscreened original to the model. It now applies the packet
14
+ (`rewrite_reason: "sanitized"`), and the length guard is skipped for screened
15
+ packets, which are applied for what they removed, not for what they saved.
16
+ - **Receipt on the message** (`response_metadata["needlepath"]`) now also carries
17
+ `outcome`, `security_action` and `usage`, so an agent trace holds the same
18
+ receipt the console shows.
19
+
20
+ ## Unreleased
21
+
22
+ ### Added
23
+
24
+ - **System One chain** (`needlepath_langchain.system_one`): `NeedlepathSelect`,
25
+ a Runnable wrapping one selection call, and `build_system_one_chain()`, which
26
+ composes it with a transport-only state-shaping step and any Runnable
27
+ classifier that accepts `{state, questions}` (TypeSafe's `TypeSafeClassifier`
28
+ is the reference, and stays an optional import). Fail open reshapes the
29
+ caller's own records, so the classifier never sees an empty state. Receipts
30
+ travel out of band through a list under `RECEIPTS_KEY` in the config's
31
+ `configurable`, which is an in-process channel: under `batch` they arrive in
32
+ completion order, and nothing crosses a serialised boundary.
33
+
34
+ `questions` travels in the shape it was passed. `TypeSafeClassifier` reads a
35
+ mapping of id to typed question, so a chain that flattened it to a list would
36
+ send the ids as the questions.
37
+
38
+ ### Requires
39
+
40
+ - **`needlepath` with `needlepath.integrations.system_one`**, which the
41
+ unreleased core adds. The dependency floor here still reads
42
+ `needlepath>=0.1.0,<1.0.0` and **must be raised to the core release that
43
+ carries that module before this package is published**, or a resolver is free
44
+ to pair this release with a core that cannot import it. Core releases first.
45
+
46
+ ## 0.2.1 — 2026-09-03
47
+
48
+ ### Changed
49
+
50
+ - Docs, docstrings and examples pin np-2026-08-r4. No behaviour change.
51
+
52
+ ## 0.2.0 — 2026-08-15
53
+
54
+ ### Removed
55
+
56
+ - **`preserve_recent`** (both `NeedlepathMiddleware` and
57
+ `NeedlepathPreModelHook`). A client-side "never rewrite the last N messages"
58
+ rule is a selection decision made locally: whichever records fall in the
59
+ window were guaranteed kept by client logic, no matter what the engine's own
60
+ selection said about them. It also made `.stats` dishonest — the counters
61
+ went on reporting the engine's *unfiltered* `tokens_after`/`tokens_saved`
62
+ while only a narrower, locally-filtered rewrite was actually installed, so
63
+ the receipt diverged from what the message list actually contained whenever
64
+ an engine selection favored the protected window (NEXPE-517/523 review).
65
+
66
+ **Migration:** remove `preserve_recent=` from every call site. If tail
67
+ protection is a real requirement, it is either a request to make of the
68
+ *engine* (a position/recency signal it can act on like any other input to
69
+ its own decision) or a genuinely separate, engine-blind mechanism you
70
+ compose yourself outside this package. Passing `preserve_recent=` to either
71
+ constructor now raises `TypeError` naming this entry.
72
+
73
+ ### Added
74
+
75
+ - **`.engine_stats`** on both classes, alongside the existing `.stats`.
76
+ `.stats` now reports what was **actually applied** — real before/after token
77
+ counts, including the placeholder text substituted for a declined record,
78
+ which the engine's own numbers cannot account for. `.engine_stats` reports
79
+ the engine's raw response, unmodified, for reconciling against what the
80
+ service itself measured or billed. See each module's "Two stats objects, two
81
+ truths" docstring note.
82
+
83
+ ### Fixed
84
+
85
+ - Records are no longer scored or filtered by position at all: no computed
86
+ `importance`, no locally-derived `task.required_record_ids`, and no local
87
+ filtering of the rewrite map (the `preserve_recent` removal above was the
88
+ last of three forms this took) — see
89
+ `src/core/agentbuilder/tests/test_needlepath_thin_client_guard.py` in the
90
+ main repo, which now detects all three.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: needlepath-langchain
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: Needlepath context selection for LangChain agents (AgentMiddleware) and LangGraph.
5
5
  Project-URL: Homepage, https://nextmoca.com
6
6
  Author: Next Moca Global, Inc.
@@ -40,7 +40,7 @@ from needlepath_langchain import NeedlepathMiddleware
40
40
  agent = create_agent(
41
41
  model,
42
42
  tools,
43
- middleware=[NeedlepathMiddleware(operating_point="np-2026-07-r2")],
43
+ middleware=[NeedlepathMiddleware(operating_point="np-2026-08-r4")],
44
44
  )
45
45
  ```
46
46
 
@@ -173,6 +173,70 @@ never need to close it. If you construct one per request or per test, call
173
173
  pools. Clients you passed in with `client=` / `async_client=` are yours and are
174
174
  never closed for you.
175
175
 
176
+ ## System One models (TypeSafe Jev, Laya)
177
+
178
+ Small classifier models that take `{state, questions}` and answer the questions
179
+ against the state. `needlepath_langchain.system_one` composes the selection and
180
+ the classifier into one chain:
181
+
182
+ ```python
183
+ from langchain_typesafe import Noul, TypeSafeClassifier
184
+ from needlepath import NeedlepathClient
185
+ from needlepath_langchain.system_one import RECEIPTS_KEY, build_system_one_chain
186
+
187
+ chain = build_system_one_chain(
188
+ needlepath_client=NeedlepathClient(operating_point="np-2026-08-r4"),
189
+ classifier=TypeSafeClassifier(), # any Runnable taking {state, questions}
190
+ questions={"refund": Noul(instructions="Is this a refund request?")},
191
+ )
192
+ answers = chain.invoke({"records": records, "prompt": question, "max_context_tokens": 4000})
193
+ ```
194
+
195
+ The chain is `NeedlepathSelect | RunnableLambda(state shaping) | classifier`.
196
+ The middle step is transport only: every record in `response.selected` reaches
197
+ `state`, in the order the service returned them, with the text unmodified. No
198
+ threshold on `score`, no drop for an empty excerpt, no re-sort, no
199
+ deduplication, no question you did not pass. `mode="rendered"` hands the
200
+ classifier a single string instead of an array, records joined by blank lines
201
+ under a one-line `[record_id] title` header.
202
+
203
+ `classifier` is any Runnable that accepts `{state, questions}`.
204
+ `langchain-typesafe`'s `TypeSafeClassifier` is the reference and is **not** a
205
+ dependency of this package; `typesafe_classifier()` imports it only if you ask.
206
+
207
+ `questions` travels in the shape you pass it. `TypeSafeClassifier` reads a
208
+ mapping of id to typed question (`Noul`, `Choice`, `Score`) and addresses each
209
+ answer by that id; a different `{state, questions}` service may read a list.
210
+ Neither is converted into the other.
211
+
212
+ Fail open works here as everywhere else: when the result is not applied (a
213
+ timeout, a 5xx, an empty selection, a stood-down engine), your **own records**
214
+ are reshaped and sent, so the classifier sees the original context, never an
215
+ empty one.
216
+
217
+ Attribution never enters the request body. Pass a list under `RECEIPTS_KEY` to
218
+ collect one receipt per call:
219
+
220
+ ```python
221
+ receipts = []
222
+ chain.invoke(payload, {"configurable": {RECEIPTS_KEY: receipts}})
223
+ # {"needlepath.request_id": ..., "needlepath.selection_id": ...,
224
+ # "needlepath.policy_version": ..., "needlepath.tokens_saved": ...,
225
+ # "needlepath.outcome": ...}
226
+ ```
227
+
228
+ A container works in either namespace, since LangChain shallow-copies both per
229
+ step. `configurable` is chosen because `metadata` is what LangChain copies into
230
+ the tracing payload for every run, and a mutable receipt sink does not belong in
231
+ a trace.
232
+
233
+ The sink is in-process. Under `batch`/`abatch` receipts arrive in completion
234
+ order, not input order, so correlate on `needlepath.request_id` rather than
235
+ position; under `stream` the receipt appends when the stream is consumed; and
236
+ nothing crosses a serialised boundary, because a config sent to a remote runner
237
+ is deserialised there and the copy appended to is the remote one. Where that
238
+ matters, drive `NeedlepathSelect` yourself and read `["receipt"]` off its output.
239
+
176
240
  ## LangGraph
177
241
 
178
242
  Same package, not a second distribution.
@@ -184,7 +248,7 @@ from needlepath_langchain.langgraph import needlepath_pre_model_hook
184
248
  agent = create_react_agent(
185
249
  model,
186
250
  tools,
187
- pre_model_hook=needlepath_pre_model_hook(operating_point="np-2026-07-r2"),
251
+ pre_model_hook=needlepath_pre_model_hook(operating_point="np-2026-08-r4"),
188
252
  )
189
253
  ```
190
254
 
@@ -16,7 +16,7 @@ from needlepath_langchain import NeedlepathMiddleware
16
16
  agent = create_agent(
17
17
  model,
18
18
  tools,
19
- middleware=[NeedlepathMiddleware(operating_point="np-2026-07-r2")],
19
+ middleware=[NeedlepathMiddleware(operating_point="np-2026-08-r4")],
20
20
  )
21
21
  ```
22
22
 
@@ -149,6 +149,70 @@ never need to close it. If you construct one per request or per test, call
149
149
  pools. Clients you passed in with `client=` / `async_client=` are yours and are
150
150
  never closed for you.
151
151
 
152
+ ## System One models (TypeSafe Jev, Laya)
153
+
154
+ Small classifier models that take `{state, questions}` and answer the questions
155
+ against the state. `needlepath_langchain.system_one` composes the selection and
156
+ the classifier into one chain:
157
+
158
+ ```python
159
+ from langchain_typesafe import Noul, TypeSafeClassifier
160
+ from needlepath import NeedlepathClient
161
+ from needlepath_langchain.system_one import RECEIPTS_KEY, build_system_one_chain
162
+
163
+ chain = build_system_one_chain(
164
+ needlepath_client=NeedlepathClient(operating_point="np-2026-08-r4"),
165
+ classifier=TypeSafeClassifier(), # any Runnable taking {state, questions}
166
+ questions={"refund": Noul(instructions="Is this a refund request?")},
167
+ )
168
+ answers = chain.invoke({"records": records, "prompt": question, "max_context_tokens": 4000})
169
+ ```
170
+
171
+ The chain is `NeedlepathSelect | RunnableLambda(state shaping) | classifier`.
172
+ The middle step is transport only: every record in `response.selected` reaches
173
+ `state`, in the order the service returned them, with the text unmodified. No
174
+ threshold on `score`, no drop for an empty excerpt, no re-sort, no
175
+ deduplication, no question you did not pass. `mode="rendered"` hands the
176
+ classifier a single string instead of an array, records joined by blank lines
177
+ under a one-line `[record_id] title` header.
178
+
179
+ `classifier` is any Runnable that accepts `{state, questions}`.
180
+ `langchain-typesafe`'s `TypeSafeClassifier` is the reference and is **not** a
181
+ dependency of this package; `typesafe_classifier()` imports it only if you ask.
182
+
183
+ `questions` travels in the shape you pass it. `TypeSafeClassifier` reads a
184
+ mapping of id to typed question (`Noul`, `Choice`, `Score`) and addresses each
185
+ answer by that id; a different `{state, questions}` service may read a list.
186
+ Neither is converted into the other.
187
+
188
+ Fail open works here as everywhere else: when the result is not applied (a
189
+ timeout, a 5xx, an empty selection, a stood-down engine), your **own records**
190
+ are reshaped and sent, so the classifier sees the original context, never an
191
+ empty one.
192
+
193
+ Attribution never enters the request body. Pass a list under `RECEIPTS_KEY` to
194
+ collect one receipt per call:
195
+
196
+ ```python
197
+ receipts = []
198
+ chain.invoke(payload, {"configurable": {RECEIPTS_KEY: receipts}})
199
+ # {"needlepath.request_id": ..., "needlepath.selection_id": ...,
200
+ # "needlepath.policy_version": ..., "needlepath.tokens_saved": ...,
201
+ # "needlepath.outcome": ...}
202
+ ```
203
+
204
+ A container works in either namespace, since LangChain shallow-copies both per
205
+ step. `configurable` is chosen because `metadata` is what LangChain copies into
206
+ the tracing payload for every run, and a mutable receipt sink does not belong in
207
+ a trace.
208
+
209
+ The sink is in-process. Under `batch`/`abatch` receipts arrive in completion
210
+ order, not input order, so correlate on `needlepath.request_id` rather than
211
+ position; under `stream` the receipt appends when the stream is consumed; and
212
+ nothing crosses a serialised boundary, because a config sent to a remote runner
213
+ is deserialised there and the copy appended to is the remote one. Where that
214
+ matters, drive `NeedlepathSelect` yourself and read `["receipt"]` off its output.
215
+
152
216
  ## LangGraph
153
217
 
154
218
  Same package, not a second distribution.
@@ -160,7 +224,7 @@ from needlepath_langchain.langgraph import needlepath_pre_model_hook
160
224
  agent = create_react_agent(
161
225
  model,
162
226
  tools,
163
- pre_model_hook=needlepath_pre_model_hook(operating_point="np-2026-07-r2"),
227
+ pre_model_hook=needlepath_pre_model_hook(operating_point="np-2026-08-r4"),
164
228
  )
165
229
  ```
166
230
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "needlepath-langchain"
7
- version = "0.2.0"
7
+ version = "0.2.2"
8
8
  description = "Needlepath context selection for LangChain agents (AgentMiddleware) and LangGraph."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10" # langchain 1.x floor
@@ -5,7 +5,7 @@
5
5
 
6
6
  agent = create_agent(
7
7
  model, tools,
8
- middleware=[NeedlepathMiddleware(operating_point="np-2026-07-r2")],
8
+ middleware=[NeedlepathMiddleware(operating_point="np-2026-08-r4")],
9
9
  )
10
10
 
11
11
  One line. Tool results are selected against the current step, the history is
@@ -76,7 +76,7 @@ Usage
76
76
 
77
77
  agent = create_react_agent(
78
78
  model, tools,
79
- pre_model_hook=needlepath_pre_model_hook(operating_point="np-2026-07-r2"),
79
+ pre_model_hook=needlepath_pre_model_hook(operating_point="np-2026-08-r4"),
80
80
  )
81
81
  """
82
82
 
@@ -139,6 +139,8 @@ class NeedlepathPreModelHook:
139
139
  include_ai_messages: bool = False,
140
140
  include_human_messages: bool = False,
141
141
  placeholder: str = DEFAULT_PLACEHOLDER,
142
+ selection_strategy: str = "fast",
143
+ support_contract: str = "auto",
142
144
  client: NeedlepathClient | None = None,
143
145
  async_client: AsyncNeedlepathClient | None = None,
144
146
  **client_kwargs: Any,
@@ -150,6 +152,8 @@ class NeedlepathPreModelHook:
150
152
  self.include_ai_messages = bool(include_ai_messages)
151
153
  self.include_human_messages = bool(include_human_messages)
152
154
  self.placeholder = placeholder
155
+ self.selection_strategy = selection_strategy
156
+ self.support_contract = support_contract
153
157
  #: What this hook actually wrote to ``llm_input_messages`` — real
154
158
  #: before/after token counts. See ``middleware.py``'s "Two stats
155
159
  #: objects, two truths" note.
@@ -187,6 +191,8 @@ class NeedlepathPreModelHook:
187
191
  task=plan["task"],
188
192
  max_context_tokens=self.history_max_tokens,
189
193
  shadow=self._shadow_override(),
194
+ selection_strategy=self.selection_strategy,
195
+ support_contract=self.support_contract,
190
196
  )
191
197
  return self._apply(messages, plan, selection)
192
198
  except Exception: # noqa: BLE001 - a defect here must not break the graph
@@ -212,6 +218,8 @@ class NeedlepathPreModelHook:
212
218
  task=plan["task"],
213
219
  max_context_tokens=self.history_max_tokens,
214
220
  shadow=self._shadow_override(),
221
+ selection_strategy=self.selection_strategy,
222
+ support_contract=self.support_contract,
215
223
  )
216
224
  else:
217
225
  import asyncio
@@ -225,6 +233,8 @@ class NeedlepathPreModelHook:
225
233
  task=plan["task"],
226
234
  max_context_tokens=self.history_max_tokens,
227
235
  shadow=self._shadow_override(),
236
+ selection_strategy=self.selection_strategy,
237
+ support_contract=self.support_contract,
228
238
  ),
229
239
  )
230
240
  return self._apply(messages, plan, selection)
@@ -98,7 +98,7 @@ class NeedlepathMiddleware(AgentMiddleware):
98
98
 
99
99
  agent = create_agent(
100
100
  model, tools,
101
- middleware=[NeedlepathMiddleware(operating_point="np-2026-07-r2")],
101
+ middleware=[NeedlepathMiddleware(operating_point="np-2026-08-r4")],
102
102
  )
103
103
 
104
104
  That is the whole integration. The key comes from ``NEEDLEPATH_API_KEY``, the
@@ -118,7 +118,7 @@ class NeedlepathMiddleware(AgentMiddleware):
118
118
  record it sent.
119
119
 
120
120
  :param operating_point: **Required.** An immutable label such as
121
- ``np-2026-07-r2``. Also readable from ``NEEDLEPATH_OPERATING_POINT``.
121
+ ``np-2026-08-r4``. Also readable from ``NEEDLEPATH_OPERATING_POINT``.
122
122
  :param shadow: Measure and report; never apply. The one-line switch.
123
123
  :param enabled: A kill switch. ``False`` makes every hook a pure passthrough
124
124
  without constructing a client or making a call.
@@ -148,6 +148,8 @@ class NeedlepathMiddleware(AgentMiddleware):
148
148
  include_ai_messages: bool = False,
149
149
  include_human_messages: bool = False,
150
150
  placeholder: str = DEFAULT_PLACEHOLDER,
151
+ selection_strategy: str = "fast",
152
+ support_contract: str = "auto",
151
153
  name: str | None = None,
152
154
  client: NeedlepathClient | None = None,
153
155
  async_client: AsyncNeedlepathClient | None = None,
@@ -169,6 +171,8 @@ class NeedlepathMiddleware(AgentMiddleware):
169
171
  self.include_ai_messages = bool(include_ai_messages)
170
172
  self.include_human_messages = bool(include_human_messages)
171
173
  self.placeholder = placeholder
174
+ self.selection_strategy = selection_strategy
175
+ self.support_contract = support_contract
172
176
  #: What this middleware actually did to the message(s) it rewrote —
173
177
  #: real before/after token counts. See the module docstring's "Two
174
178
  #: stats objects, two truths" note.
@@ -424,7 +428,22 @@ class NeedlepathMiddleware(AgentMiddleware):
424
428
  self.stats.record(unchanged)
425
429
  return _annotate(result, selection)
426
430
  excerpt = selection.excerpts.get(plan.records[0].id or "")
427
- if not excerpt or not excerpt.strip() or len(excerpt) >= len(original):
431
+ rewrite_reason = "excerpt"
432
+ if excerpt is None and selection.reason == Reason.SANITIZED_FALLBACK:
433
+ # A sanitized fallback carries no per-record detail: the service
434
+ # answers with one model-facing packet, the record with the
435
+ # offending span removed and marked in place. This seam sends
436
+ # exactly one record, so that packet is the record's replacement
437
+ # and is applied the way an excerpt is; the length and emptiness
438
+ # guards below still decide whether it lands.
439
+ excerpt = selection.rendered_context
440
+ rewrite_reason = "sanitized"
441
+ # A screened packet is applied for what it removed, not for what it
442
+ # saved: the length guard that refuses a longer excerpt must not hand
443
+ # the unscreened original back to the model when the marker happens to
444
+ # be longer than the span it replaced.
445
+ no_saving = len(excerpt or "") >= len(original) and rewrite_reason != "sanitized"
446
+ if not excerpt or not excerpt.strip() or no_saving:
428
447
  declined = selection.declined(Reason.NO_SAVING)
429
448
  unchanged = _with_actual_tokens(declined, before=original_tokens, after=original_tokens)
430
449
  self.stats.record(unchanged)
@@ -436,7 +455,7 @@ class NeedlepathMiddleware(AgentMiddleware):
436
455
  _with_actual_tokens(selection, before=original_tokens, after=approx_tokens(excerpt))
437
456
  )
438
457
  rewritten = rewrite_message(
439
- result, excerpt, reason="excerpt", request_id=selection.request_id
458
+ result, excerpt, reason=rewrite_reason, request_id=selection.request_id
440
459
  )
441
460
  return _annotate(rewritten, selection)
442
461
 
@@ -510,6 +529,8 @@ class NeedlepathMiddleware(AgentMiddleware):
510
529
  task=plan.task,
511
530
  max_context_tokens=plan.max_context_tokens,
512
531
  shadow=self._shadow_override(),
532
+ selection_strategy=self.selection_strategy,
533
+ support_contract=self.support_contract,
513
534
  )
514
535
 
515
536
  async def _select_async(self, plan: _Plan) -> SelectionResult:
@@ -519,6 +540,8 @@ class NeedlepathMiddleware(AgentMiddleware):
519
540
  task=plan.task,
520
541
  max_context_tokens=plan.max_context_tokens,
521
542
  shadow=self._shadow_override(),
543
+ selection_strategy=self.selection_strategy,
544
+ support_contract=self.support_contract,
522
545
  )
523
546
  # A caller-supplied sync client on the async path. Run it on the default
524
547
  # executor rather than blocking the loop — a blocked loop in an agent
@@ -621,6 +644,19 @@ def _annotate(message: ToolMessage, selection: SelectionResult) -> ToolMessage:
621
644
  metadata.setdefault("needlepath", {})
622
645
  merged = dict(metadata["needlepath"]) if isinstance(metadata["needlepath"], dict) else {}
623
646
  merged.update(selection.metadata(prefix=""))
647
+ response = selection.response
648
+ if response is not None:
649
+ # The rest of the receipt, metadata-only like everything above: how the
650
+ # service resolved the request, what the screening did, and the
651
+ # metered line it billed. Nothing here is derived from record text.
652
+ if response.outcome is not None:
653
+ merged["outcome"] = response.outcome
654
+ action = response.format_metrics.get("security_action")
655
+ if action:
656
+ merged["security_action"] = str(action)
657
+ usage = response.extra.get("usage")
658
+ if isinstance(usage, dict):
659
+ merged["usage"] = dict(usage)
624
660
  metadata["needlepath"] = merged
625
661
  return message.model_copy(update={"response_metadata": metadata})
626
662
 
@@ -0,0 +1,236 @@
1
+ """The System One chain: select, reshape, classify.
2
+
3
+ A family of small classifier models (TypeSafe's Jev, Laya) takes a block of
4
+ state plus a list of questions and answers the questions against the state.
5
+ They are cheap and fast, and they get more accurate as the state they are given
6
+ gets more relevant, which is the whole of the fit with a selection service:
7
+
8
+ chain = build_system_one_chain(
9
+ needlepath_client=NeedlepathClient(operating_point="np-2026-08-r4"),
10
+ classifier=TypeSafeClassifier(...),
11
+ questions={"refund": Noul(instructions="Is this a refund request?")},
12
+ )
13
+ answers = chain.invoke({"records": records, "prompt": question,
14
+ "max_context_tokens": 4000})
15
+
16
+ The chain is ``NeedlepathSelect | RunnableLambda(state shaping) | classifier``.
17
+ ``classifier`` is **any** Runnable that accepts ``{state, questions}``;
18
+ ``langchain-typesafe``'s ``TypeSafeClassifier`` is the reference, and it is
19
+ deliberately not a dependency of this package, and :func:`typesafe_classifier`
20
+ imports it only if you ask for it.
21
+
22
+ **The middle step is transport only.** It carries every record in
23
+ ``response.selected``, in the order the service returned them, with the text
24
+ unmodified: no threshold on ``score``, no drop for an empty excerpt, no
25
+ re-sort, no deduplication, and no question the caller did not pass. It is a
26
+ three-line function on purpose, and ``tests/test_system_one_chain.py`` is
27
+ written to fail the moment it grows a fourth.
28
+
29
+ Fail open works here the way it works everywhere else in this package: when the
30
+ result is not applied (a timeout, a 5xx, an empty selection, a stood-down
31
+ engine), the caller's **own records** are reshaped and sent, so the classifier
32
+ sees the original context rather than an empty one. That is NEXPE-413's
33
+ precedent at a new seam.
34
+
35
+ Where the receipt goes
36
+ ----------------------
37
+
38
+ ``request_id``, ``selection_id``, ``policy_version``, ``tokens_saved`` and
39
+ ``outcome`` never enter the request body. Two channels carry them instead:
40
+
41
+ 1. :class:`NeedlepathSelect` returns the receipt on its own output, so a caller
42
+ driving the Runnable directly already has it.
43
+ 2. Pass a list under :data:`RECEIPTS_KEY` in the config's ``configurable`` and
44
+ each call appends its receipt to it::
45
+
46
+ receipts = []
47
+ chain.invoke(payload, {"configurable": {RECEIPTS_KEY: receipts}})
48
+
49
+ A *container* works in either namespace: LangChain shallow-copies both per
50
+ step, so a list placed in either keeps its identity (writing a new *key*
51
+ into ``metadata`` inside a step does not, which is a different thing).
52
+ ``configurable`` is chosen because ``metadata`` is what LangChain copies
53
+ into the tracing payload for every run, and a mutable receipt sink does not
54
+ belong in a trace.
55
+
56
+ The sink is an in-process channel and has the limits of one. Under
57
+ ``batch``/``abatch`` receipts arrive in completion order, not input order,
58
+ so correlate on ``needlepath.request_id`` rather than position. Under
59
+ ``stream`` the receipt appends when the stream is consumed. Nothing crosses
60
+ a serialised boundary: a config sent to a remote runner is deserialised
61
+ there, and the copy that is appended to is the remote one. Channel 1 is the
62
+ answer wherever that matters -- drive :class:`NeedlepathSelect` yourself and
63
+ read the receipt off its output.
64
+ """
65
+
66
+ from __future__ import annotations
67
+
68
+ from collections.abc import Sequence
69
+ from typing import Any
70
+
71
+ from needlepath import (
72
+ AsyncNeedlepathClient,
73
+ NeedlepathClient,
74
+ NeedlepathConfigError,
75
+ TaskSpec,
76
+ )
77
+ from needlepath.integrations.system_one import (
78
+ MODE_RECORDS,
79
+ Questions,
80
+ selection_receipt,
81
+ to_system_one_state,
82
+ )
83
+
84
+ try: # pragma: no cover
85
+ from langchain_core.runnables import Runnable, RunnableLambda
86
+ from langchain_core.runnables.config import RunnableConfig
87
+ except ImportError as exc: # pragma: no cover
88
+ raise ImportError("needlepath-langchain requires langchain-core") from exc
89
+
90
+
91
+ #: The ``configurable`` key a caller puts a list under to collect one receipt
92
+ #: per call. See the module docstring for why it is not ``metadata``.
93
+ RECEIPTS_KEY = "needlepath_receipts"
94
+
95
+
96
+ class NeedlepathSelect(Runnable[dict[str, Any], dict[str, Any]]):
97
+ """One selection call, as a Runnable. **The selection never raises.**
98
+
99
+ Every way the service can fail comes back as a
100
+ :class:`~needlepath.SelectionResult` that did not apply, exactly as it does
101
+ everywhere else in this package. Wire-up mistakes do raise
102
+ :class:`~needlepath.NeedlepathConfigError`: a payload with no records, no
103
+ task or prompt, or no budget, and ``ainvoke`` without an async client.
104
+
105
+ Input is a dict: ``records`` (required), ``task`` or ``prompt``, and
106
+ ``max_context_tokens`` unless one was pinned at construction. Output is a
107
+ dict carrying the :class:`~needlepath.SelectionResult`, the records exactly
108
+ as they were passed in, and the receipt. The records travel through because
109
+ the next step needs them for the fail-open path, where the caller's own
110
+ context is what has to be sent.
111
+
112
+ The type parameters are ``dict`` to ``dict`` so that LangChain can infer a
113
+ schema for the step and for any sequence it heads.
114
+ """
115
+
116
+ def __init__(
117
+ self,
118
+ *,
119
+ client: NeedlepathClient,
120
+ async_client: AsyncNeedlepathClient | None = None,
121
+ max_context_tokens: int | None = None,
122
+ **select_kwargs: Any,
123
+ ) -> None:
124
+ reserved = {"records", "task", "max_context_tokens"} & set(select_kwargs)
125
+ if reserved:
126
+ raise NeedlepathConfigError(
127
+ f"{sorted(reserved)} come from the payload, not from construction; "
128
+ "pass max_context_tokens= to pin a budget"
129
+ )
130
+ self.client = client
131
+ self.async_client = async_client
132
+ self.max_context_tokens = max_context_tokens
133
+ self.select_kwargs = select_kwargs
134
+
135
+ def invoke(self, input: dict, config: RunnableConfig | None = None, **kwargs: Any) -> dict:
136
+ records, call = self._call_args(input)
137
+ result = self.client.select(**call)
138
+ return self._output(result, records, config)
139
+
140
+ async def ainvoke(
141
+ self, input: dict, config: RunnableConfig | None = None, **kwargs: Any
142
+ ) -> dict:
143
+ if self.async_client is None:
144
+ raise NeedlepathConfigError("ainvoke needs an async_client")
145
+ records, call = self._call_args(input)
146
+ result = await self.async_client.select(**call)
147
+ return self._output(result, records, config)
148
+
149
+ # ------------------------------------------------------------------ #
150
+
151
+ def _call_args(self, payload: dict) -> tuple[Sequence[Any], dict]:
152
+ if "records" not in payload:
153
+ raise NeedlepathConfigError("the payload must carry `records`")
154
+ records = payload["records"]
155
+ task = payload.get("task")
156
+ if task is None:
157
+ if "prompt" not in payload:
158
+ raise NeedlepathConfigError("the payload must carry `task` or `prompt`")
159
+ task = TaskSpec(prompt=payload["prompt"])
160
+ budget = payload.get("max_context_tokens", self.max_context_tokens)
161
+ if budget is None:
162
+ raise NeedlepathConfigError(
163
+ "max_context_tokens is required, in the payload or at construction"
164
+ )
165
+ call = dict(self.select_kwargs)
166
+ call.update(records=records, task=task, max_context_tokens=budget)
167
+ return records, call
168
+
169
+ def _output(self, result: Any, records: Sequence[Any], config: Any) -> dict:
170
+ receipt = selection_receipt(result)
171
+ _emit(receipt, config)
172
+ return {"selection": result, "records": records, "receipt": receipt}
173
+
174
+
175
+ def build_system_one_chain(
176
+ *,
177
+ needlepath_client: NeedlepathClient,
178
+ classifier: Runnable,
179
+ questions: Questions,
180
+ mode: str = MODE_RECORDS,
181
+ async_client: AsyncNeedlepathClient | None = None,
182
+ **select_kwargs: Any,
183
+ ) -> Runnable[dict[str, Any], Any]:
184
+ """``NeedlepathSelect | state shaping | classifier``.
185
+
186
+ ``questions`` is required and travels verbatim, in order, in the shape it
187
+ was passed: ``langchain-typesafe`` reads a mapping of id to typed question,
188
+ another ``{state, questions}`` service may read a list. ``mode`` is
189
+ ``"records"`` for a ``state`` array or ``"rendered"`` for a single string;
190
+ both are the adapter's, and neither changes which records travel.
191
+ """
192
+ select = NeedlepathSelect(client=needlepath_client, async_client=async_client, **select_kwargs)
193
+
194
+ def _shape(payload: dict) -> dict:
195
+ result = payload["selection"]
196
+ source = result if result.applied else payload["records"]
197
+ return to_system_one_state(source, questions=questions, mode=mode)
198
+
199
+ return select | RunnableLambda(_shape, name="system_one_state") | classifier
200
+
201
+
202
+ def typesafe_classifier(**kwargs: Any) -> Runnable:
203
+ """``langchain-typesafe``'s ``TypeSafeClassifier``, if it is installed.
204
+
205
+ A convenience, not a dependency: the chain takes any Runnable that accepts
206
+ ``{state, questions}``, and this package does not pin a classifier.
207
+ """
208
+ try:
209
+ from langchain_typesafe import TypeSafeClassifier
210
+ except ImportError as exc: # pragma: no cover
211
+ raise NeedlepathConfigError(
212
+ "typesafe_classifier() needs langchain-typesafe installed; "
213
+ "any Runnable accepting {state, questions} works instead"
214
+ ) from exc
215
+ return TypeSafeClassifier(**kwargs)
216
+
217
+
218
+ def _emit(receipt: dict, config: Any) -> None:
219
+ if not config:
220
+ return
221
+ sink = (config.get("configurable") or {}).get(RECEIPTS_KEY)
222
+ if sink is None:
223
+ return
224
+ if not isinstance(sink, list):
225
+ raise NeedlepathConfigError(
226
+ f"{RECEIPTS_KEY} must be a list to append receipts to, got {type(sink).__name__}"
227
+ )
228
+ sink.append(receipt)
229
+
230
+
231
+ __all__ = [
232
+ "NeedlepathSelect",
233
+ "build_system_one_chain",
234
+ "typesafe_classifier",
235
+ "RECEIPTS_KEY",
236
+ ]
@@ -1,3 +1,3 @@
1
- __version__ = "0.2.0"
1
+ __version__ = "0.2.2"
2
2
 
3
3
  __all__ = ["__version__"]
@@ -82,6 +82,20 @@ def test_the_tool_name_and_args_are_sent_as_task_signal(long_tool_message):
82
82
  assert task["prompt"] == "what is the total?"
83
83
 
84
84
 
85
+ def test_advanced_r4_controls_reach_the_core_client_wire(long_tool_message):
86
+ mw, transport, _ = middleware(
87
+ [echoing_service()],
88
+ operating_point=OP,
89
+ selection_strategy="auto",
90
+ support_contract="relational",
91
+ )
92
+
93
+ mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
94
+
95
+ assert transport.bodies[0]["selection_strategy"] == "auto"
96
+ assert transport.bodies[0]["support_contract"] == "relational"
97
+
98
+
85
99
  def test_a_command_result_is_never_touched(long_tool_message):
86
100
  """The handler may return a Command. Reaching for `.content` on one would be
87
101
  an AttributeError in the middle of somebody's agent."""
@@ -118,6 +132,79 @@ def test_every_failure_leaves_the_tool_result_intact(script, long_tool_message):
118
132
  assert out.response_metadata[METADATA_KEY]["applied"] is False
119
133
 
120
134
 
135
+ def test_a_sanitized_fallback_replaces_the_tool_result_with_the_screened_packet(long_tool_message):
136
+ """``sanitized_fallback`` has no per-record detail (NEXPE security finalization):
137
+ the whole answer is ``rendered_context``. On this one-record seam that packet
138
+ is the record, so it must land, marker and all, instead of being declined
139
+ as NO_SAVING and letting the original (unscreened) result through."""
140
+ screened = (
141
+ "invoice A-1002 total 412.50\n\n[QUARANTINED: instruction-like candidate text removed]"
142
+ )
143
+ mw, transport, _ = middleware(
144
+ [
145
+ echoing_service(
146
+ selected=[],
147
+ records_selected=0,
148
+ rendered_context=screened,
149
+ outcome="sanitized_fallback",
150
+ safety={
151
+ "selection_safe": False,
152
+ "fallback_required": True,
153
+ "fallback_reason": "episodic_support_frontier_incomplete",
154
+ "coverage_score": 1.0,
155
+ "evidence_shape": "multi_anchor_coverage",
156
+ "evidence_terms": None,
157
+ "repair_reasons": [],
158
+ },
159
+ format_metrics={"security_action": "quarantine"},
160
+ usage={
161
+ "input_tokens": 203,
162
+ "charge_multiplier": "1.0",
163
+ "price_version": "npp-2026-10-r1",
164
+ },
165
+ )
166
+ ],
167
+ operating_point=OP,
168
+ )
169
+ out = mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
170
+ assert isinstance(out, ToolMessage)
171
+ assert out.text == screened
172
+ assert out.tool_call_id == "call_1"
173
+ meta = out.response_metadata[METADATA_KEY]
174
+ assert meta["rewritten"] is True
175
+ assert meta["rewrite_reason"] == "sanitized"
176
+ assert meta["reason"] == Reason.SANITIZED_FALLBACK
177
+ assert meta["applied"] is True
178
+ # The receipt travels with the message: outcome, screening action, metered line.
179
+ assert meta["outcome"] == "sanitized_fallback"
180
+ assert meta["security_action"] == "quarantine"
181
+ assert meta["usage"]["price_version"] == "npp-2026-10-r1"
182
+ assert mw.stats.applied == 1 and mw.stats.reasons == {Reason.SANITIZED_FALLBACK: 1}
183
+ assert mw.stats.tokens_after == approx_tokens(screened)
184
+
185
+
186
+ def test_a_sanitized_packet_longer_than_the_original_still_lands(long_tool_message):
187
+ """The marker can be longer than the span it replaced. Refusing the packet
188
+ on length would hand the unscreened original to the model."""
189
+ screened = long_tool_message.text + "\n\n[QUARANTINED: instruction-like candidate text removed]"
190
+ mw, transport, _ = middleware(
191
+ [
192
+ echoing_service(
193
+ selected=[],
194
+ records_selected=0,
195
+ rendered_context=screened,
196
+ outcome="sanitized_fallback",
197
+ format_metrics={"security_action": "quarantine"},
198
+ )
199
+ ],
200
+ operating_point=OP,
201
+ )
202
+ out = mw.wrap_tool_call(FakeToolCallRequest(), lambda r: long_tool_message)
203
+ assert out.text == screened
204
+ assert out.response_metadata[METADATA_KEY]["rewrite_reason"] == "sanitized"
205
+ assert mw.stats.applied == 1
206
+
207
+
121
208
  def test_an_excerpt_longer_than_the_original_is_refused(long_tool_message):
122
209
  """Whatever produced it, applying it is a regression."""
123
210
  longer = [
@@ -0,0 +1,328 @@
1
+ """The System One chain: select, reshape, classify. Nothing in between.
2
+
3
+ What is being asserted is a negative. The reshaping step between the service
4
+ and the classifier has no opinion: every record the service returned reaches
5
+ ``state``, in the order it was returned, with the text unmodified, and the
6
+ classifier is handed exactly ``{state, questions}`` and nothing else. The
7
+ attribution fields travel out of band.
8
+
9
+ ``TypeSafeClassifier`` from ``langchain-typesafe`` is the reference classifier.
10
+ It is not a dependency of this package and is not installed here, so the tests
11
+ drive the chain with a fake Runnable that records what it was given, which is
12
+ the thing worth asserting anyway.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import asyncio
18
+ from typing import Any
19
+
20
+ import pytest
21
+ from conftest import OP, big, clients, echoing_service, partial_service
22
+ from langchain_core.runnables import Runnable, RunnableLambda
23
+ from needlepath import ContextRecord, NeedlepathConfigError, Reason, TaskSpec
24
+ from needlepath.testing import error
25
+
26
+ from needlepath_langchain.system_one import (
27
+ RECEIPTS_KEY,
28
+ NeedlepathSelect,
29
+ build_system_one_chain,
30
+ )
31
+
32
+ QUESTIONS = ["is this a refund?", "which invoice does it name?"]
33
+
34
+
35
+ class RecordingClassifier(Runnable):
36
+ """A stand-in for ``TypeSafeClassifier``: it keeps what it was handed."""
37
+
38
+ def __init__(self) -> None:
39
+ self.seen: list[dict] = []
40
+
41
+ def invoke(self, input, config=None, **kwargs):
42
+ self.seen.append(input)
43
+ return {"answers": ["yes"] * len(input["questions"])}
44
+
45
+ async def ainvoke(self, input, config=None, **kwargs):
46
+ return self.invoke(input, config, **kwargs)
47
+
48
+
49
+ def records(*texts: str) -> list[ContextRecord]:
50
+ return [
51
+ ContextRecord(text=big(text), id=f"r{i}", kind="external_data", title=f"T{i}")
52
+ for i, text in enumerate(texts, start=1)
53
+ ]
54
+
55
+
56
+ def chain(script, **kwargs):
57
+ sync_client, async_client, sync_t, async_t = clients(script)
58
+ classifier = RecordingClassifier()
59
+ built = build_system_one_chain(
60
+ needlepath_client=sync_client,
61
+ classifier=classifier,
62
+ questions=kwargs.pop("questions", QUESTIONS),
63
+ **kwargs,
64
+ )
65
+ return built, classifier, sync_t
66
+
67
+
68
+ def payload(*texts: str, **extra):
69
+ body = {
70
+ "records": records(*texts),
71
+ "task": TaskSpec(prompt="what is the invoice total?"),
72
+ "max_context_tokens": 4000,
73
+ }
74
+ body.update(extra)
75
+ return body
76
+
77
+
78
+ # --------------------------------------------------------------------------- #
79
+ # The classifier gets the selection, and only the selection
80
+ # --------------------------------------------------------------------------- #
81
+
82
+
83
+ def test_the_classifier_is_handed_exactly_state_and_questions():
84
+ built, classifier, _ = chain([echoing_service()])
85
+ built.invoke(payload("invoice one", "weather two"))
86
+ assert set(classifier.seen[0]) == {"state", "questions"}
87
+
88
+
89
+ def test_every_selected_record_reaches_state_in_the_order_returned():
90
+ built, classifier, _ = chain([echoing_service()])
91
+ built.invoke(payload("invoice one", "weather two", "ledger three"))
92
+ assert [entry["record_id"] for entry in classifier.seen[0]["state"]] == ["r1", "r2", "r3"]
93
+
94
+
95
+ def test_state_entries_carry_the_four_contract_fields():
96
+ built, classifier, _ = chain([echoing_service()])
97
+ built.invoke(payload("invoice one"))
98
+ entry = classifier.seen[0]["state"][0]
99
+ assert tuple(entry) == ("record_id", "title", "source", "text")
100
+ assert entry["text"].startswith("EXCERPT:")
101
+
102
+
103
+ def test_only_what_the_service_returned_is_carried_and_all_of_it():
104
+ """The service kept r2 alone. The adapter adds nothing back and drops
105
+ nothing further: what the classifier sees is the selection."""
106
+ built, classifier, _ = chain([partial_service(["r2"])])
107
+ built.invoke(payload("invoice one", "weather two", "ledger three"))
108
+ assert [entry["record_id"] for entry in classifier.seen[0]["state"]] == ["r2"]
109
+
110
+
111
+ def test_questions_travel_verbatim_in_order():
112
+ built, classifier, _ = chain([echoing_service()])
113
+ built.invoke(payload("invoice one"))
114
+ assert classifier.seen[0]["questions"] == QUESTIONS
115
+
116
+
117
+ def test_a_question_mapping_reaches_the_classifier_as_a_mapping():
118
+ """``TypeSafeClassifier`` reads ``questions`` as ``{id: question}``. A chain
119
+ that flattened it would send the ids as the questions."""
120
+ questions = {"refund": object(), "invoice": object()}
121
+ built, classifier, _ = chain([echoing_service()], questions=questions)
122
+ built.invoke(payload("invoice one"))
123
+ assert classifier.seen[0]["questions"] == questions
124
+
125
+
126
+ def test_questions_are_required_at_wire_up():
127
+ sync_client, _, _, _ = clients([echoing_service()])
128
+ with pytest.raises(TypeError):
129
+ build_system_one_chain(needlepath_client=sync_client, classifier=RecordingClassifier())
130
+
131
+
132
+ # --------------------------------------------------------------------------- #
133
+ # Fail open
134
+ # --------------------------------------------------------------------------- #
135
+
136
+
137
+ @pytest.mark.parametrize("script", [[error(500)], [error(429)]])
138
+ def test_a_failed_call_sends_the_callers_own_records_verbatim(script):
139
+ built, classifier, _ = chain(script)
140
+ body = payload("invoice one", "weather two")
141
+ built.invoke(body)
142
+ state = classifier.seen[0]["state"]
143
+ assert [entry["record_id"] for entry in state] == ["r1", "r2"]
144
+ assert [entry["text"] for entry in state] == [r.text for r in body["records"]]
145
+
146
+
147
+ def test_an_empty_selection_sends_the_callers_own_records_never_an_empty_state():
148
+ """NEXPE-413's precedent, at a new seam: an empty selection is a
149
+ passthrough, never an empty context."""
150
+ built, classifier, _ = chain([echoing_service(selected=[], records_selected=0)])
151
+ body = payload("invoice one", "weather two")
152
+ built.invoke(body)
153
+ assert [entry["record_id"] for entry in classifier.seen[0]["state"]] == ["r1", "r2"]
154
+
155
+
156
+ def test_a_stood_down_engine_sends_the_callers_own_records():
157
+ built, classifier, _ = chain([echoing_service(fallback_used=True)])
158
+ built.invoke(payload("invoice one"))
159
+ assert classifier.seen[0]["state"][0]["text"].startswith("invoice one")
160
+
161
+
162
+ # --------------------------------------------------------------------------- #
163
+ # The receipt travels out of band
164
+ # --------------------------------------------------------------------------- #
165
+
166
+
167
+ def test_no_receipt_field_reaches_the_classifier_payload():
168
+ built, classifier, _ = chain([echoing_service()])
169
+ built.invoke(payload("invoice one"))
170
+ blob = repr(classifier.seen[0])
171
+ for field in ("request_id", "selection_id", "policy_version", "tokens_saved"):
172
+ assert field not in blob
173
+
174
+
175
+ def test_a_sink_that_is_not_a_list_is_named():
176
+ built, _, _ = chain([echoing_service()])
177
+ with pytest.raises(NeedlepathConfigError, match=RECEIPTS_KEY):
178
+ built.invoke(payload("invoice one"), {"configurable": {RECEIPTS_KEY: {}}})
179
+
180
+
181
+ def test_the_receipt_reaches_a_config_sink():
182
+ built, _, _ = chain([echoing_service()])
183
+ sink: list[dict] = []
184
+ built.invoke(payload("invoice one"), {"configurable": {RECEIPTS_KEY: sink}})
185
+ assert len(sink) == 1
186
+ assert set(sink[0]) == {
187
+ "needlepath.request_id",
188
+ "needlepath.selection_id",
189
+ "needlepath.policy_version",
190
+ "needlepath.tokens_saved",
191
+ "needlepath.outcome",
192
+ }
193
+ assert sink[0]["needlepath.policy_version"] == OP
194
+
195
+
196
+ def test_a_failed_call_still_issues_a_receipt():
197
+ built, _, _ = chain([error(500)])
198
+ sink: list[dict] = []
199
+ built.invoke(payload("invoice one"), {"configurable": {RECEIPTS_KEY: sink}})
200
+ assert sink[0]["needlepath.tokens_saved"] == 0
201
+
202
+
203
+ def test_no_record_text_reaches_the_receipt():
204
+ built, _, _ = chain([echoing_service()])
205
+ sink: list[dict] = []
206
+ built.invoke(payload("invoice one"), {"configurable": {RECEIPTS_KEY: sink}})
207
+ assert "invoice" not in repr(sink[0])
208
+
209
+
210
+ def test_without_a_sink_the_chain_still_runs():
211
+ built, classifier, _ = chain([echoing_service()])
212
+ built.invoke(payload("invoice one"))
213
+ assert classifier.seen[0]["state"]
214
+
215
+
216
+ # --------------------------------------------------------------------------- #
217
+ # Modes
218
+ # --------------------------------------------------------------------------- #
219
+
220
+
221
+ def test_rendered_mode_hands_the_classifier_a_string():
222
+ built, classifier, _ = chain([echoing_service()], mode="rendered")
223
+ built.invoke(payload("invoice one", "weather two"))
224
+ state = classifier.seen[0]["state"]
225
+ assert isinstance(state, str)
226
+ # The header carries what the *response* said, and this service returns no
227
+ # title, so there is none to print.
228
+ assert state.startswith("[r1]\nEXCERPT:")
229
+ assert "\n\n[r2]\nEXCERPT:" in state
230
+
231
+
232
+ def test_records_mode_is_the_default():
233
+ built, classifier, _ = chain([echoing_service()])
234
+ built.invoke(payload("invoice one"))
235
+ assert isinstance(classifier.seen[0]["state"], list)
236
+
237
+
238
+ # --------------------------------------------------------------------------- #
239
+ # The Runnable on its own
240
+ # --------------------------------------------------------------------------- #
241
+
242
+
243
+ def test_needlepath_select_returns_the_result_the_records_and_the_receipt():
244
+ sync_client, _, _, _ = clients([echoing_service()])
245
+ out = NeedlepathSelect(client=sync_client).invoke(payload("invoice one"))
246
+ assert set(out) == {"selection", "records", "receipt"}
247
+ assert out["selection"].applied is True
248
+ assert out["selection"].reason == Reason.OK
249
+ assert out["receipt"]["needlepath.request_id"] == out["selection"].request_id
250
+
251
+
252
+ def test_needlepath_select_refuses_a_payload_without_records():
253
+ sync_client, _, _, _ = clients([echoing_service()])
254
+ with pytest.raises(NeedlepathConfigError, match="records"):
255
+ NeedlepathSelect(client=sync_client).invoke(
256
+ {"task": TaskSpec(prompt="x"), "max_context_tokens": 100}
257
+ )
258
+
259
+
260
+ def test_needlepath_select_refuses_a_payload_without_a_task_or_a_prompt():
261
+ sync_client, _, _, _ = clients([echoing_service()])
262
+ with pytest.raises(NeedlepathConfigError, match="task"):
263
+ NeedlepathSelect(client=sync_client).invoke(
264
+ {"records": records("invoice one"), "max_context_tokens": 100}
265
+ )
266
+
267
+
268
+ def test_the_payload_fields_cannot_be_pinned_at_construction():
269
+ """They come from the payload and were being silently overwritten there."""
270
+ sync_client, _, _, _ = clients([echoing_service()])
271
+ with pytest.raises(NeedlepathConfigError, match="records"):
272
+ NeedlepathSelect(client=sync_client, records=[])
273
+
274
+
275
+ def test_the_step_carries_a_schema_langchain_can_infer():
276
+ """Bare `Runnable` leaves LangChain with a TypeVar for the input type, and
277
+ a sequence takes its input schema from its first step."""
278
+ sync_client, _, _, _ = clients([echoing_service()])
279
+ assert NeedlepathSelect(client=sync_client).InputType == dict[str, Any]
280
+
281
+
282
+ def test_a_prompt_string_is_accepted_in_place_of_a_task():
283
+ sync_client, _, sync_t, _ = clients([echoing_service()])
284
+ NeedlepathSelect(client=sync_client).invoke(
285
+ {"records": records("invoice one"), "prompt": "what failed?", "max_context_tokens": 4000}
286
+ )
287
+ assert sync_t.bodies[0]["task"]["prompt"] == "what failed?"
288
+
289
+
290
+ def test_the_chain_is_a_composition_a_caller_can_extend():
291
+ built, classifier, _ = chain([echoing_service()])
292
+ extended = built | RunnableLambda(lambda out: out["answers"])
293
+ assert extended.invoke(payload("invoice one")) == ["yes", "yes"]
294
+
295
+
296
+ # --------------------------------------------------------------------------- #
297
+ # The async twin cannot drift
298
+ # --------------------------------------------------------------------------- #
299
+
300
+
301
+ def test_async_behaves_identically():
302
+ sync_client, async_client, _, _ = clients([echoing_service()])
303
+ classifier = RecordingClassifier()
304
+ built = build_system_one_chain(
305
+ needlepath_client=sync_client,
306
+ async_client=async_client,
307
+ classifier=classifier,
308
+ questions=QUESTIONS,
309
+ )
310
+ sink: list[dict] = []
311
+ asyncio.run(built.ainvoke(payload("invoice one"), {"configurable": {RECEIPTS_KEY: sink}}))
312
+ assert [entry["record_id"] for entry in classifier.seen[0]["state"]] == ["r1"]
313
+ assert classifier.seen[0]["questions"] == QUESTIONS
314
+ assert sink[0]["needlepath.policy_version"] == OP
315
+
316
+
317
+ def test_async_fails_open_with_the_callers_records():
318
+ sync_client, async_client, _, _ = clients([error(500)])
319
+ classifier = RecordingClassifier()
320
+ built = build_system_one_chain(
321
+ needlepath_client=sync_client,
322
+ async_client=async_client,
323
+ classifier=classifier,
324
+ questions=QUESTIONS,
325
+ )
326
+ body = payload("invoice one")
327
+ asyncio.run(built.ainvoke(body))
328
+ assert classifier.seen[0]["state"][0]["text"] == body["records"][0].text
@@ -1,46 +0,0 @@
1
- # Changelog
2
-
3
- Nothing in this tree has been published yet (`sdk/BLOCKED.md`), so there is no
4
- installed base to protect — this file exists anyway, because a breaking change
5
- should read like one whether or not a release ever shipped it, and because the
6
- constructors now raise pointing here by name.
7
-
8
- ## 0.2.0 — unreleased
9
-
10
- ### Removed
11
-
12
- - **`preserve_recent`** (both `NeedlepathMiddleware` and
13
- `NeedlepathPreModelHook`). A client-side "never rewrite the last N messages"
14
- rule is a selection decision made locally: whichever records fall in the
15
- window were guaranteed kept by client logic, no matter what the engine's own
16
- selection said about them. It also made `.stats` dishonest — the counters
17
- went on reporting the engine's *unfiltered* `tokens_after`/`tokens_saved`
18
- while only a narrower, locally-filtered rewrite was actually installed, so
19
- the receipt diverged from what the message list actually contained whenever
20
- an engine selection favored the protected window (NEXPE-517/523 review).
21
-
22
- **Migration:** remove `preserve_recent=` from every call site. If tail
23
- protection is a real requirement, it is either a request to make of the
24
- *engine* (a position/recency signal it can act on like any other input to
25
- its own decision) or a genuinely separate, engine-blind mechanism you
26
- compose yourself outside this package. Passing `preserve_recent=` to either
27
- constructor now raises `TypeError` naming this entry.
28
-
29
- ### Added
30
-
31
- - **`.engine_stats`** on both classes, alongside the existing `.stats`.
32
- `.stats` now reports what was **actually applied** — real before/after token
33
- counts, including the placeholder text substituted for a declined record,
34
- which the engine's own numbers cannot account for. `.engine_stats` reports
35
- the engine's raw response, unmodified, for reconciling against what the
36
- service itself measured or billed. See each module's "Two stats objects, two
37
- truths" docstring note.
38
-
39
- ### Fixed
40
-
41
- - Records are no longer scored or filtered by position at all: no computed
42
- `importance`, no locally-derived `task.required_record_ids`, and no local
43
- filtering of the rewrite map (the `preserve_recent` removal above was the
44
- last of three forms this took) — see
45
- `src/core/agentbuilder/tests/test_needlepath_thin_client_guard.py` in the
46
- main repo, which now detects all three.