Metadata-Version: 2.4
Name: langgraph-cosmosdb-checkpointer
Version: 1.0.0
Summary: State-of-the-art Azure Cosmos DB checkpointer for LangGraph
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio>=4.12.1
Requires-Dist: azure-cosmos>=4.14.6
Requires-Dist: azure-identity>=1.25.2
Requires-Dist: langchain>=1.2.10
Requires-Dist: langgraph>=1.0.9
Requires-Dist: pytest>=9.0.2
Requires-Dist: pytest-asyncio>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Dynamic: license-file

# langgraph-cosmosdb-checkpointer

State-of-the-art Azure Cosmos DB checkpointer implementation for LangGraph with:

- strict config semantics (`thread_id`, `checkpoint_ns`, `checkpoint_id`)
- deterministic/idempotent `put_writes` ordering rules
- optimistic concurrency handling for special writes
- payload guardrails for Cosmos 2MB item limit (compression + chunking)

## Install

```bash
pip install langgraph-cosmosdb-checkpointer
```

## Usage

```python
from langgraph_cosmosdb_checkpointer import CosmosDBSaver, CosmosDBSettings

settings = CosmosDBSettings(
    database_name="langgraph",
    checkpoint_container_name="checkpoints",
    writes_container_name="writes",
    blob_container_name="checkpoint_blobs",
)

saver = CosmosDBSaver.from_endpoint(
    endpoint="https://<account>.documents.azure.com:443/",
    credential="<account-key>",
    settings=settings,
)
```

You can also use `AsyncCosmosDBSaver` for async graph execution.

By default (`create_containers=True`), the saver creates the database and containers automatically if they don't exist.

### Cosmos DB indexing policy

The `writes` container must have a composite index to support the multi-field sort used when loading pending writes:

`ORDER BY c.task_id ASC, c.idx ASC`

If you create the container using this library, it will include the required composite index. If the container already
exists, Cosmos DB will keep the existing indexing policy (i.e., `create_container_if_not_exists(...)` will not update
it), so you must update the container indexing policy in Azure or recreate the container.

### Azure AD / Entra ID authentication

`from_endpoint` supports `DefaultAzureCredential` for Azure AD auth:

```python
from azure.identity import DefaultAzureCredential
from langgraph_cosmosdb_checkpointer import CosmosDBSaver

saver = CosmosDBSaver.from_endpoint(
    endpoint="https://<account>.documents.azure.com:443/",
    credential=DefaultAzureCredential(),
)
```

If `credential` is omitted, `from_endpoint` will use `DefaultAzureCredential()` automatically.
