langgraph-api 0.4.20__py3-none-any.whl → 0.4.22__py3-none-any.whl

langgraph_api/api/runs.py

@@ -1,7 +1,7 @@
 import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 from typing import Literal, cast
-from uuid import uuid4
+from uuid import UUID, uuid4
 
 import orjson
 import structlog
@@ -32,12 +32,116 @@ from langgraph_api.validation import (
 )
 from langgraph_license.validation import plus_features_enabled
 from langgraph_runtime.database import connect
-from langgraph_runtime.ops import Crons, Runs, Threads
+from langgraph_runtime.ops import Crons, Runs, StreamHandler, Threads
 from langgraph_runtime.retry import retry_db
 
 logger = structlog.stdlib.get_logger(__name__)
 
 
+_RunResultFallback = Callable[[], Awaitable[bytes]]
+
+
+def _thread_values_fallback(thread_id: UUID) -> _RunResultFallback:
+    async def fetch_thread_values() -> bytes:
+        async with connect() as conn:
+            thread_iter = await Threads.get(conn, thread_id)
+            try:
+                thread = await anext(thread_iter)
+                if thread["status"] == "error":
+                    return orjson.dumps({"__error__": orjson.Fragment(thread["error"])})
+                if thread["status"] == "interrupted":
+                    # Get an interrupt for the thread. There is the case where there are multiple interrupts for the same run and we may not show the same
+                    # interrupt, but we'll always show one. Long term we should show all of them.
+                    try:
+                        if isinstance(thread["interrupts"], dict):
+                            # Handle in memory format
+                            interrupt_map = thread["interrupts"]
+                        else:
+                            interrupt_map = orjson.loads(thread["interrupts"].buf)
+                        interrupt = [next(iter(interrupt_map.values()))[0]]
+                        return orjson.dumps({"__interrupt__": interrupt})
+                    except Exception:
+                        # No interrupt, but status is interrupted from a before/after block. Default back to values.
+                        pass
+                return cast(bytes, thread["values"])
+            except StopAsyncIteration:
+                await logger.awarning(
+                    f"No checkpoint found for thread {thread_id}",
+                    thread_id=thread_id,
+                )
+                return b"{}"
+
+    return fetch_thread_values
+
+
+def _run_result_body(
+    *,
+    run_id: UUID,
+    thread_id: UUID,
+    sub: StreamHandler,
+    cancel_on_disconnect: bool = False,
+    ignore_404: bool = False,
+    fallback: _RunResultFallback | None = None,
+    cancel_message: str | None = None,
+) -> Callable[[], AsyncIterator[bytes]]:
+    last_chunk = ValueEvent()
+
+    async def consume() -> None:
+        vchunk: bytes | None = None
+        try:
+            async for mode, chunk, _ in Runs.Stream.join(
+                run_id,
+                stream_channel=sub,
+                cancel_on_disconnect=cancel_on_disconnect,
+                thread_id=thread_id,
+                ignore_404=ignore_404,
+            ):
+                if (
+                    mode == b"values"
+                    or mode == b"updates"
+                    and b"__interrupt__" in chunk
+                ):
+                    vchunk = chunk
+                elif mode == b"error":
+                    vchunk = orjson.dumps({"__error__": orjson.Fragment(chunk)})
+            if vchunk is not None:
+                last_chunk.set(vchunk)
+            elif fallback is not None:
+                last_chunk.set(await fallback())
+            else:
+                last_chunk.set(b"{}")
+        finally:
+            # Make sure to always clean up the pubsub
+            await sub.__aexit__(None, None, None)
+
+    # keep the connection open by sending whitespace every 5 seconds
+    # leading whitespace will be ignored by json parsers
+    async def body() -> AsyncIterator[bytes]:
+        try:
+            stream = asyncio.create_task(consume())
+            while True:
+                try:
+                    if stream.done():
+                        # raise stream exception if any
+                        stream.result()
+                    yield await asyncio.wait_for(last_chunk.wait(), timeout=5)
+                    break
+                except TimeoutError:
+                    yield b"\n"
+                except asyncio.CancelledError:
+                    if cancel_message is not None:
+                        stream.cancel(cancel_message)
+                    else:
+                        stream.cancel()
+                    await stream
+                    raise
+        finally:
+            # Make sure to always clean up the pubsub
+            await sub.__aexit__(None, None, None)
+
+    return body
+
+
 @retry_db
 async def create_run(request: ApiRequest):
     """Create a run."""
@@ -218,56 +322,13 @@ async def wait_run(request: ApiRequest):
         await sub.__aexit__(None, None, None)
         raise
 
-    last_chunk = ValueEvent()
-
-    async def consume():
-        vchunk: bytes | None = None
-        async for mode, chunk, _ in Runs.Stream.join(
-            run["run_id"],
-            thread_id=run["thread_id"],
-            stream_channel=sub,
-            cancel_on_disconnect=on_disconnect == "cancel",
-        ):
-            if mode == b"values" or mode == b"updates" and b"__interrupt__" in chunk:
-                vchunk = chunk
-            elif mode == b"error":
-                vchunk = orjson.dumps({"__error__": orjson.Fragment(chunk)})
-        if vchunk is not None:
-            last_chunk.set(vchunk)
-        else:
-            async with connect() as conn:
-                thread_iter = await Threads.get(conn, thread_id)
-                try:
-                    thread = await anext(thread_iter)
-                    last_chunk.set(thread["values"])
-                except StopAsyncIteration:
-                    await logger.awarning(
-                        f"No checkpoint found for thread {thread_id}",
-                        thread_id=thread_id,
-                    )
-                    last_chunk.set(b"{}")
-
-    # keep the connection open by sending whitespace every 5 seconds
-    # leading whitespace will be ignored by json parsers
-    async def body() -> AsyncIterator[bytes]:
-        try:
-            stream = asyncio.create_task(consume())
-            while True:
-                try:
-                    if stream.done():
-                        # raise stream exception if any
-                        stream.result()
-                    yield await asyncio.wait_for(last_chunk.wait(), timeout=5)
-                    break
-                except TimeoutError:
-                    yield b"\n"
-                except asyncio.CancelledError:
-                    stream.cancel()
-                    await stream
-                    raise
-        finally:
-            # Make sure to always clean up the pubsub
-            await sub.__aexit__(None, None, None)
+    body = _run_result_body(
+        run_id=run["run_id"],
+        thread_id=run["thread_id"],
+        sub=sub,
+        cancel_on_disconnect=on_disconnect == "cancel",
+        fallback=_thread_values_fallback(thread_id),
+    )
 
     return StreamingResponse(
         body(),
@@ -305,53 +366,23 @@ async def wait_run_stateless(request: ApiRequest):
         await sub.__aexit__(None, None, None)
         raise
 
-    last_chunk = ValueEvent()
-
-    async def consume():
-        vchunk: bytes | None = None
-        async for mode, chunk, _ in Runs.Stream.join(
-            run["run_id"],
+    async def stateless_fallback() -> bytes:
+        await logger.awarning(
+            "No checkpoint emitted for stateless run",
+            run_id=run["run_id"],
             thread_id=run["thread_id"],
-            stream_channel=sub,
-            ignore_404=True,
-            cancel_on_disconnect=on_disconnect == "cancel",
-        ):
-            if mode == b"values" or mode == b"updates" and b"__interrupt__" in chunk:
-                vchunk = chunk
-            elif mode == b"error":
-                vchunk = orjson.dumps({"__error__": orjson.Fragment(chunk)})
-        if vchunk is not None:
-            last_chunk.set(vchunk)
-        else:
-            # we can't fetch the thread (it was deleted), so just return empty values
-            await logger.awarning(
-                "No checkpoint emitted for stateless run",
-                run_id=run["run_id"],
-                thread_id=run["thread_id"],
-            )
-            last_chunk.set(b"{}")
-
-    # keep the connection open by sending whitespace every 5 seconds
-    # leading whitespace will be ignored by json parsers
-    async def body() -> AsyncIterator[bytes]:
-        try:
-            stream = asyncio.create_task(consume())
-            while True:
-                try:
-                    if stream.done():
-                        # raise stream exception if any
-                        stream.result()
-                    yield await asyncio.wait_for(last_chunk.wait(), timeout=5)
-                    break
-                except TimeoutError:
-                    yield b"\n"
-                except asyncio.CancelledError:
-                    stream.cancel("Run stream cancelled")
-                    await stream
-                    raise
-        finally:
-            # Make sure to always clean up the pubsub
-            await sub.__aexit__(None, None, None)
+        )
+        return b"{}"
+
+    body = _run_result_body(
+        run_id=run["run_id"],
+        thread_id=run["thread_id"],
+        sub=sub,
+        cancel_on_disconnect=on_disconnect == "cancel",
+        ignore_404=True,
+        fallback=stateless_fallback,
+        cancel_message="Run stream cancelled",
+    )
 
     return StreamingResponse(
         body(),
@@ -422,11 +453,23 @@ async def join_run(request: ApiRequest):
     validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
     validate_uuid(run_id, "Invalid run ID: must be a UUID")
 
-    return ApiResponse(
-        await Runs.join(
-            run_id,
-            thread_id=thread_id,
-        )
+    # A touch redundant, but to meet the existing signature of join, we need to throw any 404s before we enter the streaming body
+    await Runs.Stream.check_run_stream_auth(run_id, thread_id)
+    sub = await Runs.Stream.subscribe(run_id, thread_id)
+    body = _run_result_body(
+        run_id=run_id,
+        thread_id=thread_id,
+        sub=sub,
+        fallback=_thread_values_fallback(thread_id),
+    )
+
+    return StreamingResponse(
+        body(),
+        media_type="application/json",
+        headers={
+            "Location": f"/threads/{thread_id}/runs/{run_id}/join",
+            "Content-Location": f"/threads/{thread_id}/runs/{run_id}",
+        },
     )
 
 
@@ -456,6 +499,10 @@ async def join_run_stream(request: ApiRequest):
 
     return EventSourceResponse(
         body(),
+        headers={
+            "Location": f"/threads/{thread_id}/runs/{run_id}/stream",
+            "Content-Location": f"/threads/{thread_id}/runs/{run_id}",
+        },
     )
 
 
@@ -476,19 +523,36 @@ async def cancel_run(
         action_str if action_str in {"interrupt", "rollback"} else "interrupt",
     )
 
-    async with connect() as conn:
-        await Runs.cancel(
-            conn,
-            [run_id],
-            action=action,
-            thread_id=thread_id,
-        )
-    if wait:
-        await Runs.join(
-            run_id,
-            thread_id=thread_id,
-        )
-    return Response(status_code=204 if wait else 202)
+    sub = await Runs.Stream.subscribe(run_id, thread_id) if wait else None
+    try:
+        async with connect() as conn:
+            await Runs.cancel(
+                conn,
+                [run_id],
+                action=action,
+                thread_id=thread_id,
+            )
+    except Exception:
+        if sub is not None:
+            await sub.__aexit__(None, None, None)
+        raise
+    if not wait:
+        return Response(status_code=202)
+
+    body = _run_result_body(
+        run_id=run_id,
+        thread_id=thread_id,
+        sub=sub,
+    )
+
+    return StreamingResponse(
+        body(),
+        media_type="application/json",
+        headers={
+            "Location": f"/threads/{thread_id}/runs/{run_id}/join",
+            "Content-Location": f"/threads/{thread_id}/runs/{run_id}",
+        },
+    )
 
 
 @retry_db

langgraph_api/cli.py

@@ -11,12 +11,17 @@ from typing import Literal
 from typing_extensions import TypedDict
 
 if typing.TYPE_CHECKING:
+    from packaging.version import Version
+
     from langgraph_api.config import HttpConfig, StoreConfig
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
+SUPPORT_STATUS = Literal["active", "critical", "eol"]
+
+
 def _get_ls_origin() -> str | None:
     from langsmith.client import Client
     from langsmith.utils import tracing_is_enabled
@@ -121,46 +126,6 @@ class AuthConfig(TypedDict, total=False):
     cache: CacheConfig | None
 
 
-def _check_newer_version(pkg: str, timeout: float = 0.2) -> None:
-    """Log a notice if PyPI reports a newer version."""
-    import importlib.metadata as md
-    import json
-    import urllib.request
-
-    from packaging.version import Version
-
-    thread_logger = logging.getLogger("check_version")
-    if not thread_logger.handlers:
-        handler = logging.StreamHandler()
-        handler.setFormatter(logging.Formatter("%(message)s"))
-        thread_logger.addHandler(handler)
-
-    try:
-        current = Version(md.version(pkg))
-        with urllib.request.urlopen(
-            f"https://pypi.org/pypi/{pkg}/json", timeout=timeout
-        ) as resp:
-            latest_str = json.load(resp)["info"]["version"]
-        latest = Version(latest_str)
-        if latest > current:
-            thread_logger.info(
-                "🔔  A newer version of %s is available: %s → %s (pip install -U %s)",
-                pkg,
-                current,
-                latest,
-                pkg,
-            )
-
-    except Exception:
-        pass
-
-    except RuntimeError:
-        thread_logger.info(
-            f"Failed to check for newer version of {pkg}."
-            " To disable version checks, set LANGGRAPH_NO_VERSION_CHECK=true"
-        )
-
-
 def run_server(
     host: str = "127.0.0.1",
     port: int = 2024,
@@ -291,7 +256,7 @@ def run_server(
             if k in to_patch:
                 logger.debug(f"Skipping loaded env var {k}={v}")
                 continue
-            to_patch[k] = v
+            to_patch[k] = v  # type: ignore[invalid-assignment]
     with patch_environment(
         **to_patch,
     ):
@@ -362,8 +327,12 @@ For production use, please use LangGraph Platform.
             threading.Thread(target=_open_browser, daemon=True).start()
         nvc = os.getenv("LANGGRAPH_NO_VERSION_CHECK")
         if nvc is None or nvc.lower() not in ("true", "1"):
+            from langgraph_api import __version__
+
             threading.Thread(
-                target=_check_newer_version, args=("langgraph-api",), daemon=True
+                target=_check_newer_version,
+                args=("langgraph-api", __version__),
+                daemon=True,
             ).start()
         supported_kwargs = {
             k: v
@@ -471,5 +440,133 @@ def main():
     )
 
 
+def _check_newer_version(pkg: str, current_version: str, timeout: float = 0.5) -> None:
+    """Check PyPI for newer versions and log support status.
+
+    Critical = one minor behind on same major, OR latest minor of previous major while latest is X.0.*
+    EOL = two+ minors behind on same major, OR any previous major after X.1.*
+    """
+    import json
+    import urllib.request
+
+    from packaging.version import InvalidVersion, Version
+
+    log = logging.getLogger("version_check")
+    if not log.handlers:
+        h = logging.StreamHandler()
+        h.setFormatter(logging.Formatter("%(message)s"))
+        log.addHandler(h)
+
+    if os.getenv("LANGGRAPH_NO_VERSION_CHECK", "").lower() in ("true", "1"):
+        return
+
+    def _parse(v: str) -> Version | None:
+        try:
+            return Version(v)
+        except InvalidVersion:
+            return None
+
+    try:
+        current = Version(current_version)
+    except InvalidVersion:
+        log.info(
+            f"[version] Could not parse installed version {current_version!r}. Skipping support check."
+        )
+        return
+
+    try:
+        with urllib.request.urlopen(
+            f"https://pypi.org/pypi/{pkg}/json", timeout=timeout
+        ) as resp:
+            payload = json.load(resp)
+        latest_str = payload["info"]["version"]
+        latest = Version(latest_str)
+        releases: dict[str, list[dict]] = payload.get("releases", {})
+    except Exception:
+        log.debug("Failed to retrieve latest version info for %s", pkg)
+        return
+    prev_major_latest_minor: Version | None = None
+    if latest.major > 0:
+        pm = latest.major - 1
+        prev_major_versions = [
+            v
+            for s in releases
+            if (v := _parse(s)) is not None and not v.is_prerelease and v.major == pm
+        ]
+        if prev_major_versions:
+            prev_major_latest_minor = max(
+                prev_major_versions, key=lambda v: (v.major, v.minor, v.micro)
+            )
+
+    if latest > current and not current.is_prerelease:
+        log.info(
+            "[version] A newer version of %s is available: %s → %s  (pip install -U %s)",
+            pkg,
+            current,
+            latest,
+            pkg,
+        )
+
+    level = _support_level(current, latest, prev_major_latest_minor)
+    changelog = (
+        "https://docs.langchain.com/langgraph-platform/langgraph-server-changelog"
+    )
+
+    if level == "critical":
+        # Distinguish same-major vs cross-major grace in the wording
+        if current.major == latest.major and current.minor == latest.minor - 1:
+            tail = "You are one minor version behind the latest (%d.%d.x).\n"
+        else:
+            tail = "You are on the latest minor of the previous major while a new major (%d.%d.x) just released.\n"
+        log.info(
+            "⚠️ [support] %s %s is in Critical support.\n"
+            "Only critical security and installation fixes are provided.\n"
+            + tail
+            + "Please plan an upgrade soon. See changelog: %s",
+            pkg,
+            current,
+            latest.major,
+            latest.minor,
+            changelog,
+        )
+    elif level == "eol":
+        log.info(
+            "⚠️ [support] %s %s is End of Life.\n"
+            "No bug fixes or security updates will be provided.\n"
+            "You are two or more minor versions behind the latest (%d.%d.x).\n"
+            "You should upgrade immediately. See changelog: %s",
+            pkg,
+            current,
+            latest.major,
+            latest.minor,
+            changelog,
+        )
+
+
+def _support_level(
+    cur: "Version", lat: "Version", prev_major_latest_minor: "Version | None"
+) -> SUPPORT_STATUS:
+    if cur.major > lat.major:
+        return "active"
+    if cur.major == lat.major:
+        if cur.minor == lat.minor:
+            return "active"
+        if cur.minor == lat.minor - 1:
+            return "critical"
+        if cur.minor <= lat.minor - 2:
+            return "eol"
+        return "active"
+
+    if cur.major == lat.major - 1 and lat.minor == 0:
+        if (
+            prev_major_latest_minor is not None
+            and cur.minor == prev_major_latest_minor.minor
+        ):
+            return "critical"
+        return "eol"
+
+    return "eol"
+
+
 if __name__ == "__main__":
     main()

langgraph_api/command.py

@@ -21,7 +21,7 @@ def map_cmd(cmd: RunCommand) -> Command:
         update=update,
         goto=(
             [
-                it if isinstance(it, str) else Send(it["node"], it["input"])
+                it if isinstance(it, str) else Send(it["node"], it["input"])  # type: ignore[non-subscriptable]
                 for it in goto
             ]
             if goto

langgraph_api/js/package.json

@@ -18,7 +18,7 @@
     "@typescript/vfs": "^1.6.0",
     "dedent": "^1.5.3",
     "exit-hook": "^4.0.0",
-    "hono": "^4.5.4",
+    "hono": "^4.9.7",
     "p-queue": "^8.0.1",
     "p-retry": "^6.2.0",
     "tsx": "^4.19.3",

langgraph_api/js/remote.py

@@ -239,7 +239,7 @@ class RemotePregel(BaseRemotePregel):
                         tuple(task["path"]) if task.get("path") else tuple(),
                         # TODO: figure out how to properly deserialise errors
                         task.get("error"),
-                        tuple(interrupts),
+                        tuple(interrupts),  # type: ignore[arg-type]
                         state,
                         task.get("result"),
                     )

langgraph_api/js/yarn.lock

@@ -974,10 +974,10 @@ has-flag@^4.0.0:
   resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b"
   integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==
 
-hono@^4.5.4:
-  version "4.6.14"
-  resolved "https://registry.yarnpkg.com/hono/-/hono-4.6.14.tgz#f83f51e81b8ae5611dab459570990bf4c977d20c"
-  integrity sha512-j4VkyUp2xazGJ8eCCLN1Vm/bxdvm/j5ZuU9AIjLu9vapn2M44p9L3Ktr9Vnb2RN2QtcR/wVjZVMlT5k7GJQgPw==
+hono@^4.5.4, hono@^4.9.7:
+  version "4.9.7"
+  resolved "https://registry.yarnpkg.com/hono/-/hono-4.9.7.tgz#8ac244477397de71d7d3d393fad129209b5b631e"
+  integrity sha512-t4Te6ERzIaC48W3x4hJmBwgNlLhmiEdEE5ViYb02ffw4ignHNHa5IBtPjmbKstmtKa8X6C35iWwK4HaqvrzG9w==
 
 icss-utils@^5.0.0, icss-utils@^5.1.0:
   version "5.1.0"

langgraph_api/metadata.py

@@ -7,6 +7,8 @@ import langgraph.version
 import orjson
 import structlog
 
+import langgraph_api.config as config
+from langgraph_api.auth.custom import get_auth_instance
 from langgraph_api.config import (
     LANGGRAPH_CLOUD_LICENSE_KEY,
     LANGSMITH_API_KEY,
@@ -17,7 +19,9 @@ from langgraph_api.config import (
     USES_STORE_TTL,
     USES_THREAD_TTL,
 )
+from langgraph_api.graph import GRAPHS, is_js_graph
 from langgraph_api.http import http_request
+from langgraph_api.js.base import is_js_path
 from langgraph_license.validation import plus_features_enabled
 
 logger = structlog.stdlib.get_logger(__name__)
@@ -72,6 +76,36 @@ if LANGSMITH_AUTH_ENDPOINT:
         )
 
 
+def _lang_usage_metadata() -> tuple[dict[str, str], dict[str, int]]:
+    js_graph_count = sum(1 for graph_id in GRAPHS if is_js_graph(graph_id))
+    py_graph_count = len(GRAPHS) - js_graph_count
+
+    auth_instance = get_auth_instance()
+    custom_auth_enabled = auth_instance is not None
+    custom_js_auth_enabled = auth_instance == "js"
+
+    js_proxy_middleware_enabled = False
+    if (
+        config.HTTP_CONFIG
+        and (app := config.HTTP_CONFIG.get("app"))
+        and isinstance(app, str)
+    ):
+        app_path = app.split(":", 1)[0]  # type: ignore[possibly-unresolved-reference]
+        js_proxy_middleware_enabled = is_js_path(app_path)
+
+    tags = {
+        "langgraph.platform.uses_custom_auth": str(custom_auth_enabled),
+        "langgraph.platform.uses_js_custom_auth": str(custom_js_auth_enabled),
+        "langgraph.platform.uses_js_proxy_middleware": str(js_proxy_middleware_enabled),
+    }
+    measures = {
+        "langgraph.platform.py_graphs": py_graph_count,
+        "langgraph.platform.js_graphs": js_graph_count,
+    }
+
+    return tags, measures
+
+
 def incr_runs(*, incr: int = 1) -> None:
     global RUN_COUNTER
     RUN_COUNTER += incr
@@ -111,6 +145,7 @@ async def metadata_loop() -> None:
         RUN_COUNTER = 0
         NODE_COUNTER = 0
         FROM_TIMESTAMP = to_timestamp
+        usage_tags, usage_measures = _lang_usage_metadata()
 
         base_payload = {
             "from_timestamp": from_timestamp,
@@ -131,10 +166,12 @@ async def metadata_loop() -> None:
                 "user_app.uses_custom_auth": str(USES_CUSTOM_AUTH),
                 "user_app.uses_thread_ttl": str(USES_THREAD_TTL),
                 "user_app.uses_store_ttl": str(USES_STORE_TTL),
+                **usage_tags,
             },
             "measures": {
                 "langgraph.platform.runs": runs,
                 "langgraph.platform.nodes": nodes,
+                **usage_measures,
             },
             "logs": [],
         }