langgraph-api 0.3.1__tar.gz → 0.4.0__tar.gz

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: build release lint format test test_watch start start-inmem start-inmem-license-oss start check-version
+.PHONY: build release lint format test test_watch start start-inmem start-inmem-license-oss start check-version check-base-imports
 
 # lint commands
 
@@ -11,6 +11,9 @@ format:
 	uv run ruff check --fix .
 	uv run ruff format .
 
+check-base-imports:
+	LANGGRAPH_RUNTIME_EDITION=inmem DATABASE_URI=:memory: REDIS_URI=_FAKE uv run python -c "from langgraph_api.config import *; from langgraph_runtime import *"
+
 # test commands
 
 TEST ?= tests/

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.3.1
+Version: 0.4.0
 Author-email: Nuno Campos <nuno@langchain.dev>, Will Fu-Hinthorn <will@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE

langgraph_api-0.4.0/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/api/meta.py

@@ -54,10 +54,16 @@ async def meta_metrics(request: ApiRequest):
         metadata.PROJECT_ID, metadata.HOST_REVISION_ID, metrics_format
     )
 
+    pg_redis_stats = pool_stats(
+        project_id=metadata.PROJECT_ID,
+        revision_id=metadata.HOST_REVISION_ID,
+        format=metrics_format,
+    )
+
     if metrics_format == "json":
         async with connect() as conn:
             resp = {
-                **pool_stats(),
+                **pg_redis_stats,
                 "queue": await Runs.stats(conn),
                 **http_metrics,
             }
@@ -93,6 +99,7 @@ async def meta_metrics(request: ApiRequest):
                 )
 
             metrics.extend(http_metrics)
+            metrics.extend(pg_redis_stats)
 
         metrics_response = "\n".join(metrics)
         return PlainTextResponse(metrics_response)

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/api/runs.py

@@ -1,6 +1,7 @@
 import asyncio
 from collections.abc import AsyncIterator
 from typing import Literal, cast
+from uuid import uuid4
 
 import orjson
 from starlette.exceptions import HTTPException
@@ -100,7 +101,7 @@ async def stream_run(
     payload = await request.json(RunCreateStateful)
     on_disconnect = payload.get("on_disconnect", "continue")
     run_id = uuid7()
-    sub = asyncio.create_task(Runs.Stream.subscribe(run_id))
+    sub = asyncio.create_task(Runs.Stream.subscribe(run_id, thread_id))
 
     try:
         async with connect() as conn:
@@ -138,19 +139,21 @@ async def stream_run_stateless(
 ):
     """Create a stateless run."""
     payload = await request.json(RunCreateStateless)
+    payload["if_not_exists"] = "create"
     on_disconnect = payload.get("on_disconnect", "continue")
     run_id = uuid7()
-    sub = asyncio.create_task(Runs.Stream.subscribe(run_id))
-
+    thread_id = uuid4()
+    sub = asyncio.create_task(Runs.Stream.subscribe(run_id, thread_id))
     try:
         async with connect() as conn:
             run = await create_valid_run(
                 conn,
-                None,
+                str(thread_id),
                 payload,
                 request.headers,
                 run_id=run_id,
                 request_start_time=request.scope.get("request_start_time_ms"),
+                temporary=True,
             )
     except Exception:
         if not sub.cancelled():
@@ -181,7 +184,7 @@ async def wait_run(request: ApiRequest):
     payload = await request.json(RunCreateStateful)
     on_disconnect = payload.get("on_disconnect", "continue")
     run_id = uuid7()
-    sub = asyncio.create_task(Runs.Stream.subscribe(run_id))
+    sub = asyncio.create_task(Runs.Stream.subscribe(run_id, thread_id))
 
     try:
         async with connect() as conn:
@@ -263,26 +266,28 @@ async def wait_run(request: ApiRequest):
 async def wait_run_stateless(request: ApiRequest):
     """Create a stateless run, wait for the output."""
     payload = await request.json(RunCreateStateless)
+    payload["if_not_exists"] = "create"
     on_disconnect = payload.get("on_disconnect", "continue")
     run_id = uuid7()
-    sub = asyncio.create_task(Runs.Stream.subscribe(run_id))
+    thread_id = uuid4()
+    sub = asyncio.create_task(Runs.Stream.subscribe(run_id, thread_id))
 
     try:
         async with connect() as conn:
             run = await create_valid_run(
                 conn,
-                None,
+                str(thread_id),
                 payload,
                 request.headers,
                 run_id=run_id,
                 request_start_time=request.scope.get("request_start_time_ms"),
+                temporary=True,
             )
     except Exception:
         if not sub.cancelled():
             handle = await sub
             await handle.__aexit__(None, None, None)
         raise
-
     last_chunk = ValueEvent()
 
     async def consume():

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/api/threads.py

@@ -6,11 +6,13 @@ from starlette.routing import BaseRoute
 
 from langgraph_api.route import ApiRequest, ApiResponse, ApiRoute
 from langgraph_api.schema import THREAD_FIELDS
+from langgraph_api.sse import EventSourceResponse
 from langgraph_api.state import state_snapshot_to_thread_state
 from langgraph_api.utils import (
     fetchone,
     get_pagination_headers,
     validate_select_columns,
+    validate_stream_id,
     validate_uuid,
 )
 from langgraph_api.validation import (
@@ -282,6 +284,23 @@ async def copy_thread(request: ApiRequest):
     return ApiResponse(await fetchone(iter, not_found_code=409))
 
 
+@retry_db
+async def join_thread_stream(request: ApiRequest):
+    """Join a thread stream."""
+    thread_id = request.path_params["thread_id"]
+    validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
+    last_event_id = request.headers.get("last-event-id") or None
+    validate_stream_id(
+        last_event_id, "Invalid last-event-id: must be a valid Redis stream ID"
+    )
+    return EventSourceResponse(
+        Threads.Stream.join(
+            thread_id,
+            last_event_id=last_event_id,
+        ),
+    )
+
+
 threads_routes: list[BaseRoute] = [
     ApiRoute("/threads", endpoint=create_thread, methods=["POST"]),
     ApiRoute("/threads/search", endpoint=search_threads, methods=["POST"]),
@@ -312,4 +331,9 @@ threads_routes: list[BaseRoute] = [
         endpoint=get_thread_state_at_checkpoint_post,
         methods=["POST"],
     ),
+    ApiRoute(
+        "/threads/{thread_id}/stream",
+        endpoint=join_thread_stream,
+        methods=["GET"],
+    ),
 ]

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/config.py

@@ -180,6 +180,7 @@ REDIS_CLUSTER = env("REDIS_CLUSTER", cast=bool, default=False)
 REDIS_MAX_CONNECTIONS = env("REDIS_MAX_CONNECTIONS", cast=int, default=2000)
 REDIS_CONNECT_TIMEOUT = env("REDIS_CONNECT_TIMEOUT", cast=float, default=10.0)
 REDIS_MAX_IDLE_TIME = env("REDIS_MAX_IDLE_TIME", cast=float, default=120.0)
+REDIS_STREAM_TIMEOUT = env("REDIS_STREAM_TIMEOUT", cast=float, default=30.0)
 REDIS_KEY_PREFIX = env("REDIS_KEY_PREFIX", cast=str, default="")
 RUN_STATS_CACHE_SECONDS = env("RUN_STATS_CACHE_SECONDS", cast=int, default=60)
 
@@ -374,6 +375,7 @@ API_VARIANT = env("LANGSMITH_LANGGRAPH_API_VARIANT", cast=str, default="")
 # UI
 UI_USE_BUNDLER = env("LANGGRAPH_UI_BUNDLER", cast=bool, default=False)
 IS_QUEUE_ENTRYPOINT = False
+IS_EXECUTOR_ENTRYPOINT = False
 ref_sha = None
 if not os.getenv("LANGCHAIN_REVISION_ID") and (
     ref_sha := os.getenv("LANGSMITH_LANGGRAPH_GIT_REF_SHA")

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/executor_entrypoint.py

@@ -20,4 +20,7 @@ if __name__ == "__main__":
         uvloop.install()
     except ImportError:
         pass
+    from langgraph_api import config
+
+    config.IS_EXECUTOR_ENTRYPOINT = True
     asyncio.run(main(grpc_port=args.grpc_port, entrypoint_name="python-executor"))

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/models/run.py

@@ -249,6 +249,7 @@ async def create_valid_run(
     barrier: asyncio.Barrier | None = None,
     run_id: UUID | None = None,
     request_start_time: float | None = None,
+    temporary: bool = False,
 ) -> Run:
     request_id = headers.get("x-request-id")  # Will be null in the crons scheduler.
     (
@@ -262,7 +263,7 @@ async def create_valid_run(
         run_id=run_id,
     )
     if (
-        thread_id_ is None
+        (thread_id_ is None or temporary)
         and (command := payload.get("command"))
         and command.get("resume")
     ):
@@ -270,9 +271,9 @@ async def create_valid_run(
             status_code=400,
             detail="You must provide a thread_id when resuming.",
         )
-    temporary = (
-        thread_id_ is None and payload.get("on_completion", "delete") == "delete"
-    )
+    temporary = (temporary or thread_id_ is None) and payload.get(
+        "on_completion", "delete"
+    ) == "delete"
     stream_resumable = payload.get("stream_resumable", False)
     stream_mode, multitask_strategy, prevent_insert_if_inflight = assign_defaults(
         payload

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/queue_entrypoint.py

@@ -11,10 +11,8 @@ if not (
 
 import asyncio
 import contextlib
-import http.server
 import json
 import logging.config
-import os
 import pathlib
 import signal
 from contextlib import asynccontextmanager
@@ -22,6 +20,7 @@ from typing import cast
 
 import structlog
 
+from langgraph_runtime.database import pool_stats
 from langgraph_runtime.lifespan import lifespan
 from langgraph_runtime.metrics import get_metrics
 
@@ -29,69 +28,68 @@ logger = structlog.stdlib.get_logger(__name__)
 
 
 async def health_and_metrics_server():
+    import uvicorn
+    from starlette.applications import Starlette
+    from starlette.responses import JSONResponse, PlainTextResponse
+    from starlette.routing import Route
+
     port = int(os.getenv("PORT", "8080"))
-    ok = json.dumps({"status": "ok"}).encode()
-    ok_len = str(len(ok))
-
-    class HealthAndMetricsHandler(http.server.SimpleHTTPRequestHandler):
-        def log_message(self, format, *args):
-            # Skip logging for /ok and /metrics endpoints
-            if getattr(self, "path", None) in ["/ok", "/metrics"]:
-                return
-            # Log other requests normally
-            super().log_message(format, *args)
-
-        def do_GET(self):
-            path = getattr(self, "path", None)
-            if path == "/ok":
-                self.send_response(200)
-                self.send_header("Content-Type", "application/json")
-                self.send_header("Content-Length", ok_len)
-                self.end_headers()
-                self.wfile.write(ok)
-            elif path == "/metrics":
-                metrics = get_metrics()
-                worker_metrics = cast(dict[str, int], metrics["workers"])
-                workers_max = worker_metrics["max"]
-                workers_active = worker_metrics["active"]
-                workers_available = worker_metrics["available"]
-
-                project_id = os.getenv("LANGSMITH_HOST_PROJECT_ID")
-                revision_id = os.getenv("LANGSMITH_HOST_REVISION_ID")
-
-                metrics = [
-                    "# HELP lg_api_workers_max The maximum number of workers available.",
-                    "# TYPE lg_api_workers_max gauge",
-                    f'lg_api_workers_max{{project_id="{project_id}", revision_id="{revision_id}"}} {workers_max}',
-                    "# HELP lg_api_workers_active The number of currently active workers.",
-                    "# TYPE lg_api_workers_active gauge",
-                    f'lg_api_workers_active{{project_id="{project_id}", revision_id="{revision_id}"}} {workers_active}',
-                    "# HELP lg_api_workers_available The number of available (idle) workers.",
-                    "# TYPE lg_api_workers_available gauge",
-                    f'lg_api_workers_available{{project_id="{project_id}", revision_id="{revision_id}"}} {workers_available}',
-                ]
-
-                metrics_response = "\n".join(metrics).encode()
-                metrics_len = str(len(metrics_response))
-
-                self.send_response(200)
-                self.send_header(
-                    "Content-Type", "text/plain; version=0.0.4; charset=utf-8"
-                )
-                self.send_header("Content-Length", metrics_len)
-                self.end_headers()
-                self.wfile.write(metrics_response)
-            else:
-                self.send_error(http.HTTPStatus.NOT_FOUND)
-
-    with http.server.ThreadingHTTPServer(
-        ("0.0.0.0", port), HealthAndMetricsHandler
-    ) as httpd:
-        logger.info(f"Health and metrics server started at http://0.0.0.0:{port}")
-        try:
-            await asyncio.to_thread(httpd.serve_forever)
-        finally:
-            httpd.shutdown()
+
+    async def health_endpoint(request):
+        return JSONResponse({"status": "ok"})
+
+    async def metrics_endpoint(request):
+        metrics = get_metrics()
+        worker_metrics = cast(dict[str, int], metrics["workers"])
+        workers_max = worker_metrics["max"]
+        workers_active = worker_metrics["active"]
+        workers_available = worker_metrics["available"]
+
+        project_id = os.getenv("LANGSMITH_HOST_PROJECT_ID")
+        revision_id = os.getenv("LANGSMITH_HOST_REVISION_ID")
+
+        metrics_lines = [
+            "# HELP lg_api_workers_max The maximum number of workers available.",
+            "# TYPE lg_api_workers_max gauge",
+            f'lg_api_workers_max{{project_id="{project_id}", revision_id="{revision_id}"}} {workers_max}',
+            "# HELP lg_api_workers_active The number of currently active workers.",
+            "# TYPE lg_api_workers_active gauge",
+            f'lg_api_workers_active{{project_id="{project_id}", revision_id="{revision_id}"}} {workers_active}',
+            "# HELP lg_api_workers_available The number of available (idle) workers.",
+            "# TYPE lg_api_workers_available gauge",
+            f'lg_api_workers_available{{project_id="{project_id}", revision_id="{revision_id}"}} {workers_available}',
+        ]
+
+        metrics_lines.extend(
+            pool_stats(
+                project_id=project_id,
+                revision_id=revision_id,
+            )
+        )
+
+        return PlainTextResponse(
+            "\n".join(metrics_lines),
+            media_type="text/plain; version=0.0.4; charset=utf-8",
+        )
+
+    app = Starlette(
+        routes=[
+            Route("/ok", health_endpoint),
+            Route("/metrics", metrics_endpoint),
+        ]
+    )
+
+    config = uvicorn.Config(
+        app,
+        host="0.0.0.0",
+        port=port,
+        log_level="error",
+        access_log=False,
+    )
+    server = uvicorn.Server(config)
+
+    logger.info(f"Health and metrics server started at http://0.0.0.0:{port}")
+    await server.serve()
 
 
 async def entrypoint(

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/stream.py

@@ -424,6 +424,8 @@ async def consume(
     run_id: str | uuid.UUID,
     resumable: bool = False,
     stream_modes: set[StreamMode] | None = None,
+    *,
+    thread_id: str | uuid.UUID | None = None,
 ) -> None:
     stream_modes = stream_modes or set()
     if "messages-tuple" in stream_modes:
@@ -437,6 +439,7 @@ async def consume(
                     run_id,
                     mode,
                     await run_in_executor(None, json_dumpb, payload),
+                    thread_id=thread_id,
                     resumable=resumable and mode.split("|")[0] in stream_modes,
                 )
         except Exception as e:
@@ -446,6 +449,7 @@ async def consume(
                 run_id,
                 "error",
                 await run_in_executor(None, json_dumpb, e),
+                thread_id=thread_id,
             )
             raise e
 

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/utils/__init__.py

@@ -1,4 +1,5 @@
 import contextvars
+import re
 import uuid
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
@@ -22,6 +23,7 @@ Row: TypeAlias = dict[str, Any]
 AuthContext = contextvars.ContextVar[Auth.types.BaseAuthContext | None](
     "AuthContext", default=None
 )
+STREAM_ID_PATTERN = re.compile(r"^\d+(-(\d+|\*))?$")
 
 
 @asynccontextmanager
@@ -101,6 +103,23 @@ def validate_uuid(uuid_str: str, invalid_uuid_detail: str | None) -> uuid.UUID:
         raise HTTPException(status_code=422, detail=invalid_uuid_detail) from None
 
 
+def validate_stream_id(stream_id: str | None, invalid_stream_id_detail: str | None):
+    """
+    Validate Redis stream ID format.
+    Valid formats:
+    - timestamp-sequence (e.g., "1724342400000-0")
+    - timestamp-* (e.g., "1724342400000-*")
+    - timestamp only (e.g., "1724342400000")
+    - "-" (special case, represents the beginning of the stream, use if you want to replay all events)
+    """
+    if not stream_id or stream_id == "-":
+        return stream_id
+
+    if STREAM_ID_PATTERN.match(stream_id):
+        return stream_id
+    raise HTTPException(status_code=422, detail=invalid_stream_id_detail)
+
+
 def next_cron_date(schedule: str, base_time: datetime) -> datetime:
     import croniter  # type: ignore[unresolved-import]
 

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/langgraph_api/worker.py

@@ -139,7 +139,9 @@ async def worker(
         stream_modes: set[StreamMode],
     ):
         try:
-            await consume(stream, run_id, resumable, stream_modes)
+            await consume(
+                stream, run_id, resumable, stream_modes, thread_id=run["thread_id"]
+            )
         except Exception as e:
             if not isinstance(e, UserRollback | UserInterrupt):
                 logger.exception(
@@ -151,7 +153,7 @@ async def worker(
                 raise UserTimeout(e) from e
             raise
 
-    async with Runs.enter(run_id, main_loop) as done:
+    async with Runs.enter(run_id, run["thread_id"], main_loop) as done:
         # attempt the run
         try:
             if attempt > BG_JOB_MAX_RETRIES:

{langgraph_api-0.3.1 → langgraph_api-0.4.0}/openapi.json

@@ -1520,6 +1520,73 @@
         }
       }
     },
+    "/threads/{thread_id}/stream": {
+      "get": {
+        "tags": [
+          "Threads"
+        ],
+        "summary": "Join Thread Stream",
+        "description": "This endpoint streams output in real-time from a thread. The stream will include the output of each run executed sequentially on the thread and will remain open indefinitely. It is the responsibility of the calling client to close the connection.",
+        "operationId": "join_thread_stream_threads__thread_id__stream_get",
+        "parameters": [
+          {
+            "description": "The ID of the thread.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "title": "Thread Id",
+              "description": "The ID of the thread."
+            },
+            "name": "thread_id",
+            "in": "path"
+          },
+          {
+            "required": false,
+            "schema": {
+              "type": "string",
+              "title": "Last Event ID",
+              "description": "The ID of the last event received. Used to resume streaming from a specific point. Pass '-' to resume from the beginning."
+            },
+            "name": "Last-Event-ID",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "type": "string",
+                  "description": "The server will send a stream of events in SSE format.\n\n**Example event**:\n\nid: 1\n\nevent: message\n\ndata: {}"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/threads/{thread_id}/runs": {
       "get": {
         "tags": [

langgraph_api-0.3.1/langgraph_api/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.1"