langchain-rine 0.3.0__tar.gz

langchain_rine-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+# uv pip-installs into the rig's named-volume venv; the package is hatchling-built and
+# not uv-lock-managed (matches the rine-crewai precedent — no committed lockfile).
+uv.lock
+.rine/
+# Live-E2E secrets (Together.ai key etc.) — never commit
+.e2e.env

langchain_rine-0.3.0/Dockerfile

@@ -0,0 +1,37 @@
+# Base image for the CONTAINED langchain-rine dev/test rig.
+# The LangChain tree (langchain, langchain-core, langgraph, langchain-openai,
+# langchain-tests, ...) installs INSIDE the container only (into a venv on a named volume;
+# see ../compose.langchain.yml). NOTHING langchain-related is ever installed on the host —
+# same rule as the crewai / OpenClaw rigs. The local rine-sdk and rine-langchain are
+# bind-mounted and installed editable, so the rig consumes UNRELEASED SDK fixes (Phase-0).
+FROM python:3.12-slim
+
+# git for any VCS deps; build-essential for native wheels pulled by the LangChain tree.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      git build-essential ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# uv: fast resolver/installer; populates the named-volume venv on first run.
+RUN pip install --no-cache-dir uv
+
+# The venv lives on a NAMED VOLUME (mounted at /opt/venv in compose) so heavy deps are
+# cached across runs and never land on the host tree. Activate it for every command.
+ENV VENV=/opt/venv \
+    PATH="/opt/venv/bin:$PATH" \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    CI=true
+
+WORKDIR /work/rine-langchain
+
+# Idempotent bootstrap: ensure the named-volume venv exists and the bind-mounted
+# rine-sdk + langchain-rine[dev] are installed editable into it, then exec the command.
+# `langchain-rine[dev]` pulls langchain-core/langgraph/langchain-openai/langchain-tests;
+# `rine` resolves to the bind-mounted ./rine-sdk (editable) — overriding the published
+# floor for dev/tests.
+COPY entrypoint.sh /usr/local/bin/rig-entrypoint
+RUN chmod +x /usr/local/bin/rig-entrypoint
+
+ENTRYPOINT ["rig-entrypoint"]
+CMD ["python", "-c", "import importlib.metadata as m; import langchain_rine, langgraph; print('langchain_rine', langchain_rine.__version__, '/ langgraph', m.version('langgraph'))"]

langchain_rine-0.3.0/LANGCHAIN.md

@@ -0,0 +1,195 @@
+# langchain-rine — rules for AI assistants
+
+> Drop-in rules file (CLAUDE.md / `.cursorrules` shape) for wiring the rine network into a
+> **LangChain 1.0 / LangGraph** agent. Also published at `docs.rine.network/langchain.md`.
+> `langchain-rine` is a thin adapter over the published [`rine`](https://pypi.org/project/rine/)
+> Python SDK: a pydantic `args_schema` → a `rine` client method → a human-readable string.
+> The SDK owns all crypto, HTTP, config resolution, and types — never reimplement them.
+
+## Wire it in one shot
+
+Use the **LangChain 1.0** entry point `create_agent` (NOT the deprecated `create_react_agent`).
+Pins: `langchain-core 1.4.4`, `langchain 1.3.7`, `langgraph 1.2.4`, `langchain-openai 1.3.0`,
+`rine 0.2.2`, Python ≥ 3.11. Examples are async-native (`ainvoke` → the tools' `_arun` path).
+
+```python
+from langchain.agents import create_agent          # langchain 1.0 — NOT create_react_agent
+from langgraph.checkpoint.memory import InMemorySaver
+from langchain_rine import RineToolkit
+
+# All 11 tools share ONE lazily-built client. include=["messaging","discovery"] curates a subset.
+tools = RineToolkit().get_tools()
+
+agent = create_agent(
+    "openai:gpt-4o-mini",
+    tools=tools,
+    system_prompt="You are an agent on the rine network. Every send is a real, irreversible, "
+                  "end-to-end-encrypted network message.",
+    checkpointer=InMemorySaver(),                   # required for multi-turn rine coordination
+)
+
+result = await agent.ainvoke(
+    {"messages": [{"role": "user", "content": "check my rine inbox and summarize it"}]},
+    config={"configurable": {"thread_id": "demo"}},
+)
+```
+
+Attach individual classes when you want a tight surface (the safe default for mutating agents):
+
+```python
+from langchain_rine import RineDiscoverTool, RineSendAndWaitTool, RineCheckInboxTool, RineReplyTool
+agent = create_agent("openai:gpt-4o-mini",
+                     tools=[RineDiscoverTool(), RineSendAndWaitTool(), RineCheckInboxTool(), RineReplyTool()])
+```
+
+## The 11 tools (names are stable; the descriptions ARE the AI-DX)
+
+- **Messaging:** `rine_send` (1:1 or group; **mutating**), `rine_send_and_wait` (delegate-and-await,
+  **1:1 only**, **mutating**), `rine_check_inbox` (poll new mail + ack), `rine_read`, `rine_reply`
+  (**mutating**).
+- **Discovery (no auth):** `rine_discover`, `rine_inspect`.
+- **Groups (sender-key E2EE):** `rine_group_create` (**mutating**), `rine_group_invite` (**mutating**),
+  `rine_group_remove` (**mutating**), `rine_group_inspect`.
+
+## Imperatives — the rine footguns, stated as rules
+
+1. **Onboard ONCE for keys — it is not a tool.** Run
+   `python -m langchain_rine.onboard --email you@example.com --org-slug my-org --org-name "My Org" --agent-name worker`
+   at setup time. It registers an org via a ~30–60s proof-of-work and writes credentials + keys
+   into the config dir. A PoW does not belong inside an LLM turn — NEVER expose onboarding as a tool.
+2. **Env creds alone authenticate but CANNOT decrypt.** `RINE_CLIENT_ID` + `RINE_CLIENT_SECRET`
+   get you authenticated, but E2EE decrypt/sign need the **private keys on disk** at
+   `config_dir/keys/<agent>/{signing.key,encryption.key}` (written by `onboard` / `create_agent` /
+   `rotate_keys`). "Just set two env vars" is half-true unless the keys are present. There is **no
+   `RINE_TOKEN`** — that is a Node/MCP-only concept; do not look for it.
+3. **Plaintext is a JSON string `{"text": ...}`.** Every send wraps the body as `{"text": body}`;
+   the renderers unwrap the `text` field so the model never sees raw JSON. Do not double-wrap, and
+   do not hand the model `encrypted_payload` — the raw ciphertext is **never** read in any renderer.
+4. **MLS / PQ-hybrid is UNREADABLE in Python.** The Python SDK has no MLS engine. An MLS or
+   PQ-hybrid message comes back with `plaintext=None` and `decrypt_error` set, rendered
+   `[unreadable] {err}`; a send to an MLS group raises `MlsUnsupportedError` (a readable tool
+   string), never silent. **Always check `decrypt_error` / `verified` before trusting content.**
+   Run `rine_group_inspect` first — it prints `[OK] sender-key …` (readable) or `[WARN] MLS group …`
+   (this Python agent cannot read or post). To collaborate cross-stack, have your agent create the
+   group (it will be sender-key) or have the TS side create it with MLS disabled.
+5. **NEVER expose admin / destructive operations as tools.** `onboard`, `erase_org`, `export_org`,
+   and streaming (`stream`) are SDK-level operations, not agent tools. Keep them out of the toolkit.
+6. **Group send is `to="#group@org"` on `rine_send` — there is NO separate group-send tool.** A
+   `#`-prefixed target routes `rine_send` through the sender-key path; group mail arrives in
+   `rine_check_inbox` / `rine_read` with its group context shown. `rine_send_and_wait` rejects a
+   `#` target up front ("1:1 only") and makes no network call.
+7. **Errors are readable strings, not exceptions.** Each tool wraps the SDK call and returns a
+   `_format_error` string (auth / not-found / rate-limit / MLS / API) so the agent retries or
+   continues rather than crashing. Treat a tool result that starts with `Rine auth failed`,
+   `Not found:`, `Rate-limited`, or `This group uses MLS …` as an actionable signal, not output.
+
+## Lifecycle bridge (native beats MCP)
+
+`RineCallbackHandler` sends a best-effort rine message on selected LangChain lifecycle events — a
+hook an out-of-process MCP server physically cannot reach. Opt-in by instantiation; the client is
+built lazily on the first fired event; a send failure is swallowed and never crashes the run.
+
+```python
+from langchain_rine import RineCallbackHandler
+handler = RineCallbackHandler(to="ops@acme", on=("agent_finish", "chain_error"))
+await agent.ainvoke({...}, config={"callbacks": [handler]})
+```
+
+## content_and_artifact / rich returns — leave OFF (langchain#29874)
+
+Tools return plain **strings** by default (`rich_returns=False`). Do **not** turn on
+`response_format="content_and_artifact"`: on the pinned `langchain-core 1.4.4` the still-live
+[langchain#29874](https://github.com/langchain-ai/langchain/issues/29874) bug means a ToolCall with
+`id=None` silently degrades to content-only — the artifact and `tool_call_id` are **dropped**. The
+string default is the conformance-safe path; keep it.
+
+## Receive-while-idle (Tiers 1–2 + Tier-3 idle wake)
+
+- **Tier 1 — poll-on-turn (now):** call `rine_check_inbox` inside the agent loop. Zero new infra.
+- **Tier 2 — delegate-and-await (now):** `rine_send_and_wait` blocks ≤ 300s for a 1:1 reply — the
+  single most compelling tool in a multi-agent graph. Mind your agent/graph timeouts; a `#group`
+  target raises before any request.
+
+## Tier-3 — true idle wake-up for LangGraph (v0.3, exactly-once)
+
+A `RineThreadResumer` wakes a **paused, durably-checkpointed** LangGraph thread when the peer's
+reply lands. Positioning: *"handoffs that survive process and org boundaries"* — complementary to
+in-process `langgraph-swarm`, not competing.
+
+- **Install the extra:** `pip install langchain-rine[inbound]`. LangGraph is NOT pulled by the base
+  tools; `import langchain_rine` (the 11 tools) never needs it. Importing `langchain_rine.inbound` is
+  the opt-in. The extra pulls `langgraph`, `langgraph-checkpoint-sqlite`, and `aiosqlite` (the async
+  thread-map store); the sync store imports aiosqlite lazily, so a sync-only run never needs it.
+- **Wire it (one block):** a **durable** checkpointer + a durable thread-map + the resumer + a
+  driver. The CALLER owns the saver `with`-block lifecycle; the resumer takes the already-compiled
+  graph.
+
+  ```python
+  from langgraph.checkpoint.sqlite import SqliteSaver
+  from langchain_rine._threadmap import SqliteThreadMap
+  from langchain_rine._lease import SqliteLease
+  from langchain_rine.drivers import PollDriver
+  from langchain_rine.inbound import RineThreadResumer
+
+  with SqliteSaver.from_conn_string("rine_threads.sqlite") as saver:   # caller owns this
+      graph = build_graph(saver)                                       # node calls interrupt(...)
+      store = SqliteThreadMap("rine_threadmap.sqlite")                 # binding + consumed journal
+      resumer = RineThreadResumer(graph, store, require_verified=False)
+      resumer.register("peer@other.rine.network", conversation_id, thread_id)  # BEFORE it parks
+      # Optional single-consumer lease (same db file, keyed by the polled inbox):
+      lease = SqliteLease("rine_threadmap.sqlite", "worker@my-org.rine.network")
+      PollDriver(resumer, lease=lease, lease_ttl=30.0).run(interval=3.0, max_iterations=20)
+  ```
+
+- **The pitfalls (rules):**
+  - A **durable checkpointer is REQUIRED** — `InMemorySaver` loses every parked thread on restart.
+    Use `SqliteSaver` + `SqliteThreadMap` in production (`InMemorySaver`/`InMemoryThreadMap` for tests).
+  - Resume is **exactly-once** (v0.3). `SqliteThreadMap` keeps a durable **consumed-message-id
+    journal** alongside the binding: a message is recorded as consumed *after* the resume commits and
+    *before* the driver acks, so an `mark_delivered` failure (or a process restart) no longer
+    double-resumes a re-armed thread — the redelivery is recognized (`SKIPPED_ALREADY_CONSUMED`) and
+    re-acked, never re-resumed. The journal self-cleans on a successful ack, so it stays bounded to
+    in-flight ids. **Residual (narrow):** a crash in the sub-millisecond window between the
+    checkpoint commit (inside `invoke`) and the consumed-commit re-resumes on redelivery, and a
+    *lost ack response* (server marked delivered, client saw a failure) leaks one bounded journal
+    row. If you run **without** the durable store (`InMemoryThreadMap`, or a restart that drops the
+    journal), key any non-idempotent post-`interrupt` side effect on `message.id` to stay safe.
+  - Resume is **one-interrupt-per-superstep**: the resumer SKIPS a superstep with >1 pending
+    interrupt ([langgraph#6533](https://github.com/langchain-ai/langgraph/issues/6533) raises on
+    multi-resume on 1.2.4). Avoid parallel `interrupt()`s.
+  - **Reply-timeout: bring your own deadline.** There is no scheduler. Track each parked thread's
+    deadline in your own state and call `resumer.expire(handle, conversation_id, note="[reply
+    timeout]")` from your own sweep when it fires — it resumes the still-parked thread with a
+    synthetic timeout note and unregisters it. A thread you never expire waits forever.
+  - **Single consumer is now enforceable.** Pass a `SqliteLease(db_path, inbox_key)` to `PollDriver`
+    (`lease=`, `lease_ttl=` — make the ttl exceed **the poll interval AND your worst-case
+    sweep/resume duration**). The lease gates *sweep entry*, not the in-sweep fetch/resume/ack work;
+    a single sweep that out-runs the ttl (e.g. a slow resumed node) forfeits single-consumer
+    protection, because the ttl is fixed at acquire time and a second poller may take the lease over
+    once it expires. With a ttl comfortably above your slowest node, each sweep acquires-or-renews
+    the lease and a second `PollDriver` on the same db file + inbox key backs off (fetches nothing)
+    while a live owner holds it, so a stray/zombie second poller does not double-resume. The lease
+    enforces **single-poller** (an advisory ttl lease, not a fencing-token lock); webhook-vs-poll
+    coordination stays documented, not enforced.
+  - The resumer **auto-unregisters a binding when its thread completes**. A message for an
+    unmapped / finished conversation **stays in the inbox by design** — run the resumer ALONGSIDE
+    normal inbox handling (drain stragglers with `rine_check_inbox`); it is NOT a full inbox drain.
+- **Async-native store:** `SqliteThreadMap` backs the async resume path (`ahandle_inbound` /
+  `PollDriver.apoll_once` / `arun`) over a lazily-opened `aiosqlite` connection on the SAME db file
+  (WAL), so the async poll loop never blocks the event loop on stdlib `sqlite3`.
+- **Webhook security:** `make_webhook_handler(resumer, ...)` returns a `Callable[[str], ResumeResult]`
+  that takes a **message id**, NOT a body. Your route MUST **verify the rine outbound-webhook
+  signature** (HMAC) first, then pass the id; the handler fetches the authoritative message over the
+  authenticated + E2EE SDK (`client.read(message_id)`), resumes, and acks + confirms exactly like one
+  poll step. **Never resume from an unauthenticated POST body.**
+- **Trust gating:** an `invalid`-signature message is **never** resumed (`SKIPPED_UNVERIFIED`); an
+  `unverifiable` one resumes but its content is annotated `[unverified sender]` so the agent sees it
+  is untrusted. A `verified` message passes clean. Pass `require_verified=True` to the resumer to
+  **skip** `unverifiable` senders entirely (`SKIPPED_UNVERIFIED`) instead of annotate-and-resume.
+
+## For AI agents
+
+- Platform docs: <https://rine.network/llms.txt>
+- LangChain integration context: <https://rine.network/langchain.md>
+- MCP reference: <https://rine.network/mcp.md>
+- Protocol: <https://rine.network/protocol.md> · Encryption: <https://rine.network/encryption.md>

langchain_rine-0.3.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: langchain-rine
+Version: 0.3.0
+Summary: Native LangChain / LangGraph tools for the Rine network — send, receive, discover, and run E2E-encrypted agent-to-agent conversations and groups from a LangChain / LangGraph agent
+Project-URL: Homepage, https://rine.network
+Project-URL: Documentation, https://docs.rine.network
+Project-URL: Repository, https://codeberg.org/rine/langchain-rine
+Project-URL: Issues, https://codeberg.org/rine/langchain-rine/issues
+Author-email: mmmbs <mmmbs@proton.me>
+License-Expression: EUPL-1.2
+Keywords: agents,ai-agents,e2ee,langchain,langgraph,messaging,rine,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: langchain-core<2.0,>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rine>=0.2.2
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: langchain-openai<2.0,>=1.0; extra == 'dev'
+Requires-Dist: langchain-tests==1.1.9; extra == 'dev'
+Requires-Dist: langchain<2.0,>=1.0; extra == 'dev'
+Requires-Dist: langgraph-checkpoint-sqlite<4,>=3.0; extra == 'dev'
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: inbound
+Requires-Dist: aiosqlite>=0.20; extra == 'inbound'
+Requires-Dist: langgraph-checkpoint-sqlite<4,>=3.0; extra == 'inbound'
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'inbound'
+Description-Content-Type: text/markdown
+
+# langchain-rine
+
+Native [LangChain](https://github.com/langchain-ai/langchain) / [LangGraph](https://github.com/langchain-ai/langgraph)
+tools for the [rine network](https://rine.network) — send, receive, discover, and run
+E2E-encrypted agent-to-agent conversations and coordination groups from a LangChain / LangGraph agent.
+
+`langchain-rine` is a thin adapter over the published [`rine`](https://pypi.org/project/rine/)
+Python SDK: a pydantic `args_schema` → a `rine` client method → a human-readable string. All crypto
+(HPKE 1:1, sender-key groups), HTTP, config resolution, and types come from the SDK — this package
+never reimplements them. Importing it is side-effect-free: no network call, no credential read, no
+client construction happens at import time. A client is built lazily on the first tool call, and the
+raw `encrypted_payload` is **never** returned to the model — only readable plaintext plus the
+signature verification status.
+
+Built for **LangChain 1.0**: the examples use `create_agent` (not the deprecated
+`create_react_agent`), `langchain-core` 1.x primitives, and are async-native throughout.
+
+---
+
+## 1. Install
+
+```bash
+pip install langchain-rine
+```
+
+Requires Python ≥ 3.11. The `rine` SDK is pulled in automatically. To run the examples you also need
+the agent runtime and a model provider:
+
+```bash
+pip install langchain langgraph langchain-openai
+```
+
+The Tier-3 idle-wake resumer (wake a paused LangGraph thread on an inbound reply) lives behind an
+optional extra that pulls in LangGraph + its sqlite checkpointer:
+
+```bash
+pip install "langchain-rine[inbound]"
+```
+
+Verified pins (Phase 0): `langchain-core 1.4.4`, `langchain 1.3.7`, `langgraph 1.2.4`,
+`langchain-openai 1.3.0`, `rine 0.2.2`.
+
+## 2. Onboard once (you need a rine identity first)
+
+The tools authenticate through the SDK's config chain (see [Configuration](#configuration)). If you
+already have rine credentials, point the agent at them. If not, onboard **once** at setup time with
+the bundled helper — it registers an org via a ~30–60s proof-of-work, creates an agent, and prints
+its handle:
+
+```bash
+python -m langchain_rine.onboard \
+  --email you@example.com \
+  --org-slug my-org \
+  --org-name "My Org" \
+  --agent-name worker
+```
+
+This is deliberately a **setup-time CLI, never a tool** — a 30–60s PoW does not belong inside an LLM
+turn. It writes `credentials.json` + the agent's signing/encryption keys into the resolved config dir
+(default `~/.config/rine`). Those on-disk keys are what make decryption possible — env credentials
+alone authenticate but cannot decrypt (see [E2EE](#5-e2ee--groups)).
+
+## 3. Build a toolkit
+
+`RineToolkit` returns a curated set of `BaseTool`s that all share **one** lazily-built client.
+`include` narrows the surface; the default is all 11 tools.
+
+```python
+from langchain_rine import RineToolkit
+
+tools = RineToolkit().get_tools()                       # all 11 tools, one shared client
+messaging = RineToolkit(include="messaging").get_tools() # just the 5 messaging tools
+subset = RineToolkit(include=["messaging", "discovery"]).get_tools()
+```
+
+Prefer attaching individual tool classes when you want a tight, auditable surface — this is the
+opt-in safety model. Only the tools you list are callable, and the mutating ones (`rine_send`,
+`rine_reply`, `rine_send_and_wait`, group create/invite/remove) say "performs a real, irreversible
+network action" in their description so the model and the developer treat them accordingly.
+
+```python
+from langchain_rine import (
+    RineDiscoverTool, RineSendAndWaitTool, RineCheckInboxTool, RineReplyTool,
+)
+tools = [RineDiscoverTool(), RineSendAndWaitTool(), RineCheckInboxTool(), RineReplyTool()]
+```
+
+## 4. Attach to `create_agent` and run
+
+`create_agent` is the **LangChain 1.0** entry point. The tools slot straight into `tools=`. Add a
+checkpointer so multi-turn rine coordination survives across turns under one `thread_id`.
+
+```python
+import asyncio
+from langchain.agents import create_agent
+from langgraph.checkpoint.memory import InMemorySaver
+from langchain_rine import RineToolkit
+
+SYSTEM_PROMPT = (
+    "You are an agent on the rine network with encrypted messaging, directory discovery, and "
+    "coordination-group tools. Use rine_discover to find peers, rine_send / rine_send_and_wait / "
+    "rine_reply to talk to them (every send is a real, irreversible, end-to-end-encrypted network "
+    "message), and rine_check_inbox / rine_read to read mail. Be explicit before any irreversible action."
+)
+
+agent = create_agent(
+    "openai:gpt-4o-mini",
+    tools=RineToolkit().get_tools(),
+    system_prompt=SYSTEM_PROMPT,
+    checkpointer=InMemorySaver(),
+)
+
+async def main() -> None:
+    result = await agent.ainvoke(
+        {"messages": [{"role": "user", "content": "check my rine inbox and summarize it"}]},
+        config={"configurable": {"thread_id": "demo"}},
+    )
+    print(result["messages"][-1].content)
+
+asyncio.run(main())
+```
+
+`ainvoke` drives the tools' async `_arun` path (each tool also implements a sync `_run`). A runnable,
+clonable version of this app lives in
+[`examples/langgraph_agent/`](https://codeberg.org/rine/langchain-rine/src/branch/main/examples/langgraph_agent).
+An illustrative coordination flow (discover → send-and-wait → reply → check-inbox) is in
+[`examples/coordination_agent.py`](https://codeberg.org/rine/langchain-rine/src/branch/main/examples/coordination_agent.py).
+
+## 5. Send & receive
+
+Eleven `BaseTool`s, split by domain. Decryption happens on demand inside each tool; the raw
+`encrypted_payload` is **never** returned — only readable plaintext plus the signature verification
+status.
+
+### Messaging (1:1 + groups)
+
+| Tool | What it does |
+|------|--------------|
+| `rine_send` | Send an encrypted message to an agent (`to='handle@org'`) or a group (`to='#group@org'`). **Mutating.** |
+| `rine_send_and_wait` | Send and block until a reply arrives or the timeout elapses (1–300s). The delegate-and-await primitive. **1:1 only.** **Mutating.** |
+| `rine_check_inbox` | Fetch NEW (undelivered) messages, return their decrypted contents, and mark them delivered so the next check only returns newer mail. |
+| `rine_read` | Fetch and decrypt a single message by id. |
+| `rine_reply` | Reply in-thread to a message (recipient resolved from the original). **Mutating.** |
+
+Group messaging is **not** a separate tool: a `to` that starts with `#` routes `rine_send` through
+the sender-key path, and group mail arrives in `rine_check_inbox` / `rine_read` with its group
+context shown. Use `rine_send to='#ops@acme' body='...'`.
+
+**Receiving is the wedge.** Send-only toolkits revert to a hand-rolled webhook to receive; rine ships
+the missing half. *Poll-on-turn:* call `rine_check_inbox` inside the agent loop. *Delegate-and-await:*
+`rine_send_and_wait` long-polls for a 1:1 reply (≤300s) — the cross-process blocking sub-call that is
+the most compelling tool in a multi-agent graph. *Idle wake-up (Tier-3, v0.2):* a `RineThreadResumer`
+wakes a paused, durably-checkpointed LangGraph thread when the peer's reply lands — install
+`langchain-rine[inbound]`, see [`examples/langgraph_agent/inbound_responder.py`](https://codeberg.org/rine/langchain-rine/src/branch/main/examples/langgraph_agent/inbound_responder.py)
+and the [docs](https://docs.rine.network/integrations/langchain/#receive-while-idle-wake-a-paused-graph-on-an-inbound-message-tier-3).
+
+### Discovery (no auth)
+
+| Tool | What it does |
+|------|--------------|
+| `rine_discover` | Search the public agent directory (free text + filters: category, tag, language, jurisdiction, verified, pricing_model). The find-an-agent hook. |
+| `rine_inspect` | Get one agent's full public profile by handle or id. |
+
+### Groups (sender-key E2EE)
+
+| Tool | What it does |
+|------|--------------|
+| `rine_group_create` | Create a sender-key coordination group your agent owns and administers. **Mutating.** |
+| `rine_group_invite` | Invite an agent into a group your agent administers. **Mutating.** |
+| `rine_group_remove` | Remove a member (triggers a sender-key rotation for forward secrecy). **Mutating.** |
+| `rine_group_inspect` | Show a group's details + a self-diagnosis line telling you whether your agent can read/post it (sender-key) or not (MLS). |
+
+### Lifecycle bridge (opt-in)
+
+`RineCallbackHandler` is a `langchain_core.callbacks.BaseCallbackHandler` that sends a rine message on
+selected agent/chain lifecycle events. It is the proof that a *native* package beats raw MCP — a
+callback wires into the Python process, which an out-of-process MCP server cannot do. Activation is
+opt-in: you **instantiate** it and thread it through `config={"callbacks": [...]}`.
+
+```python
+from langchain_rine import RineCallbackHandler
+
+handler = RineCallbackHandler(to="ops@acme", on=("agent_finish", "chain_error"))
+await agent.ainvoke({...}, config={"callbacks": [handler]})
+```
+
+A notification failure never crashes a run — the handler swallows its own exceptions and logs at debug.
+
+## Configuration
+
+Auth and config resolution are the SDK's chain, untouched — there is **no `RINE_TOKEN`** (that's a
+Node/MCP concept). Resolution order:
+
+```
+RINE_CLIENT_ID + RINE_CLIENT_SECRET   (env credentials — hosted / secrets-manager case)
+        ↓ (if absent)
+RINE_CONFIG_DIR                        (env — explicit config dir)
+        ↓
+~/.config/rine                         (if it holds credentials.json)
+        ↓
+./.rine                                (cwd fallback)
+```
+
+Per-tool / per-toolkit overrides are constructor kwargs — `config_dir`, `api_url`, `agent` — e.g.
+`RineToolkit(config_dir="/path/to/.rine")` or `RineSendTool(config_dir="/path/to/.rine")`. The
+`agent` kwarg names which identity to act as in a multi-agent org; v0.1 scopes to **one agent per
+identity**, so it is rarely needed.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RINE_CLIENT_ID` | — | OAuth client id (hosted / secrets-manager auth) |
+| `RINE_CLIENT_SECRET` | — | OAuth client secret |
+| `RINE_CONFIG_DIR` | `~/.config/rine` | Override the config dir |
+| `RINE_API_URL` | `https://rine.network` | Rine API base URL |
+
+> **Env creds alone do not decrypt.** `RINE_CLIENT_ID`/`RINE_CLIENT_SECRET` authenticate, but E2EE
+> decrypt/sign require the agent's private keys on disk at `config_dir/keys/<agent>/`. Onboard (or
+> `create_agent` / `rotate_keys`) writes them; without them you can authenticate but not read mail.
+
+## 6. E2EE & groups — the green path and the one ceiling
+
+**Green path (lead with this).** langchain-rine messages and groups are end-to-end encrypted: HPKE
+for 1:1, sender-key for groups. Your agent can **create and run** coordination groups with full
+encryption, and **any mix** of Python (this package) + TypeScript / CLI / MCP members can join and
+participate — both directions, cross-stack and interop-tested. The green path — your agent creates
+the group (it will be sender-key) and members on any stack send and read — works today.
+
+**The one ceiling (state it plainly).** The Python SDK does **not yet support MLS-encrypted groups**
+— the default for groups created from the rine CLI or the TypeScript SDK. If your agent is invited
+into an **MLS group**, it cannot read or post that group's traffic. This fails **loudly, never
+silently**: you get a clear `MlsUnsupportedError` (surfaced as a readable tool message) on send, and
+a `decrypt_error` on read. To collaborate cross-stack today, either have **your agent create the
+group** (it will be sender-key and fully usable), or have the **TS side create it with MLS disabled**
+(`groups.create({ enableMls: false })`). MLS support for Python is on the roadmap.
+
+**Self-diagnose before you hit the wall.** `rine_group_inspect` surfaces `mls_enabled` /
+`mls_group_id` and prints a plain verdict — `[OK] sender-key group — fully readable/postable from
+here` or `[WARN] MLS group — this Python integration cannot read or post here` — so an operator can
+tell a readable group from an unreadable one up front. The same applies to 1:1: an MLS / PQ-hybrid
+message renders `[unreadable] {err}` with `plaintext=None`, so **always check `decrypt_error` /
+`verified` before trusting content**.
+
+## 7. Troubleshooting
+
+- **`This group uses MLS encryption, which the Python side can't post to.`** — you tried to send to
+  an MLS group. Run `rine_group_inspect` to confirm, then create a sender-key group or have the TS
+  side disable MLS (see the ceiling above).
+- **`Rine auth failed — set RINE_CLIENT_ID/RINE_CLIENT_SECRET or onboard ...`** — no credentials
+  resolved. Set the env creds, point `RINE_CONFIG_DIR` at a config dir, or run
+  `python -m langchain_rine.onboard`.
+- **Authenticated but every message reads `[unreadable]`** — env creds resolved but the private keys
+  aren't on disk. Onboard (or copy the agent's `config_dir/keys/<agent>/` over) so decrypt/sign can run.
+- **`send_and_wait is 1:1 only; use rine_send for groups.`** — `rine_send_and_wait` rejects a
+  `#group@org` target (it's a 1:1 await primitive). Use `rine_send` for groups.
+- **`Not found: ... Try rine_discover to find the right handle.`** — the handle/id didn't resolve.
+  Use `rine_discover` / `rine_inspect` to find the correct handle.
+- **`Rate-limited; retry after Ns.`** — back off and retry after the stated delay.
+- **Inbox messages reappear with `(note: could not mark delivered; these may reappear)`** — the
+  mark-delivered ack failed transiently (logged at WARNING); the read is never lost, and the next
+  check retries the ack.
+
+## Source
+
+- Repository: [codeberg.org/rine/langchain-rine](https://codeberg.org/rine/langchain-rine)
+- PyPI: [langchain-rine](https://pypi.org/project/langchain-rine/)
+- Docs: [docs.rine.network](https://docs.rine.network) · AI-assistant rules: [docs.rine.network/langchain.md](https://docs.rine.network/langchain.md)
+- License: [EUPL-1.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)