langgraph-checkpoint-tigris 0.1.0__tar.gz

langgraph_checkpoint_tigris-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.ty_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+</content>

langgraph_checkpoint_tigris-0.1.0/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS Instructions — checkpoint-tigris
+
+`langgraph-checkpoint-tigris`: a `BaseCheckpointSaver` backed by Tigris object
+storage (S3 API), with a zero-copy bucket-fork helper for instant branching.
+
+## What this package is
+
+- A standalone checkpointer backend, parallel to `checkpoint-postgres` and
+  `checkpoint-sqlite`. It depends only on `langgraph-checkpoint` (the base
+  interface). Core `langgraph` is not modified.
+- Sync saver: `langgraph.checkpoint.tigris.TigrisSaver`.
+- Async saver: `langgraph.checkpoint.tigris.aio.AsyncTigrisSaver`.
+- Fork helper: `TigrisSaver.fork(target_bucket)` →
+  `langgraph/checkpoint/tigris/_fork.py`.
+
+## Layout
+
+```
+langgraph/checkpoint/tigris/
+  __init__.py   # TigrisSaver (sync) + fork()
+  aio.py        # AsyncTigrisSaver (aioboto3)
+  _keys.py      # pure object-key layout helpers (unit-tested, no network)
+  _client.py    # boto3 / aioboto3 client construction (endpoint: t3.storage.dev)
+  _fork.py      # X-Tigris-Fork-Source-Bucket fork helper
+  utils.py      # manifest (de)serialization + filter matching
+tests/          # test_keys (offline) + conformance/integration/fork (live)
+```
+
+## Design invariants (don't break these)
+
+- Checkpoints are immutable and uniquely keyed by
+  `(thread_id, checkpoint_ns, checkpoint_id)`; `checkpoint_id` is time-sortable
+  so "latest" = `max()` over a prefix listing (no mutable HEAD pointer).
+- Requires a **Single-region or Multi-region** bucket for strong consistency.
+- Conditional writes (`If-Match` / `If-None-Match`) are for idempotency/CAS only.
+
+## Workflow (run inside this dir)
+
+```bash
+uv sync
+make format
+make lint        # ruff + ty
+make test        # offline unit tests; live tests auto-skip without creds
+```
+
+Live conformance/integration/fork tests need `TIGRIS_TEST_BUCKET`,
+`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (optional `TIGRIS_ENDPOINT_URL`).
+
+## Source of truth
+
+The LangGraph checkpointer conformance suite (`langgraph-checkpoint-conformance`,
+installed from PyPI) is the primary correctness gate: `report.passed_all_base()`
+must be True, and the `copy_thread` capability must be detected and pass. The
+live conformance/integration/fork tests live in `tests/` and run only when
+Tigris credentials are present in the environment.
+
+Formatting: use single backticks for inline code in docstrings/comments (no
+Sphinx-style double backticks).

langgraph_checkpoint_tigris-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tigris Data, Inc.
+
+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_checkpoint_tigris-0.1.0/Makefile

@@ -0,0 +1,37 @@
+.PHONY: test test_watch lint type format
+
+######################
+# TESTING AND COVERAGE
+######################
+
+TEST ?= .
+
+test:
+	uv run pytest $(TEST)
+
+test_watch:
+	uv run ptw $(TEST)
+
+######################
+# LINTING AND FORMATTING
+######################
+
+# Define a variable for Python and notebook files.
+PYTHON_FILES=.
+lint format: PYTHON_FILES=.
+lint_diff format_diff: PYTHON_FILES=$(shell git diff --name-only --relative --diff-filter=d main . | grep -E '\.py$$|\.ipynb$$')
+lint_package: PYTHON_FILES=langgraph
+lint_tests: PYTHON_FILES=tests
+
+lint lint_diff lint_package lint_tests:
+	uv run ruff check .
+	[ "$(PYTHON_FILES)" = "" ] || uv run ruff format $(PYTHON_FILES) --diff
+	[ "$(PYTHON_FILES)" = "" ] || uv run ruff check --select I $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run ty check $(PYTHON_FILES)
+
+type:
+	uv run ty check $(PYTHON_FILES)
+
+format format_diff:
+	uv run ruff format $(PYTHON_FILES)
+	uv run ruff check --select I --fix $(PYTHON_FILES)

langgraph_checkpoint_tigris-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: langgraph-checkpoint-tigris
+Version: 0.1.0
+Summary: Library with a Tigris object-storage implementation of LangGraph checkpoint saver, with zero-copy bucket-fork branching.
+Project-URL: Homepage, https://www.tigrisdata.com/
+Project-URL: Source, https://github.com/tigrisdata/tigris-langgraph/tree/main/libs/checkpoint-tigris
+Project-URL: Documentation, https://www.tigrisdata.com/docs/
+Author: Tigris Data, Inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,checkpoint,langchain,langgraph,s3,tigris
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: aioboto3>=12.3
+Requires-Dist: boto3>=1.34
+Requires-Dist: langgraph-checkpoint<5.0.0,>=4.1.0
+Description-Content-Type: text/markdown
+
+# LangGraph Tigris Checkpoint
+
+Implementation of a LangGraph `BaseCheckpointSaver` that persists agent state in
+[Tigris](https://www.tigrisdata.com/) globally-distributed object storage over
+the S3 API (sync and async), plus a **zero-copy bucket-fork** helper for instant
+branching of an entire thread's checkpoint lineage.
+
+## Why Tigris
+
+- **Durable, global, cheap state** — checkpoints live in globally-replicated
+  object storage with no egress fees.
+- **Instant branching** — `fork()` creates a zero-copy fork of the bucket, so an
+  agent's entire checkpoint history can be branched in O(1) for parallel
+  experiments, evals, or what-if exploration. Writes to the fork are isolated
+  from the source.
+- **Pure object store** — no separate database to operate. "Latest checkpoint"
+  is found via a sorted list under strong consistency; conditional writes are
+  available for idempotency/CAS.
+
+## Bucket requirement
+
+> Use a **Single-region** or **Multi-region** Tigris bucket. These provide
+> strong, globally consistent reads, lists, and conditional operations, which
+> this saver relies on. **Global** and **Dual-region** buckets give only
+> eventual cross-region consistency and can return stale "latest" results.
+
+## Install
+
+```bash
+pip install langgraph-checkpoint-tigris
+```
+
+## Usage
+
+```python
+from langgraph.checkpoint.tigris import TigrisSaver
+
+# Credentials from the standard AWS env chain
+# (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY), endpoint defaults to Tigris.
+with TigrisSaver.from_conn_string("my-bucket") as checkpointer:
+    checkpointer.setup()
+    graph = builder.compile(checkpointer=checkpointer)
+    graph.invoke({"messages": [...]}, {"configurable": {"thread_id": "1"}})
+```
+
+Async:
+
+```python
+from langgraph.checkpoint.tigris.aio import AsyncTigrisSaver
+
+async with AsyncTigrisSaver.from_conn_string("my-bucket") as checkpointer:
+    await checkpointer.setup()
+    graph = builder.compile(checkpointer=checkpointer)
+    await graph.ainvoke({"messages": [...]}, {"configurable": {"thread_id": "1"}})
+```
+
+## Instant branching with forks
+
+```python
+with TigrisSaver.from_conn_string("prod-agent-state") as checkpointer:
+    # Branch the ENTIRE bucket (all threads/checkpoints) instantly.
+    experiment = checkpointer.fork("experiment-run-42")
+    # `experiment` is an isolated TigrisSaver; writes here never touch prod.
+```
+
+## Object layout
+
+```
+{prefix}checkpoints/{thread}/{ns}/{checkpoint_id}/manifest.json
+{prefix}checkpoints/{thread}/{ns}/{checkpoint_id}/checkpoint.bin
+{prefix}checkpoints/{thread}/{ns}/{checkpoint_id}/writes/{task_id}/{idx}.bin
+```
+
+Checkpoints are immutable and uniquely keyed; `checkpoint_id`s are time-sortable
+so the latest is `max(...)` of a prefix listing — no mutable HEAD pointer.
+
+## Development
+
+```bash
+cd libs/checkpoint-tigris
+uv sync
+make format && make lint && make test         # unit tests run without creds
+
+# Full suite (conformance + integration + fork) needs a live Tigris bucket:
+TIGRIS_TEST_BUCKET=my-bucket \
+AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... \
+make test
+```
+
+Integration, conformance, and fork tests are skipped automatically when those
+environment variables are absent. The pure key-layout unit tests
+(`tests/test_keys.py`) always run.
+
+## Status
+
+The synchronous and asynchronous savers, the `copy_thread`/`acopy_thread`
+branching capability, and the zero-copy `fork()` helper are implemented and
+pass the LangGraph checkpointer conformance suite
+(`langgraph-checkpoint-conformance`) against a live Tigris bucket. The pure
+key-layout and manifest logic are additionally unit-tested offline.

langgraph_checkpoint_tigris-0.1.0/README.md

@@ -0,0 +1,100 @@
+# LangGraph Tigris Checkpoint
+
+Implementation of a LangGraph `BaseCheckpointSaver` that persists agent state in
+[Tigris](https://www.tigrisdata.com/) globally-distributed object storage over
+the S3 API (sync and async), plus a **zero-copy bucket-fork** helper for instant
+branching of an entire thread's checkpoint lineage.
+
+## Why Tigris
+
+- **Durable, global, cheap state** — checkpoints live in globally-replicated
+  object storage with no egress fees.
+- **Instant branching** — `fork()` creates a zero-copy fork of the bucket, so an
+  agent's entire checkpoint history can be branched in O(1) for parallel
+  experiments, evals, or what-if exploration. Writes to the fork are isolated
+  from the source.
+- **Pure object store** — no separate database to operate. "Latest checkpoint"
+  is found via a sorted list under strong consistency; conditional writes are
+  available for idempotency/CAS.
+
+## Bucket requirement
+
+> Use a **Single-region** or **Multi-region** Tigris bucket. These provide
+> strong, globally consistent reads, lists, and conditional operations, which
+> this saver relies on. **Global** and **Dual-region** buckets give only
+> eventual cross-region consistency and can return stale "latest" results.
+
+## Install
+
+```bash
+pip install langgraph-checkpoint-tigris
+```
+
+## Usage
+
+```python
+from langgraph.checkpoint.tigris import TigrisSaver
+
+# Credentials from the standard AWS env chain
+# (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY), endpoint defaults to Tigris.
+with TigrisSaver.from_conn_string("my-bucket") as checkpointer:
+    checkpointer.setup()
+    graph = builder.compile(checkpointer=checkpointer)
+    graph.invoke({"messages": [...]}, {"configurable": {"thread_id": "1"}})
+```
+
+Async:
+
+```python
+from langgraph.checkpoint.tigris.aio import AsyncTigrisSaver
+
+async with AsyncTigrisSaver.from_conn_string("my-bucket") as checkpointer:
+    await checkpointer.setup()
+    graph = builder.compile(checkpointer=checkpointer)
+    await graph.ainvoke({"messages": [...]}, {"configurable": {"thread_id": "1"}})
+```
+
+## Instant branching with forks
+
+```python
+with TigrisSaver.from_conn_string("prod-agent-state") as checkpointer:
+    # Branch the ENTIRE bucket (all threads/checkpoints) instantly.
+    experiment = checkpointer.fork("experiment-run-42")
+    # `experiment` is an isolated TigrisSaver; writes here never touch prod.
+```
+
+## Object layout
+
+```
+{prefix}checkpoints/{thread}/{ns}/{checkpoint_id}/manifest.json
+{prefix}checkpoints/{thread}/{ns}/{checkpoint_id}/checkpoint.bin
+{prefix}checkpoints/{thread}/{ns}/{checkpoint_id}/writes/{task_id}/{idx}.bin
+```
+
+Checkpoints are immutable and uniquely keyed; `checkpoint_id`s are time-sortable
+so the latest is `max(...)` of a prefix listing — no mutable HEAD pointer.
+
+## Development
+
+```bash
+cd libs/checkpoint-tigris
+uv sync
+make format && make lint && make test         # unit tests run without creds
+
+# Full suite (conformance + integration + fork) needs a live Tigris bucket:
+TIGRIS_TEST_BUCKET=my-bucket \
+AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... \
+make test
+```
+
+Integration, conformance, and fork tests are skipped automatically when those
+environment variables are absent. The pure key-layout unit tests
+(`tests/test_keys.py`) always run.
+
+## Status
+
+The synchronous and asynchronous savers, the `copy_thread`/`acopy_thread`
+branching capability, and the zero-copy `fork()` helper are implemented and
+pass the LangGraph checkpointer conformance suite
+(`langgraph-checkpoint-conformance`) against a live Tigris bucket. The pure
+key-layout and manifest logic are additionally unit-tested offline.