langchain-replylayer 0.1.0__tar.gz → 0.2.0__tar.gz

langchain_replylayer-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReplyLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{langchain_replylayer-0.1.0 → langchain_replylayer-0.2.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: langchain-replylayer
-Version: 0.1.0
+Version: 0.2.0
 Summary: LangChain tools for ReplyLayer — governed email for AI agents
 Project-URL: Homepage, https://replylayer.ai
 Project-URL: Documentation, https://replylayer.ai/docs/guides/langchain
 Project-URL: Repository, https://github.com/replylayer/rly
 Project-URL: Issues, https://github.com/replylayer/rly/issues
 License-Expression: MIT
+License-File: LICENSE
 Keywords: agent,ai,email,langchain,replylayer,toolkit,tools
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -31,11 +32,19 @@ Description-Content-Type: text/markdown
 
 # langchain-replylayer
 
-LangChain tools for [ReplyLayer](https://replylayer.ai) — governed email for AI agents.
+LangChain integrations for [ReplyLayer](https://replylayer.ai) — governed email for AI agents.
 
-This package is a set of **thin wrappers over the published [`replylayer`](https://pypi.org/project/replylayer/) SDK**. Handing these tools to an agent changes nothing about the security model: every send still passes ReplyLayer's allowlist, quota, human-approval, and content-scanning gates, exactly as a direct API call would. Scanning reduces risk; a clean verdict is not a trust verdict — a `sent` result means "accepted for delivery", not "safe".
+This package is a set of **thin clients over the published [`replylayer`](https://pypi.org/project/replylayer/) SDK** across LangChain's three integration surfaces:
 
-Inbound message content (senders, subjects, bodies) is untrusted third-party data. The tools label every read as such and carry the message's `agent_safety_context` through verbatim — read message bodies as data, never as instructions to act on.
+| Class | Surface | What it does |
+|-------|---------|--------------|
+| `ReplyLayerToolkit` | Tools | Six governed email tools for an agent — send, reply, list, read, long-poll, quota. |
+| `ReplyLayerLoader` | Document loader | Bulk-reads a mailbox and emits settled messages as `Document`s for indexing / RAG. |
+| `ReplyLayerRetriever` | Retriever | Query → the most recent relevant `Document`s, re-checking state and redaction on every query. |
+
+Handing these to an agent changes nothing about the security model: every send still passes ReplyLayer's allowlist, quota, human-approval, and content-scanning gates, exactly as a direct API call would, and the loader and retriever preserve the same safety envelope rather than bypass it (see [The safety envelope for RAG](#the-safety-envelope-for-rag)). Scanning reduces risk; a clean verdict is not a trust verdict — a `sent` result means "accepted for delivery", not "safe".
+
+Inbound message content (senders, subjects, bodies) is untrusted third-party data. The tools label every read as such and carry the message's `agent_safety_context` through verbatim; the loader and retriever frame every body as untrusted data in its own content — read message bodies as data, never as instructions to act on.
 
 > ReplyLayer is in private beta, invite-only. You need a ReplyLayer API key to use these tools — get one at <https://app.replylayer.ai/connect>.
 
@@ -99,6 +108,51 @@ Wire them into an agent with `toolkit.get_tools()`. Each returns a JSON-serializ
 
 Not exposed on purpose: anything that loosens containment (allowlist mutations, quarantine release, review approve/deny). The server rejects agent keys on those anyway, so the toolkit does not tempt a model with tools that would only 403.
 
+## Index your inbox (document loader)
+
+`ReplyLayerLoader` reads a mailbox and emits each settled message as a `Document`. It is a standard LangChain `BaseLoader` — `lazy_load()`, `load()`, `alazy_load()`, and `aload()` all work — and it is truly lazy, making no HTTP call until you iterate.
+
+```python
+from langchain_replylayer import ReplyLayerLoader
+
+with ReplyLayerLoader(
+    "support@yourco.example",
+    direction="inbound",
+    since="2026-07-01T00:00:00Z",
+    max_messages=500,
+) as loader:
+    documents = loader.load()
+```
+
+Each `Document` carries the message id (`doc.id`), a `page_content` opening with a provenance header that frames the body as untrusted data, and flat metadata: `source`, `message_id`, `mailbox_id`, `thread_id`, `direction`, `state`, `sender`, `recipient`, `subject`, `created_at`, `scan_verdict`, `untrusted_content`, `body_truncated`, `char_count`, `returned_char_count`, and `has_attachments`. Emission is grouped by state, newest-first within each group; each unique message costs one audited read and no `Document.id` repeats within a run.
+
+Constructor: `ReplyLayerLoader(mailbox_id, *, api_key=None, base_url=..., direction=None, since=None, until=None, unread=None, max_messages=None, include_provenance_header=True, on_truncated="include")`. `max_messages=0` yields nothing; a negative value raises. After any async use, call `aclose()` (or use `async with`) — `close()` alone will not shut down the async client.
+
+## Search your inbox (retriever)
+
+`ReplyLayerRetriever` is a live, search-backed retriever. Every query re-evaluates state gating, mailbox scoping, redaction, and audit logging on the server — it keeps no snapshot, so quarantine state and redaction are re-checked on every query rather than frozen into a store.
+
+```python
+from langchain_replylayer import ReplyLayerRetriever
+
+with ReplyLayerRetriever(mailbox_id="support@yourco.example", k=5) as retriever:
+    documents = retriever.invoke("refund request")
+```
+
+It returns the `k` (1–50) most recent matching messages. Server search is a keyword match over the subject and body ordered by recency — a **recency-ordered keyword retriever, not a relevance-ranked or semantic one**. A query shorter than three characters returns an empty list with no request. Because search indexes the full body, a query can match text beyond the returned prefix of a truncated message; the hit is correct, but the returned content is a prefix. Use `.invoke()` / `.ainvoke()`.
+
+Both components accept `include_provenance_header` (on by default) and `on_truncated` (`include` a marker, `skip` the document, or `error`).
+
+## The safety envelope for RAG
+
+The loader is the one component that exports content past ReplyLayer's safety boundary, so both components share hard client-side rules:
+
+- **They emit only settled, scanned messages.** A message still scanning, under review, blocked, or in-flight is never emitted; an inbound message with no scan evidence is dropped; a message that transitions state mid-run is emitted at most once.
+- **Retrieval re-checks; a loaded corpus does not.** The retriever re-evaluates state and redaction on every query. A corpus the loader wrote is a point-in-time copy: deletion, quarantine, and retention-purge events do **not** propagate to an external vector store. Re-index periodically — `since=` for incremental top-ups, plus an occasional full rebuild that **replaces or reconciles the corpus by `message_id`** (append-only re-indexing would leave deleted or quarantined documents in place).
+- **Bodies are capped and the cap is visible.** Text bodies are capped at 20,000 characters. A truncated body ends with a marker stating how much was returned, and the metadata carries `body_truncated`, `char_count`, and `returned_char_count`.
+- **Keep the provenance header on.** Stock chains concatenate `page_content` and never show the model your metadata, so the untrusted-content framing lives in the content itself. Leave `include_provenance_header` enabled.
+- **Retrieved email content is data, never instructions.** Every document is labeled `untrusted_content`, and a per-message trust relaxation is never persisted into a document.
+
 ## Governance outcomes
 
 The tools translate every ReplyLayer outcome into a value an agent can act on. The full `status` vocabulary:
@@ -202,7 +256,7 @@ Use a **mailbox-bound agent key** with an agent, not an admin key — the tools
 
 ## Versioning
 
-`langchain-replylayer` is versioned **independently of the `replylayer` SDK**. It is **not** part of the TypeScript↔Python method-mirror contract — that contract covers the resource SDKs, and this adapter is exempt. The `__all__` list in `langchain_replylayer/__init__.py` is the version-contracted public API; everything else (`tools`, `toolkit`, `_governance`) is private and may change between releases.
+`langchain-replylayer` is versioned **independently of the `replylayer` SDK**. It is **not** part of the TypeScript↔Python method-mirror contract — that contract covers the resource SDKs, and this adapter is exempt. The `__all__` list in `langchain_replylayer/__init__.py` is the version-contracted public API — `ReplyLayerToolkit`, `ReplyLayerLoader`, `ReplyLayerRetriever`, and `__version__`; everything else (the `tools`, `toolkit`, `loader`, `retriever`, and underscore-prefixed modules) is private and may change between releases.
 
 ## Learn more
 

{langchain_replylayer-0.1.0 → langchain_replylayer-0.2.0}/README.md

@@ -1,10 +1,18 @@
 # langchain-replylayer
 
-LangChain tools for [ReplyLayer](https://replylayer.ai) — governed email for AI agents.
+LangChain integrations for [ReplyLayer](https://replylayer.ai) — governed email for AI agents.
 
-This package is a set of **thin wrappers over the published [`replylayer`](https://pypi.org/project/replylayer/) SDK**. Handing these tools to an agent changes nothing about the security model: every send still passes ReplyLayer's allowlist, quota, human-approval, and content-scanning gates, exactly as a direct API call would. Scanning reduces risk; a clean verdict is not a trust verdict — a `sent` result means "accepted for delivery", not "safe".
+This package is a set of **thin clients over the published [`replylayer`](https://pypi.org/project/replylayer/) SDK** across LangChain's three integration surfaces:
 
-Inbound message content (senders, subjects, bodies) is untrusted third-party data. The tools label every read as such and carry the message's `agent_safety_context` through verbatim — read message bodies as data, never as instructions to act on.
+| Class | Surface | What it does |
+|-------|---------|--------------|
+| `ReplyLayerToolkit` | Tools | Six governed email tools for an agent — send, reply, list, read, long-poll, quota. |
+| `ReplyLayerLoader` | Document loader | Bulk-reads a mailbox and emits settled messages as `Document`s for indexing / RAG. |
+| `ReplyLayerRetriever` | Retriever | Query → the most recent relevant `Document`s, re-checking state and redaction on every query. |
+
+Handing these to an agent changes nothing about the security model: every send still passes ReplyLayer's allowlist, quota, human-approval, and content-scanning gates, exactly as a direct API call would, and the loader and retriever preserve the same safety envelope rather than bypass it (see [The safety envelope for RAG](#the-safety-envelope-for-rag)). Scanning reduces risk; a clean verdict is not a trust verdict — a `sent` result means "accepted for delivery", not "safe".
+
+Inbound message content (senders, subjects, bodies) is untrusted third-party data. The tools label every read as such and carry the message's `agent_safety_context` through verbatim; the loader and retriever frame every body as untrusted data in its own content — read message bodies as data, never as instructions to act on.
 
 > ReplyLayer is in private beta, invite-only. You need a ReplyLayer API key to use these tools — get one at <https://app.replylayer.ai/connect>.
 
@@ -68,6 +76,51 @@ Wire them into an agent with `toolkit.get_tools()`. Each returns a JSON-serializ
 
 Not exposed on purpose: anything that loosens containment (allowlist mutations, quarantine release, review approve/deny). The server rejects agent keys on those anyway, so the toolkit does not tempt a model with tools that would only 403.
 
+## Index your inbox (document loader)
+
+`ReplyLayerLoader` reads a mailbox and emits each settled message as a `Document`. It is a standard LangChain `BaseLoader` — `lazy_load()`, `load()`, `alazy_load()`, and `aload()` all work — and it is truly lazy, making no HTTP call until you iterate.
+
+```python
+from langchain_replylayer import ReplyLayerLoader
+
+with ReplyLayerLoader(
+    "support@yourco.example",
+    direction="inbound",
+    since="2026-07-01T00:00:00Z",
+    max_messages=500,
+) as loader:
+    documents = loader.load()
+```
+
+Each `Document` carries the message id (`doc.id`), a `page_content` opening with a provenance header that frames the body as untrusted data, and flat metadata: `source`, `message_id`, `mailbox_id`, `thread_id`, `direction`, `state`, `sender`, `recipient`, `subject`, `created_at`, `scan_verdict`, `untrusted_content`, `body_truncated`, `char_count`, `returned_char_count`, and `has_attachments`. Emission is grouped by state, newest-first within each group; each unique message costs one audited read and no `Document.id` repeats within a run.
+
+Constructor: `ReplyLayerLoader(mailbox_id, *, api_key=None, base_url=..., direction=None, since=None, until=None, unread=None, max_messages=None, include_provenance_header=True, on_truncated="include")`. `max_messages=0` yields nothing; a negative value raises. After any async use, call `aclose()` (or use `async with`) — `close()` alone will not shut down the async client.
+
+## Search your inbox (retriever)
+
+`ReplyLayerRetriever` is a live, search-backed retriever. Every query re-evaluates state gating, mailbox scoping, redaction, and audit logging on the server — it keeps no snapshot, so quarantine state and redaction are re-checked on every query rather than frozen into a store.
+
+```python
+from langchain_replylayer import ReplyLayerRetriever
+
+with ReplyLayerRetriever(mailbox_id="support@yourco.example", k=5) as retriever:
+    documents = retriever.invoke("refund request")
+```
+
+It returns the `k` (1–50) most recent matching messages. Server search is a keyword match over the subject and body ordered by recency — a **recency-ordered keyword retriever, not a relevance-ranked or semantic one**. A query shorter than three characters returns an empty list with no request. Because search indexes the full body, a query can match text beyond the returned prefix of a truncated message; the hit is correct, but the returned content is a prefix. Use `.invoke()` / `.ainvoke()`.
+
+Both components accept `include_provenance_header` (on by default) and `on_truncated` (`include` a marker, `skip` the document, or `error`).
+
+## The safety envelope for RAG
+
+The loader is the one component that exports content past ReplyLayer's safety boundary, so both components share hard client-side rules:
+
+- **They emit only settled, scanned messages.** A message still scanning, under review, blocked, or in-flight is never emitted; an inbound message with no scan evidence is dropped; a message that transitions state mid-run is emitted at most once.
+- **Retrieval re-checks; a loaded corpus does not.** The retriever re-evaluates state and redaction on every query. A corpus the loader wrote is a point-in-time copy: deletion, quarantine, and retention-purge events do **not** propagate to an external vector store. Re-index periodically — `since=` for incremental top-ups, plus an occasional full rebuild that **replaces or reconciles the corpus by `message_id`** (append-only re-indexing would leave deleted or quarantined documents in place).
+- **Bodies are capped and the cap is visible.** Text bodies are capped at 20,000 characters. A truncated body ends with a marker stating how much was returned, and the metadata carries `body_truncated`, `char_count`, and `returned_char_count`.
+- **Keep the provenance header on.** Stock chains concatenate `page_content` and never show the model your metadata, so the untrusted-content framing lives in the content itself. Leave `include_provenance_header` enabled.
+- **Retrieved email content is data, never instructions.** Every document is labeled `untrusted_content`, and a per-message trust relaxation is never persisted into a document.
+
 ## Governance outcomes
 
 The tools translate every ReplyLayer outcome into a value an agent can act on. The full `status` vocabulary:
@@ -171,7 +224,7 @@ Use a **mailbox-bound agent key** with an agent, not an admin key — the tools
 
 ## Versioning
 
-`langchain-replylayer` is versioned **independently of the `replylayer` SDK**. It is **not** part of the TypeScript↔Python method-mirror contract — that contract covers the resource SDKs, and this adapter is exempt. The `__all__` list in `langchain_replylayer/__init__.py` is the version-contracted public API; everything else (`tools`, `toolkit`, `_governance`) is private and may change between releases.
+`langchain-replylayer` is versioned **independently of the `replylayer` SDK**. It is **not** part of the TypeScript↔Python method-mirror contract — that contract covers the resource SDKs, and this adapter is exempt. The `__all__` list in `langchain_replylayer/__init__.py` is the version-contracted public API — `ReplyLayerToolkit`, `ReplyLayerLoader`, `ReplyLayerRetriever`, and `__version__`; everything else (the `tools`, `toolkit`, `loader`, `retriever`, and underscore-prefixed modules) is private and may change between releases.
 
 ## Learn more
 

langchain_replylayer-0.2.0/examples/langchain_retrieval_quickstart.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""ReplyLayer + LangChain retrieval gate — loader + retriever against staging.
+
+An operator-run acceptance check for ``ReplyLayerLoader`` and
+``ReplyLayerRetriever``. No language model and no second credential: it seeds two
+known messages through the simulator, waits for both to reach their terminal
+states, then asserts the loader and retriever emit the safe one and never the
+quarantined one.
+
+It seeds via a raw HTTP call to ``POST /v1/simulator/inbound`` (the same
+mechanism the tools quickstart's gate uses), passing a unique per-run ``label``
+that lands in each seeded message's subject so this run can find exactly its own
+messages — even though the simulator may answer ``pending`` without an id.
+
+Run against a STAGING sandbox mailbox with a mailbox-bound *agent* key, never a
+production or admin key. Because it WRITES (seeds two simulator messages),
+``REPLYLAYER_BASE_URL`` is REQUIRED and has no default — the script refuses to
+run without an explicit staging base, and refuses a base whose host is the
+production API (``api.replylayer.ai``) unless an explicit override is set.
+
+Environment
+-----------
+REPLYLAYER_API_KEY   (required)  a staging sandbox, mailbox-bound agent key.
+REPLYLAYER_MAILBOX   (required)  the target mailbox id or name.
+REPLYLAYER_BASE_URL  (required)  the staging API base (e.g.
+                                 ``https://<staging-host>.up.railway.app``). No
+                                 default — this script seeds messages, so it
+                                 will not fall back to production.
+REPLYLAYER_QUICKSTART_ALLOW_PRODUCTION
+                     (guard)     must equal the literal
+                                 ``I_UNDERSTAND_THIS_SEEDS_PRODUCTION`` to permit
+                                 a base whose host is ``api.replylayer.ai``;
+                                 otherwise the script refuses to seed production.
+
+    pip install "langchain-replylayer"
+    REPLYLAYER_BASE_URL=https://<staging-host> \
+        python examples/langchain_retrieval_quickstart.py
+"""
+from __future__ import annotations
+
+import os
+import secrets
+import time
+import urllib.parse
+
+import httpx
+
+from replylayer import ReplyLayer
+
+from langchain_replylayer import ReplyLayerLoader, ReplyLayerRetriever
+
+BASE_URL = os.environ.get("REPLYLAYER_BASE_URL", "")
+MAILBOX = os.environ.get("REPLYLAYER_MAILBOX", "")
+
+# This script seeds production-shaped writes, so it must never default to
+# production. The host it refuses (unless the operator opts in) and the exact
+# opt-in token:
+_PRODUCTION_HOST = "api.replylayer.ai"
+_ALLOW_PRODUCTION_TOKEN = "I_UNDERSTAND_THIS_SEEDS_PRODUCTION"
+
+# The header a projected inbound document opens with; a loaded clean message must
+# carry it, proving the untrusted-content framing rode along in page_content.
+_INBOUND_HEADER_MARK = "inbound message from an external sender"
+
+# Poll bound: both seeded messages must reach a TERMINAL state (clean ->
+# available, quarantined -> quarantined) before the assertions run — otherwise
+# "quarantined absent" could pass merely because the row is still scanning.
+_POLL_DEADLINE_SECONDS = 60
+_POLL_INTERVAL_SECONDS = 3
+
+
+def _seed(api_key: str, scenario: str, label: str) -> None:
+    """Raw HTTP seed of one simulator message carrying the run label."""
+    response = httpx.post(
+        f"{BASE_URL}/v1/simulator/inbound",
+        headers={"Authorization": f"Bearer {api_key}"},
+        json={"mailbox_id": MAILBOX, "scenario": scenario, "label": label},
+        timeout=30.0,
+    )
+    response.raise_for_status()
+    print(f"  seeded {scenario} -> {response.json().get('status')}")
+
+
+def _await_both_terminal(client: ReplyLayer, label: str) -> bool:
+    """Poll until BOTH the clean (available) and quarantined rows carrying the
+    label are present, or the deadline passes. Returns True on success."""
+    deadline = time.monotonic() + _POLL_DEADLINE_SECONDS
+    while time.monotonic() < deadline:
+        available = client.messages.list(MAILBOX, status="available", search=label).data
+        quarantined = client.messages.list(
+            MAILBOX, status="quarantined", search=label
+        ).data
+        if available and quarantined:
+            return True
+        time.sleep(_POLL_INTERVAL_SECONDS)
+    return False
+
+
+def _has_instruction_trust(metadata: dict) -> bool:
+    """True if any key named ``instruction_trust`` exists at any depth."""
+    stack = [metadata]
+    while stack:
+        current = stack.pop()
+        if isinstance(current, dict):
+            if "instruction_trust" in current:
+                return True
+            stack.extend(current.values())
+        elif isinstance(current, (list, tuple)):
+            stack.extend(current)
+    return False
+
+
+def main() -> int:
+    if not BASE_URL:
+        print(
+            "Set REPLYLAYER_BASE_URL to your STAGING API base first — this script "
+            "WRITES (seeds two simulator messages) and has no production default."
+        )
+        return 1
+    if (
+        urllib.parse.urlparse(BASE_URL).hostname == _PRODUCTION_HOST
+        and os.environ.get("REPLYLAYER_QUICKSTART_ALLOW_PRODUCTION")
+        != _ALLOW_PRODUCTION_TOKEN
+    ):
+        print(
+            f"Refusing to run against production ({BASE_URL}): this script seeds "
+            "two simulator messages into the target mailbox. To override, set "
+            f"REPLYLAYER_QUICKSTART_ALLOW_PRODUCTION={_ALLOW_PRODUCTION_TOKEN}."
+        )
+        return 1
+
+    api_key = os.environ.get("REPLYLAYER_API_KEY")
+    if not api_key:
+        print("Set REPLYLAYER_API_KEY (a staging sandbox, mailbox-bound agent key) first.")
+        return 1
+    if not MAILBOX:
+        print("Set REPLYLAYER_MAILBOX to the target mailbox id or name first.")
+        return 1
+
+    label = secrets.token_hex(4)  # 8 hex chars — unique per run, >= 3 chars.
+    print(f"ReplyLayer LangChain retrieval gate against {BASE_URL}")
+    print(f"  mailbox: {MAILBOX} | run label: {label}")
+
+    print("\n1) seed a clean and a quarantined message:")
+    _seed(api_key, "clean", label)
+    _seed(api_key, "prompt_injection_quarantined", label)
+
+    print("\n2) wait for both to reach terminal states:")
+    with ReplyLayer(api_key=api_key, base_url=BASE_URL) as client:
+        if not _await_both_terminal(client, label):
+            print("  FAIL: both terminal states not reached within the deadline.")
+            return 1
+    print("  both terminal — proceeding to assertions.")
+
+    print("\n3) loader: the quarantined message is absent, the clean one present:")
+    with ReplyLayerLoader(
+        MAILBOX, api_key=api_key, base_url=BASE_URL, direction="inbound"
+    ) as loader:
+        docs = [d for d in loader.load() if label in (d.metadata.get("subject") or "")]
+
+    subjects = [d.metadata.get("subject") for d in docs]
+    assert docs, f"loader emitted no labelled document (label={label})"
+    assert all(
+        "quarantine" not in (s or "").lower() for s in subjects
+    ), f"loader emitted a quarantined message: {subjects}"
+    clean = next((d for d in docs if "clean" in (d.metadata.get("subject") or "").lower()), None)
+    assert clean is not None, f"loader did not emit the clean message: {subjects}"
+    assert _INBOUND_HEADER_MARK in clean.page_content, "clean doc missing the inbound header"
+    assert not any(_has_instruction_trust(d.metadata) for d in docs), (
+        "an emitted document carried an instruction_trust metadata key"
+    )
+    print(f"  loader emitted {len(docs)} labelled doc(s); quarantined absent; header present.")
+
+    print("\n4) retriever: the clean message is a hit for the run label:")
+    with ReplyLayerRetriever(
+        api_key=api_key, base_url=BASE_URL, mailbox_id=MAILBOX, k=5
+    ) as retriever:
+        hits = retriever.invoke(label)
+
+    hit_subjects = [h.metadata.get("subject") for h in hits]
+    assert any(
+        "clean" in (s or "").lower() for s in hit_subjects
+    ), f"retriever did not return the clean hit: {hit_subjects}"
+    assert not any(_has_instruction_trust(h.metadata) for h in hits), (
+        "a retrieved document carried an instruction_trust metadata key"
+    )
+    print(f"  retriever returned {len(hits)} hit(s); clean message present.")
+
+    print("\nGate passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

langchain_replylayer-0.2.0/langchain_replylayer/__init__.py

@@ -0,0 +1,29 @@
+"""LangChain integrations for ReplyLayer — governed email for AI agents.
+
+Thin clients over the published ``replylayer`` SDK across LangChain's three
+integration surfaces: the ``ReplyLayerToolkit`` (agent action tools), the
+``ReplyLayerLoader`` (bulk-read an inbox as ``Document``s for indexing), and the
+``ReplyLayerRetriever`` (query -> relevant ``Document``s, re-checking state and
+redaction on every query). The loader and retriever preserve ReplyLayer's safety
+envelope rather than bypass it: they emit only settled-state messages with scan
+evidence for inbound mail, never persist a per-message trust relaxation, and
+frame every body as untrusted data. This package is versioned independently of
+the ``replylayer`` SDK and is not part of the TypeScript<->Python method-mirror
+contract.
+
+``__all__`` below is the version-contracted public API; everything else
+(``tools``, ``toolkit``, ``loader``, ``retriever``, and the underscore-prefixed
+modules) is private.
+"""
+from .loader import ReplyLayerLoader
+from .retriever import ReplyLayerRetriever
+from .toolkit import ReplyLayerToolkit
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ReplyLayerToolkit",
+    "ReplyLayerLoader",
+    "ReplyLayerRetriever",
+    "__version__",
+]

langchain_replylayer-0.2.0/langchain_replylayer/_clients.py

@@ -0,0 +1,69 @@
+"""Lazy sync+async ReplyLayer client pair with a shared lifecycle.
+
+Not a pydantic model — the toolkit, retriever, and loader each hold one as a
+private attribute. Both clients are built with ``strict_outcome=True`` and
+created lazily, so a sync-only caller never constructs the async client. The
+governed-outcome mapping the send tools rely on only applies when the server
+sees ``Prefer: outcome=strict``, which ``strict_outcome=True`` sends.
+
+``close()`` releases the sync client; ``aclose()`` releases both. After either,
+the pair is closed and any further client access raises ``RuntimeError`` — a
+reused-after-close object fails loudly instead of handing back a live client.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from replylayer import AsyncReplyLayer, ReplyLayer
+
+
+class _ClientPair:
+    def __init__(self, *, api_key: str, base_url: str, owner: str) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        # Names the owner in the closed-guard error so the message reads naturally
+        # (e.g. "ReplyLayerRetriever is closed.").
+        self._owner = owner
+        self._sync_client: Optional[ReplyLayer] = None
+        self._async_client: Optional[AsyncReplyLayer] = None
+        self._closed = False
+
+    def get_sync(self) -> ReplyLayer:
+        if self._closed:
+            raise RuntimeError(f"{self._owner} is closed.")
+        if self._sync_client is None:
+            self._sync_client = ReplyLayer(
+                api_key=self._api_key,
+                base_url=self._base_url,
+                strict_outcome=True,
+            )
+        return self._sync_client
+
+    def get_async(self) -> AsyncReplyLayer:
+        if self._closed:
+            raise RuntimeError(f"{self._owner} is closed.")
+        if self._async_client is None:
+            self._async_client = AsyncReplyLayer(
+                api_key=self._api_key,
+                base_url=self._base_url,
+                strict_outcome=True,
+            )
+        return self._async_client
+
+    def close(self) -> None:
+        """Close the sync client. Idempotent. If any async work ran, call
+        ``aclose()`` as well to close the async client."""
+        self._closed = True
+        if self._sync_client is not None:
+            self._sync_client.close()
+            self._sync_client = None
+
+    async def aclose(self) -> None:
+        """Close both clients. Idempotent."""
+        self._closed = True
+        if self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+        if self._sync_client is not None:
+            self._sync_client.close()
+            self._sync_client = None