langgraph_checkpoint_firestore 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,42 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # Distribution / packaging
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+
11
+ # Virtual environments
12
+ venv/
13
+ env/
14
+ .env/
15
+ .venv/
16
+ ENV/
17
+
18
+ # IDE specific files
19
+ .idea/
20
+ .vscode/
21
+ *.swp
22
+ *.swo
23
+
24
+ # Unit test / coverage reports
25
+ htmcov/
26
+ .tox/
27
+ .coverage
28
+ .coverage.*
29
+ .cache
30
+ nosetests.xml
31
+ coverage.xml
32
+ *.cover
33
+
34
+ # Jupyter Notebook
35
+ .ipynb_checkpoints
36
+
37
+ # Environment variables
38
+ .env
39
+
40
+ # Local development settings
41
+ *.log
42
+ .DS_Store
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ ## [0.1.7]
4
+ ### Changed
5
+ - Subgraph support
6
+ - Performance fix
7
+ - Update for langraph 1.0.1
8
+
9
+ ## [0.1.4]
10
+ ### Changed
11
+ - Async support
12
+
13
+ ## [0.1.3]
14
+
15
+ - **Added**: Configurable checkpoint and writes collection feature.
16
+ - **Fixed**: List function bug.
17
+
18
+ This version introduces a new configurable checkpoint and writes collection feature
@@ -0,0 +1,191 @@
1
+ Metadata-Version: 2.4
2
+ Name: langgraph_checkpoint_firestore
3
+ Version: 0.2.0
4
+ Summary: LangGraph checkpoint saver for Google Firestore with built-in message history pruning via agentstate-reducer
5
+ Author-email: Kamal <skamalj@github.com>
6
+ Keywords: agent-state,checkpoint,firestore,google-cloud,langchain,langgraph,memory,message-reducer
7
+ Classifier: License :: OSI Approved :: MIT License
8
+ Classifier: Operating System :: OS Independent
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
11
+ Requires-Python: >=3.10
12
+ Requires-Dist: google-cloud-firestore
13
+ Requires-Dist: langchain-core
14
+ Requires-Dist: langgraph
15
+ Provides-Extra: dev
16
+ Requires-Dist: black; extra == 'dev'
17
+ Requires-Dist: isort; extra == 'dev'
18
+ Requires-Dist: mypy; extra == 'dev'
19
+ Requires-Dist: pytest-cov; extra == 'dev'
20
+ Requires-Dist: pytest>=7.0; extra == 'dev'
21
+ Provides-Extra: reducer
22
+ Requires-Dist: agentstate-reducer>=0.1.1; extra == 'reducer'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # langgraph-checkpoint-firestore
26
+
27
+ Google Firestore checkpoint saver for [LangGraph](https://github.com/langchain-ai/langgraph). Persists agent state between runs so your graphs can resume from any prior checkpoint.
28
+
29
+ **What makes this checkpointer different:** it has message history pruning built in. Pass a `MessageReducer` and the checkpointer automatically caps your message list before writing to Firestore — no extra code in your graph, no state annotation changes required. This is the only LangGraph Firestore checkpointer with this capability.
30
+
31
+ ## Features
32
+
33
+ - **Full checkpoint persistence** — save, retrieve, and list LangGraph checkpoints in Google Firestore
34
+ - **Built-in message pruning** — optional `MessageReducer` prunes message history at the persistence layer, keeping checkpoints lean without changing your graph code
35
+ - **Sync and async API** — `put`/`get_tuple`/`list` and their `aput`/`aget_tuple`/`alist` async counterparts
36
+ - **Subgraph support** — correctly checkpoints parent and subgraph state independently
37
+ - **Native Firestore hierarchy** — checkpoints stored in subcollections per thread, enabling efficient per-thread queries
38
+
39
+ ## Installation
40
+
41
+ ```bash
42
+ pip install langgraph-checkpoint-firestore
43
+ ```
44
+
45
+ With optional message pruning support:
46
+
47
+ ```bash
48
+ pip install "langgraph-checkpoint-firestore[reducer]"
49
+ ```
50
+
51
+ **Requires Python 3.10+**
52
+
53
+ ## Firestore Setup
54
+
55
+ The saver uses Google Cloud Application Default Credentials. Set up auth with one of:
56
+
57
+ ```bash
58
+ # Local development — authenticate with your Google account
59
+ gcloud auth application-default login
60
+
61
+ # Service account (CI / production)
62
+ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
63
+ ```
64
+
65
+ Your Firestore instance must be in **Native mode** (not Datastore mode). Collections are created automatically on first write — no manual setup required.
66
+
67
+ ## Quick Start
68
+
69
+ ```python
70
+ from langgraph.graph import StateGraph, MessagesState, START
71
+ from langchain_openai import ChatOpenAI
72
+ from langgraph_checkpoint_firestore import FirestoreSaver
73
+
74
+ model = ChatOpenAI(model="gpt-4o-mini")
75
+
76
+ def call_model(state: MessagesState):
77
+ return {"messages": model.invoke(state["messages"])}
78
+
79
+ builder = StateGraph(MessagesState)
80
+ builder.add_node("call_model", call_model)
81
+ builder.add_edge(START, "call_model")
82
+
83
+ with FirestoreSaver.from_conn_info(project_id="my-gcp-project", checkpoints_collection="checkpoints") as checkpointer:
84
+ graph = builder.compile(checkpointer=checkpointer)
85
+
86
+ config = {"configurable": {"thread_id": "user-123"}}
87
+
88
+ # First run — state is saved to Firestore
89
+ graph.invoke({"messages": [{"role": "user", "content": "Hi, I'm Kamal"}]}, config)
90
+
91
+ # Second run — picks up where it left off
92
+ graph.invoke({"messages": [{"role": "user", "content": "What's my name?"}]}, config)
93
+ ```
94
+
95
+ ## API Reference
96
+
97
+ ### `FirestoreSaver(project_id, checkpoints_collection, reducer=None, messages_key="messages")`
98
+
99
+ | Parameter | Type | Default | Description |
100
+ |---|---|---|---|
101
+ | `project_id` | `str` | required | Google Cloud project ID |
102
+ | `checkpoints_collection` | `str` | `"checkpoints"` | Root Firestore collection name |
103
+ | `reducer` | `MessageReducer` | `None` | Optional pruner — see [Message Pruning](#built-in-message-pruning) |
104
+ | `messages_key` | `str` | `"messages"` | State channel name that holds the message list |
105
+
106
+ You can also use the context manager factory:
107
+
108
+ ```python
109
+ with FirestoreSaver.from_conn_info(
110
+ project_id="my-gcp-project",
111
+ checkpoints_collection="checkpoints",
112
+ reducer=reducer,
113
+ messages_key="messages"
114
+ ) as saver:
115
+ graph = builder.compile(checkpointer=saver)
116
+ ```
117
+
118
+ ### Sync methods
119
+
120
+ | Method | Description |
121
+ |---|---|
122
+ | `put(config, checkpoint, metadata, new_versions)` | Save a checkpoint |
123
+ | `put_writes(config, writes, task_id)` | Save pending writes for a checkpoint |
124
+ | `get_tuple(config)` | Retrieve the latest (or a specific) checkpoint |
125
+ | `list(config, *, before, limit)` | Iterate checkpoints for a thread |
126
+
127
+ ### Async methods
128
+
129
+ All sync methods have async counterparts: `aput`, `aput_writes`, `aget_tuple`, `alist`.
130
+
131
+ ## Built-in Message Pruning
132
+
133
+ Long-running agents accumulate message history with every turn. Left unchecked this inflates checkpoint size, increases Firestore storage costs, and eventually blows past LLM context limits.
134
+
135
+ This checkpointer solves that at the persistence layer: pass a `MessageReducer` and it automatically prunes the message list inside `put()` before the checkpoint is serialised and written to Firestore. **Your graph code, state definition, and node logic stay untouched.**
136
+
137
+ This is an alternative to — or complement of — the LangGraph `Annotated[list, reducer_fn]` pattern. Use the checkpoint-layer approach when:
138
+
139
+ - You don't own the graph or state definition (e.g. using a pre-built LangGraph agent)
140
+ - You want pruning to happen unconditionally at every save, regardless of which node triggered it
141
+ - You want to keep all in-memory state intact and only prune what gets persisted
142
+
143
+ ### Install with reducer support
144
+
145
+ ```bash
146
+ pip install "langgraph-checkpoint-firestore[reducer]"
147
+ ```
148
+
149
+ ### Usage
150
+
151
+ ```python
152
+ from agentstate_reducer import MessageReducer
153
+ from langgraph_checkpoint_firestore import FirestoreSaver
154
+
155
+ reducer = MessageReducer(min_messages=10, max_messages=20)
156
+
157
+ with FirestoreSaver.from_conn_info(
158
+ project_id="my-gcp-project",
159
+ checkpoints_collection="checkpoints",
160
+ reducer=reducer, # prune before each checkpoint save
161
+ messages_key="messages" # state channel holding the message list (default)
162
+ ) as checkpointer:
163
+ graph = builder.compile(checkpointer=checkpointer)
164
+ ```
165
+
166
+ When `len(messages) > max_messages`, the oldest `human`/`ai` messages are removed until `min_messages` remain. The following are **never** pruned:
167
+
168
+ - Index 0 (typically the system prompt) — controlled by `preserve_first=True`
169
+ - `system` and `function` messages
170
+ - `tool` messages — unless their parent `ai` message is pruned (cascade behaviour, configurable)
171
+
172
+ See [agentstate-reducer on PyPI](https://pypi.org/project/agentstate-reducer/) for full configuration: `preserve_first`, `cascade_tool_messages`, `summarize_fn`, and role alias support (`user`/`assistant`/`agent`).
173
+
174
+ ## Data Model
175
+
176
+ Checkpoints are stored in a hierarchical Firestore structure:
177
+
178
+ ```
179
+ {checkpoints_collection}/
180
+ {thread_id}_{checkpoint_ns}/ ← partition document
181
+ checkpoints/
182
+ {checkpoint_id} ← checkpoint document
183
+ writes/
184
+ {task_id}_{idx} ← pending write documents
185
+ ```
186
+
187
+ This structure enables efficient per-thread checkpoint queries and keeps checkpoint data co-located with its pending writes.
188
+
189
+ ## License
190
+
191
+ MIT
@@ -0,0 +1,167 @@
1
+ # langgraph-checkpoint-firestore
2
+
3
+ Google Firestore checkpoint saver for [LangGraph](https://github.com/langchain-ai/langgraph). Persists agent state between runs so your graphs can resume from any prior checkpoint.
4
+
5
+ **What makes this checkpointer different:** it has message history pruning built in. Pass a `MessageReducer` and the checkpointer automatically caps your message list before writing to Firestore — no extra code in your graph, no state annotation changes required. This is the only LangGraph Firestore checkpointer with this capability.
6
+
7
+ ## Features
8
+
9
+ - **Full checkpoint persistence** — save, retrieve, and list LangGraph checkpoints in Google Firestore
10
+ - **Built-in message pruning** — optional `MessageReducer` prunes message history at the persistence layer, keeping checkpoints lean without changing your graph code
11
+ - **Sync and async API** — `put`/`get_tuple`/`list` and their `aput`/`aget_tuple`/`alist` async counterparts
12
+ - **Subgraph support** — correctly checkpoints parent and subgraph state independently
13
+ - **Native Firestore hierarchy** — checkpoints stored in subcollections per thread, enabling efficient per-thread queries
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ pip install langgraph-checkpoint-firestore
19
+ ```
20
+
21
+ With optional message pruning support:
22
+
23
+ ```bash
24
+ pip install "langgraph-checkpoint-firestore[reducer]"
25
+ ```
26
+
27
+ **Requires Python 3.10+**
28
+
29
+ ## Firestore Setup
30
+
31
+ The saver uses Google Cloud Application Default Credentials. Set up auth with one of:
32
+
33
+ ```bash
34
+ # Local development — authenticate with your Google account
35
+ gcloud auth application-default login
36
+
37
+ # Service account (CI / production)
38
+ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
39
+ ```
40
+
41
+ Your Firestore instance must be in **Native mode** (not Datastore mode). Collections are created automatically on first write — no manual setup required.
42
+
43
+ ## Quick Start
44
+
45
+ ```python
46
+ from langgraph.graph import StateGraph, MessagesState, START
47
+ from langchain_openai import ChatOpenAI
48
+ from langgraph_checkpoint_firestore import FirestoreSaver
49
+
50
+ model = ChatOpenAI(model="gpt-4o-mini")
51
+
52
+ def call_model(state: MessagesState):
53
+ return {"messages": model.invoke(state["messages"])}
54
+
55
+ builder = StateGraph(MessagesState)
56
+ builder.add_node("call_model", call_model)
57
+ builder.add_edge(START, "call_model")
58
+
59
+ with FirestoreSaver.from_conn_info(project_id="my-gcp-project", checkpoints_collection="checkpoints") as checkpointer:
60
+ graph = builder.compile(checkpointer=checkpointer)
61
+
62
+ config = {"configurable": {"thread_id": "user-123"}}
63
+
64
+ # First run — state is saved to Firestore
65
+ graph.invoke({"messages": [{"role": "user", "content": "Hi, I'm Kamal"}]}, config)
66
+
67
+ # Second run — picks up where it left off
68
+ graph.invoke({"messages": [{"role": "user", "content": "What's my name?"}]}, config)
69
+ ```
70
+
71
+ ## API Reference
72
+
73
+ ### `FirestoreSaver(project_id, checkpoints_collection, reducer=None, messages_key="messages")`
74
+
75
+ | Parameter | Type | Default | Description |
76
+ |---|---|---|---|
77
+ | `project_id` | `str` | required | Google Cloud project ID |
78
+ | `checkpoints_collection` | `str` | `"checkpoints"` | Root Firestore collection name |
79
+ | `reducer` | `MessageReducer` | `None` | Optional pruner — see [Message Pruning](#built-in-message-pruning) |
80
+ | `messages_key` | `str` | `"messages"` | State channel name that holds the message list |
81
+
82
+ You can also use the context manager factory:
83
+
84
+ ```python
85
+ with FirestoreSaver.from_conn_info(
86
+ project_id="my-gcp-project",
87
+ checkpoints_collection="checkpoints",
88
+ reducer=reducer,
89
+ messages_key="messages"
90
+ ) as saver:
91
+ graph = builder.compile(checkpointer=saver)
92
+ ```
93
+
94
+ ### Sync methods
95
+
96
+ | Method | Description |
97
+ |---|---|
98
+ | `put(config, checkpoint, metadata, new_versions)` | Save a checkpoint |
99
+ | `put_writes(config, writes, task_id)` | Save pending writes for a checkpoint |
100
+ | `get_tuple(config)` | Retrieve the latest (or a specific) checkpoint |
101
+ | `list(config, *, before, limit)` | Iterate checkpoints for a thread |
102
+
103
+ ### Async methods
104
+
105
+ All sync methods have async counterparts: `aput`, `aput_writes`, `aget_tuple`, `alist`.
106
+
107
+ ## Built-in Message Pruning
108
+
109
+ Long-running agents accumulate message history with every turn. Left unchecked this inflates checkpoint size, increases Firestore storage costs, and eventually blows past LLM context limits.
110
+
111
+ This checkpointer solves that at the persistence layer: pass a `MessageReducer` and it automatically prunes the message list inside `put()` before the checkpoint is serialised and written to Firestore. **Your graph code, state definition, and node logic stay untouched.**
112
+
113
+ This is an alternative to — or complement of — the LangGraph `Annotated[list, reducer_fn]` pattern. Use the checkpoint-layer approach when:
114
+
115
+ - You don't own the graph or state definition (e.g. using a pre-built LangGraph agent)
116
+ - You want pruning to happen unconditionally at every save, regardless of which node triggered it
117
+ - You want to keep all in-memory state intact and only prune what gets persisted
118
+
119
+ ### Install with reducer support
120
+
121
+ ```bash
122
+ pip install "langgraph-checkpoint-firestore[reducer]"
123
+ ```
124
+
125
+ ### Usage
126
+
127
+ ```python
128
+ from agentstate_reducer import MessageReducer
129
+ from langgraph_checkpoint_firestore import FirestoreSaver
130
+
131
+ reducer = MessageReducer(min_messages=10, max_messages=20)
132
+
133
+ with FirestoreSaver.from_conn_info(
134
+ project_id="my-gcp-project",
135
+ checkpoints_collection="checkpoints",
136
+ reducer=reducer, # prune before each checkpoint save
137
+ messages_key="messages" # state channel holding the message list (default)
138
+ ) as checkpointer:
139
+ graph = builder.compile(checkpointer=checkpointer)
140
+ ```
141
+
142
+ When `len(messages) > max_messages`, the oldest `human`/`ai` messages are removed until `min_messages` remain. The following are **never** pruned:
143
+
144
+ - Index 0 (typically the system prompt) — controlled by `preserve_first=True`
145
+ - `system` and `function` messages
146
+ - `tool` messages — unless their parent `ai` message is pruned (cascade behaviour, configurable)
147
+
148
+ See [agentstate-reducer on PyPI](https://pypi.org/project/agentstate-reducer/) for full configuration: `preserve_first`, `cascade_tool_messages`, `summarize_fn`, and role alias support (`user`/`assistant`/`agent`).
149
+
150
+ ## Data Model
151
+
152
+ Checkpoints are stored in a hierarchical Firestore structure:
153
+
154
+ ```
155
+ {checkpoints_collection}/
156
+ {thread_id}_{checkpoint_ns}/ ← partition document
157
+ checkpoints/
158
+ {checkpoint_id} ← checkpoint document
159
+ writes/
160
+ {task_id}_{idx} ← pending write documents
161
+ ```
162
+
163
+ This structure enables efficient per-thread checkpoint queries and keeps checkpoint data co-located with its pending writes.
164
+
165
+ ## License
166
+
167
+ MIT
@@ -0,0 +1,57 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "langgraph_checkpoint_firestore"
7
+ version = "0.2.0"
8
+ description = "LangGraph checkpoint saver for Google Firestore with built-in message history pruning via agentstate-reducer"
9
+ authors = [{name = "Kamal", email = "skamalj@github.com"}]
10
+ readme = "README.md"
11
+ requires-python = ">=3.10"
12
+ dependencies = [
13
+ "langchain-core",
14
+ "langgraph",
15
+ "google-cloud-firestore"
16
+ ]
17
+ keywords = [
18
+ "langgraph", "checkpoint", "firestore", "google-cloud",
19
+ "message-reducer", "agent-state", "memory", "langchain"
20
+ ]
21
+ classifiers = [
22
+ "Programming Language :: Python :: 3",
23
+ "License :: OSI Approved :: MIT License",
24
+ "Operating System :: OS Independent",
25
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
26
+ ]
27
+
28
+ [project.optional-dependencies]
29
+ reducer = [
30
+ "agentstate-reducer>=0.1.1",
31
+ ]
32
+ dev = [
33
+ "pytest>=7.0",
34
+ "pytest-cov",
35
+ "black",
36
+ "isort",
37
+ "mypy"
38
+ ]
39
+
40
+ [dependency-groups]
41
+ dev = [
42
+ "pytest>=7.0",
43
+ "pytest-cov",
44
+ "langchain-openai",
45
+ "langgraph-checkpoint-firestore[reducer]",
46
+ ]
47
+
48
+ [tool.hatch.build.targets.wheel]
49
+ packages = ["src/langgraph_checkpoint_firestore"]
50
+
51
+ [tool.black]
52
+ line-length = 88
53
+ target-version = ['py39']
54
+
55
+ [tool.isort]
56
+ profile = "black"
57
+ multi_line_output = 3
@@ -0,0 +1,167 @@
1
+ # langgraph-checkpoint-firestore
2
+
3
+ Google Firestore checkpoint saver for [LangGraph](https://github.com/langchain-ai/langgraph). Persists agent state between runs so your graphs can resume from any prior checkpoint.
4
+
5
+ **What makes this checkpointer different:** it has message history pruning built in. Pass a `MessageReducer` and the checkpointer automatically caps your message list before writing to Firestore — no extra code in your graph, no state annotation changes required. This is the only LangGraph Firestore checkpointer with this capability.
6
+
7
+ ## Features
8
+
9
+ - **Full checkpoint persistence** — save, retrieve, and list LangGraph checkpoints in Google Firestore
10
+ - **Built-in message pruning** — optional `MessageReducer` prunes message history at the persistence layer, keeping checkpoints lean without changing your graph code
11
+ - **Sync and async API** — `put`/`get_tuple`/`list` and their `aput`/`aget_tuple`/`alist` async counterparts
12
+ - **Subgraph support** — correctly checkpoints parent and subgraph state independently
13
+ - **Native Firestore hierarchy** — checkpoints stored in subcollections per thread, enabling efficient per-thread queries
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ pip install langgraph-checkpoint-firestore
19
+ ```
20
+
21
+ With optional message pruning support:
22
+
23
+ ```bash
24
+ pip install "langgraph-checkpoint-firestore[reducer]"
25
+ ```
26
+
27
+ **Requires Python 3.10+**
28
+
29
+ ## Firestore Setup
30
+
31
+ The saver uses Google Cloud Application Default Credentials. Set up auth with one of:
32
+
33
+ ```bash
34
+ # Local development — authenticate with your Google account
35
+ gcloud auth application-default login
36
+
37
+ # Service account (CI / production)
38
+ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
39
+ ```
40
+
41
+ Your Firestore instance must be in **Native mode** (not Datastore mode). Collections are created automatically on first write — no manual setup required.
42
+
43
+ ## Quick Start
44
+
45
+ ```python
46
+ from langgraph.graph import StateGraph, MessagesState, START
47
+ from langchain_openai import ChatOpenAI
48
+ from langgraph_checkpoint_firestore import FirestoreSaver
49
+
50
+ model = ChatOpenAI(model="gpt-4o-mini")
51
+
52
+ def call_model(state: MessagesState):
53
+ return {"messages": model.invoke(state["messages"])}
54
+
55
+ builder = StateGraph(MessagesState)
56
+ builder.add_node("call_model", call_model)
57
+ builder.add_edge(START, "call_model")
58
+
59
+ with FirestoreSaver.from_conn_info(project_id="my-gcp-project", checkpoints_collection="checkpoints") as checkpointer:
60
+ graph = builder.compile(checkpointer=checkpointer)
61
+
62
+ config = {"configurable": {"thread_id": "user-123"}}
63
+
64
+ # First run — state is saved to Firestore
65
+ graph.invoke({"messages": [{"role": "user", "content": "Hi, I'm Kamal"}]}, config)
66
+
67
+ # Second run — picks up where it left off
68
+ graph.invoke({"messages": [{"role": "user", "content": "What's my name?"}]}, config)
69
+ ```
70
+
71
+ ## API Reference
72
+
73
+ ### `FirestoreSaver(project_id, checkpoints_collection, reducer=None, messages_key="messages")`
74
+
75
+ | Parameter | Type | Default | Description |
76
+ |---|---|---|---|
77
+ | `project_id` | `str` | required | Google Cloud project ID |
78
+ | `checkpoints_collection` | `str` | `"checkpoints"` | Root Firestore collection name |
79
+ | `reducer` | `MessageReducer` | `None` | Optional pruner — see [Message Pruning](#built-in-message-pruning) |
80
+ | `messages_key` | `str` | `"messages"` | State channel name that holds the message list |
81
+
82
+ You can also use the context manager factory:
83
+
84
+ ```python
85
+ with FirestoreSaver.from_conn_info(
86
+ project_id="my-gcp-project",
87
+ checkpoints_collection="checkpoints",
88
+ reducer=reducer,
89
+ messages_key="messages"
90
+ ) as saver:
91
+ graph = builder.compile(checkpointer=saver)
92
+ ```
93
+
94
+ ### Sync methods
95
+
96
+ | Method | Description |
97
+ |---|---|
98
+ | `put(config, checkpoint, metadata, new_versions)` | Save a checkpoint |
99
+ | `put_writes(config, writes, task_id)` | Save pending writes for a checkpoint |
100
+ | `get_tuple(config)` | Retrieve the latest (or a specific) checkpoint |
101
+ | `list(config, *, before, limit)` | Iterate checkpoints for a thread |
102
+
103
+ ### Async methods
104
+
105
+ All sync methods have async counterparts: `aput`, `aput_writes`, `aget_tuple`, `alist`.
106
+
107
+ ## Built-in Message Pruning
108
+
109
+ Long-running agents accumulate message history with every turn. Left unchecked this inflates checkpoint size, increases Firestore storage costs, and eventually blows past LLM context limits.
110
+
111
+ This checkpointer solves that at the persistence layer: pass a `MessageReducer` and it automatically prunes the message list inside `put()` before the checkpoint is serialised and written to Firestore. **Your graph code, state definition, and node logic stay untouched.**
112
+
113
+ This is an alternative to — or complement of — the LangGraph `Annotated[list, reducer_fn]` pattern. Use the checkpoint-layer approach when:
114
+
115
+ - You don't own the graph or state definition (e.g. using a pre-built LangGraph agent)
116
+ - You want pruning to happen unconditionally at every save, regardless of which node triggered it
117
+ - You want to keep all in-memory state intact and only prune what gets persisted
118
+
119
+ ### Install with reducer support
120
+
121
+ ```bash
122
+ pip install "langgraph-checkpoint-firestore[reducer]"
123
+ ```
124
+
125
+ ### Usage
126
+
127
+ ```python
128
+ from agentstate_reducer import MessageReducer
129
+ from langgraph_checkpoint_firestore import FirestoreSaver
130
+
131
+ reducer = MessageReducer(min_messages=10, max_messages=20)
132
+
133
+ with FirestoreSaver.from_conn_info(
134
+ project_id="my-gcp-project",
135
+ checkpoints_collection="checkpoints",
136
+ reducer=reducer, # prune before each checkpoint save
137
+ messages_key="messages" # state channel holding the message list (default)
138
+ ) as checkpointer:
139
+ graph = builder.compile(checkpointer=checkpointer)
140
+ ```
141
+
142
+ When `len(messages) > max_messages`, the oldest `human`/`ai` messages are removed until `min_messages` remain. The following are **never** pruned:
143
+
144
+ - Index 0 (typically the system prompt) — controlled by `preserve_first=True`
145
+ - `system` and `function` messages
146
+ - `tool` messages — unless their parent `ai` message is pruned (cascade behaviour, configurable)
147
+
148
+ See [agentstate-reducer on PyPI](https://pypi.org/project/agentstate-reducer/) for full configuration: `preserve_first`, `cascade_tool_messages`, `summarize_fn`, and role alias support (`user`/`assistant`/`agent`).
149
+
150
+ ## Data Model
151
+
152
+ Checkpoints are stored in a hierarchical Firestore structure:
153
+
154
+ ```
155
+ {checkpoints_collection}/
156
+ {thread_id}_{checkpoint_ns}/ ← partition document
157
+ checkpoints/
158
+ {checkpoint_id} ← checkpoint document
159
+ writes/
160
+ {task_id}_{idx} ← pending write documents
161
+ ```
162
+
163
+ This structure enables efficient per-thread checkpoint queries and keeps checkpoint data co-located with its pending writes.
164
+
165
+ ## License
166
+
167
+ MIT
File without changes
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2018 The Python Packaging Authority
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in all
11
+ copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19
+ SOFTWARE.
@@ -0,0 +1,7 @@
1
+
2
+
3
+ from langgraph_checkpoint_firestore.firestoreSaver import FirestoreSaver
4
+ from .firestoreSerializer import FirestoreSerializer
5
+
6
+ __all__ = ["FirestoreSaver", "FirestoreSerializer"]
7
+