langgraph-tenancy 0.1.0__tar.gz

langgraph_tenancy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: langgraph_tenancy_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      LG_TENANCY_PG_URI: postgresql://postgres:postgres@localhost:5432/langgraph_tenancy_test
+      LG_TENANCY_PG_REQUIRED: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv pip install -e ".[test]"
+      - name: Test
+        run: uv run pytest -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Ruff check
+        run: uvx ruff check .
+      - name: Ruff format check
+        run: uvx ruff format --check .

langgraph_tenancy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: langgraph_tenancy_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      LG_TENANCY_PG_URI: postgresql://postgres:postgres@localhost:5432/langgraph_tenancy_test
+      LG_TENANCY_PG_REQUIRED: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv pip install -e ".[test]"
+      - name: Test
+        run: uv run pytest -v
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build distributions
+        run: uv build
+      - name: Check release tag matches package version
+        run: |
+          version=$(uvx hatchling version 2>/dev/null || grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          if [ "v${version}" != "${{ github.event.release.tag_name }}" ]; then
+            echo "Release tag ${{ github.event.release.tag_name }} does not match package version v${version}"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/langgraph-tenancy
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

langgraph_tenancy-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# environments
+.venv/
+venv/
+.env
+
+# tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# editors / os
+.idea/
+.vscode/
+.DS_Store

langgraph_tenancy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Chauhan
+
+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.

langgraph_tenancy-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: langgraph-tenancy
+Version: 0.1.0
+Summary: Tenant isolation and per-tenant usage metering for LangGraph checkpointers and stores
+Project-URL: Source, https://github.com/ac12644/langgraph-tenancy
+Project-URL: Issues, https://github.com/ac12644/langgraph-tenancy/issues
+Author-email: Abhishek Chauhan <ac12644@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,checkpointer,langgraph,llm,multi-tenant,tenant-isolation
+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 :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.2.38
+Requires-Dist: langgraph-checkpoint>=2.0.0
+Provides-Extra: test
+Requires-Dist: langgraph-checkpoint-postgres>=2.0.0; extra == 'test'
+Requires-Dist: langgraph>=0.4; extra == 'test'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langgraph-tenancy
+
+[![CI](https://github.com/ac12644/langgraph-tenancy/actions/workflows/ci.yml/badge.svg)](https://github.com/ac12644/langgraph-tenancy/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/langgraph-tenancy)](https://pypi.org/project/langgraph-tenancy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Tenant isolation for LangGraph persistence — as a drop-in wrapper.**
+
+LangGraph's own [threat model](https://github.com/langchain-ai/langgraph/blob/main/.github/THREAT_MODEL.md) says it plainly:
+
+> Checkpoint savers index by `thread_id`. Without application-level auth, any
+> caller with a valid thread_id can access that thread's state. [...] Users
+> embedding LangGraph directly must implement their own access controls.
+
+If you run a multi-tenant product on open-source LangGraph, the only thing
+between Customer A's agent state and Customer B's is a query filter in your
+application code. This package replaces that convention with enforcement.
+
+## Install
+
+```bash
+pip install langgraph-tenancy
+```
+
+## Usage
+
+Wrap your existing checkpointer and store. Nothing else changes.
+
+```python
+from langgraph_tenancy import (
+    TenantScopedCheckpointer,
+    TenantScopedStore,
+    InMemoryUsageLedger,
+)
+
+ledger = InMemoryUsageLedger()
+checkpointer = TenantScopedCheckpointer(PostgresSaver(...), usage_ledger=ledger)
+store = TenantScopedStore(InMemoryStore())
+
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+# tenant_id is now REQUIRED on every invocation
+graph.invoke(
+    {"messages": ["hello"]},
+    config={"configurable": {"thread_id": "t1", "tenant_id": "acme"}},
+)
+
+# free per-tenant token metering, extracted from checkpointed messages
+ledger.totals("acme")  # TenantUsage(input_tokens=..., output_tokens=..., by_model={...})
+```
+
+## What it enforces
+
+| Raw LangGraph behavior | With `langgraph-tenancy` |
+|---|---|
+| Any caller with a `thread_id` reads that thread | Threads are physically keyed `tenant::thread`; wrong-thread_id bugs cannot cross tenants |
+| Missing filter → silent unscoped query | Missing `tenant_id` → `TenantRequiredError`, nothing read or written |
+| `checkpointer.list(None)` enumerates **every** tenant's threads | Refused with `UnscopedAccessError` |
+| Store namespaces are convention; any node can read any namespace | Every op is rooted at the tenant segment, resolved from the run config automatically |
+| `delete_thread("t1")` deletes whoever owns `t1` | Requires an explicit `for_tenant("acme").delete_thread("t1")` handle |
+| `usage_metadata` buried in checkpoint blobs, unqueryable | Aggregated per tenant (and per model), deduped by message id |
+
+## No magic
+
+The entire mechanism is key prefixing plus mandatory-context checks, in two
+small files you can audit in ten minutes:
+
+- thread ids become `"{tenant_id}::{thread_id}"` before reaching your
+  database; the prefix is stripped from everything returned.
+- store namespaces `("memories",)` become `("{tenant_id}", "memories")`.
+- tenant ids containing the separator are rejected, so `acme` can never craft
+  a key that collides with another tenant's space.
+
+It composes with any `BaseCheckpointSaver` / `BaseStore` implementation —
+Postgres, SQLite, Redis, MongoDB, in-memory — because it never touches
+storage itself.
+
+## What it is not
+
+- Not authentication. You decide which tenant a request belongs to; this
+  package guarantees that decision is enforced everywhere downstream.
+- Not encryption. Combine with `EncryptedSerializer` for at-rest encryption.
+- Not a replacement for database-level controls in high-assurance setups
+  (RLS, schema-per-tenant) — it's the layer that makes your *application*
+  unable to leak, whatever the database allows.
+
+## Tested
+
+The adversarial test suite — every test attempts a cross-tenant access the
+raw LangGraph API allows — runs against `InMemorySaver` **and** a real
+`PostgresSaver` in CI. The isolation guarantees are proven on actual SQL
+storage, not just the in-memory reference.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[test]"
+uv run pytest                 # postgres tests skip if no server is reachable
+
+# to run the postgres leg locally:
+export LG_TENANCY_PG_URI=postgresql://user@localhost:5432/langgraph_tenancy_test
+uv run pytest
+```
+
+## Status
+
+Early (0.1.x). Covered today: sync + async checkpointer paths, sync store
+paths, in-memory and Postgres backends. Not yet covered: subgraph
+`checkpoint_ns` edge cases, `AsyncPostgresSaver`, `PostgresStore`, store TTL
+ops. Issues and PRs welcome.
+
+## License
+
+[MIT](LICENSE)

langgraph_tenancy-0.1.0/README.md

@@ -0,0 +1,114 @@
+# langgraph-tenancy
+
+[![CI](https://github.com/ac12644/langgraph-tenancy/actions/workflows/ci.yml/badge.svg)](https://github.com/ac12644/langgraph-tenancy/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/langgraph-tenancy)](https://pypi.org/project/langgraph-tenancy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Tenant isolation for LangGraph persistence — as a drop-in wrapper.**
+
+LangGraph's own [threat model](https://github.com/langchain-ai/langgraph/blob/main/.github/THREAT_MODEL.md) says it plainly:
+
+> Checkpoint savers index by `thread_id`. Without application-level auth, any
+> caller with a valid thread_id can access that thread's state. [...] Users
+> embedding LangGraph directly must implement their own access controls.
+
+If you run a multi-tenant product on open-source LangGraph, the only thing
+between Customer A's agent state and Customer B's is a query filter in your
+application code. This package replaces that convention with enforcement.
+
+## Install
+
+```bash
+pip install langgraph-tenancy
+```
+
+## Usage
+
+Wrap your existing checkpointer and store. Nothing else changes.
+
+```python
+from langgraph_tenancy import (
+    TenantScopedCheckpointer,
+    TenantScopedStore,
+    InMemoryUsageLedger,
+)
+
+ledger = InMemoryUsageLedger()
+checkpointer = TenantScopedCheckpointer(PostgresSaver(...), usage_ledger=ledger)
+store = TenantScopedStore(InMemoryStore())
+
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+# tenant_id is now REQUIRED on every invocation
+graph.invoke(
+    {"messages": ["hello"]},
+    config={"configurable": {"thread_id": "t1", "tenant_id": "acme"}},
+)
+
+# free per-tenant token metering, extracted from checkpointed messages
+ledger.totals("acme")  # TenantUsage(input_tokens=..., output_tokens=..., by_model={...})
+```
+
+## What it enforces
+
+| Raw LangGraph behavior | With `langgraph-tenancy` |
+|---|---|
+| Any caller with a `thread_id` reads that thread | Threads are physically keyed `tenant::thread`; wrong-thread_id bugs cannot cross tenants |
+| Missing filter → silent unscoped query | Missing `tenant_id` → `TenantRequiredError`, nothing read or written |
+| `checkpointer.list(None)` enumerates **every** tenant's threads | Refused with `UnscopedAccessError` |
+| Store namespaces are convention; any node can read any namespace | Every op is rooted at the tenant segment, resolved from the run config automatically |
+| `delete_thread("t1")` deletes whoever owns `t1` | Requires an explicit `for_tenant("acme").delete_thread("t1")` handle |
+| `usage_metadata` buried in checkpoint blobs, unqueryable | Aggregated per tenant (and per model), deduped by message id |
+
+## No magic
+
+The entire mechanism is key prefixing plus mandatory-context checks, in two
+small files you can audit in ten minutes:
+
+- thread ids become `"{tenant_id}::{thread_id}"` before reaching your
+  database; the prefix is stripped from everything returned.
+- store namespaces `("memories",)` become `("{tenant_id}", "memories")`.
+- tenant ids containing the separator are rejected, so `acme` can never craft
+  a key that collides with another tenant's space.
+
+It composes with any `BaseCheckpointSaver` / `BaseStore` implementation —
+Postgres, SQLite, Redis, MongoDB, in-memory — because it never touches
+storage itself.
+
+## What it is not
+
+- Not authentication. You decide which tenant a request belongs to; this
+  package guarantees that decision is enforced everywhere downstream.
+- Not encryption. Combine with `EncryptedSerializer` for at-rest encryption.
+- Not a replacement for database-level controls in high-assurance setups
+  (RLS, schema-per-tenant) — it's the layer that makes your *application*
+  unable to leak, whatever the database allows.
+
+## Tested
+
+The adversarial test suite — every test attempts a cross-tenant access the
+raw LangGraph API allows — runs against `InMemorySaver` **and** a real
+`PostgresSaver` in CI. The isolation guarantees are proven on actual SQL
+storage, not just the in-memory reference.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[test]"
+uv run pytest                 # postgres tests skip if no server is reachable
+
+# to run the postgres leg locally:
+export LG_TENANCY_PG_URI=postgresql://user@localhost:5432/langgraph_tenancy_test
+uv run pytest
+```
+
+## Status
+
+Early (0.1.x). Covered today: sync + async checkpointer paths, sync store
+paths, in-memory and Postgres backends. Not yet covered: subgraph
+`checkpoint_ns` edge cases, `AsyncPostgresSaver`, `PostgresStore`, store TTL
+ops. Issues and PRs welcome.
+
+## License
+
+[MIT](LICENSE)

langgraph_tenancy-0.1.0/langgraph_tenancy/__init__.py

@@ -0,0 +1,65 @@
+"""Tenant isolation for LangGraph persistence.
+
+LangGraph's own threat model: "Without application-level auth, any caller
+with a valid thread_id can access that thread's state." This package is that
+application-level wall, as a drop-in wrapper:
+
+```python
+from langgraph_tenancy import (
+    TenantScopedCheckpointer, TenantScopedStore, InMemoryUsageLedger,
+)
+
+ledger = InMemoryUsageLedger()
+checkpointer = TenantScopedCheckpointer(PostgresSaver(...), usage_ledger=ledger)
+store = TenantScopedStore(InMemoryStore())
+
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+graph.invoke(
+    {"messages": [...]},
+    config={"configurable": {"thread_id": "t1", "tenant_id": "acme"}},
+)
+
+ledger.totals("acme")  # per-tenant token usage, for free
+```
+
+Guarantees:
+- No tenant_id in config -> the call raises; nothing is read or written.
+- Thread ids and store namespaces are physically tenant-prefixed in storage.
+- `list(None)` (enumerate all tenants' threads) is refused.
+- Maintenance ops (delete/copy/prune) require an explicit `for_tenant()` handle.
+"""
+
+from langgraph_tenancy._checkpointer import (
+    TenantCheckpointerHandle,
+    TenantScopedCheckpointer,
+)
+from langgraph_tenancy._errors import (
+    InvalidTenantError,
+    TenancyError,
+    TenantRequiredError,
+    UnscopedAccessError,
+)
+from langgraph_tenancy._store import TenantScopedStore
+from langgraph_tenancy._usage import (
+    InMemoryUsageLedger,
+    TenantUsage,
+    UsageLedger,
+    UsageRecord,
+    extract_usage,
+)
+
+__all__ = [
+    "InMemoryUsageLedger",
+    "InvalidTenantError",
+    "TenancyError",
+    "TenantCheckpointerHandle",
+    "TenantRequiredError",
+    "TenantScopedCheckpointer",
+    "TenantScopedStore",
+    "TenantUsage",
+    "UnscopedAccessError",
+    "UsageLedger",
+    "UsageRecord",
+    "extract_usage",
+]

langgraph_tenancy-0.1.0/langgraph_tenancy/_checkpointer.py

@@ -0,0 +1,254 @@
+"""Tenant-scoped wrapper around any `BaseCheckpointSaver`.
+
+Design:
+- Reads `tenant_id` from `config["configurable"]` on every call. Missing
+  tenant -> `TenantRequiredError`. There is no unscoped fallback.
+- Physically prefixes `thread_id` with the tenant (``acme::thread-1``) before
+  it reaches the inner saver, and strips the prefix from everything returned.
+  A wrong-thread_id bug in app code therefore cannot cross a tenant boundary:
+  the key the database sees is always tenant-qualified.
+- Blocks the dangerous raw-API escape hatches: `list(None)` and
+  `delete_thread(...)` without a tenant.
+- Optionally records per-tenant token usage from checkpointed messages into a
+  `UsageLedger` (see `_usage.py`) — same integration point, free metering.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+)
+
+from langgraph_tenancy._errors import (
+    InvalidTenantError,
+    TenantRequiredError,
+    UnscopedAccessError,
+)
+from langgraph_tenancy._usage import UsageLedger, extract_usage
+
+SEP = "::"
+
+
+def _validate_tenant(tenant: Any, where: str) -> str:
+    if not isinstance(tenant, str) or not tenant:
+        raise TenantRequiredError(where)
+    if SEP in tenant:
+        raise InvalidTenantError(f"tenant_id may not contain '{SEP}': {tenant!r}")
+    return tenant
+
+
+class TenantScopedCheckpointer(BaseCheckpointSaver):
+    """Wrap a checkpointer so every operation is scoped to one tenant."""
+
+    def __init__(
+        self,
+        inner: BaseCheckpointSaver,
+        *,
+        usage_ledger: UsageLedger | None = None,
+    ) -> None:
+        super().__init__(serde=inner.serde)
+        self.inner = inner
+        self.usage_ledger = usage_ledger
+
+    # -- scoping helpers ----------------------------------------------------
+
+    def _scope(self, config: RunnableConfig, where: str) -> tuple[str, RunnableConfig]:
+        conf = config.get("configurable") or {}
+        tenant = _validate_tenant(conf.get("tenant_id"), where)
+        thread_id = conf.get("thread_id")
+        scoped_thread = f"{tenant}{SEP}{thread_id}"
+        return tenant, {
+            **config,
+            "configurable": {**conf, "thread_id": scoped_thread},
+        }
+
+    def _unscope_config(
+        self, tenant: str, config: RunnableConfig | None
+    ) -> RunnableConfig | None:
+        if config is None:
+            return None
+        conf = config.get("configurable") or {}
+        thread_id = conf.get("thread_id")
+        prefix = f"{tenant}{SEP}"
+        if isinstance(thread_id, str) and thread_id.startswith(prefix):
+            conf = {**conf, "thread_id": thread_id[len(prefix) :], "tenant_id": tenant}
+        return {**config, "configurable": conf}
+
+    def _unscope_tuple(
+        self, tenant: str, tup: CheckpointTuple | None
+    ) -> CheckpointTuple | None:
+        if tup is None:
+            return None
+        return CheckpointTuple(
+            config=self._unscope_config(tenant, tup.config),
+            checkpoint=tup.checkpoint,
+            metadata=tup.metadata,
+            parent_config=self._unscope_config(tenant, tup.parent_config),
+            pending_writes=tup.pending_writes,
+        )
+
+    # -- core protocol (sync) -----------------------------------------------
+
+    @property
+    def config_specs(self) -> list:
+        return self.inner.config_specs
+
+    def get_next_version(self, current: Any, channel: None = None) -> Any:
+        return self.inner.get_next_version(current, channel)
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        tenant, scoped = self._scope(config, "get_tuple()")
+        return self._unscope_tuple(tenant, self.inner.get_tuple(scoped))
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        if config is None:
+            raise UnscopedAccessError(
+                "list(None) would enumerate every tenant's threads; "
+                "pass a config with tenant_id (and optionally thread_id)."
+            )
+        tenant, scoped = self._scope(config, "list()")
+        scoped_before = self._scope(before, "list(before=...)")[1] if before else None
+        for tup in self.inner.list(
+            scoped, filter=filter, before=scoped_before, limit=limit
+        ):
+            yield self._unscope_tuple(tenant, tup)
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        tenant, scoped = self._scope(config, "put()")
+        if self.usage_ledger is not None:
+            for record in extract_usage(checkpoint):
+                self.usage_ledger.record(tenant, record)
+        result = self.inner.put(scoped, checkpoint, metadata, new_versions)
+        return self._unscope_config(tenant, result)
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        _, scoped = self._scope(config, "put_writes()")
+        self.inner.put_writes(scoped, writes, task_id, task_path)
+
+    # -- blocked / redirected escape hatches ----------------------------------
+
+    def delete_thread(self, thread_id: str) -> None:
+        raise UnscopedAccessError(
+            "delete_thread() has no tenant context; "
+            "use for_tenant(tenant_id).delete_thread(thread_id)."
+        )
+
+    def delete_for_runs(self, run_ids: Sequence[str]) -> None:
+        raise UnscopedAccessError(
+            "delete_for_runs() cannot be tenant-scoped (run ids are global); "
+            "call it on the inner saver explicitly if you accept that."
+        )
+
+    def for_tenant(self, tenant_id: str) -> TenantCheckpointerHandle:
+        """Admin/maintenance handle pinned to one tenant."""
+        return TenantCheckpointerHandle(
+            self, _validate_tenant(tenant_id, "for_tenant()")
+        )
+
+    # -- core protocol (async) ------------------------------------------------
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        tenant, scoped = self._scope(config, "aget_tuple()")
+        return self._unscope_tuple(tenant, await self.inner.aget_tuple(scoped))
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        if config is None:
+            raise UnscopedAccessError(
+                "alist(None) would enumerate every tenant's threads; "
+                "pass a config with tenant_id (and optionally thread_id)."
+            )
+        tenant, scoped = self._scope(config, "alist()")
+        scoped_before = self._scope(before, "alist(before=...)")[1] if before else None
+        async for tup in self.inner.alist(
+            scoped, filter=filter, before=scoped_before, limit=limit
+        ):
+            yield self._unscope_tuple(tenant, tup)
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        tenant, scoped = self._scope(config, "aput()")
+        if self.usage_ledger is not None:
+            for record in extract_usage(checkpoint):
+                self.usage_ledger.record(tenant, record)
+        result = await self.inner.aput(scoped, checkpoint, metadata, new_versions)
+        return self._unscope_config(tenant, result)
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        _, scoped = self._scope(config, "aput_writes()")
+        await self.inner.aput_writes(scoped, writes, task_id, task_path)
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        self.delete_thread(thread_id)
+
+
+class TenantCheckpointerHandle:
+    """Maintenance operations pre-bound to a single tenant.
+
+    Exists because `BaseCheckpointSaver.delete_thread/copy_thread/prune` take
+    bare thread ids with no config, so there is no per-call tenant to read.
+    """
+
+    def __init__(self, parent: TenantScopedCheckpointer, tenant: str) -> None:
+        self._inner = parent.inner
+        self._tenant = tenant
+
+    def _scoped(self, thread_id: str) -> str:
+        return f"{self._tenant}{SEP}{thread_id}"
+
+    def delete_thread(self, thread_id: str) -> None:
+        self._inner.delete_thread(self._scoped(thread_id))
+
+    def copy_thread(self, source_thread_id: str, target_thread_id: str) -> None:
+        self._inner.copy_thread(
+            self._scoped(source_thread_id), self._scoped(target_thread_id)
+        )
+
+    def prune(
+        self, thread_ids: Sequence[str], *, strategy: str = "keep_latest"
+    ) -> None:
+        self._inner.prune([self._scoped(t) for t in thread_ids], strategy=strategy)

langgraph_tenancy-0.1.0/langgraph_tenancy/_errors.py

@@ -0,0 +1,39 @@
+"""Errors raised by langgraph-tenancy.
+
+Every error here exists to turn a silent cross-tenant leak into a loud failure.
+"""
+
+
+class TenancyError(Exception):
+    """Base class for all tenancy errors."""
+
+
+class TenantRequiredError(TenancyError):
+    """Raised when an operation runs without a tenant_id in scope.
+
+    The wrapper never falls back to an unscoped read or write: no tenant, no data.
+    """
+
+    def __init__(self, where: str) -> None:
+        super().__init__(
+            f"{where} requires a tenant. Pass it in the run config: "
+            "config={'configurable': {'thread_id': ..., 'tenant_id': ...}} "
+            "or use .for_tenant(tenant_id) for out-of-band access."
+        )
+
+
+class UnscopedAccessError(TenancyError):
+    """Raised for operations that would touch data across tenant boundaries.
+
+    Example: `checkpointer.list(None)` on a raw saver enumerates every
+    customer's threads. This wrapper refuses that call instead.
+    """
+
+
+class InvalidTenantError(TenancyError):
+    """Raised when a tenant_id could be used to escape its scope.
+
+    The tenant id becomes part of storage keys, so it must not contain the
+    separator (or be empty) — otherwise tenant "a" could craft ids that
+    collide with tenant "a::b".
+    """

langgraph_tenancy-0.1.0/langgraph_tenancy/_store.py

@@ -0,0 +1,124 @@
+"""Tenant-scoped wrapper around any `BaseStore`.
+
+Raw `BaseStore` namespaces are pure convention — any caller can `get()`,
+`search()`, or `list_namespaces()` across all of them. This wrapper prepends
+the tenant id as the root namespace segment on every operation and strips it
+from every result, so two tenants using the identical namespace tuple
+(e.g. ``("memories",)``) land in physically distinct locations.
+
+Tenant resolution, in order:
+1. A pinned tenant from `.for_tenant(tenant_id)` (out-of-band/admin access).
+2. The ambient run config via `langgraph.config.get_config()` — inside a node,
+   the `tenant_id` you passed to `graph.invoke(...)` is picked up automatically.
+3. Otherwise: `TenantRequiredError`. Never an unscoped operation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    ListNamespacesOp,
+    MatchCondition,
+    Op,
+    PutOp,
+    Result,
+    SearchOp,
+)
+
+from langgraph_tenancy._errors import InvalidTenantError, TenantRequiredError
+
+SEP = "::"
+
+
+class TenantScopedStore(BaseStore):
+    def __init__(self, inner: BaseStore, *, _tenant: str | None = None) -> None:
+        self.inner = inner
+        self._tenant = _tenant
+
+    def for_tenant(self, tenant_id: str) -> TenantScopedStore:
+        """A view of the store pinned to one tenant, for use outside a run."""
+        self._validate(tenant_id)
+        return TenantScopedStore(self.inner, _tenant=tenant_id)
+
+    # -- tenant resolution ----------------------------------------------------
+
+    @staticmethod
+    def _validate(tenant: Any) -> str:
+        if not isinstance(tenant, str) or not tenant:
+            raise TenantRequiredError("store access")
+        if SEP in tenant:
+            raise InvalidTenantError(f"tenant_id may not contain '{SEP}': {tenant!r}")
+        return tenant
+
+    def _current_tenant(self) -> str:
+        if self._tenant is not None:
+            return self._tenant
+        try:
+            from langgraph.config import get_config
+
+            config = get_config()
+        except Exception:
+            config = None
+        tenant = ((config or {}).get("configurable") or {}).get("tenant_id")
+        return self._validate(tenant)
+
+    # -- op rewriting -----------------------------------------------------------
+
+    def _scope_op(self, tenant: str, op: Op) -> Op:
+        if isinstance(op, (GetOp, PutOp)):
+            return op._replace(namespace=(tenant, *op.namespace))
+        if isinstance(op, SearchOp):
+            return op._replace(namespace_prefix=(tenant, *op.namespace_prefix))
+        if isinstance(op, ListNamespacesOp):
+            conditions = list(op.match_conditions or ())
+            for i, cond in enumerate(conditions):
+                if cond.match_type == "prefix":
+                    conditions[i] = MatchCondition(
+                        match_type="prefix", path=(tenant, *cond.path)
+                    )
+                    break
+            else:
+                conditions.insert(
+                    0, MatchCondition(match_type="prefix", path=(tenant,))
+                )
+            return op._replace(
+                match_conditions=tuple(conditions),
+                max_depth=None if op.max_depth is None else op.max_depth + 1,
+            )
+        raise TypeError(f"unsupported op: {op!r}")
+
+    def _unscope_result(self, tenant: str, op: Op, result: Result) -> Result:
+        if isinstance(op, GetOp) and result is not None:
+            result.namespace = tuple(result.namespace[1:])
+            return result
+        if isinstance(op, SearchOp):
+            for item in result:
+                item.namespace = tuple(item.namespace[1:])
+            return result
+        if isinstance(op, ListNamespacesOp):
+            return [tuple(ns[1:]) for ns in result if ns and ns[0] == tenant]
+        return result
+
+    # -- BaseStore protocol -------------------------------------------------------
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        tenant = self._current_tenant()
+        ops = list(ops)
+        results = self.inner.batch([self._scope_op(tenant, op) for op in ops])
+        return [
+            self._unscope_result(tenant, op, result)
+            for op, result in zip(ops, results, strict=True)
+        ]
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Result]:
+        tenant = self._current_tenant()
+        ops = list(ops)
+        results = await self.inner.abatch([self._scope_op(tenant, op) for op in ops])
+        return [
+            self._unscope_result(tenant, op, result)
+            for op, result in zip(ops, results, strict=True)
+        ]

langgraph_tenancy-0.1.0/langgraph_tenancy/_usage.py

@@ -0,0 +1,95 @@
+"""Per-tenant token usage, extracted at the checkpoint boundary.
+
+LangGraph already persists `usage_metadata` on every AI message inside
+`checkpoint["channel_values"]` — it is just never indexed or aggregated.
+Since the tenant-scoped checkpointer sees every checkpoint anyway, it can
+pull usage out and attribute it to the tenant for free.
+
+Messages are deduplicated by message id, so re-checkpointing the same
+conversation does not double-count.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class UsageRecord:
+    message_id: str
+    model: str | None
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+
+
+class UsageLedger(Protocol):
+    """Anything that can receive per-tenant usage records.
+
+    Swap the in-memory default for one backed by your own Postgres table,
+    StatsD, OpenMeter, etc.
+    """
+
+    def record(self, tenant_id: str, record: UsageRecord) -> None: ...
+
+
+@dataclass
+class TenantUsage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    messages: int = 0
+    by_model: dict[str, int] = field(default_factory=lambda: defaultdict(int))
+
+
+class InMemoryUsageLedger:
+    """Reference ledger: per-tenant totals, deduped by message id."""
+
+    def __init__(self) -> None:
+        self._seen: set[tuple[str, str]] = set()
+        self._totals: dict[str, TenantUsage] = defaultdict(TenantUsage)
+        self._lock = Lock()
+
+    def record(self, tenant_id: str, record: UsageRecord) -> None:
+        with self._lock:
+            key = (tenant_id, record.message_id)
+            if key in self._seen:
+                return
+            self._seen.add(key)
+            usage = self._totals[tenant_id]
+            usage.input_tokens += record.input_tokens
+            usage.output_tokens += record.output_tokens
+            usage.total_tokens += record.total_tokens
+            usage.messages += 1
+            if record.model:
+                usage.by_model[record.model] += record.total_tokens
+
+    def totals(self, tenant_id: str) -> TenantUsage:
+        with self._lock:
+            return self._totals[tenant_id]
+
+
+def extract_usage(checkpoint: dict[str, Any]) -> list[UsageRecord]:
+    """Pull usage records out of message objects in a checkpoint's channels."""
+    records: list[UsageRecord] = []
+    for value in (checkpoint.get("channel_values") or {}).values():
+        items = value if isinstance(value, (list, tuple)) else [value]
+        for item in items:
+            usage = getattr(item, "usage_metadata", None)
+            message_id = getattr(item, "id", None)
+            if not usage or not message_id:
+                continue
+            model = (getattr(item, "response_metadata", None) or {}).get("model_name")
+            records.append(
+                UsageRecord(
+                    message_id=message_id,
+                    model=model,
+                    input_tokens=usage.get("input_tokens", 0),
+                    output_tokens=usage.get("output_tokens", 0),
+                    total_tokens=usage.get("total_tokens", 0),
+                )
+            )
+    return records

langgraph_tenancy-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "langgraph-tenancy"
+version = "0.1.0"
+description = "Tenant isolation and per-tenant usage metering for LangGraph checkpointers and stores"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Abhishek Chauhan", email = "ac12644@gmail.com" }]
+keywords = [
+    "langgraph",
+    "multi-tenant",
+    "tenant-isolation",
+    "checkpointer",
+    "agents",
+    "llm",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Security",
+]
+dependencies = [
+    "langgraph-checkpoint>=2.0.0",
+    "langchain-core>=0.2.38",
+]
+
+[project.urls]
+Source = "https://github.com/ac12644/langgraph-tenancy"
+Issues = "https://github.com/ac12644/langgraph-tenancy/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "langgraph>=0.4",
+    "langgraph-checkpoint-postgres>=2.0.0",
+    "psycopg[binary]>=3.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langgraph_tenancy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

langgraph_tenancy-0.1.0/tests/conftest.py

@@ -0,0 +1,53 @@
+"""Checkpointer backends for the isolation suite.
+
+Every checkpointer test runs against each backend, so the isolation
+guarantees are proven on real storage, not just the in-memory reference.
+Postgres tests skip automatically if no server is reachable.
+"""
+
+import os
+
+import pytest
+
+PG_URI = os.environ.get(
+    "LG_TENANCY_PG_URI",
+    "postgresql://postgres:postgres@localhost:5432/langgraph_tenancy_test",
+)
+# In CI we want a missing database to FAIL the postgres leg, not skip it —
+# otherwise a service misconfiguration silently halves the suite.
+PG_REQUIRED = os.environ.get("LG_TENANCY_PG_REQUIRED") == "1"
+
+
+@pytest.fixture(params=["memory", "postgres"])
+def make_inner(request):
+    """Factory producing fresh inner savers on a clean backend."""
+    if request.param == "memory":
+        from langgraph.checkpoint.memory import InMemorySaver
+
+        yield InMemorySaver
+        return
+
+    psycopg = pytest.importorskip("psycopg")
+    from langgraph.checkpoint.postgres import PostgresSaver
+    from psycopg.rows import dict_row
+
+    try:
+        conn = psycopg.Connection.connect(
+            PG_URI, autocommit=True, prepare_threshold=0, row_factory=dict_row
+        )
+    except Exception as exc:  # pragma: no cover - environment dependent
+        if PG_REQUIRED:
+            raise
+        pytest.skip(f"postgres unavailable: {exc}")
+
+    PostgresSaver(conn).setup()
+    # clean slate per test (keep the migrations table)
+    tables = conn.execute(
+        "select tablename from pg_tables where schemaname='public' "
+        "and tablename like 'checkpoint%' and tablename not like '%migrations'"
+    ).fetchall()
+    for row in tables:
+        conn.execute(f'TRUNCATE "{row["tablename"]}"')
+
+    yield lambda: PostgresSaver(conn)
+    conn.close()

langgraph_tenancy-0.1.0/tests/test_isolation.py

@@ -0,0 +1,180 @@
+"""Adversarial isolation tests.
+
+Every test here attempts a cross-tenant access the raw LangGraph API allows,
+and asserts the wrapper makes it either impossible or an explicit error.
+Run against the real InMemorySaver/InMemoryStore from langgraph.
+"""
+
+import operator
+from typing import Annotated, TypedDict
+from uuid import uuid4
+
+import pytest
+from langchain_core.messages import AIMessage
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.config import get_store
+from langgraph.graph import StateGraph
+from langgraph.store.memory import InMemoryStore
+
+from langgraph_tenancy import (
+    InMemoryUsageLedger,
+    InvalidTenantError,
+    TenantRequiredError,
+    TenantScopedCheckpointer,
+    TenantScopedStore,
+    UnscopedAccessError,
+)
+
+
+class State(TypedDict):
+    messages: Annotated[list, operator.add]
+
+
+def make_graph(checkpointer, store=None, model_name="claude-sonnet-4-6"):
+    """One-node graph that fakes an LLM reply (with usage) and writes a memory."""
+
+    def agent(state: State) -> State:
+        # real chat models always set an id; the ledger dedupes on it
+        reply = AIMessage(
+            id=str(uuid4()),
+            content=f"echo: {state['messages'][-1]}",
+            usage_metadata={
+                "input_tokens": 10,
+                "output_tokens": 5,
+                "total_tokens": 15,
+            },
+            response_metadata={"model_name": model_name},
+        )
+        if store is not None:
+            get_store().put(
+                ("memories",),
+                f"note-{len(state['messages'])}",
+                {"last": str(state["messages"][-1])},
+            )
+        return {"messages": [reply]}
+
+    builder = StateGraph(State)
+    builder.add_node("agent", agent)
+    builder.set_entry_point("agent")
+    builder.set_finish_point("agent")
+    return builder.compile(checkpointer=checkpointer, store=store)
+
+
+def cfg(tenant, thread="t1"):
+    return {"configurable": {"thread_id": thread, "tenant_id": tenant}}
+
+
+# --- checkpointer isolation ---------------------------------------------------
+
+
+def test_same_thread_id_different_tenants_do_not_collide(make_inner):
+    graph = make_graph(TenantScopedCheckpointer(make_inner()))
+    graph.invoke({"messages": ["from acme"]}, cfg("acme"))
+    graph.invoke({"messages": ["from globex"]}, cfg("globex"))
+
+    acme = graph.get_state(cfg("acme")).values["messages"]
+    globex = graph.get_state(cfg("globex")).values["messages"]
+    assert acme[0] == "from acme" and len(acme) == 2
+    assert globex[0] == "from globex" and len(globex) == 2
+    assert not any("globex" in str(m) for m in acme)
+
+
+def test_missing_tenant_id_raises_instead_of_leaking(make_inner):
+    graph = make_graph(TenantScopedCheckpointer(make_inner()))
+    with pytest.raises(TenantRequiredError):
+        graph.invoke({"messages": ["hi"]}, {"configurable": {"thread_id": "t1"}})
+
+
+def test_tenant_id_cannot_contain_separator(make_inner):
+    graph = make_graph(TenantScopedCheckpointer(make_inner()))
+    with pytest.raises(InvalidTenantError):
+        graph.invoke({"messages": ["hi"]}, cfg("acme::evil"))
+
+
+def test_list_none_is_refused(make_inner):
+    saver = TenantScopedCheckpointer(make_inner())
+    make_graph(saver).invoke({"messages": ["hi"]}, cfg("acme"))
+    with pytest.raises(UnscopedAccessError):
+        list(saver.list(None))
+
+
+def test_list_only_sees_own_tenant(make_inner):
+    saver = TenantScopedCheckpointer(make_inner())
+    graph = make_graph(saver)
+    graph.invoke({"messages": ["a"]}, cfg("acme"))
+    graph.invoke({"messages": ["b"]}, cfg("globex"))
+
+    seen = [t.config["configurable"]["thread_id"] for t in saver.list(cfg("acme"))]
+    assert seen and all(t == "t1" for t in seen)
+    values = [t for t in saver.list(cfg("acme"))]
+    assert not any("globex" in str(t.checkpoint.get("channel_values")) for t in values)
+
+
+def test_delete_thread_requires_tenant_handle(make_inner):
+    saver = TenantScopedCheckpointer(make_inner())
+    graph = make_graph(saver)
+    graph.invoke({"messages": ["a"]}, cfg("acme"))
+    graph.invoke({"messages": ["b"]}, cfg("globex"))
+
+    with pytest.raises(UnscopedAccessError):
+        saver.delete_thread("t1")
+
+    saver.for_tenant("acme").delete_thread("t1")
+    assert saver.get_tuple(cfg("acme")) is None
+    assert saver.get_tuple(cfg("globex")) is not None  # other tenant untouched
+
+
+def test_storage_keys_are_physically_tenant_prefixed(make_inner):
+    inner = make_inner()
+    make_graph(TenantScopedCheckpointer(inner)).invoke({"messages": ["a"]}, cfg("acme"))
+    raw_threads = {t.config["configurable"]["thread_id"] for t in inner.list(None)}
+    assert raw_threads == {"acme::t1"}
+
+
+# --- store isolation ----------------------------------------------------------
+
+
+def test_store_namespaces_are_isolated_per_tenant():
+    store = TenantScopedStore(InMemoryStore())
+    graph = make_graph(TenantScopedCheckpointer(InMemorySaver()), store=store)
+    graph.invoke({"messages": ["secret-acme"]}, cfg("acme"))
+    graph.invoke({"messages": ["secret-globex"]}, cfg("globex"))
+
+    acme_items = store.for_tenant("acme").search(("memories",))
+    globex_items = store.for_tenant("globex").search(("memories",))
+    assert [i.value["last"] for i in acme_items] == ["secret-acme"]
+    assert [i.value["last"] for i in globex_items] == ["secret-globex"]
+    # returned namespaces are unprefixed — the tenant segment never leaks out
+    assert acme_items[0].namespace == ("memories",)
+
+
+def test_store_outside_run_without_tenant_raises():
+    store = TenantScopedStore(InMemoryStore())
+    with pytest.raises(TenantRequiredError):
+        store.search(("memories",))
+
+
+def test_list_namespaces_only_sees_own_tenant():
+    store = TenantScopedStore(InMemoryStore())
+    store.for_tenant("acme").put(("memories", "work"), "k", {"v": 1})
+    store.for_tenant("globex").put(("memories", "home"), "k", {"v": 2})
+    assert store.for_tenant("acme").list_namespaces() == [("memories", "work")]
+
+
+# --- usage metering -------------------------------------------------------------
+
+
+def test_usage_attributed_per_tenant_and_deduped(make_inner):
+    ledger = InMemoryUsageLedger()
+    graph = make_graph(TenantScopedCheckpointer(make_inner(), usage_ledger=ledger))
+
+    graph.invoke({"messages": ["q1"]}, cfg("acme"))
+    graph.invoke({"messages": ["q2"]}, cfg("acme"))  # 2nd turn, same thread
+    graph.invoke({"messages": ["q1"]}, cfg("globex"))
+
+    acme, globex = ledger.totals("acme"), ledger.totals("globex")
+    # two LLM calls for acme, one for globex; old messages re-checkpointed
+    # on turn 2 must not double-count
+    assert acme.messages == 2 and acme.total_tokens == 30
+    assert globex.messages == 1 and globex.total_tokens == 15
+    assert acme.by_model == {"claude-sonnet-4-6": 30}