langgraph-api 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

langgraph_api/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.4"
+__version__ = "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/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/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/stream.py

@@ -2,7 +2,7 @@ import uuid
 from collections.abc import AsyncIterator, Callable
 from contextlib import AsyncExitStack, aclosing, asynccontextmanager
 from functools import lru_cache
-from typing import Any, Literal, cast
+from typing import Any, cast
 
 import langgraph.version
 import langsmith
@@ -423,7 +423,9 @@ async def consume(
     stream: AnyStream,
     run_id: str | uuid.UUID,
     resumable: bool = False,
-    stream_modes: set[StreamMode | Literal["metadata"]] | None = None,
+    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/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/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.4.dist-info → langgraph_api-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.3.4
+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.3.4.dist-info → langgraph_api-0.4.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-langgraph_api/__init__.py,sha256=oYLGMpySamd16KLiaBTfRyrAS7_oyp-TOEHmzmeumwg,22
+langgraph_api/__init__.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
 langgraph_api/asgi_transport.py,sha256=XtiLOu4WWsd-xizagBLzT5xUkxc9ZG9YqwvETBPjBFE,5161
 langgraph_api/asyncio.py,sha256=mZ7G32JjrGxrlH4OMy7AKlBQo5bZt4Sm2rlrBcU-Vj8,9483
 langgraph_api/cli.py,sha256=-ruIeKi1imvS6GriOfRDZY-waV4SbWiJ0BEFAciPVYI,16330
@@ -22,21 +22,21 @@ langgraph_api/server.py,sha256=uCAqPgCLJ6ckslLs0i_dacSR8mzuR0Y6PkkJYk0O3bE,7196
 langgraph_api/sse.py,sha256=SLdtZmTdh5D8fbWrQjuY9HYLd2dg8Rmi6ZMmFMVc2iE,4204
 langgraph_api/state.py,sha256=5RTOShiFVnkx-o6t99_x63CGwXw_8Eb-dSTpYirP8ro,4683
 langgraph_api/store.py,sha256=NIoNZojs6NbtG3VLBPQEFNttvp7XPkHAfjbQ3gY7aLY,4701
-langgraph_api/stream.py,sha256=iRF4Hu6A1n-KvDR4ki1BeOvOnOxGoV2NV8tiBHUWZOs,18428
+langgraph_api/stream.py,sha256=IpGW9vpknI_wWteEmZfQKqCYqbaJAzOpq0FgdFJP60s,18528
 langgraph_api/thread_ttl.py,sha256=7H3gFlWcUiODPoaEzcwB0LR61uvcuyjD0ew_4BztB7k,1902
 langgraph_api/traceblock.py,sha256=Qq5CUdefnMDaRDnyvBSWGBClEj-f3oO7NbH6fedxOSE,630
 langgraph_api/utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langgraph_api/validation.py,sha256=86jftgOsMa7tkeshBw6imYe7zyUXPoVuf5Voh6dFiR8,5285
 langgraph_api/webhook.py,sha256=SvSM1rdnNtiH4q3JQYmAqJUk2Sable5xAcwOLuRhtlo,1723
-langgraph_api/worker.py,sha256=HVGyGVEYcXG-iKVgoBdFgANGxPjSs57JRl5OB4ra4nw,15267
+langgraph_api/worker.py,sha256=M9WQdxEzVGDZqdjz3LHEHhM1g6isPcf3k1V4PEkcSY8,15343
 langgraph_api/api/__init__.py,sha256=WHy6oNLWtH1K7AxmmsU9RD-Vm6WP-Ov16xS8Ey9YCmQ,6090
 langgraph_api/api/assistants.py,sha256=5gVvU58Y1-EftBhCHGbEaOi_7cqGMKWhOt_GVfBC0Gg,16836
 langgraph_api/api/mcp.py,sha256=qe10ZRMN3f-Hli-9TI8nbQyWvMeBb72YB1PZVbyqBQw,14418
 langgraph_api/api/meta.py,sha256=dFD9ZgykbKARLdVSaJD9vO3CShvEyBmGpkjE8tqii0c,4448
 langgraph_api/api/openapi.py,sha256=If-z1ckXt-Yu5bwQytK1LWyX_T7G46UtLfixgEP8hwc,11959
-langgraph_api/api/runs.py,sha256=AiohGTFLjWCb-oTXoNDvPMod4v6RS_ivlieoiqDmtQM,21812
+langgraph_api/api/runs.py,sha256=1RlD4WA8auCNugFjJSgaM9WPnwEHeWsJLEuKpwSRqcU,22089
 langgraph_api/api/store.py,sha256=xGcPFx4v-VxlK6HRU9uCjzCQ0v66cvc3o_PB5_g7n0Q,5550
-langgraph_api/api/threads.py,sha256=Ap5zUcYqK5GJqwEc-q4QY6qCkmbLxfMmEvQZm0MCFxk,10427
+langgraph_api/api/threads.py,sha256=xjeA6eUp4r19YYvqkfe8c3b_u4yIg6jvjq-EmlGu1kI,11150
 langgraph_api/api/ui.py,sha256=_genglTUy5BMHlL0lkQypX524yFv6Z5fraIvnrxp7yE,2639
 langgraph_api/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langgraph_api/auth/custom.py,sha256=psETw_GpLWClBbd_ESVPRLUz9GLQ0_XNsuUDSVbtZy0,22522
@@ -75,9 +75,9 @@ langgraph_api/middleware/http_logger.py,sha256=2LABfhzTAUtqT8nf1ACy8cYXteatkwraB
 langgraph_api/middleware/private_network.py,sha256=eYgdyU8AzU2XJu362i1L8aSFoQRiV7_aLBPw7_EgeqI,2111
 langgraph_api/middleware/request_id.py,sha256=SDj3Yi3WvTbFQ2ewrPQBjAV8sYReOJGeIiuoHeZpR9g,1242
 langgraph_api/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-langgraph_api/models/run.py,sha256=q99y57RqUgZgw5kNkUeezo5E9yazg-4-uxKhJR2agag,15479
+langgraph_api/models/run.py,sha256=jPGWcW9fd1KFoXZTSXMMvc0IiXDXk3yoZ5kjdqxZ1mg,15536
 langgraph_api/tunneling/cloudflare.py,sha256=iKb6tj-VWPlDchHFjuQyep2Dpb-w2NGfJKt-WJG9LH0,3650
-langgraph_api/utils/__init__.py,sha256=kj3uCnO2Md9EEhabm331Tg4Jx9qXcxbACMh2T2P-FYw,5028
+langgraph_api/utils/__init__.py,sha256=yCMq7pOMlmeNmi2Fh8U7KLiljBdOMcF0L2SfpobnKKE,5703
 langgraph_api/utils/cache.py,sha256=SrtIWYibbrNeZzLXLUGBFhJPkMVNQnVxR5giiYGHEfI,1810
 langgraph_api/utils/config.py,sha256=Tbp4tKDSLKXQJ44EKr885wAQupY-9VWNJ6rgUU2oLOY,4162
 langgraph_api/utils/future.py,sha256=lXsRQPhJwY7JUbFFZrK-94JjgsToLu-EWU896hvbUxE,7289
@@ -96,9 +96,9 @@ langgraph_runtime/retry.py,sha256=V0duD01fO7GUQ_btQkp1aoXcEOFhXooGVP6q4yMfuyY,11
 langgraph_runtime/store.py,sha256=7mowndlsIroGHv3NpTSOZDJR0lCuaYMBoTnTrewjslw,114
 LICENSE,sha256=ZPwVR73Biwm3sK6vR54djCrhaRiM4cAD2zvOQZV8Xis,3859
 logging.json,sha256=3RNjSADZmDq38eHePMm1CbP6qZ71AmpBtLwCmKU9Zgo,379
-openapi.json,sha256=h1LbSeGqr2Oor6vO8d3m67XJ1lHhVYVyt2ULvyhf_Ks,160215
-langgraph_api-0.3.4.dist-info/METADATA,sha256=L5VNuwfF9vgK-Pq3KK1AOz1E2_45tosXJlbigcHVd0Q,3890
-langgraph_api-0.3.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-langgraph_api-0.3.4.dist-info/entry_points.txt,sha256=hGedv8n7cgi41PypMfinwS_HfCwA7xJIfS0jAp8htV8,78
-langgraph_api-0.3.4.dist-info/licenses/LICENSE,sha256=ZPwVR73Biwm3sK6vR54djCrhaRiM4cAD2zvOQZV8Xis,3859
-langgraph_api-0.3.4.dist-info/RECORD,,
+openapi.json,sha256=kT_Xi6PAI64jLUalbdh0TtIRy1PfqQBxSu-rbyo_ZyA,162474
+langgraph_api-0.4.0.dist-info/METADATA,sha256=dzjz3DMGzJSLbRmjGY7YJeL336DdeNe1_Cgcy9IYcmg,3890
+langgraph_api-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+langgraph_api-0.4.0.dist-info/entry_points.txt,sha256=hGedv8n7cgi41PypMfinwS_HfCwA7xJIfS0jAp8htV8,78
+langgraph_api-0.4.0.dist-info/licenses/LICENSE,sha256=ZPwVR73Biwm3sK6vR54djCrhaRiM4cAD2zvOQZV8Xis,3859
+langgraph_api-0.4.0.dist-info/RECORD,,

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": [