aicordon-langchain 0.1.0__tar.gz

aicordon_langchain-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Secrets never live next to code. This line is a fuse, not a description of what is here.
+.env
+.env.*
+
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+
+# The injection bank and any datasets never travel: the bank is both a resource of the project and
+# its only honest held-out test. Insurance against an accidental `git add`, not a precaution in the
+# abstract — memory is not the thing to rely on here.
+datasets/
+data/pools/
+*.jsonl
+
+# Three exceptions, each of them ours end to end and rebuildable from the script beside it: the ten
+# demonstration exchanges and the two ground-truth manifests. Without them a clone can neither read
+# the example sets nor run `show_material.py` / `show_request.py` over them.
+!integrations/examples/dialogues.jsonl
+!integrations/examples/dialog_manifest.jsonl
+!integrations/examples/manifest.jsonl
+
+# The sources the base is built from stay out: the slot dictionaries and the rule file are at once
+# the recipe for the base and the instructions for walking around it. The product does not claim its
+# rules are readable; what ships is the built base, one file (`src/aicordon/picket/data/*.bin`).
+src/aicordon/picket/data/slots/
+src/aicordon/picket/data/*.json
+
+# Research notes live in the research repository and do not travel. This line is not caution in the
+# abstract: an append to RESULTS.md from this directory has already dropped fifty lines of
+# measurement prose in here once. Better the mistake is caught by git than by eye.
+RESULTS.md
+HANDOFF.md
+PLAN*.md
+
+# Working notes and release plans: ours, not part of what ships. Same rule as the research
+# notes above -- the repository holds the product, not the scaffolding around a release.
+TODO/

aicordon_langchain-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 — 2026-08-26
+
+First release. AI Cordon Picket for LangChain, in four places a string reaches a model.
+
+| entry point | host contract | reads | with |
+|---|---|---|---|
+| `PromptInjectionFilter` | `BaseDocumentTransformer` | documents at ingest | `ipi` |
+| `ToolOutputFilter` | `AgentMiddleware.wrap_tool_call` | what a tool handed back | `ipi` |
+| `PromptInjectionGuard` | `AgentMiddleware.wrap_model_call` | the turn an agent will answer | `dpi` |
+| `PromptInjectionValidator` | `Runnable` | the request in a chain | `dpi` |
+
+The policy is `aicordon.guard`, shipped inside the detector: modes, cut boundaries and metadata are
+the same here as in `aicordon-haystack`, and the acceptance measurements reproduce that package's
+numbers on the same corpora.
+
+**The tool result is the surface a RAG pipeline has no equivalent of.** A page a tool fetches enters
+the conversation with nothing between it and the model, and it is material by any reading — so it is
+read with the `ipi` rules at the point the tool returns, where cutting is what the policy was
+measured on. `drop` there withholds the text and keeps the message: every tool call must be answered
+by a result carrying its id.
+
+**Nothing rewrites a request.** `PromptInjectionGuard` and `PromptInjectionValidator` take
+`annotate`, `drop` and `fail` only, and a chain link takes no `drop` at all — a `Runnable` returns a
+value and the next link is the model, so it raises or marks and lets a `RunnableBranch` decide.
+
+Against `langchain-core` 1.6, `langchain` 1.3 and `langgraph` 1.2. The contract each entry point
+stands on, and the four traps behind these choices, are in `NOTES.md`.

aicordon_langchain-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mikhail Gribov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aicordon_langchain-0.1.0/NOTES.md

@@ -0,0 +1,112 @@
+# LangChain: the contract, established from the sources
+
+Checked 2026-08-26. The clone is `langchain-ai/langchain` at `502b2b4`, which carries
+`langchain-core` 1.6.1 and `langchain` 1.3.17 in development; the wrapper is written against the
+released `langchain-core` 1.6.0, `langchain` 1.3.17 and `langgraph` 1.2.11, which is what the venv
+here has. Repository MIT, the framework's own.
+
+**The framework moved under the name.** `langchain` 1.x is an agent library: `create_agent` plus
+middleware. What used to be `langchain` — chains, retrievers, the whole 0.3 surface — was renamed
+`langchain-classic` (1.0.8) and left where it was. So an integration written for "LangChain" today
+has to answer for two shapes, the agent and the chain, and this package carries one entry per shape.
+
+## Where we sit
+
+Four slots, because a string reaches a model by four routes and the role it plays differs.
+
+| slot | host contract | ours | rules |
+|---|---|---|---|
+| documents at ingest | `BaseDocumentTransformer.transform_documents` | `PromptInjectionFilter` | `ipi` |
+| a tool's answer | `AgentMiddleware.wrap_tool_call` | `ToolOutputFilter` | `ipi` |
+| the turn an agent will answer | `AgentMiddleware.wrap_model_call` | `PromptInjectionGuard` | `dpi` |
+| the request in a chain | `Runnable` between prompt and model | `PromptInjectionValidator` | `dpi` |
+
+The ingest slot is a line of the caller's own code, not a pipeline object: LangChain has no
+`IngestionPipeline`, the loader hands you a list and you pass it on. That makes the transformer the
+plainest of the four and the only one with no host lifecycle to respect.
+
+## What a middleware is obliged to do
+
+Source of truth: `langchain/agents/middleware/types.py` and `langchain/agents/factory.py`, plus
+`middleware/pii.py`, which is the closest thing in the tree to what we are doing.
+
+* Subclass `AgentMiddleware`, implement the hooks you need, pass the instance in
+  `create_agent(middleware=[...])`. First in the list is the outermost layer.
+* `before_model` / `after_model` are nodes: they return state updates or `None`.
+* `wrap_model_call(request, handler)` and `wrap_tool_call(request, handler)` are wrappers: they may
+  call the handler more than once, or not at all.
+* Every hook has an async twin (`awrap_tool_call`, `abefore_model`, …). See trap 4 — the asymmetry
+  there is sharp.
+* State that goes through a checkpointer must be JSON-serialisable. Our metadata is bools, strings
+  and lists.
+
+There is **no serialisation of the middleware object itself** — a middleware is constructed in the
+caller's code and never rebuilt from a dict, so the trap that cost the Haystack wrapper a whole
+mechanism (`to_dict`/`from_dict`, settings silently restored to their defaults) does not exist here.
+The `BaseDocumentTransformer` is not `Serializable` either.
+
+## Traps the mock-ups caught (2026-08-26)
+
+Each was run against a control on `langchain` 1.3.17; the probes are in the session scratchpad and
+the behaviour each describes is covered by a test in `tests/`.
+
+1. **`jump_to` is ignored unless the hook is decorated.** A `before_model` may end a run by
+   returning `{"jump_to": "end"}` — but only if it also carries `@hook_config(can_jump_to=["end"])`.
+   The decorator is what makes `_add_middleware_edge` build a conditional edge; without it the
+   builder emits `graph.add_edge(name, default_destination)`, the value sits in state unread, and
+   the model is called with the attack. Nothing is raised, nothing is logged. Measured: undecorated,
+   the model was called once; decorated, zero times. **We use `wrap_model_call` instead**, where
+   refusing means not calling the handler — there is no edge to forget.
+
+2. **A tool may answer with a `Command`, and then its text is not in a `ToolMessage`.** A tool that
+   writes agent state returns `Command(update={"messages": [ToolMessage(...)]})`, and a wrapper
+   matching on `ToolMessage` alone passes it through unread — the text still reaches the model, and
+   the metadata does not even record that nobody looked. Measured with one tool of each kind in the
+   same run: the plain one was rewritten, the `Command` one was not. We walk `update["messages"]`.
+
+3. **A message copy without the original `id` is appended, not replaced.** The `messages` channel
+   reduces by id. Annotating a turn by building a fresh `HumanMessage` leaves BOTH in the list, so
+   the model is sent the turn twice — and in a redacting design it would be sent the clean copy and
+   the original side by side. Measured: with the id, two messages in the final state; without it,
+   three. `model_copy(update=...)` keeps the id, so that is what we use everywhere.
+
+4. **Sync-only hooks are not symmetrical under `ainvoke`.** A sync `before_model` or
+   `wrap_model_call` is run in an executor and works. A sync `wrap_tool_call` raises
+   `NotImplementedError` from the tools node, mid-run. Both halves of every hook are written out
+   here, and both are tested.
+
+5. **`str(message.content)` is not the message text.** Content is either a string or a list of
+   blocks; `str()` of the list is a Python repr, so a check over it reads punctuation and dictionary
+   keys that nobody sent, and an edit to it destroys the message. `langchain-core` 1.x has
+   `message.text`, which joins the text blocks and ignores images and files — that is what we read.
+   (`middleware/pii.py` in the framework itself does the `str(content)` thing.)
+
+6. **The two vocabularies disagree about role names.** `HumanMessage.type` is `human` where the
+   policy says `user`, `AIMessage.type` is `ai` where it says `assistant`. A role map keyed on the
+   host's word matches nothing in the default policy: the guard reads no message at all while
+   reporting each one read and clean. `ROLE_OF` in `_common.py` translates; the test that would fail
+   without it is `test_the_human_message_is_read_as_the_user_role`.
+
+## Decisions that are ours, not the host's
+
+**`drop` on a tool result withholds the text, not the message.** Every tool call must be answered by
+a result carrying its `tool_call_id`; a call left unanswered makes the provider error or re-ask. So
+the message stays and the model is told the output was withheld — which is also the honest thing to
+tell it.
+
+**A chain link may not `drop`.** A `Runnable` returns a value and the next link is the model; there
+is no arrangement in which it declines the call and answers instead. `PromptInjectionValidator`
+raises on the mode rather than imitating it, and points at the two real ways to have it: `fail`, or
+a `RunnableBranch` on `.flagged`. In an agent the decision has a proper home.
+
+**The request guard reads what arrived since the model last spoke.** `wrap_model_call` runs once per
+model call, so reading the whole history each time would re-bill the opening turn on every step of
+a loop. The tail after the last `AIMessage` is what is new; on the first call there is none, and the
+tail is the whole list — right for a run resumed with a history nobody has read yet.
+
+## What carries over to another framework
+
+The policy (`aicordon.guard`) carried over from Haystack unchanged: modes, cut boundaries, metadata,
+the role map, the refusal of editing modes on the request side. What had to be written here is the
+translation and the host's contract — and one surface Haystack has no equivalent of, the tool
+result, which is where an agent takes in material.

aicordon_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: aicordon-langchain
+Version: 0.1.0
+Summary: Check what an LLM is given for prompt injection: material at ingest, tool output, and the turn it answers
+Project-URL: Homepage, https://github.com/AICordon/aicordon/blob/main/integrations/langchain/README.md
+Project-URL: Repository, https://github.com/AICordon/aicordon
+Project-URL: Issues, https://github.com/AICordon/aicordon/issues
+Project-URL: Changelog, https://github.com/AICordon/aicordon/blob/main/integrations/langchain/CHANGELOG.md
+Author-email: Mikhail Gribov <mihail.gribov.rs@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,guardrails,jailbreak,langchain,llm-security,prompt-injection,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: aicordon>=1.1.1
+Requires-Dist: langchain-core>=1.0.0
+Requires-Dist: langchain>=1.3.0
+Description-Content-Type: text/markdown
+
+# AI Cordon Picket for LangChain
+
+Check what an LLM is given for prompt injection, in each place it can arrive:
+
+| entry point | reads | with |
+|---|---|---|
+| `PromptInjectionFilter` | **material**: documents at ingest, before they are chunked and embedded | Picket's `ipi` rules |
+| `ToolOutputFilter` | **material**: what a tool handed back, before the model reads it | `ipi` |
+| `PromptInjectionGuard` | **the request**: the turn an agent is about to answer | Picket's `dpi` rules |
+| `PromptInjectionValidator` | **the request**: the same, in a chain that is not an agent | `dpi` |
+
+The two rule sets are disjoint, and neither is a stricter version of the other — this is not a
+sensitivity knob. Pick by role: material is what the model works on, the request is what it answers.
+Your code knows which is which; it puts them in different places when it assembles the call.
+
+The check is a rule, not a model: no GPU, no network, no key, a few hundred kilobytes of base, and a
+fraction of a millisecond per turn on one core — see [what it costs](#what-it-costs).
+
+## Installation
+
+```bash
+pip install aicordon-langchain
+```
+
+## Material at ingest
+
+```python
+from aicordon_langchain import PromptInjectionFilter
+from langchain_community.document_loaders import DirectoryLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+docs = DirectoryLoader("kb/").load()
+docs = PromptInjectionFilter(mode="redact").transform_documents(docs)   # <- here
+chunks = RecursiveCharacterTextSplitter().split_documents(docs)
+store.add_documents(chunks)
+```
+
+The filter sits **before the splitter**: a cut here takes the injection out of the chunks, the
+embeddings and the store at once, with no offsets to reconcile across chunk boundaries.
+
+### What it does with a finding
+
+| `mode` | the document | the length |
+|---|---|---|
+| `annotate` | indexed unchanged, the finding recorded in metadata | unchanged |
+| `blank` | every character of the block becomes `blank_char` (default `*`) | **preserved** |
+| `mask` | the block is replaced by `mask_with` | changes |
+| `redact` *(default)* | the block is cut out | changes |
+| `drop` | not indexed | — |
+| `fail` | the run stops on the first finding | — |
+
+`blank` is for pipelines that carry offsets, page maps or diffs downstream and cannot have a
+document change length under them.
+
+The cut takes **the whole utterance the span sits in** — the sentence, across the lines a
+wrapper broke it over: the span points at the injection, but what must leave the index is
+everything it was saying. A short line that ends without punctuation is a bullet or a table
+row and is left alone, so a list is not eaten item by item.
+
+In `drop` mode the host's contract lets `transform_documents` return the survivors and nothing else,
+so use `split` when the removed pile should stay visible:
+
+```python
+kept, rejected = PromptInjectionFilter(mode="drop").split(docs)
+```
+
+## Tool output in an agent
+
+```python
+from aicordon_langchain import ToolOutputFilter
+from langchain.agents import create_agent
+
+agent = create_agent(
+    model="openai:gpt-5.5",
+    tools=[fetch_page, read_ticket],
+    middleware=[ToolOutputFilter(mode="redact")],           # every tool, or tools=["fetch_page"]
+)
+```
+
+A page a tool brings back is material by any reading — the model is to work on it, not answer it —
+and it enters the conversation with nothing between it and the model. The filter reads it at the
+point the tool returns, which is the same ingest point a document has and the only place where
+cutting is what the policy was measured on.
+
+**`drop` here withholds the text, not the message.** Every tool call must be answered by a result
+carrying its id, so the message stays and the model is told the output was withheld — which is also
+the honest thing to tell it.
+
+## The request in an agent
+
+```python
+from aicordon_langchain import PromptInjectionGuard
+
+agent = create_agent(
+    model="openai:gpt-5.5",
+    tools=[fetch_page],
+    middleware=[PromptInjectionGuard()],                    # mode="drop" by default
+)
+```
+
+On a flagged turn the model is **not called**, and the agent answers with the guard's own message
+instead — `mode="annotate"` calls the model and records the finding on the answer, `mode="fail"`
+raises `InjectionFound`. What is read is the request: by default the user's turns, and nothing else.
+The system message is the operator's own text, and an operator who wants to steer their own model
+does not need an injection to do it.
+
+Both middlewares in one agent, each on its own side:
+
+```python
+middleware=[PromptInjectionGuard(), ToolOutputFilter(mode="redact")]
+```
+
+## The request in a chain
+
+```python
+from aicordon_langchain import PromptInjectionValidator
+
+chain = prompt | PromptInjectionValidator() | model        # raises InjectionFound on a finding
+```
+
+A link in a chain returns a value and the next link is the model; there is no arrangement in which
+it declines the call and answers instead. So it raises, or it marks and lets the chain decide:
+
+```python
+guard = PromptInjectionValidator(mode="annotate")
+chain = prompt | RunnableBranch((guard.flagged, refusal), model)
+```
+
+Inside an agent the same decision has a proper home — prefer `PromptInjectionGuard` when there is
+an agent to put it in.
+
+## Nothing is rewritten on the request side
+
+`PromptInjectionGuard` and `PromptInjectionValidator` accept `annotate`, `drop` and `fail` only; ask
+either for `redact` and it raises. Material can lose a paragraph and stay usable. Take a clause out
+of what somebody asked for and the model answers a question nobody put, with the user seeing an
+answer rather than a notice — and the cut itself is fitted to the wrong shape, because a typed
+attack is not spliced into a turn, it *is* the turn.
+
+## What is written where
+
+Metadata is written on every text that was read, including the clean ones: "read, clean" and "not
+read" are different facts, and a field that appeared only on a finding could not be filtered on.
+
+| surface | where it lands | keys |
+|---|---|---|
+| documents | `Document.metadata` | `ipi_flagged`, `ipi_action`, `ipi_base`, and on a finding `ipi_threats`, `ipi_spans`, `ipi_removed_chars` |
+| tool output | `ToolMessage.response_metadata` | `ipi_flagged`, `ipi_action`, `ipi_base`, `ipi_threats` |
+| the agent's request | the answer's `response_metadata` | `picket_blocked` or `picket_request_flagged`, `picket_request_threats`, `picket_messages` (keyed by message id) |
+| the chain's request | each read message's `additional_kwargs` | `picket_flagged`, `picket_action`, `picket_base`, `picket_threats`, `picket_spans` |
+
+Findings are also logged through the standard library logger under `aicordon_langchain.*` at
+`warning` level, in every mode. Writing it down is not a policy choice.
+
+## Measured
+
+Not the detector's recall — that ships with the detector — but what your line delivers with this
+package in it and without.
+
+**Material at ingest.** [Quadrat-IPI v1.0.1](https://huggingface.co/datasets/mihailgribov/quadrat-ipi),
+2000 injected and 2000 clean documents, `mode="redact"`; how much of a planted payload still reaches
+the splitter:
+
+| | whole corpus | injections that ask the model to **reveal** something |
+|---|---|---|
+| payload gets through intact, without the filter | 100% | 100% |
+| payload gets through intact, with it | **85.2%** | **43.4%** |
+| payload gone without a trace | 13.5% | **51.3%** |
+| clean documents dropped or trimmed | 1 of 2000 | 1 of 2000 |
+
+Both columns matter: the first is an arbitrary stream, the second is where the rule is strong.
+
+**Material through a tool.** The same corpus, 1000 injected and 1000 clean pages, fetched by a tool
+inside a real agent loop — and read off the message list the MODEL was handed, not off the filter's
+own return value:
+
+| | |
+|---|---|
+| payload reaching the model intact, without the filter | 100% (1000 of 1000) |
+| payload reaching the model intact, with it | **85.4%** |
+| payload gone without a trace | 13.1% |
+| clean pages withheld or trimmed | 0 of 1000 |
+
+**The request.** Held-out forum jailbreaks from
+[TrustAIRLab in-the-wild](https://huggingface.co/datasets/TrustAIRLab/in-the-wild-jailbreak-prompts)
+(537, near-duplicates of the fitting half removed) against 20 000 real user turns from
+[WildChat](https://huggingface.co/datasets/allenai/WildChat-1M), an agent in `mode="drop"`:
+
+| | |
+|---|---|
+| attacks reaching the model, without the guard | 100% (537 of 537) |
+| attacks reaching the model, with it | **65.2%** |
+| turns not answered, out of 20 000 real ones | 0.070% (14) |
+| verdicts differing from the bare detector | **0** |
+
+WildChat carries no attack labels and real jailbreaks sit inside it, so "turns not answered" is an
+upper bound on the cost to a real user, not a false-alarm rate. The detector's working point, on a
+labelled pool, is in its report.
+
+The last row outranks the other two: a wrapper may neither lose text nor add its own, and a figure
+taken while it does would be describing a different string than the one the user sent.
+
+Reproduce all three with `eval/measure_ingest.py`, `eval/measure_tools.py` and
+`eval/measure_agent.py`.
+
+## What it costs
+
+Checking a turn costs **0.32 ms at the median length**, and 1.78 ± 0.06 ms averaged over ordinary
+traffic — 3000 real WildChat turns, each timed five times (`eval/costturn.py`). Loading the base
+costs 21 ms, once per process. Of that 1.78 ms, 1.75 is the rule engine itself and 0.03 is
+everything this package adds.
+
+The average is five times the median: cost follows length, and a chat pool has a long tail. Find
+your row:
+
+| turn length | turns in the pool | cost |
+|---|---|---|
+| under 200 characters | 1943 | 0.21 ms |
+| 200–500 | 411 | 0.71 ms |
+| 500–1500 | 321 | 1.72 ms |
+| 1500–4000 | 182 | 4.62 ms |
+| over 4000 | 143 | 15.63 ms |
+
+For scale, an agent step through LangGraph costs 0.57 ms before any middleware is installed. A
+document at ingest costs 11 ms — documents are long, and cost follows length there too.
+
+Cost drifts with machine load. These were taken in one run by one procedure — the only way two
+figures compare.
+
+No GPU, no network call, no key. The rule base is a few hundred kilobytes and loads once.
+
+## Not a prefilter
+
+Silence from a rule is not a verdict. Picket reports what it recognises; what it does not recognise
+it says nothing about, and no finding does not mean no injection. It belongs where a cheap, local,
+deterministic check is worth having on everything you ingest — not as the only thing between a model
+and the web.
+
+## Licence
+
+Apache-2.0. The detector itself is [`aicordon`](https://pypi.org/project/aicordon/); the policy the
+wrappers share lives there as `aicordon.guard`.