typesense-langgraph-checkpointer 0.1.7

LangGraph checkpointer backed by Typesense

🔍 typesense-langgraph-checkpointer

LangGraph checkpoint saver backed by Typesense — for Python and JavaScript/TypeScript.

Features · Installation · Quick Start · API Reference · Development · Contributing

---

✨ Features

• Drop-in LangGraph saver — implements the full BaseCheckpointSaver interface
• Dual-language — first-class Python and TypeScript packages from the same repo
• Blazingly fast search — leverages Typesense's in-memory engine for sub-millisecond checkpoint retrieval
• Thread management — full CRUD for threads, checkpoints, and pending writes
• Automatic schema setup — call setup() once and collections are created for you
• Zero-config local dev — Docker Compose included for instant Typesense instance

---

📦 Installation

Python

pip install langgraph-checkpoint-typesense

JavaScript / TypeScript

npm install @typesense-langgraph/checkpoint

---

🚀 Quick Start

Python

import typesense
from langgraph_checkpoint_typesense import AsyncTypesenseSaver

# 1. Create the saver
saver = AsyncTypesenseSaver.from_config(
    host="localhost",
    port=8108,
    api_key="your-api-key",
    protocol="http",
)

# 2. Initialize collections (run once)
await saver.setup()

# 3. Use with any LangGraph graph
from langgraph.graph import StateGraph

graph = StateGraph(...)
# ... define your nodes & edges ...
app = graph.compile(checkpointer=saver)

# 4. Invoke with a thread
config = {"configurable": {"thread_id": "my-thread"}}
result = await app.ainvoke({"input": "hello"}, config)

JavaScript / TypeScript

import { TypesenseSaver } from "@typesense-langgraph/checkpoint";

// 1. Create the saver
const saver = TypesenseSaver.fromConfig({
  host: "localhost",
  port: 8108,
  apiKey: "your-api-key",
  protocol: "http",
});

// 2. Initialize collections (run once)
await saver.setup();

// 3. Use with any LangGraph graph
import { StateGraph } from "@langchain/langgraph";

const graph = new StateGraph(...)
  // ... define your nodes & edges ...
  .compile({ checkpointer: saver });

// 4. Invoke with a thread
const config = { configurable: { thread_id: "my-thread" } };
const result = await graph.invoke({ input: "hello" }, config);

---

⚙️ Configuration

Parameter	Python	JS/TS	Default	Description
Host	host	host	localhost	Typesense server hostname
Port	port	port	8108	Typesense API port
API Key	api_key	apiKey	—	Typesense API key
Protocol	protocol	protocol	http	http or https
Timeout	connection_timeout_seconds	connectionTimeoutSeconds	5	Connection timeout in seconds

You can also pass a pre-configured Typesense Client directly to the constructor.

---

📖 API Reference

Python — AsyncTypesenseSaver

Method	Description
from_config(cls, **kwargs)	Create a saver from connection parameters
setup()	Create Typesense collections if they don't exist
aget_tuple(config)	Retrieve a checkpoint tuple
aput(config, checkpoint, metadata, new_versions)	Store a checkpoint
aput_writes(config, writes, task_id)	Store pending writes
alist(config, *, filter, before, limit)	List checkpoint tuples
adelete_thread(thread_id)	Delete all data for a thread

JavaScript / TypeScript — TypesenseSaver

Method	Description
fromConfig(config)	Create a saver from connection parameters
setup()	Create Typesense collections if they don't exist
getTuple(config)	Retrieve a checkpoint tuple
put(config, checkpoint, metadata, newVersions)	Store a checkpoint
putWrites(config, writes, taskId)	Store pending writes
list(config, options?)	Async-generator of checkpoint tuples
deleteThread(threadId)	Delete all data for a thread

---

🏗️ Architecture

graph LR
    A["LangGraph Runtime"] -->|checkpoint & writes| B["TypesenseSaver"]
    B -->|upsert / search| C["Typesense"]
    C --> D[("checkpoints collection")]
    C --> E[("writes collection")]
    B -->|getTuple / list| A

The saver manages two Typesense collections:

• langgraph_checkpoints — stores serialized checkpoint state, metadata, and channel versions
• langgraph_writes — stores pending writes keyed by (thread_id, checkpoint_id, task_id, idx)

Both collections are created automatically by setup() with optimized schemas and sorting fields.

---

🛠️ Development

Prerequisites

• Docker
• Python ≥ 3.9
• Node.js ≥ 22

Start Typesense

docker compose up -d

Default API key: test-api-key (override with TYPESENSE_API_KEY env var).

Python

cd python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

JavaScript / TypeScript

cd js
npm ci
npm run build
npm test

---

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide and the Code of Conduct before opening a PR.

---

📄 License

This project is licensed under the MIT License.