langchain-replylayer 0.1.0__tar.gz

langchain_replylayer-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+node_modules/
+dist/
+.env
+.env.*
+*.env
+!.env.example
+# .claude is session-local (worktrees, local settings) EXCEPT the shared
+# subagent definitions, which are repo-versioned (plays with `.claude/*`
+# rather than `.claude/` so the re-include below can take effect).
+.claude/*
+!.claude/agents/
+.antigravitycli/
+*.log
+coverage/
+.turbo/
+*.tsbuildinfo
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+*.egg-info/
+.DS_Store
+# Local npm pack tarballs (W0/W4 use these for pre-publish artifact verification)
+packages/cli/*.tgz
+# CLI single-executable-app (SEA) build output — generated by the binary
+# packaging step; the release artifacts are built fresh in CI, never committed.
+packages/cli/sea-prep/
+benchmarks/cost-experiment/results.json
+benchmarks/cost-experiment/*results*.json
+
+# Stray tsc output in sdk src/ — real output lives in packages/sdk/dist/
+packages/sdk/src/**/*.js
+packages/sdk/src/**/*.js.map
+packages/sdk/src/**/*.d.ts
+packages/sdk/src/**/*.d.ts.map
+
+# Guardrail-proxy eval/opt run outputs (corpora are tracked, results are not)
+services/guardrail-proxy/eval_results*.json
+services/guardrail-proxy/opt_round*.json
+services/guardrail-proxy/oos_*_eval.json
+scripts/.smoke-byoes-fixture.env
+scripts/.smoke-byoes-extras.env
+
+# Local-only archive of stray/orphaned files we want off the working tree
+# but preserved on disk for forensics. Never committed.
+archive/
+
+# Operational briefings — local operator notes, never committed.
+docs/briefings/
+plans/fault-briefings/
+
+# Allow eval-baseline logs as audit-trail evidence
+!services/guardrail-proxy/eval_baselines/*.log
+
+# Allow stress-test scenario evidence (stdout.log + proxy-log-excerpt.log)
+# under audits/ — these are signed-verdict-anchored evidence per
+# plans/granite-guardian-failover-saturation-stress-test.md §11.
+!audits/**/*.log
+uat-grading-results*.json
+
+# Scanner eval run outputs (corpora are tracked, results are not)
+packages/scanner/src/eval/*-results.json

langchain_replylayer-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: langchain-replylayer
+Version: 0.1.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
+Keywords: agent,ai,email,langchain,replylayer,toolkit,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2.0,>=0.3.0
+Requires-Dist: replylayer>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: langchain-openai; extra == 'examples'
+Requires-Dist: langchain>=1.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# langchain-replylayer
+
+LangChain tools 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".
+
+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.
+
+> 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>.
+
+## Install
+
+```bash
+pip install langchain-replylayer
+```
+
+Requires Python 3.10+. The optional real-agent walkthrough in `examples/langchain_quickstart.py` needs the extra:
+
+```bash
+pip install "langchain-replylayer[examples]"
+```
+
+## Quickstart
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+# api_key falls back to the REPLYLAYER_API_KEY environment variable.
+with ReplyLayerToolkit(default_mailbox_id="support") as toolkit:
+    tools = {tool.name: tool for tool in toolkit.get_tools()}
+
+    result = tools["send_email"].invoke(
+        {"to": "user@example.com", "subject": "Hi", "body": "Hello from my agent."}
+    )
+
+    if result["status"] == "sent":
+        print("accepted for delivery:", result["message_id"])
+    elif result["status"] == "rejected_by_policy":
+        print("a send gate refused it:", result["code"])
+    else:
+        print("outcome:", result["status"])
+```
+
+Async is symmetric — every tool ships both a sync `invoke` and an async `ainvoke`:
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+async def main():
+    async with ReplyLayerToolkit(default_mailbox_id="support") as toolkit:
+        tools = {tool.name: tool for tool in toolkit.get_tools()}
+        result = await tools["check_send_quota"].ainvoke({})
+        print(result["quota"]["sends_remaining"])
+```
+
+## The six tools
+
+Wire them into an agent with `toolkit.get_tools()`. Each returns a JSON-serializable dict with a `status` field to branch on; a governed outcome is never raised.
+
+| Tool | What it does | Result |
+|------|--------------|--------|
+| `send_email` | Send a new outbound email from a mailbox. | `{status, message_id?}` — `status` is one of `sent`, `rejected_by_policy`, `rejected`, `held_for_human_review`, `retry_later`, `rate_limited`, `error`. |
+| `reply_to_email` | Reply to an inbound message, continuing its thread. | Same `status` set as `send_email`. |
+| `list_messages` | List recent messages (cursor-paginated). | `{status: "ok", messages: [...], has_more, cursor, untrusted_content: true}`. Each row carries `id`, `sender`, `subject`, `state`, `created_at`. |
+| `read_message` | Read one message in full. | `{status: "ok", id, sender, subject, state, created_at, body, body_format, body_truncated, agent_safety_context, untrusted_content: true}` — or `{status: "not_found", recheck: false}`. |
+| `wait_for_message` | Long-poll a mailbox for the next message (≤30s). | `{status: "ok", message, untrusted_content: true}` — `message` is a compact row or `null` if none arrived. |
+| `check_send_quota` | Preflight the remaining daily send budget. | `{status: "ok", quota}` — `quota.sends_remaining`, `quota.reset_at`, and `quota.today.limit`. |
+
+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.
+
+## Governance outcomes
+
+The tools translate every ReplyLayer outcome into a value an agent can act on. The full `status` vocabulary:
+
+| `status` | Tools | Meaning |
+|----------|-------|---------|
+| `sent` | send, reply | Accepted for delivery. Carries `message_id`. Not a safety judgment. |
+| `rejected_by_policy` | send, reply | A pre-admission gate refused the recipient **before any bytes left**: not on the allowlist, agent-contained, on your do-not-contact (suppression) list — including a platform-scoped hard-bounce hit — a failed recipient-verification/MX check, a sandbox budget/expiry limit, or a billing gate. Carries `code`, a human-readable `detail`, and `agent_instructions` when the server supplied them. Branch on `code`; don't retry unchanged. |
+| `rejected` | send, reply | Post-admission **content** block (terminal). Carries `code` and `agent_instructions`. Edit the content or escalate — never resend the same body. |
+| `held_for_human_review` | send, reply | The send was queued for human approval before it can go out. Carries `message_id` and `agent_instructions`. Report "awaiting approval"; do not treat it as a content error to fix by editing. |
+| `retry_later` | send, reply | A transient infrastructure hold — the content was never judged. Carries `code`, `retry_after`, and `agent_instructions`. Retry after `retry_after` seconds; back off on repeats. |
+| `rate_limited` | send, reply | A send limit was hit. Read `variant` (see below). |
+| `error` | all | Another client-side problem the agent can see but that is not a governed policy outcome. Carries `code` and `details`. No retry is implied — fix the inputs. |
+| `not_found` | read | The message id is unknown or not visible to this key. `recheck: false` — the wire cannot distinguish "not yet available" from "wrong id", so any recheck loop belongs to your workflow. |
+| `ok` | list, read, wait, quota | The read succeeded; the payload follows. |
+
+`rate_limited` carries a `variant` so the agent knows which limit it hit:
+
+| `variant` | Fields | Meaning |
+|-----------|--------|---------|
+| `daily_budget` | `daily_limit`, `sends_remaining`, `reset_at` | The daily send budget is exhausted. Wait until `reset_at`. |
+| `new_account_warmup` | `retry_after_seconds` | A new paid account's warm-up throttle. |
+| `short_window` | `retry_after` | A generic short-window throttle. `retry_after` may be `null` when the server sent no hint. |
+
+## Error policy — what each tool returns vs raises
+
+The mapping mirrors where the server enforces each gate. A refusal an agent can act on comes back as a dict; a caller-misconfiguration or infrastructure fault is raised.
+
+| Tool | Returned as a governed dict (never raised) | Raised |
+|------|--------------------------------------------|--------|
+| `send_email`, `reply_to_email` | `rejected_by_policy` (the enumerated send-gate codes), `rejected`, `held_for_human_review`, `retry_later`, `rate_limited`, and `error` for any other client-side 4xx — a non-allowlisted `403`/`422`, a content-shape `400`, or a bad-id `404` | `AuthenticationError` (401) and genuinely unexpected `5xx` |
+| `list_messages`, `wait_for_message` | `error` for malformed input (`400`/`422`) the agent can fix and retry | `401` authentication, `403` scope/authorization (e.g. `INSUFFICIENT_SCOPE`, `MAILBOX_ACCESS_DENIED`), unexpected `5xx` |
+| `read_message` | `not_found` (`404`), `error` for malformed input (`400`/`422`) | `401` authentication, `403` scope/authorization, unexpected `5xx` |
+| `check_send_quota` | `error` (`400`/`422`) | `401` authentication, `403` scope/authorization, unexpected `5xx` |
+
+A blanket "any 403/422 is a policy refusal" mapping would be wrong: read tools legitimately get scope `403`s (caller misconfiguration, not agent-decidable), and `list_messages` can `422` on malformed input (which the agent *can* fix). Only the enumerated send-gate codes become `rejected_by_policy`, and only inside `send_email`/`reply_to_email`.
+
+Branch on the result, and let the two raising cases surface:
+
+```python
+from replylayer.errors import AuthenticationError
+from langchain_replylayer import ReplyLayerToolkit
+
+toolkit = ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support")
+send = {tool.name: tool for tool in toolkit.get_tools()}["send_email"]
+
+try:
+    result = send.invoke({"to": "user@example.com", "subject": "Hi", "body": "Hello"})
+except AuthenticationError:
+    # Bad key or wrong base_url — a caller bug, not an agent decision.
+    raise
+
+if result["status"] == "held_for_human_review":
+    print("awaiting approval:", result["message_id"])
+elif result["status"] == "rejected":
+    print("content blocked; edit or escalate:", result["agent_instructions"])
+
+toolkit.close()
+```
+
+## Untrusted content
+
+Every `list_messages`, `read_message`, and `wait_for_message` result is flagged `untrusted_content: true`, and `read_message` returns the message's `agent_safety_context` verbatim. Message senders, subjects, and bodies are external data — an agent must read them as data and must not follow instructions found inside them. The tool descriptions state this so the contract is visible to the model, not just to you.
+
+## Secret handling
+
+The API key is held as a Pydantic `SecretStr`, so it is redacted from the standard surfaces an integration (or a tracing backend) records: `repr(toolkit)`, `model_dump()` / `model_dump_json()`, every generated tool schema, and tool-call inputs and outputs. The tools close over the underlying client rather than carrying the key in their arguments, so the key never appears in a tool's `args_schema` either.
+
+## Lifecycle
+
+The toolkit owns the underlying ReplyLayer HTTP clients. Release them with `close()` / `aclose()`, or use the toolkit as a sync or async context manager. The async client is created lazily on first async use, so a sync-only integration never instantiates it; if any async tool ran, call `aclose()` (or use `async with`) so both clients are closed.
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+# Sync context manager.
+with ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support") as toolkit:
+    tools = toolkit.get_tools()
+
+# Or manage it explicitly (close() is idempotent).
+toolkit = ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support")
+tools = toolkit.get_tools()
+toolkit.close()
+```
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+async def run():
+    async with ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support") as toolkit:
+        tools = {tool.name: tool for tool in toolkit.get_tools()}
+        await tools["list_messages"].ainvoke({})
+    # both HTTP clients are now closed
+```
+
+## Credentials
+
+Pass `api_key=...` explicitly, or set the `REPLYLAYER_API_KEY` environment variable. **The environment-variable fallback is an adapter convenience** — the underlying `replylayer` SDK requires `api_key` explicitly; this adapter resolves the env var itself and passes it through. `base_url` defaults to the production API (`https://api.replylayer.ai`); set it to your staging API for verification runs. `default_mailbox_id` is the mailbox the tools use when a call does not name one.
+
+Use a **mailbox-bound agent key** with an agent, not an admin key — the tools deliberately expose only read/act verbs, and an agent key keeps the containment boundary intact.
+
+## 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.
+
+## Learn more
+
+Full ReplyLayer documentation, including the API reference and the security model: <https://replylayer.ai/docs>.
+
+## License
+
+MIT

langchain_replylayer-0.1.0/README.md

@@ -0,0 +1,182 @@
+# langchain-replylayer
+
+LangChain tools 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".
+
+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.
+
+> 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>.
+
+## Install
+
+```bash
+pip install langchain-replylayer
+```
+
+Requires Python 3.10+. The optional real-agent walkthrough in `examples/langchain_quickstart.py` needs the extra:
+
+```bash
+pip install "langchain-replylayer[examples]"
+```
+
+## Quickstart
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+# api_key falls back to the REPLYLAYER_API_KEY environment variable.
+with ReplyLayerToolkit(default_mailbox_id="support") as toolkit:
+    tools = {tool.name: tool for tool in toolkit.get_tools()}
+
+    result = tools["send_email"].invoke(
+        {"to": "user@example.com", "subject": "Hi", "body": "Hello from my agent."}
+    )
+
+    if result["status"] == "sent":
+        print("accepted for delivery:", result["message_id"])
+    elif result["status"] == "rejected_by_policy":
+        print("a send gate refused it:", result["code"])
+    else:
+        print("outcome:", result["status"])
+```
+
+Async is symmetric — every tool ships both a sync `invoke` and an async `ainvoke`:
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+async def main():
+    async with ReplyLayerToolkit(default_mailbox_id="support") as toolkit:
+        tools = {tool.name: tool for tool in toolkit.get_tools()}
+        result = await tools["check_send_quota"].ainvoke({})
+        print(result["quota"]["sends_remaining"])
+```
+
+## The six tools
+
+Wire them into an agent with `toolkit.get_tools()`. Each returns a JSON-serializable dict with a `status` field to branch on; a governed outcome is never raised.
+
+| Tool | What it does | Result |
+|------|--------------|--------|
+| `send_email` | Send a new outbound email from a mailbox. | `{status, message_id?}` — `status` is one of `sent`, `rejected_by_policy`, `rejected`, `held_for_human_review`, `retry_later`, `rate_limited`, `error`. |
+| `reply_to_email` | Reply to an inbound message, continuing its thread. | Same `status` set as `send_email`. |
+| `list_messages` | List recent messages (cursor-paginated). | `{status: "ok", messages: [...], has_more, cursor, untrusted_content: true}`. Each row carries `id`, `sender`, `subject`, `state`, `created_at`. |
+| `read_message` | Read one message in full. | `{status: "ok", id, sender, subject, state, created_at, body, body_format, body_truncated, agent_safety_context, untrusted_content: true}` — or `{status: "not_found", recheck: false}`. |
+| `wait_for_message` | Long-poll a mailbox for the next message (≤30s). | `{status: "ok", message, untrusted_content: true}` — `message` is a compact row or `null` if none arrived. |
+| `check_send_quota` | Preflight the remaining daily send budget. | `{status: "ok", quota}` — `quota.sends_remaining`, `quota.reset_at`, and `quota.today.limit`. |
+
+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.
+
+## Governance outcomes
+
+The tools translate every ReplyLayer outcome into a value an agent can act on. The full `status` vocabulary:
+
+| `status` | Tools | Meaning |
+|----------|-------|---------|
+| `sent` | send, reply | Accepted for delivery. Carries `message_id`. Not a safety judgment. |
+| `rejected_by_policy` | send, reply | A pre-admission gate refused the recipient **before any bytes left**: not on the allowlist, agent-contained, on your do-not-contact (suppression) list — including a platform-scoped hard-bounce hit — a failed recipient-verification/MX check, a sandbox budget/expiry limit, or a billing gate. Carries `code`, a human-readable `detail`, and `agent_instructions` when the server supplied them. Branch on `code`; don't retry unchanged. |
+| `rejected` | send, reply | Post-admission **content** block (terminal). Carries `code` and `agent_instructions`. Edit the content or escalate — never resend the same body. |
+| `held_for_human_review` | send, reply | The send was queued for human approval before it can go out. Carries `message_id` and `agent_instructions`. Report "awaiting approval"; do not treat it as a content error to fix by editing. |
+| `retry_later` | send, reply | A transient infrastructure hold — the content was never judged. Carries `code`, `retry_after`, and `agent_instructions`. Retry after `retry_after` seconds; back off on repeats. |
+| `rate_limited` | send, reply | A send limit was hit. Read `variant` (see below). |
+| `error` | all | Another client-side problem the agent can see but that is not a governed policy outcome. Carries `code` and `details`. No retry is implied — fix the inputs. |
+| `not_found` | read | The message id is unknown or not visible to this key. `recheck: false` — the wire cannot distinguish "not yet available" from "wrong id", so any recheck loop belongs to your workflow. |
+| `ok` | list, read, wait, quota | The read succeeded; the payload follows. |
+
+`rate_limited` carries a `variant` so the agent knows which limit it hit:
+
+| `variant` | Fields | Meaning |
+|-----------|--------|---------|
+| `daily_budget` | `daily_limit`, `sends_remaining`, `reset_at` | The daily send budget is exhausted. Wait until `reset_at`. |
+| `new_account_warmup` | `retry_after_seconds` | A new paid account's warm-up throttle. |
+| `short_window` | `retry_after` | A generic short-window throttle. `retry_after` may be `null` when the server sent no hint. |
+
+## Error policy — what each tool returns vs raises
+
+The mapping mirrors where the server enforces each gate. A refusal an agent can act on comes back as a dict; a caller-misconfiguration or infrastructure fault is raised.
+
+| Tool | Returned as a governed dict (never raised) | Raised |
+|------|--------------------------------------------|--------|
+| `send_email`, `reply_to_email` | `rejected_by_policy` (the enumerated send-gate codes), `rejected`, `held_for_human_review`, `retry_later`, `rate_limited`, and `error` for any other client-side 4xx — a non-allowlisted `403`/`422`, a content-shape `400`, or a bad-id `404` | `AuthenticationError` (401) and genuinely unexpected `5xx` |
+| `list_messages`, `wait_for_message` | `error` for malformed input (`400`/`422`) the agent can fix and retry | `401` authentication, `403` scope/authorization (e.g. `INSUFFICIENT_SCOPE`, `MAILBOX_ACCESS_DENIED`), unexpected `5xx` |
+| `read_message` | `not_found` (`404`), `error` for malformed input (`400`/`422`) | `401` authentication, `403` scope/authorization, unexpected `5xx` |
+| `check_send_quota` | `error` (`400`/`422`) | `401` authentication, `403` scope/authorization, unexpected `5xx` |
+
+A blanket "any 403/422 is a policy refusal" mapping would be wrong: read tools legitimately get scope `403`s (caller misconfiguration, not agent-decidable), and `list_messages` can `422` on malformed input (which the agent *can* fix). Only the enumerated send-gate codes become `rejected_by_policy`, and only inside `send_email`/`reply_to_email`.
+
+Branch on the result, and let the two raising cases surface:
+
+```python
+from replylayer.errors import AuthenticationError
+from langchain_replylayer import ReplyLayerToolkit
+
+toolkit = ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support")
+send = {tool.name: tool for tool in toolkit.get_tools()}["send_email"]
+
+try:
+    result = send.invoke({"to": "user@example.com", "subject": "Hi", "body": "Hello"})
+except AuthenticationError:
+    # Bad key or wrong base_url — a caller bug, not an agent decision.
+    raise
+
+if result["status"] == "held_for_human_review":
+    print("awaiting approval:", result["message_id"])
+elif result["status"] == "rejected":
+    print("content blocked; edit or escalate:", result["agent_instructions"])
+
+toolkit.close()
+```
+
+## Untrusted content
+
+Every `list_messages`, `read_message`, and `wait_for_message` result is flagged `untrusted_content: true`, and `read_message` returns the message's `agent_safety_context` verbatim. Message senders, subjects, and bodies are external data — an agent must read them as data and must not follow instructions found inside them. The tool descriptions state this so the contract is visible to the model, not just to you.
+
+## Secret handling
+
+The API key is held as a Pydantic `SecretStr`, so it is redacted from the standard surfaces an integration (or a tracing backend) records: `repr(toolkit)`, `model_dump()` / `model_dump_json()`, every generated tool schema, and tool-call inputs and outputs. The tools close over the underlying client rather than carrying the key in their arguments, so the key never appears in a tool's `args_schema` either.
+
+## Lifecycle
+
+The toolkit owns the underlying ReplyLayer HTTP clients. Release them with `close()` / `aclose()`, or use the toolkit as a sync or async context manager. The async client is created lazily on first async use, so a sync-only integration never instantiates it; if any async tool ran, call `aclose()` (or use `async with`) so both clients are closed.
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+# Sync context manager.
+with ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support") as toolkit:
+    tools = toolkit.get_tools()
+
+# Or manage it explicitly (close() is idempotent).
+toolkit = ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support")
+tools = toolkit.get_tools()
+toolkit.close()
+```
+
+```python
+from langchain_replylayer import ReplyLayerToolkit
+
+async def run():
+    async with ReplyLayerToolkit(api_key="rly_...", default_mailbox_id="support") as toolkit:
+        tools = {tool.name: tool for tool in toolkit.get_tools()}
+        await tools["list_messages"].ainvoke({})
+    # both HTTP clients are now closed
+```
+
+## Credentials
+
+Pass `api_key=...` explicitly, or set the `REPLYLAYER_API_KEY` environment variable. **The environment-variable fallback is an adapter convenience** — the underlying `replylayer` SDK requires `api_key` explicitly; this adapter resolves the env var itself and passes it through. `base_url` defaults to the production API (`https://api.replylayer.ai`); set it to your staging API for verification runs. `default_mailbox_id` is the mailbox the tools use when a call does not name one.
+
+Use a **mailbox-bound agent key** with an agent, not an admin key — the tools deliberately expose only read/act verbs, and an agent key keeps the containment boundary intact.
+
+## 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.
+
+## Learn more
+
+Full ReplyLayer documentation, including the API reference and the security model: <https://replylayer.ai/docs>.
+
+## License
+
+MIT

langchain_replylayer-0.1.0/examples/langchain_quickstart.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""ReplyLayer + LangChain quickstart — governed email tools for an agent.
+
+Run this against a STAGING sandbox with a mailbox-bound *agent* API key, never a
+production or admin key: the tools send real email through every ReplyLayer gate,
+and the point of the walkthrough is to watch those gates fire. Scanning reduces
+risk; a clean verdict is not a trust verdict.
+
+Environment
+-----------
+REPLYLAYER_API_KEY   (required)  a staging sandbox, mailbox-bound agent key.
+REPLYLAYER_MAILBOX   (required)  the sending mailbox id or name.
+REPLYLAYER_BASE_URL  (optional)  point this at your STAGING API for a verification
+                                 run; defaults to the documented production base.
+REPLYLAYER_TO        (optional)  recipient to try; defaults to an address that is
+                                 (deliberately) unlikely to be on the allowlist,
+                                 so the refusal branch actually runs.
+OPENAI_API_KEY       (optional)  used only by the final, optional real-agent
+                                 section, which needs the `[examples]` extra.
+
+    pip install "langchain-replylayer"            # the six tools
+    pip install "langchain-replylayer[examples]"  # + the real-agent section
+
+    python examples/langchain_quickstart.py
+"""
+from __future__ import annotations
+
+import os
+
+from replylayer.errors import AuthenticationError
+
+from langchain_replylayer import ReplyLayerToolkit
+
+# base_url is parameterized — set REPLYLAYER_BASE_URL to your staging API for a
+# verification run; it defaults to the documented production base.
+BASE_URL = os.environ.get("REPLYLAYER_BASE_URL", "https://api.replylayer.ai")
+MAILBOX = os.environ.get("REPLYLAYER_MAILBOX", "")
+TO = os.environ.get("REPLYLAYER_TO", "not-on-your-allowlist@example.com")
+
+# A recent-message scan is bounded — never walk the whole mailbox.
+MAX_ROWS_TO_SCAN = 5
+
+
+def demo_send(tools: dict) -> None:
+    """Send once and branch on the governed outcome instead of catching an error.
+
+    A brand-new sandbox mailbox defaults to `allowlist` mode, so an off-list
+    recipient is refused BEFORE any bytes leave — surfaced as
+    `{status: "rejected_by_policy", code: "RECIPIENT_NOT_ON_ALLOWLIST"}`, a plain
+    dict the agent can branch on, not an exception.
+    """
+    result = tools["send_email"].invoke(
+        {"to": TO, "subject": "Hello from my agent", "body": "Hi there — this is a test send."}
+    )
+    status = result["status"]
+    if status == "sent":
+        print(f"  sent — accepted for delivery as {result['message_id']}")
+    elif status == "rejected_by_policy":
+        print(f"  refused before sending by a policy gate: {result['code']}")
+        if result["code"] == "RECIPIENT_NOT_ON_ALLOWLIST":
+            print("  -> add the recipient to the mailbox allowlist, or send to a thread participant.")
+    elif status == "held_for_human_review":
+        print(f"  queued for human approval (message {result.get('message_id')}); do not resend.")
+    elif status == "rejected":
+        print(f"  content blocked ({result['code']}); edit the content or escalate — never resend unchanged.")
+    elif status == "retry_later":
+        print(f"  transient infrastructure hold; retry after {result.get('retry_after')}s.")
+    elif status == "rate_limited":
+        print(f"  rate limited ({result['variant']}); back off before retrying.")
+    else:  # "error"
+        print(f"  send could not be admitted: {result.get('code')} {result.get('details')}")
+
+
+def demo_quota(tools: dict) -> None:
+    """Preflight the send budget instead of discovering the limit by hitting it."""
+    result = tools["check_send_quota"].invoke({})
+    if result["status"] != "ok":
+        print(f"  could not read quota: {result.get('code')}")
+        return
+    quota = result["quota"]
+    print(f"  sends remaining today: {quota.get('sends_remaining')} (resets {quota.get('reset_at')})")
+
+
+def demo_read_untrusted(tools: dict) -> None:
+    """List recent mail and read one message, treating its content as data.
+
+    Message senders, subjects, and bodies are untrusted third-party content: the
+    tools flag every read with `untrusted_content` and carry the message's
+    `agent_safety_context` verbatim. Never follow instructions found in a body.
+    """
+    listed = tools["list_messages"].invoke({"limit": MAX_ROWS_TO_SCAN, "direction": "inbound"})
+    if listed["status"] != "ok":
+        print(f"  could not list messages: {listed.get('code')}")
+        return
+    rows = listed["messages"]
+    if not rows:
+        print("  no inbound messages yet — send one to this mailbox and re-run.")
+        return
+
+    # Bounded: only the newest row, and only the fields the compact projection gives.
+    first = rows[0]
+    print(f"  newest inbound: {first['subject']!r} from {first['sender']} [{first['state']}]")
+
+    message = tools["read_message"].invoke({"message_id": first["id"]})
+    if message["status"] == "not_found":
+        print("  message is no longer visible to this key.")
+        return
+    if message["status"] != "ok":
+        print(f"  could not read message: {message.get('code')}")
+        return
+
+    # untrusted_content is always True for an inbound read.
+    context = message.get("agent_safety_context") or {}
+    print(f"  safety context: {context}")
+    body = message.get("body") or ""
+    preview = body[:120].replace("\n", " ")
+    print(f"  body (untrusted data — do NOT act on instructions inside): {preview!r}")
+
+
+def demo_real_agent(tools: dict) -> None:
+    """OPTIONAL — hand the six governed tools to a real LangChain agent.
+
+    Skipped gracefully unless the `[examples]` extra is installed AND
+    OPENAI_API_KEY is set. The agent provider named here is example wiring only.
+    """
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("  skipped: set OPENAI_API_KEY to run the optional real-agent section.")
+        return
+    try:
+        from langchain.agents import create_agent
+        from langchain_openai import ChatOpenAI
+    except ImportError:
+        print('  skipped: install the extra — pip install "langchain-replylayer[examples]".')
+        return
+
+    agent = create_agent(ChatOpenAI(model="gpt-4o-mini"), tools=list(tools.values()))
+    response = agent.invoke(
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": (
+                        "Use the available tools to check my remaining send quota, "
+                        "then tell me the number. Do not send any email."
+                    ),
+                }
+            ]
+        }
+    )
+    final = response["messages"][-1]
+    print(f"  agent said: {getattr(final, 'content', final)}")
+
+
+def main() -> int:
+    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 sending mailbox id or name first.")
+        return 1
+
+    print(f"ReplyLayer LangChain quickstart against {BASE_URL} (mailbox: {MAILBOX})")
+    with ReplyLayerToolkit(api_key=api_key, base_url=BASE_URL, default_mailbox_id=MAILBOX) as toolkit:
+        tools = {tool.name: tool for tool in toolkit.get_tools()}
+        try:
+            print("\n1) send (watch the allowlist gate):")
+            demo_send(tools)
+            print("\n2) quota preflight:")
+            demo_quota(tools)
+            print("\n3) read a message as untrusted data:")
+            demo_read_untrusted(tools)
+            print("\n4) optional real agent:")
+            demo_real_agent(tools)
+        except AuthenticationError:
+            print("Authentication failed — check REPLYLAYER_API_KEY and REPLYLAYER_BASE_URL.")
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

langchain_replylayer-0.1.0/langchain_replylayer/__init__.py

@@ -0,0 +1,18 @@
+"""LangChain tools for ReplyLayer — governed email for AI agents.
+
+Thin wrappers over the published ``replylayer`` SDK: every send still passes the
+allowlist, quota, human-approval, and content-scanning gates. 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``, ``_governance``) is private.
+"""
+from .toolkit import ReplyLayerToolkit
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ReplyLayerToolkit",
+    "__version__",
+]