Metadata-Version: 2.4
Name: langgraph-checkpoint-timeseries
Version: 0.1.0
Summary: Time-series optimized checkpointers for LangGraph using TimescaleDB and QuestDB
Author: jersobh
License-Expression: MIT
Project-URL: Homepage, https://github.com/jersobh/langgraph-checkpoint-timeseries
Project-URL: Bug Tracker, https://github.com/jersobh/langgraph-checkpoint-timeseries/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph-checkpoint>=2.0.0
Requires-Dist: psycopg>=3.1.0
Requires-Dist: psycopg-pool>=3.2.0
Dynamic: license-file

# LangGraph Time-Series Checkpointers

Custom [LangGraph](https://github.com/langchain-ai/langgraph) checkpointer implementations optimized for **Time-Series Databases**. Drop-in replacements for `PostgresSaver` that store AI agent state in **TimescaleDB** or **QuestDB** for superior performance under concurrent and high-volume workloads.

## Why Time-Series Memory?

Standard checkpointers (`PostgresSaver`) store state using row-level locking and WAL-based durability. This is ideal for simple apps, but **becomes a bottleneck** when you have:

- 🏭 **Multiple agents writing concurrently** (fleet management, parallel pipelines)
- 📈 **High-frequency state updates** (trading bots, real-time monitoring)
- 🔄 **Long-running agents** accumulating millions of checkpoints over weeks

Time-Series databases are purpose-built for these exact workloads.

## Installation

```bash
pip install langgraph-checkpoint-timeseries
```

## Supported Backends

### 1. TimescaleDB (`TimescaleDBSaver`)
Perfect for relational agent memory interspersed with IoT or metrics data. Uses UNLOGGED tables and pipeline mode for high-throughput.

### 2. QuestDB (`QuestDBSaver`)
Extremely high-throughput ingestion using `timestamp(ts) PARTITION BY DAY`. Ideal for write-heavy, append-only workloads.

## Quick Start

### TimescaleDB

```python
from langgraph_checkpoint_timeseries import TimescaleDBSaver

# The checkpointer automatically configures database schema and hypertables on setup()
with TimescaleDBSaver.from_conn_string("postgresql://postgres:postgres@localhost:5432/postgres") as saver:
    saver.setup()
    # app = workflow.compile(checkpointer=saver)
```

### QuestDB

```python
from langgraph_checkpoint_timeseries import QuestDBSaver

with QuestDBSaver.from_conn_string("postgresql://admin:quest@localhost:8812/qdb") as saver:
    saver.setup()
    # app = workflow.compile(checkpointer=saver)
```

## Benchmarks

Benchmarked against the standard `PostgresSaver` on the same hardware:

| Scenario | PostgresSaver | TimescaleDB | QuestDB | 🏆 Winner |
| :--- | ---: | ---: | ---: | :--- |
| Sequential Writes (1K) | 192 ops/s | 179 ops/s | 170 ops/s | PostgresSaver |
| **Concurrent Writes (15T×200)** | 186 ops/s | **470 ops/s** | **489 ops/s** | **QuestDB** |
| **High-Volume Writes (5K)** | 183 ops/s | **181 ops/s** | 172 ops/s | PostgresSaver |
| History Query (list 100) | **2,569 ops/s** | 457 ops/s | 404 ops/s | PostgresSaver |

### Concurrent Writes — Where TSDB Shines

```
  PostgresSaver   ███████████████ 186 ops/s
  TimescaleDB     ██████████████████████████████████████ 470 ops/s
  QuestDB         ████████████████████████████████████████ 489 ops/s
```

> **QuestDB is 2.6x faster** and **TimescaleDB is 2.5x faster** than PostgresSaver under 15-thread concurrent write load.

## When to Use This

| Use Case | Recommended Backend |
| :--- | :--- |
| Simple apps, prototyping | `PostgresSaver` |
| **Multi-agent, high concurrency** | **`TimescaleDBSaver`** |
| **Maximum write throughput** (IoT, trading) | **`QuestDBSaver`** |
| Full PostgreSQL ecosystem + time-series | **`TimescaleDBSaver`** |

### 🏭 Multi-Agent / High-Concurrency Systems
When you have **multiple AI agents writing state simultaneously** (fleet of IoT monitoring agents, parallel customer service bots), TimescaleDB and QuestDB handle write contention far better than standard Postgres. Our benchmarks show **~3x throughput** under 15-thread concurrent load.

### 📈 High-Frequency Decision Agents
Trading bots, real-time bidding agents, or any system making **hundreds of decisions per second** benefit from the optimized ingestion pipelines of time-series databases. UNLOGGED tables and disabled synchronous commit eliminate WAL overhead entirely.

### 🔄 Long-Running Agents with Data Retention
Agents that run for **weeks or months** accumulate millions of checkpoints. Time-series databases offer efficient partition-based cleanup (`DROP PARTITION`) instead of expensive `DELETE` operations, keeping performance stable over time.

### 🔍 Debugging & Compliance Auditing
When you need to answer *"What was the agent thinking at 14:03:22?"*, time-series databases provide native timestamp-indexed queries. Correlate agent decisions with real-world events stored in the same database.

## Examples

See the `examples/` directory for practical demos:

- **IoT Monitoring Agent** (`examples/timescaledb_iot_agent.py`) — Streaming sensor data with time-series checkpointing
- **Algorithmic Trading Agent** (`examples/questdb_trading_agent.py`) — High-frequency state updates and rapid decision preservation

## License

MIT — see `LICENSE` for details.
