langgraph-checkpointer-couchbase 1.0.9__tar.gz → 2.0.0__tar.gz

langgraph_checkpointer_couchbase-2.0.0/.github/workflows/ci.yaml

@@ -0,0 +1,95 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    services:
+      couchbase:
+        image: couchbase:enterprise-7.6.4
+        ports:
+          - 8091-8096:8091-8096
+          - 11210:11210
+    env:
+      CB_CLUSTER: couchbase://localhost
+      CB_USERNAME: Administrator
+      CB_PASSWORD: password
+      CB_BUCKET: test
+      CB_SCOPE: langgraph
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Dependencies
+        run: pip install -e . pytest pytest-asyncio hatch
+
+      - name: Initialize Couchbase
+        env:
+          CB_CONTAINER: ${{ job.services.couchbase.id }}
+        run: |
+          for i in $(seq 1 60); do
+            curl -sf http://localhost:8091/ui/index.html > /dev/null && break
+            sleep 2
+          done
+          cli() { docker exec "$CB_CONTAINER" couchbase-cli "$@" -c localhost; }
+          cli cluster-init --cluster-username "$CB_USERNAME" --cluster-password "$CB_PASSWORD" \
+            --services data,index,query --cluster-ramsize 1024 --cluster-index-ramsize 256
+          cli bucket-create -u "$CB_USERNAME" -p "$CB_PASSWORD" --bucket "$CB_BUCKET" \
+            --bucket-type couchbase --bucket-ramsize 256 --wait
+          cli collection-manage -u "$CB_USERNAME" -p "$CB_PASSWORD" --bucket "$CB_BUCKET" --create-scope "$CB_SCOPE"
+
+      # A freshly initialized node can reject queries for a short while.
+      - name: Wait for Couchbase Query Service
+        shell: python
+        run: |
+          import os, time
+          from langgraph_checkpointer_couchbase import CouchbaseSaver
+
+          deadline = time.time() + 180
+          while True:
+              try:
+                  with CouchbaseSaver.from_conn_info(
+                      cb_conn_str=os.environ["CB_CLUSTER"],
+                      cb_username=os.environ["CB_USERNAME"],
+                      cb_password=os.environ["CB_PASSWORD"],
+                      bucket_name=os.environ["CB_BUCKET"],
+                      scope_name=os.environ["CB_SCOPE"],
+                  ) as saver:
+                      saver.get_tuple({"configurable": {"thread_id": "ci-readiness"}})
+                  print("Couchbase query service is ready")
+                  break
+              except Exception as e:
+                  if time.time() > deadline:
+                      raise
+                  print(f"Waiting for Couchbase: {type(e).__name__}")
+                  time.sleep(3)
+
+      - name: Create Checkpoint Indexes
+        run: |
+          for c in checkpoints checkpoint_writes; do
+            curl -sf -u "$CB_USERNAME:$CB_PASSWORD" http://localhost:8093/query/service \
+              --data-urlencode "statement=CREATE INDEX idx_${c}_thread IF NOT EXISTS ON \`$CB_BUCKET\`.\`$CB_SCOPE\`.\`$c\`(thread_id, checkpoint_ns, checkpoint_id)"
+          done
+
+      - name: Run Tests
+        run: pytest tests/test_checkpointer.py tests/test_python_version_guard.py -v
+
+      - name: Hatch build
+        run: hatch build

{langgraph_checkpointer_couchbase-1.0.9 → langgraph_checkpointer_couchbase-2.0.0}/.github/workflows/release.yaml

@@ -13,10 +13,10 @@ jobs:
       contents: write
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 
@@ -34,7 +34,7 @@ jobs:
 
       - name: Create GitHub Release
         id: create_release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.ref_name }} 
           draft: false

langgraph_checkpointer_couchbase-2.0.0/AGENTS.md

@@ -0,0 +1,30 @@
+# Agent Notes
+
+- Packaging uses hatch/pip (`pyproject.toml`, `hatchling`). Do not add a lockfile or switch package managers.
+- PR validation is `.github/workflows/ci.yaml`: it starts a Couchbase container, creates the bucket/scope, creates the recommended indexes, runs `pytest tests/test_checkpointer.py`, then `hatch build`.
+- Local validation needs a Couchbase cluster with an existing bucket and scope (see "Running the Tests" in `README.md`). The saver creates its own collections but not indexes; without the README indexes, sequential-scan reads can miss just-written checkpoints and tests flake.
+- `tests/agent_e2e_test.py` is the README agent flow and needs `OPENAI_API_KEY`; it is not run in CI.
+
+## Release Process
+
+Maintainers release this package in two steps:
+
+1. A PR bumps `__version__` in `langgraph_checkpointer_couchbase/__about__.py`.
+2. After that PR merges, a maintainer runs the **Publish Package to PyPI** workflow (`.github/workflows/release.yaml`) from the Actions tab on `main`. It builds with hatch, publishes to PyPI, and creates a GitHub release. Pushing a `v*` tag also triggers it.
+
+Agents prepare step 1 only. Do not create tags or releases, and do not dispatch the release workflow.
+
+### Version bumps in dependency upgrade PRs
+
+Any PR that changes `dependencies` or `requires-python` in `pyproject.toml`, or changes code to follow a dependency upgrade, must bump `__version__` in the same PR. The maintainer can then approve, merge, and run the release workflow without a separate bump PR.
+
+- Check the current release first (`https://pypi.org/pypi/langgraph-checkpointer-couchbase/json`) and bump from that version. Never reuse a published version.
+- Pick the level with semver:
+  - **Major** (`X.0.0`): the release stops working for some current users, for example raising `requires-python`, moving a dependency floor across a major version, or changing public API in an incompatible way.
+  - **Minor** (`x.Y.0`): new backward-compatible features.
+  - **Patch** (`x.y.Z`): backward-compatible dependency floor raises and bug fixes.
+- For a major bump, fence the incompatibility so users get a clear error instead of a confusing failure: declare it in `pyproject.toml` (`requires-python`, dependency floors, classifiers) and, where install metadata cannot enforce it, add a runtime check with a message that names the requirement.
+- Put `Make new Release vX.Y.Z` at the start of the PR title so maintainers can tell release PRs apart (for example `Make new Release v1.0.10: bump langgraph floor`).
+- In the PR body, state the old and new version, the bump level and the reason for it, and that a maintainer must run the release workflow after merging.
+
+PRs that only touch CI, docs, or tests do not need a version bump.

{langgraph_checkpointer_couchbase-1.0.9 → langgraph_checkpointer_couchbase-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: langgraph-checkpointer-couchbase
-Version: 1.0.9
+Version: 2.0.0
 Project-URL: Documentation, https://github.com/couchbase-ecosystem/langgraph-checkpointer-couchbase#readme
 Project-URL: Issues, https://github.com/couchbase-ecosystem/langgraph-checkpointer-couchbase/issues
 Project-URL: Source, https://github.com/couchbase-ecosystem/langgraph-checkpointer-couchbase
@@ -10,15 +10,14 @@ License-File: LICENSE
 Keywords: checkpointer,couchbase,langchain,langgraph,persistence
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 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: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.8
-Requires-Dist: couchbase>=4.5.0
+Requires-Python: >=3.10
+Requires-Dist: couchbase>=4.6.3
 Requires-Dist: langchain-openai>=1.1.3
 Requires-Dist: langchain>=1.1.3
 Requires-Dist: langgraph>=1.0.5
@@ -50,10 +49,11 @@ pip install langgraph-checkpointer-couchbase
 
 ## Requirements
 
-- Python 3.8+
+- Python 3.10+
 - Couchbase Server (7.0+ recommended)
-- LangGraph 0.3.22+
-- LangChain OpenAI 0.3.11+
+- Couchbase Python SDK 4.6.3+
+- LangGraph 1.0.5+
+- LangChain 1.1.3+ and LangChain OpenAI 1.1.3+
 
 ## Prerequisites
 
@@ -67,6 +67,7 @@ First, set up your agent tools and model:
 
 ```python
 from typing import Literal
+from langchain_core.tools import tool
 from langchain_openai import ChatOpenAI
 
 @tool
@@ -81,7 +82,7 @@ def get_weather(city: Literal["nyc", "sf"]):
 
 
 tools = [get_weather]
-model = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
+model = ChatOpenAI(model="gpt-5-mini", temperature=0)
 ```
 
 ### Synchronous Usage
@@ -89,7 +90,7 @@ model = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
 ```python
 import os
 from langgraph_checkpointer_couchbase import CouchbaseSaver
-from langgraph.graph import create_react_agent
+from langchain.agents import create_agent
 
 with CouchbaseSaver.from_conn_info(
         cb_conn_str=os.getenv("CB_CLUSTER") or "couchbase://localhost",
@@ -99,7 +100,7 @@ with CouchbaseSaver.from_conn_info(
         scope_name=os.getenv("CB_SCOPE") or "langgraph",
     ) as checkpointer:
     # Create the agent with checkpointing
-    graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)
+    graph = create_agent(model, tools=tools, checkpointer=checkpointer)
     
     # Configure with a unique thread ID
     config = {"configurable": {"thread_id": "1"}}
@@ -125,7 +126,7 @@ from acouchbase.cluster import Cluster as ACluster
 from couchbase.auth import PasswordAuthenticator
 from couchbase.options import ClusterOptions
 from langgraph_checkpointer_couchbase import AsyncCouchbaseSaver
-from langgraph.graph import create_react_agent
+from langchain.agents import create_agent
 
 auth = PasswordAuthenticator(
     os.getenv("CB_USERNAME") or "Administrator",
@@ -143,7 +144,7 @@ async with AsyncCouchbaseSaver.from_cluster(
         scope_name=scope_name,
     ) as checkpointer:
     # Create the agent with checkpointing
-    graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)
+    graph = create_agent(model, tools=tools, checkpointer=checkpointer)
     
     # Configure with a unique thread ID
     config = {"configurable": {"thread_id": "2"}}
@@ -166,6 +167,17 @@ async with AsyncCouchbaseSaver.from_cluster(
 await cluster.close()
 ```
 
+## Recommended Indexes
+
+The saver creates the `checkpoints` and `checkpoint_writes` collections on first use, but not indexes. Without them, queries fall back to sequential scans, which are slow on large collections and may not return a checkpoint written immediately before. Create these indexes once per scope (replace `test` and `langgraph` with your bucket and scope):
+
+```sql
+CREATE INDEX idx_checkpoints_thread IF NOT EXISTS
+  ON `test`.`langgraph`.`checkpoints`(thread_id, checkpoint_ns, checkpoint_id);
+CREATE INDEX idx_checkpoint_writes_thread IF NOT EXISTS
+  ON `test`.`langgraph`.`checkpoint_writes`(thread_id, checkpoint_ns, checkpoint_id);
+```
+
 ## Configuration Options
 
 | Parameter | Description | Default |
@@ -176,6 +188,22 @@ await cluster.close()
 | CB_BUCKET | Bucket to store checkpoints | test |
 | CB_SCOPE | Scope within bucket | langgraph |
 
+## Running the Tests
+
+The checkpointer tests run against a live Couchbase cluster and do not need an LLM. Create the bucket, scope, and the [recommended indexes](#recommended-indexes) first, then:
+
+```bash
+pip install -e . pytest pytest-asyncio
+export CB_CLUSTER=couchbase://localhost CB_USERNAME=Administrator CB_PASSWORD=password CB_BUCKET=test CB_SCOPE=langgraph
+pytest tests/test_checkpointer.py
+```
+
+The end-to-end agent example in `tests/agent_e2e_test.py` additionally requires `OPENAI_API_KEY`:
+
+```bash
+python tests/agent_e2e_test.py
+```
+
 ## Usage Data
 
 This product automatically collects usage and performance data (such as product name and version) and browser information (such as IP address) (collectively, "Usage Data"). Couchbase uses Usage Data, along with other data you may provide to Couchbase (such as your user name or email address), to develop and improve our products as well as inform our sales and marketing programs. We do not access or collect any data you store in Couchbase products. We use Usage Data to understand aggregate usage patterns and make our products more useful to you.  For more information on how Couchbase collects, protects, and processes information, please refer to the Couchbase Privacy Policy viewable at https://www.couchbase.com/privacy-policy.

{langgraph_checkpointer_couchbase-1.0.9 → langgraph_checkpointer_couchbase-2.0.0}/README.md

@@ -20,10 +20,11 @@ pip install langgraph-checkpointer-couchbase
 
 ## Requirements
 
-- Python 3.8+
+- Python 3.10+
 - Couchbase Server (7.0+ recommended)
-- LangGraph 0.3.22+
-- LangChain OpenAI 0.3.11+
+- Couchbase Python SDK 4.6.3+
+- LangGraph 1.0.5+
+- LangChain 1.1.3+ and LangChain OpenAI 1.1.3+
 
 ## Prerequisites
 
@@ -37,6 +38,7 @@ First, set up your agent tools and model:
 
 ```python
 from typing import Literal
+from langchain_core.tools import tool
 from langchain_openai import ChatOpenAI
 
 @tool
@@ -51,7 +53,7 @@ def get_weather(city: Literal["nyc", "sf"]):
 
 
 tools = [get_weather]
-model = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
+model = ChatOpenAI(model="gpt-5-mini", temperature=0)
 ```
 
 ### Synchronous Usage
@@ -59,7 +61,7 @@ model = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
 ```python
 import os
 from langgraph_checkpointer_couchbase import CouchbaseSaver
-from langgraph.graph import create_react_agent
+from langchain.agents import create_agent
 
 with CouchbaseSaver.from_conn_info(
         cb_conn_str=os.getenv("CB_CLUSTER") or "couchbase://localhost",
@@ -69,7 +71,7 @@ with CouchbaseSaver.from_conn_info(
         scope_name=os.getenv("CB_SCOPE") or "langgraph",
     ) as checkpointer:
     # Create the agent with checkpointing
-    graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)
+    graph = create_agent(model, tools=tools, checkpointer=checkpointer)
     
     # Configure with a unique thread ID
     config = {"configurable": {"thread_id": "1"}}
@@ -95,7 +97,7 @@ from acouchbase.cluster import Cluster as ACluster
 from couchbase.auth import PasswordAuthenticator
 from couchbase.options import ClusterOptions
 from langgraph_checkpointer_couchbase import AsyncCouchbaseSaver
-from langgraph.graph import create_react_agent
+from langchain.agents import create_agent
 
 auth = PasswordAuthenticator(
     os.getenv("CB_USERNAME") or "Administrator",
@@ -113,7 +115,7 @@ async with AsyncCouchbaseSaver.from_cluster(
         scope_name=scope_name,
     ) as checkpointer:
     # Create the agent with checkpointing
-    graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)
+    graph = create_agent(model, tools=tools, checkpointer=checkpointer)
     
     # Configure with a unique thread ID
     config = {"configurable": {"thread_id": "2"}}
@@ -136,6 +138,17 @@ async with AsyncCouchbaseSaver.from_cluster(
 await cluster.close()
 ```
 
+## Recommended Indexes
+
+The saver creates the `checkpoints` and `checkpoint_writes` collections on first use, but not indexes. Without them, queries fall back to sequential scans, which are slow on large collections and may not return a checkpoint written immediately before. Create these indexes once per scope (replace `test` and `langgraph` with your bucket and scope):
+
+```sql
+CREATE INDEX idx_checkpoints_thread IF NOT EXISTS
+  ON `test`.`langgraph`.`checkpoints`(thread_id, checkpoint_ns, checkpoint_id);
+CREATE INDEX idx_checkpoint_writes_thread IF NOT EXISTS
+  ON `test`.`langgraph`.`checkpoint_writes`(thread_id, checkpoint_ns, checkpoint_id);
+```
+
 ## Configuration Options
 
 | Parameter | Description | Default |
@@ -146,6 +159,22 @@ await cluster.close()
 | CB_BUCKET | Bucket to store checkpoints | test |
 | CB_SCOPE | Scope within bucket | langgraph |
 
+## Running the Tests
+
+The checkpointer tests run against a live Couchbase cluster and do not need an LLM. Create the bucket, scope, and the [recommended indexes](#recommended-indexes) first, then:
+
+```bash
+pip install -e . pytest pytest-asyncio
+export CB_CLUSTER=couchbase://localhost CB_USERNAME=Administrator CB_PASSWORD=password CB_BUCKET=test CB_SCOPE=langgraph
+pytest tests/test_checkpointer.py
+```
+
+The end-to-end agent example in `tests/agent_e2e_test.py` additionally requires `OPENAI_API_KEY`:
+
+```bash
+python tests/agent_e2e_test.py
+```
+
 ## Usage Data
 
 This product automatically collects usage and performance data (such as product name and version) and browser information (such as IP address) (collectively, "Usage Data"). Couchbase uses Usage Data, along with other data you may provide to Couchbase (such as your user name or email address), to develop and improve our products as well as inform our sales and marketing programs. We do not access or collect any data you store in Couchbase products. We use Usage Data to understand aggregate usage patterns and make our products more useful to you.  For more information on how Couchbase collects, protects, and processes information, please refer to the Couchbase Privacy Policy viewable at https://www.couchbase.com/privacy-policy.

langgraph_checkpointer_couchbase-2.0.0/langgraph_checkpointer_couchbase/__about__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

langgraph_checkpointer_couchbase-2.0.0/langgraph_checkpointer_couchbase/__init__.py

@@ -0,0 +1,16 @@
+import sys
+
+if sys.version_info < (3, 10):
+    raise ImportError(
+        "langgraph-checkpointer-couchbase 2.x requires Python 3.10 or newer "
+        f"(found {sys.version_info[0]}.{sys.version_info[1]}). "
+        "Upgrade Python, or pin langgraph-checkpointer-couchbase<2 to stay on an older release."
+    )
+
+from .async_cb_saver import AsyncCouchbaseSaver
+from .couchbase_saver import CouchbaseSaver
+
+__all__ = ["CouchbaseSaver", "AsyncCouchbaseSaver"]
+
+# --- Package-level telemetry (non-blocking, fire-and-forget) ---
+import langgraph_checkpointer_couchbase.telemetry  # noqa: F401, E402

{langgraph_checkpointer_couchbase-1.0.9 → langgraph_checkpointer_couchbase-2.0.0}/langgraph_checkpointer_couchbase/async_cb_saver.py

@@ -9,6 +9,7 @@ from acouchbase.bucket import Bucket as ABucket
 from couchbase.auth import PasswordAuthenticator
 from couchbase.options import ClusterOptions, QueryOptions, UpsertOptions
 from couchbase.exceptions import CollectionAlreadyExistsException
+from couchbase.n1ql import QueryScanConsistency
 
 from langgraph.checkpoint.base import (
     BaseCheckpointSaver,
@@ -179,7 +180,7 @@ class AsyncCouchbaseSaver(BaseCheckpointSaver):
             query = f'SELECT * FROM `{self.bucket_name}`.`{self.scope_name}`.`{self.checkpoints_collection_name}` WHERE thread_id = $1 AND checkpoint_ns = $2 ORDER BY checkpoint_id DESC LIMIT 1'
             query_params = [thread_id, checkpoint_ns]
 
-        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params))
+        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params, scan_consistency=QueryScanConsistency.REQUEST_PLUS))
 
         async for row in result:
             doc = row[self.checkpoints_collection_name]
@@ -193,7 +194,7 @@ class AsyncCouchbaseSaver(BaseCheckpointSaver):
             serialized_writes_query = f'SELECT * FROM `{self.bucket_name}`.`{self.scope_name}`.`{self.checkpoint_writes_collection_name}` WHERE thread_id = $1 AND checkpoint_ns = $2 AND checkpoint_id = $3'
             serialized_writes_params = [thread_id, checkpoint_ns, doc["checkpoint_id"] or ""]
             
-            serialized_writes_result = self.cluster.query(serialized_writes_query, QueryOptions(positional_parameters=serialized_writes_params))
+            serialized_writes_result = self.cluster.query(serialized_writes_query, QueryOptions(positional_parameters=serialized_writes_params, scan_consistency=QueryScanConsistency.REQUEST_PLUS))
 
             pending_writes = []
             async for write_doc in serialized_writes_result:
@@ -273,7 +274,7 @@ class AsyncCouchbaseSaver(BaseCheckpointSaver):
         if limit is not None:
             query += f" LIMIT {limit}"
 
-        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params))
+        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params, scan_consistency=QueryScanConsistency.REQUEST_PLUS))
 
         async for row in result:
             doc = row[self.checkpoints_collection_name]

{langgraph_checkpointer_couchbase-1.0.9 → langgraph_checkpointer_couchbase-2.0.0}/langgraph_checkpointer_couchbase/couchbase_saver.py

@@ -9,6 +9,7 @@ from couchbase.bucket import Bucket
 from couchbase.auth import PasswordAuthenticator
 from couchbase.options import ClusterOptions, QueryOptions, UpsertOptions
 from couchbase.exceptions import CollectionAlreadyExistsException
+from couchbase.n1ql import QueryScanConsistency
 
 from langgraph.checkpoint.base import (
     BaseCheckpointSaver,
@@ -163,7 +164,7 @@ class CouchbaseSaver(BaseCheckpointSaver):
             query = f'SELECT * FROM `{self.bucket_name}`.`{self.scope_name}`.`{self.checkpoints_collection_name}` WHERE thread_id = $1 AND checkpoint_ns = $2 ORDER BY checkpoint_id DESC LIMIT 1'
             query_params = [thread_id, checkpoint_ns]
 
-        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params))
+        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params, scan_consistency=QueryScanConsistency.REQUEST_PLUS))
 
         for row in result:
             doc = row[self.checkpoints_collection_name]
@@ -179,7 +180,7 @@ class CouchbaseSaver(BaseCheckpointSaver):
 
             serialized_writes_query = f'SELECT * FROM `{self.bucket_name}`.`{self.scope_name}`.`{self.checkpoint_writes_collection_name}` WHERE thread_id = $1 AND checkpoint_ns = $2 AND checkpoint_id = $3'
             serialized_writes_params = [thread_id, checkpoint_ns, doc["checkpoint_id"] or ""]
-            serialized_writes_result = self.cluster.query(serialized_writes_query, QueryOptions(positional_parameters=serialized_writes_params))
+            serialized_writes_result = self.cluster.query(serialized_writes_query, QueryOptions(positional_parameters=serialized_writes_params, scan_consistency=QueryScanConsistency.REQUEST_PLUS))
 
             pending_writes = []
             for write_doc in serialized_writes_result:
@@ -265,7 +266,7 @@ class CouchbaseSaver(BaseCheckpointSaver):
         if limit is not None:
             query += f" LIMIT {limit}"
 
-        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params))
+        result = self.cluster.query(query, QueryOptions(positional_parameters=query_params, scan_consistency=QueryScanConsistency.REQUEST_PLUS))
 
         for row in result:
             doc = row[self.checkpoints_collection_name]

{langgraph_checkpointer_couchbase-1.0.9 → langgraph_checkpointer_couchbase-2.0.0}/pyproject.toml

@@ -7,7 +7,7 @@ name = "langgraph-checkpointer-couchbase"
 dynamic = ["version"]
 description = ''
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 license = "MIT"
 keywords = ["langchain","langgraph", "couchbase", "checkpointer", "persistence"]
 authors = [
@@ -16,16 +16,15 @@ authors = [
 classifiers = [
   "Development Status :: 4 - Beta",
   "Programming Language :: Python",
-  "Programming Language :: Python :: 3.8",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
 dependencies = [
-  "couchbase>=4.5.0",
+  "couchbase>=4.6.3",
   "langgraph>=1.0.5",
   "langchain-openai>=1.1.3",
   "pydantic>=2.12.5",

langgraph_checkpointer_couchbase-2.0.0/tests/test_checkpointer.py

@@ -0,0 +1,147 @@
+"""Checkpointer integration tests against a live Couchbase cluster.
+
+These tests do not need an LLM. They exercise CouchbaseSaver and
+AsyncCouchbaseSaver directly and through a minimal LangGraph StateGraph.
+
+Required environment variables: CB_CLUSTER, CB_USERNAME, CB_PASSWORD,
+CB_BUCKET, CB_SCOPE. The bucket and scope must already exist; the saver
+creates its collections. Create the indexes listed in the README so reads
+see checkpoints written immediately before.
+"""
+import operator
+import os
+import uuid
+from typing import Annotated, TypedDict
+
+import pytest
+from langgraph.checkpoint.base import empty_checkpoint
+from langgraph.graph import END, START, StateGraph
+
+from langgraph_checkpointer_couchbase import AsyncCouchbaseSaver, CouchbaseSaver
+
+REQUIRED_ENV = ["CB_CLUSTER", "CB_USERNAME", "CB_PASSWORD", "CB_BUCKET", "CB_SCOPE"]
+
+pytestmark = pytest.mark.skipif(
+    any(not os.getenv(name) for name in REQUIRED_ENV),
+    reason=f"Couchbase connection not configured ({', '.join(REQUIRED_ENV)})",
+)
+
+
+def conn_info():
+    return dict(
+        cb_conn_str=os.environ["CB_CLUSTER"],
+        cb_username=os.environ["CB_USERNAME"],
+        cb_password=os.environ["CB_PASSWORD"],
+        bucket_name=os.environ["CB_BUCKET"],
+        scope_name=os.environ["CB_SCOPE"],
+    )
+
+
+def new_thread_config():
+    return {"configurable": {"thread_id": f"test-{uuid.uuid4()}", "checkpoint_ns": ""}}
+
+
+def make_checkpoint(step):
+    checkpoint = empty_checkpoint()
+    checkpoint["channel_values"] = {"step": step}
+    checkpoint["channel_versions"] = {"step": step}
+    return checkpoint
+
+
+class State(TypedDict):
+    items: Annotated[list, operator.add]
+
+
+def build_graph(checkpointer):
+    builder = StateGraph(State)
+    builder.add_node("first", lambda state: {"items": ["first"]})
+    builder.add_node("second", lambda state: {"items": ["second"]})
+    builder.add_edge(START, "first")
+    builder.add_edge("first", "second")
+    builder.add_edge("second", END)
+    return builder.compile(checkpointer=checkpointer)
+
+
+def test_sync_put_get_list_and_writes():
+    with CouchbaseSaver.from_conn_info(**conn_info()) as saver:
+        config = new_thread_config()
+        assert saver.get_tuple(config) is None
+
+        first = make_checkpoint(1)
+        first_config = saver.put(config, first, {"source": "input", "step": 1}, {})
+        second = make_checkpoint(2)
+        second_config = saver.put(first_config, second, {"source": "loop", "step": 2}, {})
+        saver.put_writes(second_config, [("items", "a"), ("items", "b")], "task-1")
+
+        latest = saver.get_tuple(config)
+        assert latest.config["configurable"]["checkpoint_id"] == second["id"]
+        assert latest.checkpoint["channel_values"] == {"step": 2}
+        assert latest.metadata == {"source": "loop", "step": 2}
+        assert latest.parent_config["configurable"]["checkpoint_id"] == first["id"]
+        assert sorted(latest.pending_writes) == [("task-1", "items", "a"), ("task-1", "items", "b")]
+
+        by_id = saver.get_tuple(first_config)
+        assert by_id.checkpoint["id"] == first["id"]
+        assert by_id.parent_config is None
+
+        listed = list(saver.list(config))
+        assert [t.checkpoint["id"] for t in listed] == [second["id"], first["id"]]
+        assert [t.checkpoint["id"] for t in saver.list(config, limit=1)] == [second["id"]]
+        assert [t.checkpoint["id"] for t in saver.list(config, before=second_config)] == [first["id"]]
+
+
+@pytest.mark.asyncio
+async def test_async_put_get_list_and_writes():
+    async with AsyncCouchbaseSaver.from_conn_info(**conn_info()) as saver:
+        config = new_thread_config()
+        assert await saver.aget_tuple(config) is None
+
+        first = make_checkpoint(1)
+        first_config = await saver.aput(config, first, {"source": "input", "step": 1}, {})
+        second = make_checkpoint(2)
+        second_config = await saver.aput(first_config, second, {"source": "loop", "step": 2}, {})
+        await saver.aput_writes(second_config, [("items", "a")], "task-1")
+
+        latest = await saver.aget_tuple(config)
+        assert latest.config["configurable"]["checkpoint_id"] == second["id"]
+        assert latest.checkpoint["channel_values"] == {"step": 2}
+        assert latest.metadata == {"source": "loop", "step": 2}
+        assert latest.parent_config["configurable"]["checkpoint_id"] == first["id"]
+        assert latest.pending_writes == [("task-1", "items", "a")]
+
+        listed = [t async for t in saver.alist(config)]
+        assert [t.checkpoint["id"] for t in listed] == [second["id"], first["id"]]
+        limited = [t async for t in saver.alist(config, limit=1)]
+        assert [t.checkpoint["id"] for t in limited] == [second["id"]]
+
+
+def test_sync_graph_persists_state():
+    with CouchbaseSaver.from_conn_info(**conn_info()) as saver:
+        graph = build_graph(saver)
+        config = new_thread_config()
+
+        result = graph.invoke({"items": ["start"]}, config)
+        assert result == {"items": ["start", "first", "second"]}
+
+        state = graph.get_state(config)
+        assert state.values == {"items": ["start", "first", "second"]}
+        assert len(list(graph.get_state_history(config))) >= 3
+
+        # A second run on the same thread continues from the persisted state.
+        result = graph.invoke({"items": ["again"]}, config)
+        assert result["items"] == ["start", "first", "second", "again", "first", "second"]
+
+
+@pytest.mark.asyncio
+async def test_async_graph_persists_state():
+    async with AsyncCouchbaseSaver.from_conn_info(**conn_info()) as saver:
+        graph = build_graph(saver)
+        config = new_thread_config()
+
+        result = await graph.ainvoke({"items": ["start"]}, config)
+        assert result == {"items": ["start", "first", "second"]}
+
+        state = await graph.aget_state(config)
+        assert state.values == {"items": ["start", "first", "second"]}
+        history = [s async for s in graph.aget_state_history(config)]
+        assert len(history) >= 3

langgraph_checkpointer_couchbase-2.0.0/tests/test_python_version_guard.py

@@ -0,0 +1,18 @@
+"""The package refuses to import on Python versions older than 3.10."""
+import importlib
+import sys
+
+import pytest
+
+import langgraph_checkpointer_couchbase
+
+
+def test_import_fails_with_clear_error_on_old_python(monkeypatch):
+    monkeypatch.setattr(sys, "version_info", (3, 9, 18, "final", 0))
+    with pytest.raises(ImportError, match="requires Python 3.10 or newer"):
+        importlib.reload(langgraph_checkpointer_couchbase)
+
+
+def test_import_succeeds_on_supported_python():
+    importlib.reload(langgraph_checkpointer_couchbase)
+    assert langgraph_checkpointer_couchbase.CouchbaseSaver

langgraph_checkpointer_couchbase-1.0.9/langgraph_checkpointer_couchbase/__about__.py

@@ -1 +0,0 @@
-__version__ = "1.0.9"

langgraph_checkpointer_couchbase-1.0.9/langgraph_checkpointer_couchbase/__init__.py

@@ -1,7 +0,0 @@
-from .async_cb_saver import AsyncCouchbaseSaver
-from .couchbase_saver import CouchbaseSaver
-
-__all__ = ["CouchbaseSaver", "AsyncCouchbaseSaver"]
-
-# --- Package-level telemetry (non-blocking, fire-and-forget) ---
-import langgraph_checkpointer_couchbase.telemetry  # noqa: F401, E402