langgraph-dbos 0.1.0__py3-none-any.whl
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.
- langgraph_dbos/__init__.py +42 -0
- langgraph_dbos/_graph.py +645 -0
- langgraph_dbos/_input.py +131 -0
- langgraph_dbos/py.typed +0 -0
- langgraph_dbos-0.1.0.dist-info/METADATA +327 -0
- langgraph_dbos-0.1.0.dist-info/RECORD +8 -0
- langgraph_dbos-0.1.0.dist-info/WHEEL +4 -0
- langgraph_dbos-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Durable LangGraph agents on DBOS.
|
|
2
|
+
|
|
3
|
+
Crash recovery, durable human-in-the-loop and streaming on your own Postgres.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from ._graph import (
|
|
7
|
+
DEFAULT_STREAM_KEY,
|
|
8
|
+
INPUT_TOPIC,
|
|
9
|
+
PENDING_INPUT_EVENT,
|
|
10
|
+
CheckpointLostError,
|
|
11
|
+
DBOSGraph,
|
|
12
|
+
DBOSGraphError,
|
|
13
|
+
ForkNotSupportedError,
|
|
14
|
+
InterruptInfo,
|
|
15
|
+
PendingInput,
|
|
16
|
+
)
|
|
17
|
+
from ._input import (
|
|
18
|
+
NoPendingInputError,
|
|
19
|
+
get_pending_input,
|
|
20
|
+
get_pending_input_async,
|
|
21
|
+
send_input,
|
|
22
|
+
send_input_async,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
__version__ = "0.1.0"
|
|
26
|
+
|
|
27
|
+
__all__ = [
|
|
28
|
+
"DEFAULT_STREAM_KEY",
|
|
29
|
+
"INPUT_TOPIC",
|
|
30
|
+
"PENDING_INPUT_EVENT",
|
|
31
|
+
"CheckpointLostError",
|
|
32
|
+
"DBOSGraph",
|
|
33
|
+
"DBOSGraphError",
|
|
34
|
+
"ForkNotSupportedError",
|
|
35
|
+
"InterruptInfo",
|
|
36
|
+
"NoPendingInputError",
|
|
37
|
+
"PendingInput",
|
|
38
|
+
"get_pending_input",
|
|
39
|
+
"get_pending_input_async",
|
|
40
|
+
"send_input",
|
|
41
|
+
"send_input_async",
|
|
42
|
+
]
|
langgraph_dbos/_graph.py
ADDED
|
@@ -0,0 +1,645 @@
|
|
|
1
|
+
"""Run LangGraph graphs as durable DBOS workflows.
|
|
2
|
+
|
|
3
|
+
How it works
|
|
4
|
+
------------
|
|
5
|
+
A graph run is split into *segments*. A segment is one call to the graph that
|
|
6
|
+
lasts until the graph finishes or stops at an ``interrupt()``. Each segment runs
|
|
7
|
+
as one DBOS step, and the human-in-the-loop waits between segments are DBOS
|
|
8
|
+
workflow operations (``set_event`` and ``recv``). So the order of operations the
|
|
9
|
+
workflow records is always the same on replay.
|
|
10
|
+
|
|
11
|
+
Inside a segment, LangGraph's own checkpointer records progress after every
|
|
12
|
+
super-step. If the process dies mid-segment, DBOS recovers the workflow and
|
|
13
|
+
runs the segment step again. The step sees that the thread has moved past the
|
|
14
|
+
checkpoint it started from, so it resumes the graph from the latest checkpoint
|
|
15
|
+
instead of starting over: nodes that already finished are not run again.
|
|
16
|
+
|
|
17
|
+
To tell "the input was never applied" from "an earlier attempt applied it and
|
|
18
|
+
then died", a segment records the thread's latest checkpoint id *and* a hash of
|
|
19
|
+
that checkpoint's pending writes. LangGraph can apply a resume value and stop
|
|
20
|
+
at the next ``interrupt()`` without writing a new checkpoint (two interrupts in
|
|
21
|
+
one node, or in a subgraph), so the checkpoint id alone is not enough.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
import hashlib
|
|
27
|
+
import warnings
|
|
28
|
+
from collections.abc import Sequence
|
|
29
|
+
from typing import Any, Optional, TypedDict, Union, cast
|
|
30
|
+
|
|
31
|
+
from dbos import DBOS, StepOptions
|
|
32
|
+
from langchain_core.runnables import RunnableConfig
|
|
33
|
+
from langgraph.checkpoint.base import BaseCheckpointSaver, CheckpointTuple
|
|
34
|
+
from langgraph.checkpoint.memory import InMemorySaver
|
|
35
|
+
from langgraph.pregel import Pregel
|
|
36
|
+
from langgraph.types import Command, Interrupt, StreamMode
|
|
37
|
+
|
|
38
|
+
PENDING_INPUT_EVENT = "langgraph.pending_input"
|
|
39
|
+
"""DBOS event key a waiting workflow sets to describe the input it needs."""
|
|
40
|
+
|
|
41
|
+
INPUT_TOPIC = "langgraph.input"
|
|
42
|
+
"""DBOS message topic that carries human input back to a waiting workflow."""
|
|
43
|
+
|
|
44
|
+
DEFAULT_STREAM_KEY = "langgraph.stream"
|
|
45
|
+
"""DBOS stream key that graph stream chunks are written to by default."""
|
|
46
|
+
|
|
47
|
+
_INTERRUPT = "__interrupt__"
|
|
48
|
+
# Names LangGraph stores in checkpoint writes. They are part of the persisted
|
|
49
|
+
# checkpoint format, so they are stable across LangGraph versions.
|
|
50
|
+
_RESUME = "__resume__"
|
|
51
|
+
_NULL_TASK_ID = "00000000-0000-0000-0000-000000000000"
|
|
52
|
+
_WAIT_CHUNK_SECONDS = 24 * 60 * 60
|
|
53
|
+
|
|
54
|
+
StreamModes = Union[StreamMode, Sequence[StreamMode]]
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class InterruptInfo(TypedDict):
|
|
58
|
+
"""One pending ``interrupt()`` raised by a node."""
|
|
59
|
+
|
|
60
|
+
id: str
|
|
61
|
+
value: Any
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class PendingInput(TypedDict):
|
|
65
|
+
"""What a workflow waiting for human input publishes as a DBOS event."""
|
|
66
|
+
|
|
67
|
+
token: str
|
|
68
|
+
"""Identifies this wait. Pass it back with the reply so a late or repeated
|
|
69
|
+
reply is never applied to a different question."""
|
|
70
|
+
thread_id: str
|
|
71
|
+
interrupts: list[InterruptInfo]
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class DBOSGraphError(RuntimeError):
|
|
75
|
+
"""Base class for errors raised by langgraph-dbos."""
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class CheckpointLostError(DBOSGraphError):
|
|
79
|
+
"""The checkpointer no longer has the thread this workflow was running.
|
|
80
|
+
|
|
81
|
+
Raised when a recovered workflow finds an empty thread although it had
|
|
82
|
+
already made progress, for example when an in-memory checkpointer was used
|
|
83
|
+
and the process restarted.
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class ForkNotSupportedError(DBOSGraphError):
|
|
88
|
+
"""A forked workflow tried to continue a graph run that started before the fork."""
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
# Step outputs are plain dicts so that pending workflows survive a rename of
|
|
92
|
+
# this module's classes, and so that DBOS serializers other than pickle work.
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
class _Position(TypedDict):
|
|
96
|
+
"""Where a thread stood when a step finished."""
|
|
97
|
+
|
|
98
|
+
checkpoint_id: Optional[str]
|
|
99
|
+
writes: Optional[str]
|
|
100
|
+
"""Hash of the checkpoint's pending writes."""
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
class _Run(TypedDict):
|
|
104
|
+
"""Recorded once per ``invoke`` by the start step."""
|
|
105
|
+
|
|
106
|
+
owner: str
|
|
107
|
+
thread_id: str
|
|
108
|
+
position: _Position
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class _Segment(TypedDict):
|
|
112
|
+
"""Recorded by every segment step."""
|
|
113
|
+
|
|
114
|
+
output: Any
|
|
115
|
+
interrupts: list[InterruptInfo]
|
|
116
|
+
position: _Position
|
|
117
|
+
token: str
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _require_workflow(method: str) -> None:
|
|
121
|
+
if DBOS.step_id is not None:
|
|
122
|
+
raise DBOSGraphError(
|
|
123
|
+
f"DBOSGraph.{method}() was called inside a DBOS step. "
|
|
124
|
+
"Call it directly from a @DBOS.workflow() function."
|
|
125
|
+
)
|
|
126
|
+
if DBOS.workflow_id is None:
|
|
127
|
+
raise DBOSGraphError(
|
|
128
|
+
f"DBOSGraph.{method}() must be called from inside a @DBOS.workflow() function."
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _thread_config(
|
|
133
|
+
config: RunnableConfig, thread_id: str, *, keep_checkpoint_id: bool = False
|
|
134
|
+
) -> RunnableConfig:
|
|
135
|
+
"""Return ``config`` pointed at the root namespace of ``thread_id``."""
|
|
136
|
+
configurable = dict(config.get("configurable") or {})
|
|
137
|
+
configurable["thread_id"] = thread_id
|
|
138
|
+
configurable["checkpoint_ns"] = ""
|
|
139
|
+
if not keep_checkpoint_id:
|
|
140
|
+
configurable.pop("checkpoint_id", None)
|
|
141
|
+
return {**config, "configurable": configurable}
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _checkpoint_id(config: Optional[RunnableConfig]) -> Optional[str]:
|
|
145
|
+
if not config:
|
|
146
|
+
return None
|
|
147
|
+
value = (config.get("configurable") or {}).get("checkpoint_id")
|
|
148
|
+
return str(value) if value is not None else None
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _interrupt_infos(interrupts: Sequence[Interrupt]) -> list[InterruptInfo]:
|
|
152
|
+
return [{"id": i.id, "value": i.value} for i in interrupts]
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _position(
|
|
156
|
+
checkpointer: BaseCheckpointSaver[Any], latest: Optional[CheckpointTuple]
|
|
157
|
+
) -> _Position:
|
|
158
|
+
if latest is None:
|
|
159
|
+
return {"checkpoint_id": None, "writes": None}
|
|
160
|
+
digest = hashlib.sha256()
|
|
161
|
+
parts = []
|
|
162
|
+
for task_id, channel, value in latest.pending_writes or []:
|
|
163
|
+
kind, data = checkpointer.serde.dumps_typed(value)
|
|
164
|
+
parts.append((str(task_id), str(channel), str(kind), bytes(data)))
|
|
165
|
+
for task_id, channel, kind, data in sorted(parts):
|
|
166
|
+
for part in (task_id.encode(), channel.encode(), kind.encode(), data):
|
|
167
|
+
digest.update(len(part).to_bytes(8, "big"))
|
|
168
|
+
digest.update(part)
|
|
169
|
+
return {"checkpoint_id": _checkpoint_id(latest.config), "writes": digest.hexdigest()}
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _stale_resume(latest: Optional[CheckpointTuple]) -> bool:
|
|
173
|
+
"""True if the checkpoint holds a resume value that a previous attempt already applied."""
|
|
174
|
+
if latest is None:
|
|
175
|
+
return False
|
|
176
|
+
return any(
|
|
177
|
+
task_id == _NULL_TASK_ID and channel == _RESUME and value is not None
|
|
178
|
+
for task_id, channel, value in latest.pending_writes or []
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _as_modes(stream_mode: StreamModes) -> list[StreamMode]:
|
|
183
|
+
if isinstance(stream_mode, str):
|
|
184
|
+
return [stream_mode]
|
|
185
|
+
return list(stream_mode)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
class _StreamCollector:
|
|
189
|
+
"""Builds ``invoke``-style output from stream chunks and picks the ones to forward."""
|
|
190
|
+
|
|
191
|
+
def __init__(self, stream_mode: StreamModes, subgraphs: bool) -> None:
|
|
192
|
+
self.single = isinstance(stream_mode, str)
|
|
193
|
+
self.wanted = _as_modes(stream_mode)
|
|
194
|
+
self.subgraphs = subgraphs
|
|
195
|
+
# "values" and "updates" are always requested: they carry the output and
|
|
196
|
+
# the interrupts, the same way Pregel.invoke collects them.
|
|
197
|
+
self.run_modes: list[StreamMode] = list(dict.fromkeys([*self.wanted, "values", "updates"]))
|
|
198
|
+
self.latest: Any = None
|
|
199
|
+
self.interrupts: list[Interrupt] = []
|
|
200
|
+
|
|
201
|
+
def feed(self, chunk: Any) -> Optional[Any]:
|
|
202
|
+
"""Record ``chunk`` and return what to forward, or None to skip it."""
|
|
203
|
+
if self.subgraphs:
|
|
204
|
+
namespace, mode, data = chunk
|
|
205
|
+
else:
|
|
206
|
+
namespace, (mode, data) = (), chunk
|
|
207
|
+
if not namespace:
|
|
208
|
+
if mode == "values":
|
|
209
|
+
self.latest = data
|
|
210
|
+
elif mode == "updates" and isinstance(data, dict):
|
|
211
|
+
found = data.get(_INTERRUPT)
|
|
212
|
+
if found:
|
|
213
|
+
self.interrupts.extend(found)
|
|
214
|
+
if mode not in self.wanted:
|
|
215
|
+
return None
|
|
216
|
+
if self.single:
|
|
217
|
+
return (namespace, data) if self.subgraphs else data
|
|
218
|
+
return (namespace, mode, data) if self.subgraphs else (mode, data)
|
|
219
|
+
|
|
220
|
+
def output(self) -> Any:
|
|
221
|
+
if not self.interrupts:
|
|
222
|
+
return self.latest
|
|
223
|
+
if isinstance(self.latest, dict):
|
|
224
|
+
return {**self.latest, _INTERRUPT: self.interrupts}
|
|
225
|
+
return {_INTERRUPT: self.interrupts}
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
class DBOSGraph:
|
|
229
|
+
"""Wraps a compiled LangGraph graph so its runs are durable DBOS workflows.
|
|
230
|
+
|
|
231
|
+
Call :meth:`invoke` (or :meth:`ainvoke`) from inside a ``@DBOS.workflow()``::
|
|
232
|
+
|
|
233
|
+
durable = DBOSGraph(graph, checkpointer=PostgresSaver(conn))
|
|
234
|
+
|
|
235
|
+
@DBOS.workflow()
|
|
236
|
+
def research(question: str) -> dict:
|
|
237
|
+
return durable.invoke({"question": question})
|
|
238
|
+
|
|
239
|
+
If the process crashes, DBOS recovers the workflow on restart and the graph
|
|
240
|
+
resumes from its latest checkpoint. Nodes that already finished are not run
|
|
241
|
+
again. A node that calls ``interrupt()`` makes the workflow wait durably for
|
|
242
|
+
:func:`~langgraph_dbos.send_input`, for minutes or days, across restarts.
|
|
243
|
+
|
|
244
|
+
Args:
|
|
245
|
+
graph: A compiled graph (``StateGraph.compile()`` or an ``@entrypoint``).
|
|
246
|
+
checkpointer: Overrides the graph's checkpointer. A persistent one
|
|
247
|
+
(``PostgresSaver``, ``SqliteSaver`` or their async versions) is needed
|
|
248
|
+
for in-run progress to survive a crash.
|
|
249
|
+
name: Prefix for the DBOS step names. Defaults to the graph's name. Keep
|
|
250
|
+
it stable: pending workflows replay steps by name.
|
|
251
|
+
step_options: DBOS step options for each graph segment, for example
|
|
252
|
+
``{"retries_allowed": True, "max_attempts": 3}``. A retried segment
|
|
253
|
+
resumes from the latest checkpoint, so only the failed node reruns.
|
|
254
|
+
Errors from this library (lost checkpoints, forks) are never retried.
|
|
255
|
+
"""
|
|
256
|
+
|
|
257
|
+
def __init__(
|
|
258
|
+
self,
|
|
259
|
+
graph: Pregel[Any, Any],
|
|
260
|
+
*,
|
|
261
|
+
checkpointer: Optional[BaseCheckpointSaver[Any]] = None,
|
|
262
|
+
name: Optional[str] = None,
|
|
263
|
+
step_options: Optional[StepOptions] = None,
|
|
264
|
+
) -> None:
|
|
265
|
+
if not isinstance(graph, Pregel):
|
|
266
|
+
raise TypeError(
|
|
267
|
+
f"DBOSGraph expects a compiled LangGraph graph, got {type(graph).__name__}. "
|
|
268
|
+
"Call .compile() on a StateGraph first."
|
|
269
|
+
)
|
|
270
|
+
if checkpointer is not None:
|
|
271
|
+
graph = graph.copy(update={"checkpointer": checkpointer})
|
|
272
|
+
if not isinstance(graph.checkpointer, BaseCheckpointSaver):
|
|
273
|
+
raise ValueError(
|
|
274
|
+
"DBOSGraph needs a checkpointer. Compile the graph with one or pass "
|
|
275
|
+
"checkpointer=..., for example PostgresSaver on the same Postgres "
|
|
276
|
+
"database DBOS uses."
|
|
277
|
+
)
|
|
278
|
+
if isinstance(graph.checkpointer, InMemorySaver):
|
|
279
|
+
warnings.warn(
|
|
280
|
+
"DBOSGraph is using an in-memory checkpointer: a graph run that is "
|
|
281
|
+
"recovered after a crash cannot resume and raises CheckpointLostError. "
|
|
282
|
+
"Use PostgresSaver or SqliteSaver outside tests.",
|
|
283
|
+
stacklevel=2,
|
|
284
|
+
)
|
|
285
|
+
self.graph: Pregel[Any, Any] = graph
|
|
286
|
+
self.checkpointer: BaseCheckpointSaver[Any] = graph.checkpointer
|
|
287
|
+
self.name: str = name or graph.name or "LangGraph"
|
|
288
|
+
options: dict[str, Any] = {**(step_options or {}), "name": f"{self.name}.run"}
|
|
289
|
+
user_should_retry = options.get("should_retry")
|
|
290
|
+
|
|
291
|
+
def should_retry(error: BaseException) -> bool:
|
|
292
|
+
if isinstance(error, DBOSGraphError):
|
|
293
|
+
return False
|
|
294
|
+
return True if user_should_retry is None else bool(user_should_retry(error))
|
|
295
|
+
|
|
296
|
+
options["should_retry"] = should_retry
|
|
297
|
+
self._step_options = cast(StepOptions, options)
|
|
298
|
+
|
|
299
|
+
# ------------------------------------------------------------------ sync
|
|
300
|
+
|
|
301
|
+
def invoke(
|
|
302
|
+
self,
|
|
303
|
+
input: Any,
|
|
304
|
+
config: Optional[RunnableConfig] = None,
|
|
305
|
+
*,
|
|
306
|
+
wait_for_input: bool = True,
|
|
307
|
+
input_timeout: Optional[float] = None,
|
|
308
|
+
stream_mode: Optional[StreamModes] = None,
|
|
309
|
+
stream_key: str = DEFAULT_STREAM_KEY,
|
|
310
|
+
close_stream: bool = True,
|
|
311
|
+
**kwargs: Any,
|
|
312
|
+
) -> Any:
|
|
313
|
+
"""Run the graph durably and return its output, like ``graph.invoke``.
|
|
314
|
+
|
|
315
|
+
Must be called from a synchronous ``@DBOS.workflow()``.
|
|
316
|
+
|
|
317
|
+
Args:
|
|
318
|
+
input: The graph input, or a ``Command``.
|
|
319
|
+
config: LangGraph config. Pass ``configurable.thread_id`` to continue
|
|
320
|
+
an existing conversation thread; otherwise each call gets its own
|
|
321
|
+
thread named after the workflow. Only one run at a time may use
|
|
322
|
+
a thread.
|
|
323
|
+
wait_for_input: When a node calls ``interrupt()``, wait for
|
|
324
|
+
:func:`~langgraph_dbos.send_input` and continue. When False,
|
|
325
|
+
return the interrupted output (with ``"__interrupt__"``) instead.
|
|
326
|
+
input_timeout: Seconds to wait for each human reply. None waits with
|
|
327
|
+
no limit. On timeout the interrupted output is returned. A reply
|
|
328
|
+
with a wrong token restarts the wait.
|
|
329
|
+
stream_mode: When set, graph stream chunks in these modes are written
|
|
330
|
+
to the DBOS stream ``stream_key``; read them with
|
|
331
|
+
``DBOS.read_stream(workflow_id, stream_key)``. Delivery is
|
|
332
|
+
at-least-once: after a crash or retry, chunks of the node that
|
|
333
|
+
was running are written again.
|
|
334
|
+
stream_key: DBOS stream key for ``stream_mode``. Use a different key
|
|
335
|
+
for each streaming ``invoke`` in one workflow.
|
|
336
|
+
close_stream: Close the stream when the run ends, so readers stop.
|
|
337
|
+
**kwargs: Passed to ``graph.invoke`` / ``graph.stream``. ``durability``
|
|
338
|
+
defaults to ``"sync"``, so every super-step is saved before the
|
|
339
|
+
next one starts.
|
|
340
|
+
"""
|
|
341
|
+
_require_workflow("invoke")
|
|
342
|
+
config = config or {}
|
|
343
|
+
kwargs.setdefault("durability", "sync")
|
|
344
|
+
self._check_kwargs(stream_mode, kwargs)
|
|
345
|
+
|
|
346
|
+
run: _Run = DBOS.run_step(
|
|
347
|
+
{"name": f"{self.name}.start"}, self._start, config.get("configurable")
|
|
348
|
+
)
|
|
349
|
+
value: Any = input
|
|
350
|
+
position = run["position"]
|
|
351
|
+
first = True
|
|
352
|
+
while True:
|
|
353
|
+
segment: _Segment = DBOS.run_step(
|
|
354
|
+
self._step_options,
|
|
355
|
+
self._run_segment,
|
|
356
|
+
run,
|
|
357
|
+
value,
|
|
358
|
+
config,
|
|
359
|
+
position,
|
|
360
|
+
first,
|
|
361
|
+
stream_mode,
|
|
362
|
+
stream_key,
|
|
363
|
+
kwargs,
|
|
364
|
+
)
|
|
365
|
+
if not segment["interrupts"] or not wait_for_input:
|
|
366
|
+
break
|
|
367
|
+
DBOS.set_event(PENDING_INPUT_EVENT, self._pending(run, segment))
|
|
368
|
+
reply = self._wait_for_input(segment["token"], input_timeout)
|
|
369
|
+
DBOS.set_event(PENDING_INPUT_EVENT, None)
|
|
370
|
+
if reply is _NO_INPUT:
|
|
371
|
+
break
|
|
372
|
+
value = Command(resume=reply)
|
|
373
|
+
position = segment["position"]
|
|
374
|
+
first = False
|
|
375
|
+
if stream_mode is not None and close_stream:
|
|
376
|
+
DBOS.close_stream(stream_key)
|
|
377
|
+
return segment["output"]
|
|
378
|
+
|
|
379
|
+
def _start(self, configurable: Optional[dict[str, Any]]) -> _Run:
|
|
380
|
+
thread_id = self._thread_id(configurable)
|
|
381
|
+
latest = self.checkpointer.get_tuple(_thread_config({}, thread_id))
|
|
382
|
+
return self._run_record(thread_id, latest)
|
|
383
|
+
|
|
384
|
+
def _run_segment(
|
|
385
|
+
self,
|
|
386
|
+
run: _Run,
|
|
387
|
+
value: Any,
|
|
388
|
+
config: RunnableConfig,
|
|
389
|
+
position: _Position,
|
|
390
|
+
first: bool,
|
|
391
|
+
stream_mode: Optional[StreamModes],
|
|
392
|
+
stream_key: str,
|
|
393
|
+
kwargs: dict[str, Any],
|
|
394
|
+
) -> _Segment:
|
|
395
|
+
base = _thread_config(config, run["thread_id"])
|
|
396
|
+
latest = self.checkpointer.get_tuple(base)
|
|
397
|
+
run_input, run_config, clear_resume = self._plan(
|
|
398
|
+
run, value, config, position, first, latest
|
|
399
|
+
)
|
|
400
|
+
if clear_resume and latest is not None:
|
|
401
|
+
self.checkpointer.put_writes(latest.config, [(_RESUME, None)], _NULL_TASK_ID)
|
|
402
|
+
if stream_mode is None:
|
|
403
|
+
output = self.graph.invoke(run_input, run_config, **kwargs)
|
|
404
|
+
else:
|
|
405
|
+
collector = _StreamCollector(stream_mode, bool(kwargs.get("subgraphs")))
|
|
406
|
+
stream_kwargs = {**kwargs, "stream_mode": collector.run_modes}
|
|
407
|
+
for chunk in self.graph.stream(run_input, run_config, **stream_kwargs):
|
|
408
|
+
forward = collector.feed(chunk)
|
|
409
|
+
if forward is not None:
|
|
410
|
+
DBOS.write_stream(stream_key, forward)
|
|
411
|
+
output = collector.output()
|
|
412
|
+
snapshot = self.graph.get_state(base)
|
|
413
|
+
return self._segment_record(output, snapshot, self.checkpointer.get_tuple(base))
|
|
414
|
+
|
|
415
|
+
# ----------------------------------------------------------------- async
|
|
416
|
+
|
|
417
|
+
async def ainvoke(
|
|
418
|
+
self,
|
|
419
|
+
input: Any,
|
|
420
|
+
config: Optional[RunnableConfig] = None,
|
|
421
|
+
*,
|
|
422
|
+
wait_for_input: bool = True,
|
|
423
|
+
input_timeout: Optional[float] = None,
|
|
424
|
+
stream_mode: Optional[StreamModes] = None,
|
|
425
|
+
stream_key: str = DEFAULT_STREAM_KEY,
|
|
426
|
+
close_stream: bool = True,
|
|
427
|
+
**kwargs: Any,
|
|
428
|
+
) -> Any:
|
|
429
|
+
"""Async version of :meth:`invoke`, for ``async`` workflows.
|
|
430
|
+
|
|
431
|
+
Needs an async checkpointer such as ``AsyncPostgresSaver``. Do not run
|
|
432
|
+
two ``ainvoke`` calls of one workflow concurrently: DBOS needs workflow
|
|
433
|
+
steps to start in the same order on replay. Use child workflows for
|
|
434
|
+
parallel graph runs.
|
|
435
|
+
"""
|
|
436
|
+
_require_workflow("ainvoke")
|
|
437
|
+
config = config or {}
|
|
438
|
+
kwargs.setdefault("durability", "sync")
|
|
439
|
+
self._check_kwargs(stream_mode, kwargs)
|
|
440
|
+
|
|
441
|
+
run: _Run = await DBOS.run_step_async(
|
|
442
|
+
{"name": f"{self.name}.start"}, self._astart, config.get("configurable")
|
|
443
|
+
)
|
|
444
|
+
value: Any = input
|
|
445
|
+
position = run["position"]
|
|
446
|
+
first = True
|
|
447
|
+
while True:
|
|
448
|
+
segment: _Segment = await DBOS.run_step_async(
|
|
449
|
+
self._step_options,
|
|
450
|
+
self._arun_segment,
|
|
451
|
+
run,
|
|
452
|
+
value,
|
|
453
|
+
config,
|
|
454
|
+
position,
|
|
455
|
+
first,
|
|
456
|
+
stream_mode,
|
|
457
|
+
stream_key,
|
|
458
|
+
kwargs,
|
|
459
|
+
)
|
|
460
|
+
if not segment["interrupts"] or not wait_for_input:
|
|
461
|
+
break
|
|
462
|
+
await DBOS.set_event_async(PENDING_INPUT_EVENT, self._pending(run, segment))
|
|
463
|
+
reply = await self._await_input(segment["token"], input_timeout)
|
|
464
|
+
await DBOS.set_event_async(PENDING_INPUT_EVENT, None)
|
|
465
|
+
if reply is _NO_INPUT:
|
|
466
|
+
break
|
|
467
|
+
value = Command(resume=reply)
|
|
468
|
+
position = segment["position"]
|
|
469
|
+
first = False
|
|
470
|
+
if stream_mode is not None and close_stream:
|
|
471
|
+
await DBOS.close_stream_async(stream_key)
|
|
472
|
+
return segment["output"]
|
|
473
|
+
|
|
474
|
+
async def _astart(self, configurable: Optional[dict[str, Any]]) -> _Run:
|
|
475
|
+
thread_id = self._thread_id(configurable)
|
|
476
|
+
latest = await self.checkpointer.aget_tuple(_thread_config({}, thread_id))
|
|
477
|
+
return self._run_record(thread_id, latest)
|
|
478
|
+
|
|
479
|
+
async def _arun_segment(
|
|
480
|
+
self,
|
|
481
|
+
run: _Run,
|
|
482
|
+
value: Any,
|
|
483
|
+
config: RunnableConfig,
|
|
484
|
+
position: _Position,
|
|
485
|
+
first: bool,
|
|
486
|
+
stream_mode: Optional[StreamModes],
|
|
487
|
+
stream_key: str,
|
|
488
|
+
kwargs: dict[str, Any],
|
|
489
|
+
) -> _Segment:
|
|
490
|
+
base = _thread_config(config, run["thread_id"])
|
|
491
|
+
latest = await self.checkpointer.aget_tuple(base)
|
|
492
|
+
run_input, run_config, clear_resume = self._plan(
|
|
493
|
+
run, value, config, position, first, latest
|
|
494
|
+
)
|
|
495
|
+
if clear_resume and latest is not None:
|
|
496
|
+
await self.checkpointer.aput_writes(latest.config, [(_RESUME, None)], _NULL_TASK_ID)
|
|
497
|
+
if stream_mode is None:
|
|
498
|
+
output = await self.graph.ainvoke(run_input, run_config, **kwargs)
|
|
499
|
+
else:
|
|
500
|
+
collector = _StreamCollector(stream_mode, bool(kwargs.get("subgraphs")))
|
|
501
|
+
stream_kwargs = {**kwargs, "stream_mode": collector.run_modes}
|
|
502
|
+
async for chunk in self.graph.astream(run_input, run_config, **stream_kwargs):
|
|
503
|
+
forward = collector.feed(chunk)
|
|
504
|
+
if forward is not None:
|
|
505
|
+
await DBOS.write_stream_async(stream_key, forward)
|
|
506
|
+
output = collector.output()
|
|
507
|
+
snapshot = await self.graph.aget_state(base)
|
|
508
|
+
return self._segment_record(output, snapshot, await self.checkpointer.aget_tuple(base))
|
|
509
|
+
|
|
510
|
+
# ---------------------------------------------------------------- shared
|
|
511
|
+
|
|
512
|
+
@staticmethod
|
|
513
|
+
def _check_kwargs(stream_mode: Optional[StreamModes], kwargs: dict[str, Any]) -> None:
|
|
514
|
+
if stream_mode is not None and kwargs.get("version", "v1") != "v1":
|
|
515
|
+
raise ValueError("stream_mode only supports the default v1 stream format.")
|
|
516
|
+
|
|
517
|
+
@staticmethod
|
|
518
|
+
def _thread_id(configurable: Optional[dict[str, Any]]) -> str:
|
|
519
|
+
thread_id = (configurable or {}).get("thread_id")
|
|
520
|
+
if thread_id is None:
|
|
521
|
+
# Unique per invoke call and the same on replay.
|
|
522
|
+
thread_id = f"dbos:{DBOS.workflow_id}:{DBOS.step_id}"
|
|
523
|
+
return str(thread_id)
|
|
524
|
+
|
|
525
|
+
def _run_record(self, thread_id: str, latest: Optional[CheckpointTuple]) -> _Run:
|
|
526
|
+
owner = DBOS.workflow_id
|
|
527
|
+
assert owner is not None
|
|
528
|
+
return {
|
|
529
|
+
"owner": owner,
|
|
530
|
+
"thread_id": thread_id,
|
|
531
|
+
"position": _position(self.checkpointer, latest),
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
def _plan(
|
|
535
|
+
self,
|
|
536
|
+
run: _Run,
|
|
537
|
+
value: Any,
|
|
538
|
+
config: RunnableConfig,
|
|
539
|
+
position: _Position,
|
|
540
|
+
first: bool,
|
|
541
|
+
latest: Optional[CheckpointTuple],
|
|
542
|
+
) -> tuple[Any, RunnableConfig, bool]:
|
|
543
|
+
"""Decide how this segment continues the thread.
|
|
544
|
+
|
|
545
|
+
Returns the graph input, the config, and whether a resume value left by
|
|
546
|
+
an earlier attempt must be cleared first.
|
|
547
|
+
"""
|
|
548
|
+
if DBOS.workflow_id != run["owner"]:
|
|
549
|
+
raise ForkNotSupportedError(
|
|
550
|
+
f"Workflow {DBOS.workflow_id} was forked from {run['owner']} after its graph "
|
|
551
|
+
f"run on thread {run['thread_id']!r} began. Fork from a step before the "
|
|
552
|
+
f"'{self.name}.start' step so the fork starts its own graph run."
|
|
553
|
+
)
|
|
554
|
+
resume_config = _thread_config(config, run["thread_id"])
|
|
555
|
+
now = _position(self.checkpointer, latest)
|
|
556
|
+
if now == position:
|
|
557
|
+
# Nothing has been saved since the last recorded step: apply the input.
|
|
558
|
+
# Only the first segment may target a checkpoint_id the caller asked for.
|
|
559
|
+
return value, _thread_config(config, run["thread_id"], keep_checkpoint_id=first), False
|
|
560
|
+
if now["checkpoint_id"] is None:
|
|
561
|
+
raise CheckpointLostError(
|
|
562
|
+
f"Thread {run['thread_id']!r} has no checkpoints, but this workflow already "
|
|
563
|
+
f"saved progress at checkpoint {position['checkpoint_id']!r}. The checkpointer "
|
|
564
|
+
"lost its data; use a persistent checkpointer such as PostgresSaver."
|
|
565
|
+
)
|
|
566
|
+
if now["checkpoint_id"] == position["checkpoint_id"]:
|
|
567
|
+
# An earlier attempt applied the input and saved writes, then died before a
|
|
568
|
+
# new checkpoint. LangGraph keeps that attempt's resume value on the
|
|
569
|
+
# checkpoint and would hand it to the *next* interrupt() too, answering a
|
|
570
|
+
# question the human never saw. Clear it, then resume: answers already
|
|
571
|
+
# used are replayed from the task's own record, and the next question is
|
|
572
|
+
# asked. If no node had used the answer yet, the same question is asked again.
|
|
573
|
+
return None, resume_config, _stale_resume(latest)
|
|
574
|
+
# A new checkpoint was saved: continue from it.
|
|
575
|
+
return None, resume_config, False
|
|
576
|
+
|
|
577
|
+
def _segment_record(
|
|
578
|
+
self, output: Any, snapshot: Any, latest: Optional[CheckpointTuple]
|
|
579
|
+
) -> _Segment:
|
|
580
|
+
return {
|
|
581
|
+
"output": output,
|
|
582
|
+
"interrupts": _interrupt_infos(snapshot.interrupts),
|
|
583
|
+
"position": _position(self.checkpointer, latest),
|
|
584
|
+
"token": f"{DBOS.workflow_id}:{DBOS.step_id}",
|
|
585
|
+
}
|
|
586
|
+
|
|
587
|
+
@staticmethod
|
|
588
|
+
def _pending(run: _Run, segment: _Segment) -> PendingInput:
|
|
589
|
+
return {
|
|
590
|
+
"token": segment["token"],
|
|
591
|
+
"thread_id": run["thread_id"],
|
|
592
|
+
"interrupts": segment["interrupts"],
|
|
593
|
+
}
|
|
594
|
+
|
|
595
|
+
@staticmethod
|
|
596
|
+
def _wait_for_input(token: str, timeout: Optional[float]) -> Any:
|
|
597
|
+
while True:
|
|
598
|
+
message = DBOS.recv(
|
|
599
|
+
INPUT_TOPIC, timeout_seconds=_WAIT_CHUNK_SECONDS if timeout is None else timeout
|
|
600
|
+
)
|
|
601
|
+
if message is None:
|
|
602
|
+
if timeout is None:
|
|
603
|
+
continue
|
|
604
|
+
return _NO_INPUT
|
|
605
|
+
if _matches(message, token):
|
|
606
|
+
return message["value"]
|
|
607
|
+
# A reply to an earlier question (sent late or twice): ignore it.
|
|
608
|
+
|
|
609
|
+
@staticmethod
|
|
610
|
+
async def _await_input(token: str, timeout: Optional[float]) -> Any:
|
|
611
|
+
while True:
|
|
612
|
+
message = await DBOS.recv_async(
|
|
613
|
+
INPUT_TOPIC, timeout_seconds=_WAIT_CHUNK_SECONDS if timeout is None else timeout
|
|
614
|
+
)
|
|
615
|
+
if message is None:
|
|
616
|
+
if timeout is None:
|
|
617
|
+
continue
|
|
618
|
+
return _NO_INPUT
|
|
619
|
+
if _matches(message, token):
|
|
620
|
+
return message["value"]
|
|
621
|
+
|
|
622
|
+
|
|
623
|
+
class _NoInput:
|
|
624
|
+
def __repr__(self) -> str:
|
|
625
|
+
return "<no input>"
|
|
626
|
+
|
|
627
|
+
|
|
628
|
+
_NO_INPUT: Any = _NoInput()
|
|
629
|
+
|
|
630
|
+
|
|
631
|
+
def _matches(message: Any, token: str) -> bool:
|
|
632
|
+
return isinstance(message, dict) and message.get("token") == token and "value" in message
|
|
633
|
+
|
|
634
|
+
|
|
635
|
+
__all__ = [
|
|
636
|
+
"DEFAULT_STREAM_KEY",
|
|
637
|
+
"INPUT_TOPIC",
|
|
638
|
+
"PENDING_INPUT_EVENT",
|
|
639
|
+
"CheckpointLostError",
|
|
640
|
+
"DBOSGraph",
|
|
641
|
+
"DBOSGraphError",
|
|
642
|
+
"ForkNotSupportedError",
|
|
643
|
+
"InterruptInfo",
|
|
644
|
+
"PendingInput",
|
|
645
|
+
]
|
langgraph_dbos/_input.py
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
"""Read what a waiting graph is asking, and send the human's reply.
|
|
2
|
+
|
|
3
|
+
These helpers run outside the workflow: in a web handler, a CLI, or another
|
|
4
|
+
service. Pass a ``DBOSClient`` to use them from a process that does not run
|
|
5
|
+
DBOS itself.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from typing import Any, Optional, cast
|
|
11
|
+
|
|
12
|
+
from dbos import DBOS, DBOSClient
|
|
13
|
+
|
|
14
|
+
from ._graph import INPUT_TOPIC, PENDING_INPUT_EVENT, DBOSGraphError, PendingInput
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class NoPendingInputError(DBOSGraphError):
|
|
18
|
+
"""The workflow is not waiting for input."""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def _message(token: str, value: Any) -> dict[str, Any]:
|
|
22
|
+
return {"token": token, "value": value}
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _idempotency_key(token: str) -> str:
|
|
26
|
+
# One reply per question: a double-click or a retried request is delivered once.
|
|
27
|
+
return f"langgraph-input:{token}"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def get_pending_input(
|
|
31
|
+
workflow_id: str,
|
|
32
|
+
*,
|
|
33
|
+
timeout_seconds: float = 60,
|
|
34
|
+
client: Optional[DBOSClient] = None,
|
|
35
|
+
) -> Optional[PendingInput]:
|
|
36
|
+
"""Return what the workflow is waiting for, or None if it is not waiting.
|
|
37
|
+
|
|
38
|
+
Waits up to ``timeout_seconds`` for the workflow to publish its first
|
|
39
|
+
question. Returns None once a question has been answered and before the
|
|
40
|
+
next one is asked.
|
|
41
|
+
"""
|
|
42
|
+
if client is not None:
|
|
43
|
+
value = client.get_event(workflow_id, PENDING_INPUT_EVENT, timeout_seconds)
|
|
44
|
+
else:
|
|
45
|
+
value = DBOS.get_event(workflow_id, PENDING_INPUT_EVENT, timeout_seconds)
|
|
46
|
+
return cast(Optional[PendingInput], value)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
async def get_pending_input_async(
|
|
50
|
+
workflow_id: str,
|
|
51
|
+
*,
|
|
52
|
+
timeout_seconds: float = 60,
|
|
53
|
+
client: Optional[DBOSClient] = None,
|
|
54
|
+
) -> Optional[PendingInput]:
|
|
55
|
+
"""Async version of :func:`get_pending_input`."""
|
|
56
|
+
if client is not None:
|
|
57
|
+
value = await client.get_event_async(workflow_id, PENDING_INPUT_EVENT, timeout_seconds)
|
|
58
|
+
else:
|
|
59
|
+
value = await DBOS.get_event_async(workflow_id, PENDING_INPUT_EVENT, timeout_seconds)
|
|
60
|
+
return cast(Optional[PendingInput], value)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def send_input(
|
|
64
|
+
workflow_id: str,
|
|
65
|
+
value: Any,
|
|
66
|
+
*,
|
|
67
|
+
token: Optional[str] = None,
|
|
68
|
+
timeout_seconds: float = 0,
|
|
69
|
+
client: Optional[DBOSClient] = None,
|
|
70
|
+
) -> str:
|
|
71
|
+
"""Answer the ``interrupt()`` a workflow is waiting on and return the token used.
|
|
72
|
+
|
|
73
|
+
``value`` becomes the return value of ``interrupt()`` in the node. When
|
|
74
|
+
several nodes are interrupted at once, pass a dict that maps each interrupt
|
|
75
|
+
id (from :func:`get_pending_input`) to its answer.
|
|
76
|
+
|
|
77
|
+
Pass the ``token`` from :func:`get_pending_input` to make sure the answer
|
|
78
|
+
goes to the question that was shown to the human. Without it, the question
|
|
79
|
+
pending right now is answered; if the workflow moves on to its next
|
|
80
|
+
question at that moment, the reply carries the old token and is ignored.
|
|
81
|
+
A reply with a stale token is ignored by the workflow, and a second reply
|
|
82
|
+
with the same token is not delivered.
|
|
83
|
+
|
|
84
|
+
Raises:
|
|
85
|
+
NoPendingInputError: no token was given and the workflow is not waiting.
|
|
86
|
+
"""
|
|
87
|
+
if token is None:
|
|
88
|
+
pending = get_pending_input(workflow_id, timeout_seconds=timeout_seconds, client=client)
|
|
89
|
+
if pending is None:
|
|
90
|
+
raise NoPendingInputError(f"Workflow {workflow_id} is not waiting for input.")
|
|
91
|
+
token = pending["token"]
|
|
92
|
+
if client is not None:
|
|
93
|
+
client.send(workflow_id, _message(token, value), INPUT_TOPIC, _idempotency_key(token))
|
|
94
|
+
else:
|
|
95
|
+
DBOS.send(
|
|
96
|
+
workflow_id,
|
|
97
|
+
_message(token, value),
|
|
98
|
+
INPUT_TOPIC,
|
|
99
|
+
idempotency_key=_idempotency_key(token),
|
|
100
|
+
)
|
|
101
|
+
return token
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
async def send_input_async(
|
|
105
|
+
workflow_id: str,
|
|
106
|
+
value: Any,
|
|
107
|
+
*,
|
|
108
|
+
token: Optional[str] = None,
|
|
109
|
+
timeout_seconds: float = 0,
|
|
110
|
+
client: Optional[DBOSClient] = None,
|
|
111
|
+
) -> str:
|
|
112
|
+
"""Async version of :func:`send_input`."""
|
|
113
|
+
if token is None:
|
|
114
|
+
pending = await get_pending_input_async(
|
|
115
|
+
workflow_id, timeout_seconds=timeout_seconds, client=client
|
|
116
|
+
)
|
|
117
|
+
if pending is None:
|
|
118
|
+
raise NoPendingInputError(f"Workflow {workflow_id} is not waiting for input.")
|
|
119
|
+
token = pending["token"]
|
|
120
|
+
if client is not None:
|
|
121
|
+
await client.send_async(
|
|
122
|
+
workflow_id, _message(token, value), INPUT_TOPIC, _idempotency_key(token)
|
|
123
|
+
)
|
|
124
|
+
else:
|
|
125
|
+
await DBOS.send_async(
|
|
126
|
+
workflow_id,
|
|
127
|
+
_message(token, value),
|
|
128
|
+
INPUT_TOPIC,
|
|
129
|
+
idempotency_key=_idempotency_key(token),
|
|
130
|
+
)
|
|
131
|
+
return token
|
langgraph_dbos/py.typed
ADDED
|
File without changes
|
|
@@ -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
|
+
[](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml)
|
|
35
|
+
[](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
|
+

|
|
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,8 @@
|
|
|
1
|
+
langgraph_dbos/__init__.py,sha256=0vkKOqZ8-66r_miNAca86Tcst6TVR5zTeIQVW8JUg-k,845
|
|
2
|
+
langgraph_dbos/_graph.py,sha256=I8I40wKILajoTwaN7uKyUxbbulVH7K9lMXI36qzbU1I,25902
|
|
3
|
+
langgraph_dbos/_input.py,sha256=FIPF8MUOaQKiq7j3BwgMLvl454zjGWaBPvmkkEkYElM,4459
|
|
4
|
+
langgraph_dbos/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
langgraph_dbos-0.1.0.dist-info/METADATA,sha256=P7vcWVA1pubL1b6T4kEQrABTkSOkvjedhiZsVKE-77g,13338
|
|
6
|
+
langgraph_dbos-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
7
|
+
langgraph_dbos-0.1.0.dist-info/licenses/LICENSE,sha256=MXin3GOxXPyYLFm68PT_jeXcDqAJv_6fApftDhAm8Oo,1071
|
|
8
|
+
langgraph_dbos-0.1.0.dist-info/RECORD,,
|
|
@@ -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.
|