Metadata-Version: 2.4
Name: langgraph-checkpointer-couchbase
Version: 1.0.2
Project-URL: Documentation, https://github.com/Lokesh Goel/langgraph-checkpointer-couchbase#readme
Project-URL: Issues, https://github.com/Lokesh Goel/langgraph-checkpointer-couchbase/issues
Project-URL: Source, https://github.com/Lokesh Goel/langgraph-checkpointer-couchbase
Author-email: Lokesh Goel <lokesh.goel@couchbase.com>
License-Expression: MIT
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: couchbase>=4.3.5
Requires-Dist: langchain-openai>=0.3.11
Requires-Dist: langgraph>=0.3.22
Requires-Dist: pydantic>=2.11.1
Requires-Dist: typing-extensions>=4.13.0
Description-Content-Type: text/markdown

# LangGraph Checkpoint Couchbase

A Couchbase implementation of the LangGraph `CheckpointSaver` interface that enables persisting agent state and conversation history in a Couchbase database.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

This package provides a seamless way to persist LangGraph agent states in Couchbase, enabling:
- State persistence across application restarts
- Retrieval of historical conversation steps
- Continued conversations from previous checkpoints
- Both synchronous and asynchronous interfaces

## Installation

```bash
pip install langgraph-checkpointer-couchbase
```

## Requirements

- Python 3.8+
- Couchbase Server (7.0+ recommended)
- LangGraph 0.3.22+
- LangChain OpenAI 0.3.11+

## Prerequisites

- A running Couchbase cluster
- A bucket created for storing checkpoints
- Appropriate credentials with read/write access

## Quick Start

First, set up your agent tools and model:

```python
from typing import Literal
from langchain_openai import ChatOpenAI

@tool
def get_weather(city: Literal["nyc", "sf"]):
    """Use this to get weather information."""
    if city == "nyc":
        return "It might be cloudy in nyc"
    elif city == "sf":
        return "It's always sunny in sf"
    else:
        raise AssertionError("Unknown city")


tools = [get_weather]
model = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
```

### Synchronous Usage

```python
import os
from langgraph_checkpointer_couchbase import CouchbaseSaver
from langgraph.graph import create_react_agent

with CouchbaseSaver.from_conn_info(
        cb_conn_str=os.getenv("CB_CLUSTER") or "couchbase://localhost",
        cb_username=os.getenv("CB_USERNAME") or "Administrator",
        cb_password=os.getenv("CB_PASSWORD") or "password",
        bucket_name=os.getenv("CB_BUCKET") or "test",
        scope_name=os.getenv("CB_SCOPE") or "langgraph",
    ) as checkpointer:
        # Create the agent with checkpointing
        graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)
        
        # Configure with a unique thread ID
        config = {"configurable": {"thread_id": "1"}}
        
        # Run the agent
        res = graph.invoke({"messages": [("human", "what's the weather in sf")]}, config)
        
        # Retrieve checkpoints
        latest_checkpoint = checkpointer.get(config)
        latest_checkpoint_tuple = checkpointer.get_tuple(config)
        checkpoint_tuples = list(checkpointer.list(config))

        print(latest_checkpoint)
        print(latest_checkpoint_tuple)
        print(checkpoint_tuples)
```

### Asynchronous Usage

```python
import os
from langgraph_checkpointer_couchbase import AsyncCouchbaseSaver
from langgraph.graph import create_react_agent

async with AsyncCouchbaseSaver.from_conn_info(
        cb_conn_str=os.getenv("CB_CLUSTER") or "couchbase://localhost",
        cb_username=os.getenv("CB_USERNAME") or "Administrator",
        cb_password=os.getenv("CB_PASSWORD") or "password",
        bucket_name=os.getenv("CB_BUCKET") or "test",
        scope_name=os.getenv("CB_SCOPE") or "langgraph",
    ) as checkpointer:
        # Create the agent with checkpointing
        graph = create_react_agent(model, tools=tools, checkpointer=checkpointer)
        
        # Configure with a unique thread ID
        config = {"configurable": {"thread_id": "2"}}
        
        # Run the agent asynchronously
        res = await graph.ainvoke(
            {"messages": [("human", "what's the weather in nyc")]}, config
        )

        # Retrieve checkpoints asynchronously
        latest_checkpoint = await checkpointer.aget(config)
        latest_checkpoint_tuple = await checkpointer.aget_tuple(config)
        checkpoint_tuples = [c async for c in checkpointer.alist(config)]

        print(latest_checkpoint)
        print(latest_checkpoint_tuple)
        print(checkpoint_tuples)
```

## Configuration Options

| Parameter | Description | Default |
|-----------|-------------|---------|
| CB_CLUSTER | Couchbase connection string | couchbase://localhost |
| CB_USERNAME | Username for Couchbase | Administrator |
| CB_PASSWORD | Password for Couchbase | password |
| CB_BUCKET | Bucket to store checkpoints | test |
| CB_SCOPE | Scope within bucket | langgraph |

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
---

## 📢 Support Policy

We truly appreciate your interest in this project!  
This project is **community-maintained**, which means it's **not officially supported** by our support team.

If you need help, have found a bug, or want to contribute improvements, the best place to do that is right here — by [opening a GitHub issue](https://github.com/Couchbase-Ecosystem/langgraph-checkpointer-couchbase/issues).  
Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.

Your collaboration helps us all move forward together — thank you!
