langgraph-api 0.18.0.dev2__py3-none-any.whl → 0.18.0.dev4__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_api/__init__.py +1 -1
- langgraph_api/api/a2a.py +93 -10
- langgraph_api/api/event_streaming.py +81 -9
- langgraph_api/api/mcp/_calls.py +29 -0
- langgraph_api/api/mcp/_constants.py +15 -6
- langgraph_api/api/mcp/_handlers.py +146 -196
- langgraph_api/api/mcp/_outcome.py +43 -0
- langgraph_api/api/mcp/_protocol.py +224 -0
- langgraph_api/config/__init__.py +38 -4
- langgraph_api/cron_scheduler.py +2 -2
- langgraph_api/drain.py +164 -0
- langgraph_api/event_streaming/service.py +130 -133
- langgraph_api/event_streaming/session.py +11 -6
- langgraph_api/executor/__init__.py +9 -0
- langgraph_api/executor/__main__.py +343 -0
- langgraph_api/feature_flags.py +6 -0
- langgraph_api/graph.py +12 -2
- langgraph_api/grpc/ops/runs.py +41 -5
- langgraph_api/grpc/ops/threads.py +54 -6
- langgraph_api/metrics_otlp.py +8 -0
- langgraph_api/models/run.py +11 -3
- langgraph_api/queue_entrypoint.py +13 -1
- langgraph_api/self_hosted_logs.py +3 -1
- langgraph_api/self_hosted_metrics.py +1 -1
- langgraph_api/stream.py +49 -3
- langgraph_api/timing/__init__.py +16 -0
- langgraph_api/timing/startup.py +184 -0
- langgraph_api/timing/timer.py +16 -2
- langgraph_api/utils/headers.py +20 -3
- langgraph_api/validation.py +11 -5
- langgraph_api/worker.py +146 -13
- langgraph_api/worker_runtime.py +124 -4
- {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/METADATA +1 -1
- {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/RECORD +43 -38
- langgraph_grpc_common/proto/__init__.py +4 -4
- langgraph_grpc_common/proto/orchestrator_pb2.py +50 -0
- langgraph_grpc_common/proto/{runner_pb2.pyi → orchestrator_pb2.pyi} +4 -4
- langgraph_grpc_common/proto/orchestrator_pb2_grpc.py +108 -0
- langgraph_grpc_common/proto/orchestrator_pb2_grpc.pyi +82 -0
- openapi.json +20 -0
- langgraph_api/runner/__init__.py +0 -10
- langgraph_api/runner/__main__.py +0 -275
- langgraph_grpc_common/proto/runner_pb2.py +0 -50
- langgraph_grpc_common/proto/runner_pb2_grpc.py +0 -108
- langgraph_grpc_common/proto/runner_pb2_grpc.pyi +0 -73
- {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/WHEEL +0 -0
- {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/entry_points.txt +0 -0
- {langgraph_api-0.18.0.dev2.dist-info → langgraph_api-0.18.0.dev4.dist-info}/licenses/LICENSE +0 -0
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import base64
|
|
4
|
+
import re
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from http import HTTPStatus
|
|
7
|
+
from types import MappingProxyType
|
|
8
|
+
from typing import TYPE_CHECKING, Any, ClassVar
|
|
9
|
+
|
|
10
|
+
from langgraph_api import __version__
|
|
11
|
+
from langgraph_api.api.mcp._constants import (
|
|
12
|
+
ERROR_CODE_HEADER_MISMATCH,
|
|
13
|
+
ERROR_CODE_INVALID_PARAMS,
|
|
14
|
+
ERROR_CODE_METHOD_NOT_FOUND,
|
|
15
|
+
ERROR_CODE_UNSUPPORTED_VERSION,
|
|
16
|
+
PROTOCOL_VERSION,
|
|
17
|
+
SUPPORTED_PROTOCOL_VERSIONS,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
if TYPE_CHECKING:
|
|
21
|
+
from collections.abc import Mapping
|
|
22
|
+
|
|
23
|
+
from langgraph_api.api.mcp._models import JsonRpcErrorObject, JsonRpcRequest
|
|
24
|
+
from langgraph_api.cache import JsonValue
|
|
25
|
+
from langgraph_api.route import ApiRequest
|
|
26
|
+
|
|
27
|
+
META_PREFIX = "io.modelcontextprotocol/"
|
|
28
|
+
VERSION_KEY = META_PREFIX + "protocolVersion"
|
|
29
|
+
CAPABILITIES_KEY = META_PREFIX + "clientCapabilities"
|
|
30
|
+
NAMED_METHODS = MappingProxyType(
|
|
31
|
+
{"tools/call": "name", "resources/read": "uri", "prompts/get": "name"}
|
|
32
|
+
)
|
|
33
|
+
SERVER_INFO = {"name": "LangGraph", "version": __version__}
|
|
34
|
+
SERVER_CAPABILITIES = {"tools": {"listChanged": False}}
|
|
35
|
+
CACHE_HINTS = MappingProxyType({"ttlMs": 0, "cacheScope": "private"})
|
|
36
|
+
CACHEABLE_METHODS = frozenset({"server/discover", "tools/list"})
|
|
37
|
+
HTTP_WHITESPACE = " \t"
|
|
38
|
+
PLAIN_HEADER_VALUE = re.compile(r"[\x20-\x7e]+")
|
|
39
|
+
BASE64_HEADER_VALUE = re.compile(r"=\?base64\?(?P<encoded>.*)\?=")
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class ProtocolError(ValueError):
|
|
43
|
+
def __init__(
|
|
44
|
+
self,
|
|
45
|
+
message: str,
|
|
46
|
+
code: int = ERROR_CODE_INVALID_PARAMS,
|
|
47
|
+
data: JsonValue = None,
|
|
48
|
+
):
|
|
49
|
+
super().__init__(message)
|
|
50
|
+
self.error: JsonRpcErrorObject = {"code": code, "message": message}
|
|
51
|
+
if data is not None:
|
|
52
|
+
self.error["data"] = data
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass(frozen=True, slots=True)
|
|
56
|
+
class MirroredHeaders:
|
|
57
|
+
protocol_version: str
|
|
58
|
+
method: str
|
|
59
|
+
name: str
|
|
60
|
+
|
|
61
|
+
@classmethod
|
|
62
|
+
def of(cls, headers: Mapping[str, str]) -> MirroredHeaders:
|
|
63
|
+
version, method, name = (
|
|
64
|
+
headers.get(field, "").strip(HTTP_WHITESPACE)
|
|
65
|
+
for field in ("mcp-protocol-version", "mcp-method", "mcp-name")
|
|
66
|
+
)
|
|
67
|
+
return cls(version, method, name)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass(frozen=True, slots=True)
|
|
71
|
+
class Legacy:
|
|
72
|
+
headers: ClassVar[Mapping[str, str]] = MappingProxyType({})
|
|
73
|
+
|
|
74
|
+
def result(self, method: str, payload: dict[str, Any]) -> dict[str, Any]:
|
|
75
|
+
return payload
|
|
76
|
+
|
|
77
|
+
def http_status(self, error: ProtocolError) -> HTTPStatus:
|
|
78
|
+
return HTTPStatus.OK
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@dataclass(frozen=True, slots=True)
|
|
82
|
+
class Modern:
|
|
83
|
+
version: str
|
|
84
|
+
capabilities: dict[str, Any]
|
|
85
|
+
headers: ClassVar[Mapping[str, str]] = MappingProxyType(
|
|
86
|
+
{"Cache-Control": "no-store"}
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
@classmethod
|
|
90
|
+
def of(
|
|
91
|
+
cls, headers: MirroredHeaders, params: dict[str, Any], method: str
|
|
92
|
+
) -> Modern:
|
|
93
|
+
meta = params.get("_meta")
|
|
94
|
+
if not isinstance(meta, dict):
|
|
95
|
+
raise ProtocolError("Request _meta must be an object")
|
|
96
|
+
version = meta.get(VERSION_KEY)
|
|
97
|
+
capabilities = meta.get(CAPABILITIES_KEY)
|
|
98
|
+
if not isinstance(version, str) or not isinstance(capabilities, dict):
|
|
99
|
+
raise ProtocolError("protocolVersion and clientCapabilities are required")
|
|
100
|
+
_check_capabilities(capabilities)
|
|
101
|
+
_check_headers(headers, params, method, version=version)
|
|
102
|
+
if version != PROTOCOL_VERSION:
|
|
103
|
+
raise ProtocolError(
|
|
104
|
+
"Unsupported protocol version",
|
|
105
|
+
ERROR_CODE_UNSUPPORTED_VERSION,
|
|
106
|
+
{
|
|
107
|
+
"requested": version,
|
|
108
|
+
"supported": sorted(SUPPORTED_PROTOCOL_VERSIONS),
|
|
109
|
+
},
|
|
110
|
+
)
|
|
111
|
+
return cls(version, capabilities)
|
|
112
|
+
|
|
113
|
+
def result(self, method: str, payload: dict[str, Any]) -> dict[str, Any]:
|
|
114
|
+
hints = CACHE_HINTS if method in CACHEABLE_METHODS else {}
|
|
115
|
+
return complete({**payload, **hints})
|
|
116
|
+
|
|
117
|
+
def http_status(self, error: ProtocolError) -> HTTPStatus:
|
|
118
|
+
if error.error["code"] == ERROR_CODE_METHOD_NOT_FOUND:
|
|
119
|
+
return HTTPStatus.NOT_FOUND
|
|
120
|
+
return HTTPStatus.BAD_REQUEST
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
Era = Legacy | Modern
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
@dataclass(frozen=True, slots=True)
|
|
127
|
+
class McpCall:
|
|
128
|
+
message: JsonRpcRequest
|
|
129
|
+
era: Era
|
|
130
|
+
|
|
131
|
+
@property
|
|
132
|
+
def id(self) -> str | int:
|
|
133
|
+
return self.message["id"]
|
|
134
|
+
|
|
135
|
+
@property
|
|
136
|
+
def method(self) -> str:
|
|
137
|
+
return self.message["method"]
|
|
138
|
+
|
|
139
|
+
@property
|
|
140
|
+
def params(self) -> dict[str, Any]:
|
|
141
|
+
return params_of(self.message)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def params_of(message: JsonRpcRequest) -> dict[str, Any]:
|
|
145
|
+
match message.get("params", {}):
|
|
146
|
+
case dict() as params:
|
|
147
|
+
return params
|
|
148
|
+
case _:
|
|
149
|
+
raise ProtocolError("params must be an object")
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def parse_call(request: ApiRequest, message: JsonRpcRequest) -> McpCall:
|
|
153
|
+
headers = MirroredHeaders.of(request.headers)
|
|
154
|
+
method = message["method"]
|
|
155
|
+
if not is_modern(headers, message.get("params"), method):
|
|
156
|
+
return McpCall(message, Legacy())
|
|
157
|
+
return McpCall(message, Modern.of(headers, params_of(message), method))
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def is_modern(headers: MirroredHeaders, params: object, method: str) -> bool:
|
|
161
|
+
meta = params.get("_meta") if isinstance(params, dict) else None
|
|
162
|
+
return (
|
|
163
|
+
(isinstance(meta, dict) and VERSION_KEY in meta)
|
|
164
|
+
or headers.protocol_version == PROTOCOL_VERSION
|
|
165
|
+
or method == "server/discover"
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _decode_header(value: str) -> str:
|
|
170
|
+
if not PLAIN_HEADER_VALUE.fullmatch(value):
|
|
171
|
+
raise ProtocolError("Invalid MCP header", ERROR_CODE_HEADER_MISMATCH)
|
|
172
|
+
if (sentinel := BASE64_HEADER_VALUE.fullmatch(value)) is None:
|
|
173
|
+
return value
|
|
174
|
+
try:
|
|
175
|
+
return base64.b64decode(sentinel["encoded"], validate=True).decode()
|
|
176
|
+
except ValueError:
|
|
177
|
+
raise ProtocolError(
|
|
178
|
+
"Invalid MCP header encoding", ERROR_CODE_HEADER_MISMATCH
|
|
179
|
+
) from None
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _check_capabilities(capabilities: dict[str, Any]) -> None:
|
|
183
|
+
for name in ("elicitation", "extensions"):
|
|
184
|
+
if name in capabilities and not isinstance(capabilities[name], dict):
|
|
185
|
+
raise ProtocolError(f"{name} capability must be an object")
|
|
186
|
+
for name, value in capabilities.get("elicitation", {}).items():
|
|
187
|
+
if name in {"form", "url"} and not isinstance(value, dict):
|
|
188
|
+
raise ProtocolError(f"elicitation.{name} capability must be an object")
|
|
189
|
+
if any(
|
|
190
|
+
not isinstance(value, dict)
|
|
191
|
+
for value in capabilities.get("extensions", {}).values()
|
|
192
|
+
):
|
|
193
|
+
raise ProtocolError("Extension capabilities must be objects")
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def _check_headers(
|
|
197
|
+
headers: MirroredHeaders, params: dict[str, Any], method: str, *, version: str
|
|
198
|
+
) -> None:
|
|
199
|
+
if headers.protocol_version != version:
|
|
200
|
+
raise ProtocolError(
|
|
201
|
+
"MCP-Protocol-Version header mismatch", ERROR_CODE_HEADER_MISMATCH
|
|
202
|
+
)
|
|
203
|
+
if headers.method != method:
|
|
204
|
+
raise ProtocolError("Mcp-Method header mismatch", ERROR_CODE_HEADER_MISMATCH)
|
|
205
|
+
field = NAMED_METHODS.get(method)
|
|
206
|
+
if field is None:
|
|
207
|
+
return
|
|
208
|
+
if _decode_header(headers.name) != params.get(field):
|
|
209
|
+
raise ProtocolError("Mcp-Name header mismatch", ERROR_CODE_HEADER_MISMATCH)
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def complete(result: dict[str, Any]) -> dict[str, Any]:
|
|
213
|
+
return {
|
|
214
|
+
**result,
|
|
215
|
+
"resultType": result.get("resultType", "complete"),
|
|
216
|
+
"_meta": {**result.get("_meta", {}), META_PREFIX + "serverInfo": SERVER_INFO},
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def discover() -> dict[str, Any]:
|
|
221
|
+
return {
|
|
222
|
+
"supportedVersions": sorted(SUPPORTED_PROTOCOL_VERSIONS, reverse=True),
|
|
223
|
+
"capabilities": SERVER_CAPABILITIES,
|
|
224
|
+
}
|
langgraph_api/config/__init__.py
CHANGED
|
@@ -4,6 +4,7 @@ from os import environ, getenv
|
|
|
4
4
|
from typing import TYPE_CHECKING, Annotated, Literal, TypeVar, cast
|
|
5
5
|
|
|
6
6
|
import structlog
|
|
7
|
+
from langgraph.version import __version__ as langgraph_version
|
|
7
8
|
from pydantic.functional_validators import AfterValidator
|
|
8
9
|
from starlette.config import Config
|
|
9
10
|
from starlette.datastructures import CommaSeparatedStrings
|
|
@@ -24,6 +25,7 @@ from langgraph_api.config.schemas import (
|
|
|
24
25
|
webhooks_validator,
|
|
25
26
|
)
|
|
26
27
|
from langgraph_api.feature_flags import (
|
|
28
|
+
DRAIN_RESUME_SUPPORT,
|
|
27
29
|
IS_POSTGRES_BACKEND,
|
|
28
30
|
OMIT_PENDING_SENDS,
|
|
29
31
|
PREFER_GRPC_CHECKPOINTER,
|
|
@@ -398,6 +400,8 @@ if (
|
|
|
398
400
|
|
|
399
401
|
BG_JOB_HEARTBEAT = 120 # seconds
|
|
400
402
|
BG_JOB_MAX_RETRIES = env("BG_JOB_MAX_RETRIES", cast=int, default=3)
|
|
403
|
+
# Stops graphs that drain forever. The retry limit only applies to failures.
|
|
404
|
+
BG_JOB_MAX_DRAINS = env("BG_JOB_MAX_DRAINS", cast=int, default=50)
|
|
401
405
|
BG_JOB_ISOLATED_LOOPS = env("BG_JOB_ISOLATED_LOOPS", cast=bool, default=False)
|
|
402
406
|
BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS = env(
|
|
403
407
|
"BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS",
|
|
@@ -448,7 +452,7 @@ class DispatchMode(StrEnum):
|
|
|
448
452
|
"""How background runs are dispatched.
|
|
449
453
|
|
|
450
454
|
single-process: Python queue loop in the API process (default).
|
|
451
|
-
multi-process: Go
|
|
455
|
+
multi-process: Go executor manager claims runs and dispatches to Python executors.
|
|
452
456
|
"""
|
|
453
457
|
|
|
454
458
|
SINGLE_PROCESS = "single-process"
|
|
@@ -502,8 +506,36 @@ FF_ASYNC_PUBLISH_QUEUE = env("FF_ASYNC_PUBLISH_QUEUE", cast=bool, default=False)
|
|
|
502
506
|
FF_CRONS_ENABLED = env("FF_CRONS_ENABLED", cast=bool, default=True)
|
|
503
507
|
FF_LOG_DROPPED_EVENTS = env("FF_LOG_DROPPED_EVENTS", cast=bool, default=False)
|
|
504
508
|
FF_LOG_QUERY_AND_PARAMS = env("FF_LOG_QUERY_AND_PARAMS", cast=bool, default=False)
|
|
505
|
-
#
|
|
506
|
-
|
|
509
|
+
# Opt-in handling of drained runs: the server's control signalling to the
|
|
510
|
+
# graph and its handling of drained runs, together. On, a Postgres-backed
|
|
511
|
+
# replica that is shutting down also drains its in-flight runs.
|
|
512
|
+
# Off: no control is created or seeded, and GraphDrained lands in the
|
|
513
|
+
# catch-all error branch.
|
|
514
|
+
FF_RESUME_DRAINED_RUNS = env("FF_RESUME_DRAINED_RUNS", cast=bool, default=False)
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
def _resolve_resume_drained_runs(
|
|
518
|
+
enabled: bool, *, is_postgres: bool, langgraph_supported: bool
|
|
519
|
+
) -> bool:
|
|
520
|
+
# Only the Postgres runtime re-queues drained runs: on the in-memory
|
|
521
|
+
# runtime a drain still ends the run as an error, flag or not.
|
|
522
|
+
if not (enabled and is_postgres):
|
|
523
|
+
return False
|
|
524
|
+
if not langgraph_supported:
|
|
525
|
+
logger.warning(
|
|
526
|
+
"Ignoring FF_RESUME_DRAINED_RUNS=true: resuming drained runs "
|
|
527
|
+
"requires langgraph>=1.2.15, so drained runs end as errors.",
|
|
528
|
+
langgraph_version=langgraph_version,
|
|
529
|
+
)
|
|
530
|
+
return False
|
|
531
|
+
return True
|
|
532
|
+
|
|
533
|
+
|
|
534
|
+
RESUME_DRAINED_RUNS = _resolve_resume_drained_runs(
|
|
535
|
+
FF_RESUME_DRAINED_RUNS,
|
|
536
|
+
is_postgres=IS_POSTGRES_BACKEND,
|
|
537
|
+
langgraph_supported=DRAIN_RESUME_SUPPORT,
|
|
538
|
+
)
|
|
507
539
|
|
|
508
540
|
|
|
509
541
|
# Internal flag intended for testing only
|
|
@@ -747,6 +779,7 @@ __all__ = [
|
|
|
747
779
|
"API_VARIANT",
|
|
748
780
|
"BG_JOB_HEARTBEAT",
|
|
749
781
|
"BG_JOB_ISOLATED_LOOPS",
|
|
782
|
+
"BG_JOB_MAX_DRAINS",
|
|
750
783
|
"BG_JOB_MAX_RETRIES",
|
|
751
784
|
"BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS",
|
|
752
785
|
"BG_JOB_TIMEOUT_SECS",
|
|
@@ -776,7 +809,7 @@ __all__ = [
|
|
|
776
809
|
"FF_LOG_QUERY_AND_PARAMS",
|
|
777
810
|
"FF_PYSPY_PROFILING_ENABLED",
|
|
778
811
|
"FF_PYSPY_PROFILING_MAX_DURATION_SECS",
|
|
779
|
-
"
|
|
812
|
+
"FF_RESUME_DRAINED_RUNS",
|
|
780
813
|
"GRPC_CLIENT_HTTP2_INITIAL_WINDOW_SIZE",
|
|
781
814
|
"GRPC_CLIENT_MAX_RECV_MSG_BYTES",
|
|
782
815
|
"GRPC_CLIENT_MAX_SEND_MSG_BYTES",
|
|
@@ -826,6 +859,7 @@ __all__ = [
|
|
|
826
859
|
"REDIS_MAX_CONNECTIONS",
|
|
827
860
|
"REDIS_URI",
|
|
828
861
|
"RESUMABLE_STREAM_TTL_SECONDS",
|
|
862
|
+
"RESUME_DRAINED_RUNS",
|
|
829
863
|
"RUN_STATS_CACHE_SECONDS",
|
|
830
864
|
"SELF_HOSTED_OBSERVABILITY_SERVICE_NAME",
|
|
831
865
|
"SERDE",
|
langgraph_api/cron_scheduler.py
CHANGED
|
@@ -82,11 +82,11 @@ async def cron_scheduler():
|
|
|
82
82
|
):
|
|
83
83
|
logger.debug(f"Scheduling cron run {cron}")
|
|
84
84
|
try:
|
|
85
|
-
cron_id =
|
|
85
|
+
cron_id = str(cron["cron_id"])
|
|
86
86
|
if run_payload.get("context"):
|
|
87
87
|
# Cron persistence and set_auth_ctx_for_run write these into configurable, which create_valid_run rejects next to context.
|
|
88
88
|
configurable = run_payload["config"]["configurable"]
|
|
89
|
-
|
|
89
|
+
configurable.pop("cron_id", None)
|
|
90
90
|
configurable.pop("langgraph_auth_user", None)
|
|
91
91
|
run = await create_valid_run(
|
|
92
92
|
conn,
|
langgraph_api/drain.py
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""Cooperative drain support.
|
|
2
|
+
|
|
3
|
+
Draining asks a running graph to stop at the next superstep boundary, save its
|
|
4
|
+
checkpoint, and raise ``GraphDrained`` so the run can be re-queued and resumed
|
|
5
|
+
by another worker. The support (``RunControl`` / ``GraphDrained``) arrived in
|
|
6
|
+
langgraph 1.2; the server also supports older langgraph, so the imports are
|
|
7
|
+
guarded and the placeholders below never match or instantiate anything.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import contextvars
|
|
13
|
+
import threading
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
# The control of the run whose top-level graph this context is executing. The
|
|
17
|
+
# server sets it before streaming the graph; asyncio tasks and LangGraph's node
|
|
18
|
+
# executors copy it, while threads a node starts itself don't.
|
|
19
|
+
_TOP_LEVEL_CONTROL: contextvars.ContextVar[Any] = contextvars.ContextVar(
|
|
20
|
+
"langgraph_api_top_level_run_control", default=None
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _in_graph_node() -> bool:
|
|
25
|
+
"""Whether the caller runs inside a graph node (and so in any subgraph loop).
|
|
26
|
+
|
|
27
|
+
LangGraph runs node code under a runnable config context whose
|
|
28
|
+
checkpoint_ns names the node; the run's top-level loop has no such context.
|
|
29
|
+
"""
|
|
30
|
+
try:
|
|
31
|
+
from langgraph.config import get_config # noqa: PLC0415
|
|
32
|
+
|
|
33
|
+
config = get_config()
|
|
34
|
+
except RuntimeError:
|
|
35
|
+
return False
|
|
36
|
+
return bool((config.get("configurable") or {}).get("checkpoint_ns"))
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
try:
|
|
40
|
+
from langgraph.errors import GraphDrained
|
|
41
|
+
from langgraph.runtime import RunControl
|
|
42
|
+
|
|
43
|
+
class ServerRunControl(RunControl):
|
|
44
|
+
"""A RunControl whose drain request only the run's top-level graph sees.
|
|
45
|
+
|
|
46
|
+
LangGraph hands a run's control to its subgraphs. A drain inside a
|
|
47
|
+
subgraph would, with durability="exit", lose the subgraph's progress.
|
|
48
|
+
The request is visible only where this is provably the run's top-level
|
|
49
|
+
loop: in a context the server marked for this control (see
|
|
50
|
+
mark_top_level) and outside any graph node. So the run drains only at
|
|
51
|
+
a top-level step boundary, after that step's subgraphs have finished,
|
|
52
|
+
and never before its first step.
|
|
53
|
+
Graph code inside a node, and threads a node starts, see no drain
|
|
54
|
+
(drain_requested False, drain_reason None).
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
__slots__ = ("_first_check_done",)
|
|
58
|
+
|
|
59
|
+
def __init__(self) -> None:
|
|
60
|
+
super().__init__()
|
|
61
|
+
self._first_check_done = False
|
|
62
|
+
|
|
63
|
+
def _visible(self) -> bool:
|
|
64
|
+
return _TOP_LEVEL_CONTROL.get() is self and not _in_graph_node()
|
|
65
|
+
|
|
66
|
+
@property
|
|
67
|
+
def drain_requested(self) -> bool:
|
|
68
|
+
if not self._visible():
|
|
69
|
+
return False
|
|
70
|
+
# LangGraph checks once per top-level step boundary, before the
|
|
71
|
+
# step. Only a server drain can be pending at the first check. A
|
|
72
|
+
# run started with a Command has no checkpoint of its own until its
|
|
73
|
+
# first step ends, so if it drained there, its next claim would
|
|
74
|
+
# re-send the Command and LangGraph would apply it again. So a run
|
|
75
|
+
# always completes a step before it drains.
|
|
76
|
+
if not self._first_check_done:
|
|
77
|
+
self._first_check_done = True
|
|
78
|
+
return False
|
|
79
|
+
return RunControl.drain_requested.fget(self)
|
|
80
|
+
|
|
81
|
+
@property
|
|
82
|
+
def drain_reason(self) -> str | None:
|
|
83
|
+
return RunControl.drain_reason.fget(self) if self._visible() else None
|
|
84
|
+
|
|
85
|
+
DRAIN_SUPPORT = True
|
|
86
|
+
except ImportError:
|
|
87
|
+
|
|
88
|
+
class GraphDrained(Exception):
|
|
89
|
+
"""Placeholder that is never raised or matched on langgraph < 1.2."""
|
|
90
|
+
|
|
91
|
+
reason: str | None = None
|
|
92
|
+
|
|
93
|
+
class RunControl:
|
|
94
|
+
"""Placeholder; new_run_control() never creates one on langgraph < 1.2."""
|
|
95
|
+
|
|
96
|
+
class ServerRunControl(RunControl):
|
|
97
|
+
"""Placeholder; new_run_control() never creates one on langgraph < 1.2."""
|
|
98
|
+
|
|
99
|
+
DRAIN_SUPPORT = False
|
|
100
|
+
|
|
101
|
+
# Reason the server passes to request_drain() when its pod is shutting down.
|
|
102
|
+
# Graph code can pass any reason (request_drain() defaults to "shutdown"), so
|
|
103
|
+
# this distinct value is what tells server drains from graph drains in logs.
|
|
104
|
+
SERVER_SHUTDOWN_DRAIN_REASON = "server_shutdown"
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def mark_top_level(control: ServerRunControl | None) -> None:
|
|
108
|
+
"""Mark the current context as running ``control``'s top-level graph."""
|
|
109
|
+
_TOP_LEVEL_CONTROL.set(control)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def new_run_control() -> ServerRunControl | None:
|
|
113
|
+
"""Return a fresh control for a run, or None without drain support."""
|
|
114
|
+
if DRAIN_SUPPORT:
|
|
115
|
+
return ServerRunControl()
|
|
116
|
+
return None
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class RunControlRegistry:
|
|
120
|
+
"""Controls of the runs a queue drains at shutdown, keyed by run ID.
|
|
121
|
+
|
|
122
|
+
Workers can finish on background threads (isolated loops), so every access
|
|
123
|
+
takes a lock and ``drain_all`` works on a snapshot. Controls are registered
|
|
124
|
+
before the run starts, and removed only by the claim that registered them,
|
|
125
|
+
so a fast-finishing or superseded claim can't leave or remove the wrong
|
|
126
|
+
entry.
|
|
127
|
+
"""
|
|
128
|
+
|
|
129
|
+
def __init__(self) -> None:
|
|
130
|
+
self._lock = threading.Lock()
|
|
131
|
+
self._controls: dict[str, ServerRunControl] = {}
|
|
132
|
+
|
|
133
|
+
def add(self, run_id: Any, control: ServerRunControl) -> None:
|
|
134
|
+
"""Register a run's control before the run starts."""
|
|
135
|
+
with self._lock:
|
|
136
|
+
self._controls[str(run_id)] = control
|
|
137
|
+
|
|
138
|
+
def release(self, run_id: Any, control: ServerRunControl | None) -> None:
|
|
139
|
+
"""Remove a run's control if it is still the one this claim registered."""
|
|
140
|
+
if control is None:
|
|
141
|
+
return
|
|
142
|
+
with self._lock:
|
|
143
|
+
if self._controls.get(str(run_id)) is control:
|
|
144
|
+
del self._controls[str(run_id)]
|
|
145
|
+
|
|
146
|
+
def drain_all(self, reason: str) -> int:
|
|
147
|
+
"""Request a drain from every registered run; return how many."""
|
|
148
|
+
with self._lock:
|
|
149
|
+
controls = list(self._controls.values())
|
|
150
|
+
for control in controls:
|
|
151
|
+
control.request_drain(reason)
|
|
152
|
+
return len(controls)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
__all__ = [
|
|
156
|
+
"DRAIN_SUPPORT",
|
|
157
|
+
"SERVER_SHUTDOWN_DRAIN_REASON",
|
|
158
|
+
"GraphDrained",
|
|
159
|
+
"RunControl",
|
|
160
|
+
"RunControlRegistry",
|
|
161
|
+
"ServerRunControl",
|
|
162
|
+
"mark_top_level",
|
|
163
|
+
"new_run_control",
|
|
164
|
+
]
|