langgraph-dbos 0.1.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,11 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .demo/
11
+ *.sqlite
@@ -0,0 +1,20 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ First release.
6
+
7
+ - `DBOSGraph.invoke` / `ainvoke`: run any compiled LangGraph graph inside a DBOS
8
+ workflow. After a crash the run resumes from the latest checkpoint; finished
9
+ nodes are not run again.
10
+ - Durable human-in-the-loop for `interrupt()`: `get_pending_input` and
11
+ `send_input` (sync and async, in-process or through `DBOSClient`), with a
12
+ per-question token and idempotent replies.
13
+ - `stream_mode=` writes graph stream chunks to a DBOS stream; `close_stream=`
14
+ keeps it open across calls.
15
+ - `step_options=` retries a failed segment from the latest checkpoint.
16
+ - A resume value saved by a crashed attempt is never reused for a later
17
+ question (checked with crash tests for two interrupts in one node and in a
18
+ subgraph).
19
+ - Clear errors for lost checkpoints, forks into a running graph, and calls
20
+ outside a workflow.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lakshit Mathur
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,327 @@
1
+ Metadata-Version: 2.5
2
+ Name: langgraph-dbos
3
+ Version: 0.1.0
4
+ Summary: Durable LangGraph agents on DBOS: crash recovery, durable human-in-the-loop and streaming on your own Postgres
5
+ Project-URL: Homepage, https://github.com/lllakshit/langgraph-dbos
6
+ Project-URL: Repository, https://github.com/lllakshit/langgraph-dbos
7
+ Project-URL: Issues, https://github.com/lllakshit/langgraph-dbos/issues
8
+ Project-URL: Changelog, https://github.com/lllakshit/langgraph-dbos/blob/main/CHANGELOG.md
9
+ Author: Lakshit Mathur
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agents,dbos,durable-execution,human-in-the-loop,langgraph,postgres,workflows
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.10
23
+ Requires-Dist: dbos<4,>=3.0
24
+ Requires-Dist: langgraph<2,>=1.0
25
+ Provides-Extra: postgres
26
+ Requires-Dist: langgraph-checkpoint-postgres>=3.0; extra == 'postgres'
27
+ Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
28
+ Provides-Extra: sqlite
29
+ Requires-Dist: langgraph-checkpoint-sqlite>=3.0; extra == 'sqlite'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # langgraph-dbos
33
+
34
+ [![CI](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml/badge.svg)](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml)
35
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
36
+
37
+ **Durable LangGraph agents on your own Postgres.** Wrap any compiled LangGraph
38
+ graph, call it from a [DBOS](https://github.com/dbos-inc/dbos-transact-py)
39
+ workflow, and it survives crashes, restarts and deploys:
40
+
41
+ - **Crash recovery that resumes, not restarts.** Kill the process mid-run; on
42
+ restart DBOS finds the unfinished run and continues from the node that was
43
+ running. Nodes that already finished, and the LLM calls inside them, are not
44
+ run or paid for again.
45
+ - **Human-in-the-loop that waits for days.** A node calls LangGraph's
46
+ `interrupt()`; the workflow waits in the database, not in memory, across any
47
+ number of restarts. Answer from a web handler or another service. Late,
48
+ stale or double-clicked answers are never applied to the wrong question.
49
+ - **Queues and rate limits for agents.** Run many graph runs through a DBOS
50
+ queue with concurrency and per-second limits to stay under LLM API quotas.
51
+ - **Retries that resume.** A segment that fails with a transient error is
52
+ retried from the latest checkpoint, so only the failed node runs again.
53
+ - **Streaming that outlives the request.** Stream graph events into a DBOS
54
+ stream and read them from any process, while the run is going or after.
55
+ - **No rewrite.** Your graph stays a normal LangGraph graph: `StateGraph`, the
56
+ Functional API, subgraphs, `Send`, reducers, callbacks. No nodes to
57
+ re-register.
58
+
59
+ No extra server to run: DBOS is a library, and its state lives in the same
60
+ Postgres (or SQLite) database as your LangGraph checkpoints.
61
+
62
+ ![Crash demo: the agent is killed during "write" and resumes there](https://raw.githubusercontent.com/lllakshit/langgraph-dbos/main/docs/crash-demo.svg)
63
+
64
+ ## Install
65
+
66
+ ```bash
67
+ pip install "langgraph-dbos[postgres]" # PostgresSaver + psycopg
68
+ pip install "langgraph-dbos[sqlite]" # SqliteSaver, for local development
69
+ ```
70
+
71
+ Needs Python 3.10+, `dbos>=3.0` and `langgraph>=1.0`.
72
+
73
+ ## Quickstart
74
+
75
+ ```python
76
+ import psycopg
77
+ from dbos import DBOS
78
+ from langgraph.checkpoint.postgres import PostgresSaver
79
+ from langgraph.graph import START, StateGraph
80
+ from psycopg.rows import dict_row
81
+ from typing_extensions import TypedDict
82
+
83
+ from langgraph_dbos import DBOSGraph
84
+
85
+ DATABASE_URL = "postgresql://postgres:dbos@localhost:5433/langgraph_dbos"
86
+
87
+
88
+ class State(TypedDict, total=False):
89
+ question: str
90
+ research: str
91
+ answer: str
92
+
93
+
94
+ def research(state: State) -> State:
95
+ return {"research": f"notes about {state['question']}"} # an LLM call
96
+
97
+
98
+ def write(state: State) -> State:
99
+ return {"answer": f"answer from {state['research']}"} # another LLM call
100
+
101
+
102
+ builder = StateGraph(State)
103
+ builder.add_node("research", research)
104
+ builder.add_node("write", write)
105
+ builder.add_edge(START, "research")
106
+ builder.add_edge("research", "write")
107
+
108
+ conn = psycopg.connect(DATABASE_URL, autocommit=True, prepare_threshold=0, row_factory=dict_row)
109
+ checkpointer = PostgresSaver(conn)
110
+ checkpointer.setup()
111
+
112
+ agent = DBOSGraph(builder.compile(checkpointer=checkpointer))
113
+
114
+ DBOS(config={"name": "research-agent", "system_database_url": DATABASE_URL})
115
+
116
+
117
+ @DBOS.workflow()
118
+ def answer_question(question: str) -> str:
119
+ return agent.invoke({"question": question})["answer"]
120
+
121
+
122
+ if __name__ == "__main__":
123
+ DBOS.launch() # also recovers runs that a crash left unfinished
124
+ print(answer_question("What is durable execution?"))
125
+ ```
126
+
127
+ `DBOSGraph.invoke` takes the same input and config as `graph.invoke` and
128
+ returns the same output. It must be called from a `@DBOS.workflow()`. From an
129
+ `async` workflow, use `await agent.ainvoke(...)` with an async checkpointer
130
+ such as `AsyncPostgresSaver`.
131
+
132
+ Start a local Postgres with `docker compose up -d` ([compose.yaml](compose.yaml)) or:
133
+
134
+ ```bash
135
+ docker run -d --name langgraph-dbos-pg -e POSTGRES_PASSWORD=dbos -e POSTGRES_DB=langgraph_dbos -p 5433:5432 postgres:17
136
+ ```
137
+
138
+ ## See it survive a crash
139
+
140
+ ```bash
141
+ python examples/crash_demo.py # 5 "LLM" nodes; the process is killed with SIGKILL during "write"
142
+ python examples/crash_demo.py # restart: resumes at "write", the first 3 nodes are not called again
143
+ ```
144
+
145
+ ## Human-in-the-loop
146
+
147
+ Use LangGraph's own `interrupt()` in a node. `invoke` waits durably for the
148
+ answer and then continues the graph:
149
+
150
+ ```python
151
+ from langgraph.types import interrupt
152
+
153
+
154
+ def approve(state: State) -> State:
155
+ decision = interrupt({"draft": state["draft"], "ask": "Send this reply?"})
156
+ return {"decision": decision}
157
+
158
+
159
+ @DBOS.workflow()
160
+ def reply_to_ticket(question: str) -> State:
161
+ return agent.invoke({"question": question})
162
+ ```
163
+
164
+ From anywhere else (a FastAPI route, a Slack handler, a CLI):
165
+
166
+ ```python
167
+ from dbos import DBOSClient
168
+ from langgraph_dbos import get_pending_input, send_input
169
+
170
+ client = DBOSClient(system_database_url=DATABASE_URL) # or leave out client= inside a DBOS app
171
+
172
+ pending = get_pending_input(workflow_id, client=client)
173
+ # {"token": "...", "thread_id": "...", "interrupts": [{"id": "...", "value": {"draft": ..., "ask": ...}}]}
174
+
175
+ send_input(workflow_id, "ship it", token=pending["token"], client=client)
176
+ ```
177
+
178
+ - The answer becomes the return value of `interrupt()`, exactly as with
179
+ `Command(resume=...)`.
180
+ - Pass the `token` you showed the human. A reply with an old token is ignored,
181
+ and a second reply with the same token is not delivered (DBOS idempotency).
182
+ - Several nodes interrupted at once: send a dict that maps each interrupt `id`
183
+ to its answer.
184
+ - `invoke(..., input_timeout=3600)` stops waiting after an hour and returns the
185
+ interrupted output (with `"__interrupt__"`). `wait_for_input=False` returns
186
+ at the first interrupt.
187
+
188
+ Try it: [examples/human_approval.py](examples/human_approval.py). Kill the
189
+ worker while it waits, start it again, then answer from another terminal.
190
+
191
+ ## Many agents, with limits
192
+
193
+ ```python
194
+ @DBOS.workflow()
195
+ def weather(city: str) -> str:
196
+ return agent.invoke({"city": city})["summary"]
197
+
198
+
199
+ DBOS.launch()
200
+ agents = DBOS.register_queue("agents", global_concurrency=3, limiter={"limit": 10, "period": 1})
201
+ handles = [agents.enqueue(weather, city) for city in cities]
202
+ ```
203
+
204
+ See [examples/queue_many_agents.py](examples/queue_many_agents.py).
205
+
206
+ ## Streaming
207
+
208
+ ```python
209
+ @DBOS.workflow()
210
+ def run(question: str) -> State:
211
+ return agent.invoke({"question": question}, stream_mode=["updates", "custom"])
212
+
213
+
214
+ for mode, chunk in DBOS.read_stream(workflow_id, "langgraph.stream"):
215
+ ...
216
+ ```
217
+
218
+ Chunks have the same shape as `graph.stream(...)` with the same `stream_mode`.
219
+ Change the key with `stream_key=`, and use a different key for each
220
+ streaming `invoke` in one workflow (or pass `close_stream=False` to keep
221
+ writing to one stream). The stream is closed when `invoke` returns, so
222
+ readers stop. Delivery is at-least-once: after a crash or retry, chunks from
223
+ the node that was running are written again.
224
+
225
+ ## Retries
226
+
227
+ ```python
228
+ agent = DBOSGraph(
229
+ graph, step_options={"retries_allowed": True, "max_attempts": 5, "backoff_rate": 2}
230
+ )
231
+ ```
232
+
233
+ Each retry resumes from the latest checkpoint, so nodes that finished before
234
+ the failure are not run again.
235
+
236
+ ## How it works
237
+
238
+ ```
239
+ @DBOS.workflow
240
+ ├─ step <name>.start records the thread id and the checkpoint the run starts from
241
+ ├─ step <name>.run graph.invoke(...) until it finishes or hits interrupt()
242
+ ├─ set_event "waiting for input" + token
243
+ ├─ recv the human's reply (durable wait)
244
+ ├─ step <name>.run graph.invoke(Command(resume=reply))
245
+ └─ ...
246
+ ```
247
+
248
+ - A run is split into **segments**: one `graph.invoke` until the graph ends or
249
+ interrupts. Each segment is one DBOS step, so the workflow's recorded history
250
+ is the same on every replay.
251
+ - **Inside** a segment, LangGraph's checkpointer saves every super-step
252
+ (`durability="sync"` by default).
253
+ - If the process dies mid-segment, DBOS reruns that step on recovery. The step
254
+ compares the thread's latest checkpoint and its pending writes with what was
255
+ recorded when the segment began. Unchanged: it applies the input. Changed: a
256
+ previous attempt made progress, so it resumes with `invoke(None)`, never
257
+ applying the input twice and never letting a saved answer reach a later
258
+ question.
259
+ - `@DBOS.step()` functions called inside nodes run inline as part of the
260
+ segment, so existing DBOS tools can be reused in nodes.
261
+
262
+ More detail, and the designs that were rejected: [docs/design.md](docs/design.md).
263
+
264
+ ## Guarantees and limits
265
+
266
+ - **A node that was running when the process died runs again.** Finished nodes
267
+ do not. Make side effects in nodes idempotent (an idempotency key on the
268
+ payment, upsert instead of insert), as with any at-least-once system.
269
+ - **Use a persistent checkpointer.** With `InMemorySaver`, a recovered run
270
+ cannot resume and raises `CheckpointLostError` (you get a warning when you
271
+ create the `DBOSGraph`).
272
+ - **An answer is never applied to a question it was not given for.** In one
273
+ narrow crash window (after LangGraph saved the answer, before the node read
274
+ it) the question is asked again instead of guessing; the human answers
275
+ twice, but no answer lands on the wrong question.
276
+ - **Graph output and interrupt values must be serializable by DBOS** (pickle by
277
+ default), because DBOS records each segment's output. LangChain messages
278
+ are. This package's own records are plain dicts.
279
+ - **Only this run writes to its thread.** Two workflows on the same
280
+ `thread_id` at once are not supported (with a queue, partition by thread).
281
+ Do not call `graph.update_state(...)` on a thread while its workflow waits
282
+ for input: the next reply is then treated as stale and the question is
283
+ asked again. Put edits in the reply instead.
284
+ - **Call `invoke`/`ainvoke` one after another in a workflow**, not with
285
+ `asyncio.gather`. For parallel graph runs, start child workflows.
286
+ - **Use `interrupt()`, not static `interrupt_before`/`interrupt_after`
287
+ breakpoints.** After a crash, a run paused at a static breakpoint could
288
+ continue past it.
289
+ - **Forking** (`DBOS.fork_workflow`) works from the `<name>.start` step or
290
+ earlier: the fork gets its own fresh graph run. Forking into the middle of a
291
+ run raises `ForkNotSupportedError` instead of sharing the original's thread.
292
+ - **Python 3.10 and async nodes:** LangGraph's `interrupt()` does not work in
293
+ `async` nodes on Python 3.10 (a LangGraph limitation). Sync nodes are fine.
294
+ - **Code changes:** as with any DBOS workflow, a pending run must be recovered
295
+ by compatible code. Keep `DBOSGraph(name=...)` stable.
296
+
297
+ ## Compared with
298
+
299
+ | | Checkpointer only | langgraph-dbos |
300
+ |---|---|---|
301
+ | State saved after each super-step | yes | yes (same checkpointer) |
302
+ | Unfinished runs restarted after a crash | no: you find and re-invoke them | yes, on `DBOS.launch()` |
303
+ | Waiting for a human across restarts | thread stays paused; you build the resume plumbing | built in, with stale and duplicate protection |
304
+ | Queues, concurrency and rate limits | no | DBOS queues |
305
+ | Run history, cancel, resume, fork | no | DBOS workflow management |
306
+
307
+ [`SamuelXing/dbos-langgraph`](https://github.com/SamuelXing/dbos-langgraph)
308
+ takes a different route: it runs each node as its own DBOS child workflow with
309
+ no LangGraph checkpointer, and nodes are registered through its plugin. This
310
+ package keeps LangGraph's checkpointer and runs your compiled graph as it is,
311
+ which is what lets `interrupt()`, subgraphs and streaming work unchanged.
312
+
313
+ ## Development
314
+
315
+ ```bash
316
+ uv sync
317
+ uv run pytest # SQLite
318
+ LANGGRAPH_DBOS_TEST_POSTGRES=postgresql://postgres:dbos@localhost:5433/langgraph_dbos uv run pytest
319
+ uv run ruff check . && uv run mypy
320
+ ```
321
+
322
+ The recovery tests start a real process, kill it with `SIGKILL` in the middle
323
+ of a run, restart it, and count how many times each node body ran.
324
+
325
+ ## License
326
+
327
+ MIT
@@ -0,0 +1,296 @@
1
+ # langgraph-dbos
2
+
3
+ [![CI](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml/badge.svg)](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
+
6
+ **Durable LangGraph agents on your own Postgres.** Wrap any compiled LangGraph
7
+ graph, call it from a [DBOS](https://github.com/dbos-inc/dbos-transact-py)
8
+ workflow, and it survives crashes, restarts and deploys:
9
+
10
+ - **Crash recovery that resumes, not restarts.** Kill the process mid-run; on
11
+ restart DBOS finds the unfinished run and continues from the node that was
12
+ running. Nodes that already finished, and the LLM calls inside them, are not
13
+ run or paid for again.
14
+ - **Human-in-the-loop that waits for days.** A node calls LangGraph's
15
+ `interrupt()`; the workflow waits in the database, not in memory, across any
16
+ number of restarts. Answer from a web handler or another service. Late,
17
+ stale or double-clicked answers are never applied to the wrong question.
18
+ - **Queues and rate limits for agents.** Run many graph runs through a DBOS
19
+ queue with concurrency and per-second limits to stay under LLM API quotas.
20
+ - **Retries that resume.** A segment that fails with a transient error is
21
+ retried from the latest checkpoint, so only the failed node runs again.
22
+ - **Streaming that outlives the request.** Stream graph events into a DBOS
23
+ stream and read them from any process, while the run is going or after.
24
+ - **No rewrite.** Your graph stays a normal LangGraph graph: `StateGraph`, the
25
+ Functional API, subgraphs, `Send`, reducers, callbacks. No nodes to
26
+ re-register.
27
+
28
+ No extra server to run: DBOS is a library, and its state lives in the same
29
+ Postgres (or SQLite) database as your LangGraph checkpoints.
30
+
31
+ ![Crash demo: the agent is killed during "write" and resumes there](https://raw.githubusercontent.com/lllakshit/langgraph-dbos/main/docs/crash-demo.svg)
32
+
33
+ ## Install
34
+
35
+ ```bash
36
+ pip install "langgraph-dbos[postgres]" # PostgresSaver + psycopg
37
+ pip install "langgraph-dbos[sqlite]" # SqliteSaver, for local development
38
+ ```
39
+
40
+ Needs Python 3.10+, `dbos>=3.0` and `langgraph>=1.0`.
41
+
42
+ ## Quickstart
43
+
44
+ ```python
45
+ import psycopg
46
+ from dbos import DBOS
47
+ from langgraph.checkpoint.postgres import PostgresSaver
48
+ from langgraph.graph import START, StateGraph
49
+ from psycopg.rows import dict_row
50
+ from typing_extensions import TypedDict
51
+
52
+ from langgraph_dbos import DBOSGraph
53
+
54
+ DATABASE_URL = "postgresql://postgres:dbos@localhost:5433/langgraph_dbos"
55
+
56
+
57
+ class State(TypedDict, total=False):
58
+ question: str
59
+ research: str
60
+ answer: str
61
+
62
+
63
+ def research(state: State) -> State:
64
+ return {"research": f"notes about {state['question']}"} # an LLM call
65
+
66
+
67
+ def write(state: State) -> State:
68
+ return {"answer": f"answer from {state['research']}"} # another LLM call
69
+
70
+
71
+ builder = StateGraph(State)
72
+ builder.add_node("research", research)
73
+ builder.add_node("write", write)
74
+ builder.add_edge(START, "research")
75
+ builder.add_edge("research", "write")
76
+
77
+ conn = psycopg.connect(DATABASE_URL, autocommit=True, prepare_threshold=0, row_factory=dict_row)
78
+ checkpointer = PostgresSaver(conn)
79
+ checkpointer.setup()
80
+
81
+ agent = DBOSGraph(builder.compile(checkpointer=checkpointer))
82
+
83
+ DBOS(config={"name": "research-agent", "system_database_url": DATABASE_URL})
84
+
85
+
86
+ @DBOS.workflow()
87
+ def answer_question(question: str) -> str:
88
+ return agent.invoke({"question": question})["answer"]
89
+
90
+
91
+ if __name__ == "__main__":
92
+ DBOS.launch() # also recovers runs that a crash left unfinished
93
+ print(answer_question("What is durable execution?"))
94
+ ```
95
+
96
+ `DBOSGraph.invoke` takes the same input and config as `graph.invoke` and
97
+ returns the same output. It must be called from a `@DBOS.workflow()`. From an
98
+ `async` workflow, use `await agent.ainvoke(...)` with an async checkpointer
99
+ such as `AsyncPostgresSaver`.
100
+
101
+ Start a local Postgres with `docker compose up -d` ([compose.yaml](compose.yaml)) or:
102
+
103
+ ```bash
104
+ docker run -d --name langgraph-dbos-pg -e POSTGRES_PASSWORD=dbos -e POSTGRES_DB=langgraph_dbos -p 5433:5432 postgres:17
105
+ ```
106
+
107
+ ## See it survive a crash
108
+
109
+ ```bash
110
+ python examples/crash_demo.py # 5 "LLM" nodes; the process is killed with SIGKILL during "write"
111
+ python examples/crash_demo.py # restart: resumes at "write", the first 3 nodes are not called again
112
+ ```
113
+
114
+ ## Human-in-the-loop
115
+
116
+ Use LangGraph's own `interrupt()` in a node. `invoke` waits durably for the
117
+ answer and then continues the graph:
118
+
119
+ ```python
120
+ from langgraph.types import interrupt
121
+
122
+
123
+ def approve(state: State) -> State:
124
+ decision = interrupt({"draft": state["draft"], "ask": "Send this reply?"})
125
+ return {"decision": decision}
126
+
127
+
128
+ @DBOS.workflow()
129
+ def reply_to_ticket(question: str) -> State:
130
+ return agent.invoke({"question": question})
131
+ ```
132
+
133
+ From anywhere else (a FastAPI route, a Slack handler, a CLI):
134
+
135
+ ```python
136
+ from dbos import DBOSClient
137
+ from langgraph_dbos import get_pending_input, send_input
138
+
139
+ client = DBOSClient(system_database_url=DATABASE_URL) # or leave out client= inside a DBOS app
140
+
141
+ pending = get_pending_input(workflow_id, client=client)
142
+ # {"token": "...", "thread_id": "...", "interrupts": [{"id": "...", "value": {"draft": ..., "ask": ...}}]}
143
+
144
+ send_input(workflow_id, "ship it", token=pending["token"], client=client)
145
+ ```
146
+
147
+ - The answer becomes the return value of `interrupt()`, exactly as with
148
+ `Command(resume=...)`.
149
+ - Pass the `token` you showed the human. A reply with an old token is ignored,
150
+ and a second reply with the same token is not delivered (DBOS idempotency).
151
+ - Several nodes interrupted at once: send a dict that maps each interrupt `id`
152
+ to its answer.
153
+ - `invoke(..., input_timeout=3600)` stops waiting after an hour and returns the
154
+ interrupted output (with `"__interrupt__"`). `wait_for_input=False` returns
155
+ at the first interrupt.
156
+
157
+ Try it: [examples/human_approval.py](examples/human_approval.py). Kill the
158
+ worker while it waits, start it again, then answer from another terminal.
159
+
160
+ ## Many agents, with limits
161
+
162
+ ```python
163
+ @DBOS.workflow()
164
+ def weather(city: str) -> str:
165
+ return agent.invoke({"city": city})["summary"]
166
+
167
+
168
+ DBOS.launch()
169
+ agents = DBOS.register_queue("agents", global_concurrency=3, limiter={"limit": 10, "period": 1})
170
+ handles = [agents.enqueue(weather, city) for city in cities]
171
+ ```
172
+
173
+ See [examples/queue_many_agents.py](examples/queue_many_agents.py).
174
+
175
+ ## Streaming
176
+
177
+ ```python
178
+ @DBOS.workflow()
179
+ def run(question: str) -> State:
180
+ return agent.invoke({"question": question}, stream_mode=["updates", "custom"])
181
+
182
+
183
+ for mode, chunk in DBOS.read_stream(workflow_id, "langgraph.stream"):
184
+ ...
185
+ ```
186
+
187
+ Chunks have the same shape as `graph.stream(...)` with the same `stream_mode`.
188
+ Change the key with `stream_key=`, and use a different key for each
189
+ streaming `invoke` in one workflow (or pass `close_stream=False` to keep
190
+ writing to one stream). The stream is closed when `invoke` returns, so
191
+ readers stop. Delivery is at-least-once: after a crash or retry, chunks from
192
+ the node that was running are written again.
193
+
194
+ ## Retries
195
+
196
+ ```python
197
+ agent = DBOSGraph(
198
+ graph, step_options={"retries_allowed": True, "max_attempts": 5, "backoff_rate": 2}
199
+ )
200
+ ```
201
+
202
+ Each retry resumes from the latest checkpoint, so nodes that finished before
203
+ the failure are not run again.
204
+
205
+ ## How it works
206
+
207
+ ```
208
+ @DBOS.workflow
209
+ ├─ step <name>.start records the thread id and the checkpoint the run starts from
210
+ ├─ step <name>.run graph.invoke(...) until it finishes or hits interrupt()
211
+ ├─ set_event "waiting for input" + token
212
+ ├─ recv the human's reply (durable wait)
213
+ ├─ step <name>.run graph.invoke(Command(resume=reply))
214
+ └─ ...
215
+ ```
216
+
217
+ - A run is split into **segments**: one `graph.invoke` until the graph ends or
218
+ interrupts. Each segment is one DBOS step, so the workflow's recorded history
219
+ is the same on every replay.
220
+ - **Inside** a segment, LangGraph's checkpointer saves every super-step
221
+ (`durability="sync"` by default).
222
+ - If the process dies mid-segment, DBOS reruns that step on recovery. The step
223
+ compares the thread's latest checkpoint and its pending writes with what was
224
+ recorded when the segment began. Unchanged: it applies the input. Changed: a
225
+ previous attempt made progress, so it resumes with `invoke(None)`, never
226
+ applying the input twice and never letting a saved answer reach a later
227
+ question.
228
+ - `@DBOS.step()` functions called inside nodes run inline as part of the
229
+ segment, so existing DBOS tools can be reused in nodes.
230
+
231
+ More detail, and the designs that were rejected: [docs/design.md](docs/design.md).
232
+
233
+ ## Guarantees and limits
234
+
235
+ - **A node that was running when the process died runs again.** Finished nodes
236
+ do not. Make side effects in nodes idempotent (an idempotency key on the
237
+ payment, upsert instead of insert), as with any at-least-once system.
238
+ - **Use a persistent checkpointer.** With `InMemorySaver`, a recovered run
239
+ cannot resume and raises `CheckpointLostError` (you get a warning when you
240
+ create the `DBOSGraph`).
241
+ - **An answer is never applied to a question it was not given for.** In one
242
+ narrow crash window (after LangGraph saved the answer, before the node read
243
+ it) the question is asked again instead of guessing; the human answers
244
+ twice, but no answer lands on the wrong question.
245
+ - **Graph output and interrupt values must be serializable by DBOS** (pickle by
246
+ default), because DBOS records each segment's output. LangChain messages
247
+ are. This package's own records are plain dicts.
248
+ - **Only this run writes to its thread.** Two workflows on the same
249
+ `thread_id` at once are not supported (with a queue, partition by thread).
250
+ Do not call `graph.update_state(...)` on a thread while its workflow waits
251
+ for input: the next reply is then treated as stale and the question is
252
+ asked again. Put edits in the reply instead.
253
+ - **Call `invoke`/`ainvoke` one after another in a workflow**, not with
254
+ `asyncio.gather`. For parallel graph runs, start child workflows.
255
+ - **Use `interrupt()`, not static `interrupt_before`/`interrupt_after`
256
+ breakpoints.** After a crash, a run paused at a static breakpoint could
257
+ continue past it.
258
+ - **Forking** (`DBOS.fork_workflow`) works from the `<name>.start` step or
259
+ earlier: the fork gets its own fresh graph run. Forking into the middle of a
260
+ run raises `ForkNotSupportedError` instead of sharing the original's thread.
261
+ - **Python 3.10 and async nodes:** LangGraph's `interrupt()` does not work in
262
+ `async` nodes on Python 3.10 (a LangGraph limitation). Sync nodes are fine.
263
+ - **Code changes:** as with any DBOS workflow, a pending run must be recovered
264
+ by compatible code. Keep `DBOSGraph(name=...)` stable.
265
+
266
+ ## Compared with
267
+
268
+ | | Checkpointer only | langgraph-dbos |
269
+ |---|---|---|
270
+ | State saved after each super-step | yes | yes (same checkpointer) |
271
+ | Unfinished runs restarted after a crash | no: you find and re-invoke them | yes, on `DBOS.launch()` |
272
+ | Waiting for a human across restarts | thread stays paused; you build the resume plumbing | built in, with stale and duplicate protection |
273
+ | Queues, concurrency and rate limits | no | DBOS queues |
274
+ | Run history, cancel, resume, fork | no | DBOS workflow management |
275
+
276
+ [`SamuelXing/dbos-langgraph`](https://github.com/SamuelXing/dbos-langgraph)
277
+ takes a different route: it runs each node as its own DBOS child workflow with
278
+ no LangGraph checkpointer, and nodes are registered through its plugin. This
279
+ package keeps LangGraph's checkpointer and runs your compiled graph as it is,
280
+ which is what lets `interrupt()`, subgraphs and streaming work unchanged.
281
+
282
+ ## Development
283
+
284
+ ```bash
285
+ uv sync
286
+ uv run pytest # SQLite
287
+ LANGGRAPH_DBOS_TEST_POSTGRES=postgresql://postgres:dbos@localhost:5433/langgraph_dbos uv run pytest
288
+ uv run ruff check . && uv run mypy
289
+ ```
290
+
291
+ The recovery tests start a real process, kill it with `SIGKILL` in the middle
292
+ of a run, restart it, and count how many times each node body ran.
293
+
294
+ ## License
295
+
296
+ MIT