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

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

@@ -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.4.0/langgraph_api/__init__.py

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

{langgraph_api-0.3.4 → 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.4 → 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.4 → 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.4 → langgraph_api-0.4.0}/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-0.3.4 → 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.4 → 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.4 → 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.4/langgraph_api/__init__.py

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