Metadata-Version: 2.4
Name: langgraph-surrealdb
Version: 0.3.0
Summary: SurrealDB storage backend for LangGraph.
Project-URL: homepage, https://github.com/zazabe/langgraph-surrealdb
Project-URL: repository, https://github.com/zazabe/langgraph-surrealdb
Project-URL: issues, https://github.com/zazabe/langgraph-surrealdb/issues
Author-email: zazabe-dev <zazabe-dev@proton.me>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: langgraph-checkpoint<5.0.0,>=4.1.0
Requires-Dist: langgraph>=1.1.6
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.10.6
Requires-Dist: surrealdb>=1.0.0
Description-Content-Type: text/markdown

# LangGraph Checkpoint for SurrealDB

SurrealDB-backed checkpointers for LangGraph.

## Install

```bash
pip install langgraph-surrealdb
```

## Configure SurrealDB

Set these environment variables (prefix: `LANGGRAPH_SURREALDB_`):

```bash
# required for all modes
export LANGGRAPH_SURREALDB_URL="ws://localhost:8000/rpc"
export LANGGRAPH_SURREALDB_NS="langgraph"
export LANGGRAPH_SURREALDB_DB="checkpoint"
export LANGGRAPH_SURREALDB_TABLE_PREFIX="prefix" # optionally add a prefix to checkpoint tables
# root mode
export LANGGRAPH_SURREALDB_AUTH_MODE="root"
export LANGGRAPH_SURREALDB_USER="root"
export LANGGRAPH_SURREALDB_PASSWORD="pass"

# record mode
# export LANGGRAPH_SURREALDB_AUTH_MODE="record"
# export LANGGRAPH_SURREALDB_USER="user"
# export LANGGRAPH_SURREALDB_PASSWORD="pass"
# export LANGGRAPH_SURREALDB_ACCESS="method"

# token mode
# export LANGGRAPH_SURREALDB_AUTH_MODE="token"
# export LANGGRAPH_SURREALDB_TOKEN="xyz"
```

Or create the saver directly from settings:

```python
from langgraph_surrealdb import (
    AsyncSurrealSaver,
    RootAuth,
    SurrealSaver,
    SurrealSaverSettings,
    SurrealSaverDatabaseSettings,
)

settings = SurrealSaverSettings(
    writes_table="writes", # optional, defaults to 'writes'
    checkpoints_table="checkpoints", # optional, defaults to 'checkpoints'
    db=SurrealSaverDatabaseSettings(
        url="ws://localhost:8000/rpc",
        namespace="langgraph",
        database="checkpoint",
        # supports RootAuth, TokenAuth and RecordAuth
        auth=RootAuth(
            username="root",
            password="root"
        )
    )
)

with SurrealSaver.from_settings(settings) as checkpointer:
    ...

async with AsyncSurrealSaver.from_settings(settings) as checkpointer:
    ...
```

## Initialize schema

> [!IMPORTANT]
> When using SurrealDB checkpointers for the first time, call a setup method
> to create required tables and indexes before using saver operations.

```python
# one-time setup
with SurrealSaver.from_env() as checkpointer:
    checkpointer.setup()

# async equivalent
async with AsyncSurrealSaver.from_env() as checkpointer:
    await checkpointer.setup()
```

## Use with LangGraph (sync)

```python
from langgraph.graph import StateGraph
from langgraph_surrealdb import SurrealSaver

# build your graph
builder = StateGraph(dict)
# ... add nodes and edges ...

with SurrealSaver.from_env() as checkpointer:
    checkpointer.setup()
    graph = builder.compile(checkpointer=checkpointer)
    result = graph.invoke(
        {"input": "hello"},
        config={"configurable": {"thread_id": "thread-1"}},
    )
```

## Use with LangGraph (async)

```python
from langgraph.graph import StateGraph
from langgraph_surrealdb import AsyncSurrealSaver

builder = StateGraph(dict)
# ... add nodes and edges ...

async with AsyncSurrealSaver.from_env() as checkpointer:
    await checkpointer.setup()
    graph = builder.compile(checkpointer=checkpointer)
    result = await graph.ainvoke(
        {"input": "hello"},
        config={"configurable": {"thread_id": "thread-1"}},
    )
```

Then reuse the same `thread_id` to resume conversation state across calls.
