langgraph-sdk 0.2.3__tar.gz → 0.2.5__tar.gz

{langgraph_sdk-0.2.3 → langgraph_sdk-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-sdk
-Version: 0.2.3
+Version: 0.2.5
 Summary: SDK for interacting with LangGraph API
 Project-URL: Repository, https://www.github.com/langchain-ai/langgraph
 License-Expression: MIT

{langgraph_sdk-0.2.3 → langgraph_sdk-0.2.5}/langgraph_sdk/__init__.py

@@ -1,6 +1,6 @@
 from langgraph_sdk.auth import Auth
 from langgraph_sdk.client import get_client, get_sync_client
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 __all__ = ["Auth", "get_client", "get_sync_client"]

{langgraph_sdk-0.2.3 → langgraph_sdk-0.2.5}/langgraph_sdk/auth/types.py

@@ -489,6 +489,9 @@ class ThreadsSearch(typing.TypedDict, total=False):
     offset: int
     """Offset for pagination."""
 
+    ids: Sequence[UUID] | None
+    """typing.Optional list of thread IDs to filter by."""
+
     thread_id: UUID | None
     """typing.Optional thread ID to filter by."""
 

{langgraph_sdk-0.2.3 → langgraph_sdk-0.2.5}/langgraph_sdk/client.py

@@ -15,6 +15,7 @@ import logging
 import os
 import re
 import sys
+import warnings
 from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
 from types import TracebackType
 from typing import (
@@ -45,6 +46,7 @@ from langgraph_sdk.schema import (
     CronSelectField,
     CronSortBy,
     DisconnectMode,
+    Durability,
     GraphSchema,
     IfNotExists,
     Item,
@@ -69,6 +71,7 @@ from langgraph_sdk.schema import (
     ThreadSortBy,
     ThreadState,
     ThreadStatus,
+    ThreadStreamMode,
     ThreadUpdateStateResponse,
 )
 from langgraph_sdk.sse import SSEDecoder, aiter_lines_raw, iter_lines_raw
@@ -1306,6 +1309,7 @@ class ThreadsClient:
         *,
         metadata: Json = None,
         values: Json = None,
+        ids: Sequence[str] | None = None,
         status: ThreadStatus | None = None,
         limit: int = 10,
         offset: int = 0,
@@ -1320,6 +1324,7 @@ class ThreadsClient:
         Args:
             metadata: Thread metadata to filter on.
             values: State values to filter on.
+            ids: List of thread IDs to filter by.
             status: Thread status to filter on.
                 Must be one of 'idle', 'busy', 'interrupted' or 'error'.
             limit: Limit on number of threads to return.
@@ -1353,6 +1358,8 @@ class ThreadsClient:
             payload["metadata"] = metadata
         if values:
             payload["values"] = values
+        if ids:
+            payload["ids"] = ids
         if status:
             payload["status"] = status
         if sort_by:
@@ -1682,6 +1689,53 @@ class ThreadsClient:
             params=params,
         )
 
+    async def join_stream(
+        self,
+        thread_id: str,
+        *,
+        last_event_id: str | None = None,
+        stream_mode: ThreadStreamMode | Sequence[ThreadStreamMode] = "run_modes",
+        headers: Mapping[str, str] | None = None,
+        params: QueryParamTypes | None = None,
+    ) -> AsyncIterator[StreamPart]:
+        """Get a stream of events for a thread.
+
+        Args:
+            thread_id: The ID of the thread to get the stream for.
+            last_event_id: The ID of the last event to get.
+            headers: Optional custom headers to include with the request.
+            params: Optional query parameters to include with the request.
+
+        Returns:
+            Iterator[StreamPart]: An iterator of stream parts.
+
+        ???+ example "Example Usage"
+
+            ```python
+
+            for chunk in client.threads.join_stream(
+                thread_id="my_thread_id",
+                last_event_id="my_event_id",
+            ):
+                print(chunk)
+            ```
+
+        """  # noqa: E501
+        query_params = {
+            "stream_mode": stream_mode,
+        }
+        if params:
+            query_params.update(params)
+        return self.http.stream(
+            f"/threads/{thread_id}/stream",
+            "GET",
+            headers={
+                **({"Last-Event-ID": last_event_id} if last_event_id else {}),
+                **(headers or {}),
+            },
+            params=query_params,
+        )
+
 
 class RunsClient:
     """Client for managing runs in LangGraph.
@@ -1772,7 +1826,7 @@ class RunsClient:
         context: Context | None = None,
         checkpoint: Checkpoint | None = None,
         checkpoint_id: str | None = None,
-        checkpoint_during: bool | None = None,
+        checkpoint_during: bool | None = None,  # deprecated
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         feedback_keys: Sequence[str] | None = None,
@@ -1785,6 +1839,7 @@ class RunsClient:
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
         on_run_created: Callable[[RunCreateMetadata], None] | None = None,
+        durability: Durability | None = None,
     ) -> AsyncIterator[StreamPart]:
         """Create a run and stream the results.
 
@@ -1804,7 +1859,7 @@ class RunsClient:
             context: Static context to add to the assistant.
                 !!! version-added "Supported with langgraph>=0.6.0"
             checkpoint: The checkpoint to resume from.
-            checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption).
+            checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption).
             interrupt_before: Nodes to interrupt immediately before they get executed.
             interrupt_after: Nodes to Nodes to interrupt immediately after they get executed.
             feedback_keys: Feedback keys to assign to run.
@@ -1822,6 +1877,10 @@ class RunsClient:
             headers: Optional custom headers to include with the request.
             params: Optional query parameters to include with the request.
             on_run_created: Callback when a run is created.
+            durability: The durability to use for the run. Values are "sync", "async", or "exit".
+                "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True
+                "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False
+                "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps
 
         Returns:
             AsyncIterator[StreamPart]: Asynchronous iterator of stream results.
@@ -1857,6 +1916,13 @@ class RunsClient:
             ```
 
         """  # noqa: E501
+        if checkpoint_during is not None:
+            warnings.warn(
+                "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         payload = {
             "input": input,
             "command": (
@@ -1881,6 +1947,7 @@ class RunsClient:
             "on_disconnect": on_disconnect,
             "on_completion": on_completion,
             "after_seconds": after_seconds,
+            "durability": durability,
         }
         endpoint = (
             f"/threads/{thread_id}/runs/stream"
@@ -1971,7 +2038,7 @@ class RunsClient:
         context: Context | None = None,
         checkpoint: Checkpoint | None = None,
         checkpoint_id: str | None = None,
-        checkpoint_during: bool | None = None,
+        checkpoint_during: bool | None = None,  # deprecated
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         webhook: str | None = None,
@@ -1982,6 +2049,7 @@ class RunsClient:
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
         on_run_created: Callable[[RunCreateMetadata], None] | None = None,
+        durability: Durability | None = None,
     ) -> Run:
         """Create a background run.
 
@@ -2001,7 +2069,7 @@ class RunsClient:
             context: Static context to add to the assistant.
                 !!! version-added "Supported with langgraph>=0.6.0"
             checkpoint: The checkpoint to resume from.
-            checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption).
+            checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption).
             interrupt_before: Nodes to interrupt immediately before they get executed.
             interrupt_after: Nodes to Nodes to interrupt immediately after they get executed.
             webhook: Webhook to call after LangGraph API call is done.
@@ -2015,6 +2083,10 @@ class RunsClient:
                 Use to schedule future runs.
             headers: Optional custom headers to include with the request.
             on_run_created: Optional callback to call when a run is created.
+            durability: The durability to use for the run. Values are "sync", "async", or "exit".
+                "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True
+                "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False
+                "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps
 
         Returns:
             Run: The created background run.
@@ -2090,6 +2162,12 @@ class RunsClient:
             }
             ```
         """  # noqa: E501
+        if checkpoint_during is not None:
+            warnings.warn(
+                "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         payload = {
             "input": input,
             "command": (
@@ -2112,6 +2190,7 @@ class RunsClient:
             "if_not_exists": if_not_exists,
             "on_completion": on_completion,
             "after_seconds": after_seconds,
+            "durability": durability,
         }
         payload = {k: v for k, v in payload.items() if v is not None}
 
@@ -2209,7 +2288,7 @@ class RunsClient:
         context: Context | None = None,
         checkpoint: Checkpoint | None = None,
         checkpoint_id: str | None = None,
-        checkpoint_during: bool | None = None,
+        checkpoint_during: bool | None = None,  # deprecated
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         webhook: str | None = None,
@@ -2222,6 +2301,7 @@ class RunsClient:
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
         on_run_created: Callable[[RunCreateMetadata], None] | None = None,
+        durability: Durability | None = None,
     ) -> list[dict] | dict[str, Any]:
         """Create a run, wait until it finishes and return the final state.
 
@@ -2237,7 +2317,7 @@ class RunsClient:
             context: Static context to add to the assistant.
                 !!! version-added "Supported with langgraph>=0.6.0"
             checkpoint: The checkpoint to resume from.
-            checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption).
+            checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption).
             interrupt_before: Nodes to interrupt immediately before they get executed.
             interrupt_after: Nodes to Nodes to interrupt immediately after they get executed.
             webhook: Webhook to call after LangGraph API call is done.
@@ -2253,6 +2333,10 @@ class RunsClient:
                 Use to schedule future runs.
             headers: Optional custom headers to include with the request.
             on_run_created: Optional callback to call when a run is created.
+            durability: The durability to use for the run. Values are "sync", "async", or "exit".
+                "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True
+                "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False
+                "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps
 
         Returns:
             Union[list[dict], dict[str, Any]]: The output of the run.
@@ -2306,6 +2390,12 @@ class RunsClient:
             ```
 
         """  # noqa: E501
+        if checkpoint_during is not None:
+            warnings.warn(
+                "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         payload = {
             "input": input,
             "command": (
@@ -2326,6 +2416,7 @@ class RunsClient:
             "on_disconnect": on_disconnect,
             "on_completion": on_completion,
             "after_seconds": after_seconds,
+            "durability": durability,
         }
         endpoint = (
             f"/threads/{thread_id}/runs/wait" if thread_id is not None else "/runs/wait"
@@ -4367,6 +4458,7 @@ class SyncThreadsClient:
         *,
         metadata: Json = None,
         values: Json = None,
+        ids: Sequence[str] | None = None,
         status: ThreadStatus | None = None,
         limit: int = 10,
         offset: int = 0,
@@ -4381,6 +4473,7 @@ class SyncThreadsClient:
         Args:
             metadata: Thread metadata to filter on.
             values: State values to filter on.
+            ids: List of thread IDs to filter by.
             status: Thread status to filter on.
                 Must be one of 'idle', 'busy', 'interrupted' or 'error'.
             limit: Limit on number of threads to return.
@@ -4410,6 +4503,8 @@ class SyncThreadsClient:
             payload["metadata"] = metadata
         if values:
             payload["values"] = values
+        if ids:
+            payload["ids"] = ids
         if status:
             payload["status"] = status
         if sort_by:
@@ -4733,6 +4828,54 @@ class SyncThreadsClient:
             params=params,
         )
 
+    def join_stream(
+        self,
+        thread_id: str,
+        *,
+        stream_mode: ThreadStreamMode | Sequence[ThreadStreamMode] = "run_modes",
+        last_event_id: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        params: QueryParamTypes | None = None,
+    ) -> Iterator[StreamPart]:
+        """Get a stream of events for a thread.
+
+        Args:
+            thread_id: The ID of the thread to get the stream for.
+            last_event_id: The ID of the last event to get.
+            headers: Optional custom headers to include with the request.
+            params: Optional query parameters to include with the request.
+
+        Returns:
+            Iterator[StreamPart]: An iterator of stream parts.
+
+        ???+ example "Example Usage"
+
+            ```python
+
+            for chunk in client.threads.join_stream(
+                thread_id="my_thread_id",
+                last_event_id="my_event_id",
+                stream_mode="run_modes",
+            ):
+                print(chunk)
+            ```
+
+        """  # noqa: E501
+        query_params = {
+            "stream_mode": stream_mode,
+        }
+        if params:
+            query_params.update(params)
+        return self.http.stream(
+            f"/threads/{thread_id}/stream",
+            "GET",
+            headers={
+                **({"Last-Event-ID": last_event_id} if last_event_id else {}),
+                **(headers or {}),
+            },
+            params=query_params,
+        )
+
 
 class SyncRunsClient:
     """Synchronous client for managing runs in LangGraph.
@@ -4823,7 +4966,7 @@ class SyncRunsClient:
         context: Context | None = None,
         checkpoint: Checkpoint | None = None,
         checkpoint_id: str | None = None,
-        checkpoint_during: bool | None = None,
+        checkpoint_during: bool | None = None,  # deprecated
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         feedback_keys: Sequence[str] | None = None,
@@ -4836,6 +4979,7 @@ class SyncRunsClient:
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
         on_run_created: Callable[[RunCreateMetadata], None] | None = None,
+        durability: Durability | None = None,
     ) -> Iterator[StreamPart]:
         """Create a run and stream the results.
 
@@ -4855,7 +4999,7 @@ class SyncRunsClient:
             context: Static context to add to the assistant.
                 !!! version-added "Supported with langgraph>=0.6.0"
             checkpoint: The checkpoint to resume from.
-            checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption).
+            checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption).
             interrupt_before: Nodes to interrupt immediately before they get executed.
             interrupt_after: Nodes to Nodes to interrupt immediately after they get executed.
             feedback_keys: Feedback keys to assign to run.
@@ -4872,6 +5016,11 @@ class SyncRunsClient:
                 Use to schedule future runs.
             headers: Optional custom headers to include with the request.
             on_run_created: Optional callback to call when a run is created.
+            durability: The durability to use for the run. Values are "sync", "async", or "exit".
+                "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True
+                "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False
+                "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps
+
 
         Returns:
             Iterator[StreamPart]: Iterator of stream results.
@@ -4904,6 +5053,12 @@ class SyncRunsClient:
             StreamPart(event='end', data=None)
             ```
         """  # noqa: E501
+        if checkpoint_during is not None:
+            warnings.warn(
+                "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         payload = {
             "input": input,
             "command": (
@@ -4928,6 +5083,7 @@ class SyncRunsClient:
             "on_disconnect": on_disconnect,
             "on_completion": on_completion,
             "after_seconds": after_seconds,
+            "durability": durability,
         }
         endpoint = (
             f"/threads/{thread_id}/runs/stream"
@@ -5018,7 +5174,7 @@ class SyncRunsClient:
         context: Context | None = None,
         checkpoint: Checkpoint | None = None,
         checkpoint_id: str | None = None,
-        checkpoint_during: bool | None = None,
+        checkpoint_during: bool | None = None,  # deprecated
         interrupt_before: All | Sequence[str] | None = None,
         interrupt_after: All | Sequence[str] | None = None,
         webhook: str | None = None,
@@ -5029,6 +5185,7 @@ class SyncRunsClient:
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
         on_run_created: Callable[[RunCreateMetadata], None] | None = None,
+        durability: Durability | None = None,
     ) -> Run:
         """Create a background run.
 
@@ -5048,7 +5205,7 @@ class SyncRunsClient:
             context: Static context to add to the assistant.
                 !!! version-added "Supported with langgraph>=0.6.0"
             checkpoint: The checkpoint to resume from.
-            checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption).
+            checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption).
             interrupt_before: Nodes to interrupt immediately before they get executed.
             interrupt_after: Nodes to Nodes to interrupt immediately after they get executed.
             webhook: Webhook to call after LangGraph API call is done.
@@ -5062,6 +5219,10 @@ class SyncRunsClient:
                 Use to schedule future runs.
             headers: Optional custom headers to include with the request.
             on_run_created: Optional callback to call when a run is created.
+            durability: The durability to use for the run. Values are "sync", "async", or "exit".
+                "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True
+                "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False
+                "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps
 
         Returns:
             Run: The created background run.
@@ -5137,6 +5298,12 @@ class SyncRunsClient:
             }
             ```
         """  # noqa: E501
+        if checkpoint_during is not None:
+            warnings.warn(
+                "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         payload = {
             "input": input,
             "command": (
@@ -5159,6 +5326,7 @@ class SyncRunsClient:
             "if_not_exists": if_not_exists,
             "on_completion": on_completion,
             "after_seconds": after_seconds,
+            "durability": durability,
         }
         payload = {k: v for k, v in payload.items() if v is not None}
 
@@ -5254,7 +5422,7 @@ class SyncRunsClient:
         metadata: Mapping[str, Any] | None = None,
         config: Config | None = None,
         context: Context | None = None,
-        checkpoint_during: bool | None = None,
+        checkpoint_during: bool | None = None,  # deprecated
         checkpoint: Checkpoint | None = None,
         checkpoint_id: str | None = None,
         interrupt_before: All | Sequence[str] | None = None,
@@ -5269,6 +5437,7 @@ class SyncRunsClient:
         headers: Mapping[str, str] | None = None,
         params: QueryParamTypes | None = None,
         on_run_created: Callable[[RunCreateMetadata], None] | None = None,
+        durability: Durability | None = None,
     ) -> list[dict] | dict[str, Any]:
         """Create a run, wait until it finishes and return the final state.
 
@@ -5284,7 +5453,7 @@ class SyncRunsClient:
             context: Static context to add to the assistant.
                 !!! version-added "Supported with langgraph>=0.6.0"
             checkpoint: The checkpoint to resume from.
-            checkpoint_during: Whether to checkpoint during the run (or only at the end/interruption).
+            checkpoint_during: (deprecated) Whether to checkpoint during the run (or only at the end/interruption).
             interrupt_before: Nodes to interrupt immediately before they get executed.
             interrupt_after: Nodes to Nodes to interrupt immediately after they get executed.
             webhook: Webhook to call after LangGraph API call is done.
@@ -5301,6 +5470,10 @@ class SyncRunsClient:
             raise_error: Whether to raise an error if the run fails.
             headers: Optional custom headers to include with the request.
             on_run_created: Optional callback to call when a run is created.
+            durability: The durability to use for the run. Values are "sync", "async", or "exit".
+                "async" means checkpoints are persisted async while next graph step executes, replaces checkpoint_during=True
+                "sync" means checkpoints are persisted sync after graph step executes, replaces checkpoint_during=False
+                "exit" means checkpoints are only persisted when the run exits, does not save intermediate steps
 
         Returns:
             Union[list[dict], dict[str, Any]]: The output of the run.
@@ -5355,6 +5528,12 @@ class SyncRunsClient:
             ```
 
         """  # noqa: E501
+        if checkpoint_during is not None:
+            warnings.warn(
+                "`checkpoint_during` is deprecated and will be removed in a future version. Use `durability` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         payload = {
             "input": input,
             "command": (
@@ -5376,6 +5555,7 @@ class SyncRunsClient:
             "on_completion": on_completion,
             "after_seconds": after_seconds,
             "raise_error": raise_error,
+            "durability": durability,
         }
 
         def on_response(res: httpx.Response):

{langgraph_sdk-0.2.3 → langgraph_sdk-0.2.5}/langgraph_sdk/schema.py

@@ -38,6 +38,14 @@ Represents the status of a thread:
 - "error": An exception occurred during task processing.
 """
 
+ThreadStreamMode = Literal["run_modes", "lifecycle", "state_update"]
+"""
+Defines the mode of streaming:
+- "run_modes": Stream the same events as the runs on thread, as well as run_done events.
+- "lifecycle": Stream only run start/end events.
+- "state_update": Stream state updates on the thread.
+"""
+
 StreamMode = Literal[
     "values",
     "messages",
@@ -91,6 +99,12 @@ Defines action after completion:
 - "keep": Retain resources after completion.
 """
 
+Durability = Literal["sync", "async", "exit"]
+"""Durability mode for the graph execution.
+- `"sync"`: Changes are persisted synchronously before the next step starts.
+- `"async"`: Changes are persisted asynchronously while the next step executes.
+- `"exit"`: Changes are persisted only when the graph exits."""
+
 All = Literal["*"]
 """Represents a wildcard or 'all' selector."""