langgraph-sdk 0.4.2__tar.gz → 0.4.3__tar.gz

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/.gitignore

@@ -77,6 +77,10 @@ __pypackages__/
 # Environments
 .env
 .envrc
+*.crt
+*.key
+*.pem
+credentials.json
 .venv
 .venvs
 env/
@@ -98,6 +102,7 @@ dmypy.json
 
 .vercel
 .turbo
+node_modules/
 .editorconfig
 .scratch
 .worktrees/

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/MIGRATION.md

@@ -87,7 +87,9 @@ async with client.threads.stream(assistant_id="agent") as thread:
 
 ```python
 async with client.threads.stream(assistant_id="agent") as thread:
-    await thread.run.start(input={"messages": [{"role": "user", "content": "book a flight"}]})
+    await thread.run.start(
+        input={"messages": [{"role": "user", "content": "book a flight"}]}
+    )
 
     # Wait for the run to pause at an interrupt node.
     # thread.interrupted becomes True when input.requested arrives.

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/Makefile

@@ -9,7 +9,6 @@ test:
 
 # Define a variable for Python and notebook files.
 PYTHON_FILES=.
-MYPY_CACHE=.mypy_cache
 lint format: PYTHON_FILES=.
 lint_diff format_diff: PYTHON_FILES=$(shell git diff --name-only --relative --diff-filter=d main . | grep -E '\.py$$|\.ipynb$$')
 

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: langgraph-sdk
-Version: 0.4.2
+Version: 0.4.3
 Summary: SDK for interacting with LangGraph API
 Project-URL: Source, https://github.com/langchain-ai/langgraph/tree/main/libs/sdk-py
 Project-URL: Twitter, https://x.com/langchain_oss
@@ -13,23 +13,36 @@ Requires-Dist: httpx>=0.25.2
 Requires-Dist: langchain-core<2,>=1.4.0
 Requires-Dist: langchain-protocol>=0.0.15
 Requires-Dist: orjson>=3.11.5
-Requires-Dist: websockets<16,>=14
+Requires-Dist: websockets<17,>=14
 Description-Content-Type: text/markdown
 
 # LangGraph Python SDK
 
-This repository contains the Python SDK for interacting with the LangSmith Deployment REST API.
+[![PyPI - Version](https://img.shields.io/pypi/v/langgraph-sdk?label=%20)](https://pypi.org/project/langgraph-sdk/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langgraph-sdk)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langgraph-sdk)](https://pypistats.org/packages/langgraph-sdk)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/langchain_oss.svg?style=social&label=Follow%20%40LangChain)](https://x.com/langchain_oss)
 
-## Quick Start
+To help you ship LangGraph apps to production faster, check out [LangSmith](https://www.langchain.com/langsmith).
+[LangSmith](https://www.langchain.com/langsmith) is a unified developer platform for building, testing, and monitoring LLM applications.
 
-To get started with the Python SDK, [install the package](https://pypi.org/project/langgraph-sdk/)
+## Quick Install
 
 ```bash
-pip install -U langgraph-sdk
+uv add langgraph-sdk
 ```
 
-You will need a running LangGraph API server. If you're running a server locally using `langgraph-cli`, SDK will automatically point at `http://localhost:8123`, otherwise
-you would need to specify the server URL when creating a client.
+## 🤔 What is this?
+
+This library provides the Python SDK for interacting with the LangGraph API. Use it to connect to a running LangGraph API server, manage assistants and threads, and stream runs from Python applications.
+
+You will need a running LangGraph API server. If you're running a server locally using `langgraph-cli`, the SDK will automatically point at `http://localhost:8123`; otherwise, specify the server URL when creating a client.
+
+## 📖 Documentation
+
+For full documentation, see the [API reference](https://reference.langchain.com/python/langgraph-sdk/). For conceptual guides and tutorials, see the [LangGraph Docs](https://docs.langchain.com/oss/python/langgraph/overview).
+
+## Quick Start
 
 ```python
 from langgraph_sdk import get_client
@@ -48,7 +61,9 @@ thread = await client.threads.create()
 
 # Start a streaming run
 input = {"messages": [{"role": "human", "content": "what's the weather in la"}]}
-async for chunk in client.runs.stream(thread['thread_id'], agent['assistant_id'], input=input):
+async for chunk in client.runs.stream(
+    thread["thread_id"], agent["assistant_id"], input=input
+):
     print(chunk)
 ```
 
@@ -61,9 +76,7 @@ async for chunk in client.runs.stream(thread['thread_id'], agent['assistant_id']
 
 ## Thread-Centric Streaming (v3)
 
-`client.threads.stream()` returns a context manager that owns the SSE session for one
-thread. Typed projections — values snapshots, message streams, tool calls, custom
-events — all share the same underlying connection.
+`client.threads.stream()` returns a context manager that owns the SSE session for one thread. Typed projections — values snapshots, message streams, tool calls, custom events — all share the same underlying connection.
 
 ```python
 from langgraph_sdk import get_client
@@ -87,7 +100,17 @@ async with client.threads.stream(
     messages, tool_calls = await asyncio.gather(get_messages(), get_tool_calls())
 
     for stream in messages:
-        print(await stream.text)          # accumulated text
+        print(await stream.text)  # accumulated text
 
-    final = await thread.output           # terminal state values
+    final = await thread.output  # terminal state values
 ```
+
+## 📕 Releases & Versioning
+
+See our [Releases](https://docs.langchain.com/oss/python/release-policy) and [Versioning](https://docs.langchain.com/oss/python/versioning) policies.
+
+## 💁 Contributing
+
+As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
+
+For detailed information on how to contribute, see the [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview).

langgraph_sdk-0.4.3/README.md

@@ -0,0 +1,98 @@
+# LangGraph Python SDK
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langgraph-sdk?label=%20)](https://pypi.org/project/langgraph-sdk/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langgraph-sdk)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langgraph-sdk)](https://pypistats.org/packages/langgraph-sdk)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/langchain_oss.svg?style=social&label=Follow%20%40LangChain)](https://x.com/langchain_oss)
+
+To help you ship LangGraph apps to production faster, check out [LangSmith](https://www.langchain.com/langsmith).
+[LangSmith](https://www.langchain.com/langsmith) is a unified developer platform for building, testing, and monitoring LLM applications.
+
+## Quick Install
+
+```bash
+uv add langgraph-sdk
+```
+
+## 🤔 What is this?
+
+This library provides the Python SDK for interacting with the LangGraph API. Use it to connect to a running LangGraph API server, manage assistants and threads, and stream runs from Python applications.
+
+You will need a running LangGraph API server. If you're running a server locally using `langgraph-cli`, the SDK will automatically point at `http://localhost:8123`; otherwise, specify the server URL when creating a client.
+
+## 📖 Documentation
+
+For full documentation, see the [API reference](https://reference.langchain.com/python/langgraph-sdk/). For conceptual guides and tutorials, see the [LangGraph Docs](https://docs.langchain.com/oss/python/langgraph/overview).
+
+## Quick Start
+
+```python
+from langgraph_sdk import get_client
+
+# If you're using a remote server, initialize the client with `get_client(url=REMOTE_URL)`
+client = get_client()
+
+# List all assistants
+assistants = await client.assistants.search()
+
+# We auto-create an assistant for each graph you register in config.
+agent = assistants[0]
+
+# Start a new thread
+thread = await client.threads.create()
+
+# Start a streaming run
+input = {"messages": [{"role": "human", "content": "what's the weather in la"}]}
+async for chunk in client.runs.stream(
+    thread["thread_id"], agent["assistant_id"], input=input
+):
+    print(chunk)
+```
+
+## Known Limitations
+
+- **WebSocket transport** requires `websockets>=14` and is only available on the async client (`AsyncThreadStream`). The sync client (`SyncThreadStream`) uses SSE exclusively.
+- **`thread.extensions[name]`** opens a new subscription each time the same name is accessed. Assign the projection to a variable and reuse it within a single session rather than re-indexing across multiple iterations.
+- **Sync streaming** drives the lifecycle watcher in a background thread. Long-lived sync sessions will hold that thread open until the context manager exits.
+- **Reconnect attempts** are limited to 5 by default for both the shared SSE fan-out and the lifecycle watcher. Persistent network partitions will surface as `RuntimeError` on in-flight projections.
+
+## Thread-Centric Streaming (v3)
+
+`client.threads.stream()` returns a context manager that owns the SSE session for one thread. Typed projections — values snapshots, message streams, tool calls, custom events — all share the same underlying connection.
+
+```python
+from langgraph_sdk import get_client
+import asyncio
+
+client = get_client()
+
+async with client.threads.stream(
+    thread_id="my-thread",
+    assistant_id="agent",
+) as thread:
+    await thread.run.start(input={"messages": [{"role": "user", "content": "hi"}]})
+
+    # Start all consumers concurrently so they share one SSE connection.
+    async def get_messages():
+        return [s async for s in thread.messages]
+
+    async def get_tool_calls():
+        return [c async for c in thread.tool_calls]
+
+    messages, tool_calls = await asyncio.gather(get_messages(), get_tool_calls())
+
+    for stream in messages:
+        print(await stream.text)  # accumulated text
+
+    final = await thread.output  # terminal state values
+```
+
+## 📕 Releases & Versioning
+
+See our [Releases](https://docs.langchain.com/oss/python/release-policy) and [Versioning](https://docs.langchain.com/oss/python/versioning) policies.
+
+## 💁 Contributing
+
+As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
+
+For detailed information on how to contribute, see the [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview).

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/integration/Dockerfile

@@ -22,6 +22,19 @@ RUN pip install --no-cache-dir \
     "langchain>=1.3.0" \
     "deepagents>=0.6.2"
 
+# Swap the published langgraph *core* for this monorepo's local copy, so the
+# server executes the langgraph under test rather than the latest release.
+# We keep the rest of the base image (langgraph-api, runtime, Go core server)
+# on `latest` — that still surfaces upstream regressions — but the core the
+# server runs is now the PR's, which is what lets this suite catch core
+# regressions (e.g. ensure_config / runtime changes) before they're published.
+# `--no-deps` keeps the base image's already-compatible
+# checkpoint/prebuilt/sdk; we only replace core. The local source comes from
+# the `langgraph_src` additional build context (see docker-compose.yml).
+COPY --from=langgraph_src pyproject.toml README.md LICENSE /opt/langgraph-src/
+COPY --from=langgraph_src langgraph /opt/langgraph-src/langgraph/
+RUN pip install --no-cache-dir --force-reinstall --no-deps /opt/langgraph-src
+
 # Project graphs + registration config.
 COPY graph/ /app/graph/
 COPY langgraph.json /app/langgraph.json

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/integration/docker-compose.yml

@@ -36,11 +36,18 @@ services:
   api:
     # Thin layer on top of langchain/langgraph-api:latest-py3.12 —
     # see ./Dockerfile. The base image bundles langgraph-api +
-    # langgraph_runtime_postgres + langgraph_license + the Go core-server,
-    # so we only add graph deps (deepagents) and the graph files on top.
+    # langgraph_runtime_postgres + langgraph_license + the Go core-server;
+    # on top we add graph deps (deepagents), the graph files, and this
+    # monorepo's local langgraph *core* (so the server runs the code under
+    # test, not the released langgraph).
     build:
       context: .
       dockerfile: Dockerfile
+      additional_contexts:
+        # The monorepo's local langgraph core (libs/langgraph), installed over
+        # the base image so the server runs the langgraph under test. See the
+        # Dockerfile for why.
+        langgraph_src: ../../langgraph
     image: langgraph-v3-integration-api:local
     depends_on:
       postgres:
@@ -70,7 +77,7 @@ services:
       # Tell langgraph-api which graphs to register. The langgraph CLI sets
       # this from langgraph.json; we're bypassing the CLI (running uvicorn
       # directly) so we set it manually.
-      LANGSERVE_GRAPHS: '{"agent":"/app/graph/streaming_graph.py:graph","tools_agent":"/app/graph/tools_agent.py:graph","deep_agent":"/app/graph/deep_agent.py:graph"}'
+      LANGSERVE_GRAPHS: '{"agent":"/app/graph/streaming_graph.py:graph","tools_agent":"/app/graph/tools_agent.py:graph","deep_agent":"/app/graph/deep_agent.py:graph","factory_agent":"/app/graph/factory_graph.py:make_graph"}'
 
       # The published langgraph-api image is the `licensed` variant and
       # requires a real LANGSMITH_API_KEY (or LANGGRAPH_CLOUD_LICENSE_KEY)

langgraph_sdk-0.4.3/integration/graph/factory_graph.py

@@ -0,0 +1,70 @@
+"""Integration fixture: a graph *factory* (not a pre-compiled graph).
+
+Registered as `factory_agent`. The other integration graphs are all
+pre-compiled objects, so this is the only fixture that drives the server's
+graph-factory code path on a run. That path is where langgraph-api seeds a
+`ServerRuntime` into the run config; executing a run against this graph is the
+end-to-end regression guard for the langgraph 1.2.3 `ensure_config`
+configurable-merge surfacing a leaked `__pregel_runtime`
+(`AttributeError: '_ExecutionRuntime' object has no attribute 'control'`).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from langgraph.graph.state import END, CompiledStateGraph, StateGraph
+from langgraph.store.base import BaseStore
+from typing_extensions import TypedDict
+
+if TYPE_CHECKING:
+    from langgraph.types import RunnableConfig
+
+    from langgraph_sdk.runtime import ServerRuntime
+
+
+class State(TypedDict, total=False):
+    text: str
+    access_context: str
+    is_for_execution: bool
+
+
+async def make_graph(
+    config: RunnableConfig, runtime: ServerRuntime
+) -> CompiledStateGraph:
+    """2-arg factory (config + runtime) returning a compiled echo graph.
+
+    Validates that the server injected a real `ServerRuntime`, then builds a
+    one-node graph whose output echoes the input and reports the runtime's
+    access context (so the test can confirm the factory ran under execution).
+    """
+    from langgraph_sdk.runtime import (
+        _ExecutionRuntime,
+        _ReadRuntime,
+    )
+
+    # `if/raise` rather than `assert` so the contract holds under `python -O`.
+    if not isinstance(runtime, (_ExecutionRuntime, _ReadRuntime)):
+        raise TypeError(
+            f"factory must receive a ServerRuntime, got {type(runtime).__name__}"
+        )
+    if not isinstance(runtime.store, BaseStore):
+        raise TypeError(
+            f"runtime.store must be a BaseStore, got {type(runtime.store).__name__}"
+        )
+
+    access_context = runtime.access_context
+    is_for_execution = runtime.execution_runtime is not None
+
+    def echo(state: State) -> State:
+        return {
+            "text": (state.get("text") or "") + " echoed",
+            "access_context": access_context,
+            "is_for_execution": is_for_execution,
+        }
+
+    workflow = StateGraph(State)
+    workflow.add_node("echo", echo)
+    workflow.set_entry_point("echo")
+    workflow.add_edge("echo", END)
+    return workflow.compile()

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/integration/langgraph.json

@@ -4,7 +4,8 @@
   "graphs": {
     "agent": "./graph/streaming_graph.py:graph",
     "tools_agent": "./graph/tools_agent.py:graph",
-    "deep_agent": "./graph/deep_agent.py:graph"
+    "deep_agent": "./graph/deep_agent.py:graph",
+    "factory_agent": "./graph/factory_graph.py:make_graph"
   },
   "env": {}
 }

langgraph_sdk-0.4.3/langgraph_sdk/__init__.py

@@ -0,0 +1,15 @@
+from langgraph_sdk.auth import Auth
+from langgraph_sdk.client import get_client, get_sync_client
+from langgraph_sdk.encryption import Encryption
+from langgraph_sdk.encryption.types import DecryptResult, EncryptionContext
+
+__version__ = "0.4.3"
+
+__all__ = [
+    "Auth",
+    "DecryptResult",
+    "Encryption",
+    "EncryptionContext",
+    "get_client",
+    "get_sync_client",
+]

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/langgraph_sdk/_async/cron.py

@@ -8,7 +8,11 @@ from datetime import datetime, tzinfo
 from typing import Any
 
 from langgraph_sdk._async.http import HttpClient
-from langgraph_sdk._shared.utilities import _quote_path_param, _resolve_timezone
+from langgraph_sdk._shared.utilities import (
+    NOT_PROVIDED,
+    _quote_path_param,
+    _resolve_timezone,
+)
 from langgraph_sdk.schema import (
     All,
     Config,
@@ -324,7 +328,7 @@ class CronClient:
         cron_id: str,
         *,
         schedule: str | None = None,
-        end_time: datetime | None = None,
+        end_time: datetime | None = NOT_PROVIDED,
         input: Input | None = None,
         metadata: Mapping[str, Any] | None = None,
         config: Config | None = None,
@@ -348,7 +352,8 @@ class CronClient:
             cron_id: The cron ID to update.
             schedule: The cron schedule to execute this job on.
                 Schedules are interpreted in UTC unless a timezone is specified.
-            end_time: The end date to stop running the cron.
+            end_time: The end date to stop running the cron. Pass ``None`` to
+                clear a previously set end time; omit to leave it unchanged.
             input: The input to the graph.
             metadata: Metadata to assign to the cron job runs.
             config: The configuration for the assistant.
@@ -386,7 +391,6 @@ class CronClient:
         """
         payload = {
             "schedule": schedule,
-            "end_time": end_time.isoformat() if end_time else None,
             "input": input,
             "metadata": metadata,
             "config": config,
@@ -403,6 +407,10 @@ class CronClient:
             "durability": durability,
         }
         payload = {k: v for k, v in payload.items() if v is not None}
+        # An explicit end_time=None clears the end time; NOT_PROVIDED leaves it
+        # unchanged. Inject after the None-strip so the explicit null survives.
+        if end_time is not NOT_PROVIDED:
+            payload["end_time"] = end_time.isoformat() if end_time is not None else None
         return await self.http.patch(
             f"/runs/crons/{_quote_path_param(cron_id)}",
             json=payload,

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/langgraph_sdk/_sync/cron.py

@@ -7,7 +7,11 @@ from collections.abc import Mapping, Sequence
 from datetime import datetime, tzinfo
 from typing import Any
 
-from langgraph_sdk._shared.utilities import _quote_path_param, _resolve_timezone
+from langgraph_sdk._shared.utilities import (
+    NOT_PROVIDED,
+    _quote_path_param,
+    _resolve_timezone,
+)
 from langgraph_sdk._sync.http import SyncHttpClient
 from langgraph_sdk.schema import (
     All,
@@ -313,7 +317,7 @@ class SyncCronClient:
         cron_id: str,
         *,
         schedule: str | None = None,
-        end_time: datetime | None = None,
+        end_time: datetime | None = NOT_PROVIDED,
         input: Input | None = None,
         metadata: Mapping[str, Any] | None = None,
         config: Config | None = None,
@@ -337,7 +341,8 @@ class SyncCronClient:
             cron_id: The cron ID to update.
             schedule: The cron schedule to execute this job on.
                 Schedules are interpreted in UTC unless a timezone is specified.
-            end_time: The end date to stop running the cron.
+            end_time: The end date to stop running the cron. Pass ``None`` to
+                clear a previously set end time; omit to leave it unchanged.
             input: The input to the graph.
             metadata: Metadata to assign to the cron job runs.
             config: The configuration for the assistant.
@@ -375,7 +380,6 @@ class SyncCronClient:
         """
         payload = {
             "schedule": schedule,
-            "end_time": end_time.isoformat() if end_time else None,
             "input": input,
             "metadata": metadata,
             "config": config,
@@ -392,6 +396,10 @@ class SyncCronClient:
             "durability": durability,
         }
         payload = {k: v for k, v in payload.items() if v is not None}
+        # An explicit end_time=None clears the end time; NOT_PROVIDED leaves it
+        # unchanged. Inject after the None-strip so the explicit null survives.
+        if end_time is not NOT_PROVIDED:
+            payload["end_time"] = end_time.isoformat() if end_time is not None else None
         return self.http.patch(
             f"/runs/crons/{_quote_path_param(cron_id)}",
             json=payload,

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/langgraph_sdk/auth/__init__.py

@@ -867,9 +867,8 @@ def _validate_handler(fn: Callable[..., typing.Any]) -> None:
 def is_studio_user(
     user: types.MinimalUser | types.BaseUser | types.MinimalUserDict,
 ) -> bool:
-    return (
-        isinstance(user, types.StudioUser)
-        or (isinstance(user, dict) and user.get("kind") == "StudioUser")  # ty: ignore[invalid-argument-type]
+    return isinstance(user, types.StudioUser) or (
+        isinstance(user, dict) and user.get("kind") == "StudioUser"
     )
 
 

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/langgraph_sdk/encryption/__init__.py

@@ -18,6 +18,9 @@ import warnings
 
 from langgraph_sdk.encryption import types
 
+_BlobDecryptorT = typing.TypeVar("_BlobDecryptorT", bound=types.BlobDecryptor)
+_JsonDecryptorT = typing.TypeVar("_JsonDecryptorT", bound=types.JsonDecryptor)
+
 
 class LangGraphBetaWarning(UserWarning):
     """Warning for beta features in LangGraph SDK."""
@@ -141,7 +144,7 @@ class _DecryptDecorators:
     def __init__(self, parent: Encryption):
         self._parent = parent
 
-    def blob(self, fn: types.BlobDecryptor) -> types.BlobDecryptor:
+    def blob(self, fn: _BlobDecryptorT) -> _BlobDecryptorT:
         """Register a blob decryption handler.
 
         The handler will be called to decrypt opaque data like checkpoint blobs.
@@ -149,7 +152,9 @@ class _DecryptDecorators:
         Example:
             ```python
             @encryption.decrypt.blob
-            async def decrypt_blob(ctx: EncryptionContext, blob: bytes) -> bytes:
+            async def decrypt_blob(
+                ctx: EncryptionContext, blob: bytes
+            ) -> bytes | DecryptResult[bytes]:
                 # Decrypt the blob using your encryption service
                 return decrypted_blob
             ```
@@ -170,13 +175,15 @@ class _DecryptDecorators:
         self._parent._blob_decryptor = fn
         return fn
 
-    def json(self, fn: types.JsonDecryptor) -> types.JsonDecryptor:
+    def json(self, fn: _JsonDecryptorT) -> _JsonDecryptorT:
         """Register the JSON decryption handler.
 
         Example:
             ```python
             @encryption.decrypt.json
-            async def decrypt_json(ctx: EncryptionContext, data: dict) -> dict:
+            async def decrypt_json(
+                ctx: EncryptionContext, data: dict
+            ) -> dict | DecryptResult[dict]:
                 # Decrypt the data
                 return decrypt_data(data)
             ```
@@ -369,7 +376,7 @@ class Encryption:
     """Reference to encryption type definitions.
 
     Provides access to all type definitions used in the encryption system,
-    including EncryptionContext, BlobEncryptor, BlobDecryptor,
+    including EncryptionContext, DecryptResult, BlobEncryptor, BlobDecryptor,
     JsonEncryptor, and JsonDecryptor.
     """
 

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/langgraph_sdk/encryption/types.py

@@ -9,10 +9,30 @@ from __future__ import annotations
 
 import typing
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 
 Json = dict[str, typing.Any]
 """JSON-serializable dictionary type for structured data encryption."""
 
+T = typing.TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class DecryptResult(typing.Generic[T]):
+    """Decrypted data and optional replacement ciphertext.
+
+    Return this from a decrypt handler when encrypted data should be replaced,
+    such as after rotating its encryption key. Returning plaintext directly
+    remains supported when no replacement is needed.
+
+    Attributes:
+        plaintext: Decrypted data returned to the caller
+        replacement: New encrypted data to persist in place of the input
+    """
+
+    plaintext: T
+    replacement: T | None = None
+
 
 class EncryptionContext:
     """Context passed to encryption/decryption handlers.
@@ -57,7 +77,9 @@ Returns:
     Awaitable that resolves to encrypted bytes
 """
 
-BlobDecryptor = Callable[[EncryptionContext, bytes], Awaitable[bytes]]
+BlobDecryptor = Callable[
+    [EncryptionContext, bytes], Awaitable[bytes | DecryptResult[bytes]]
+]
 """Handler for decrypting opaque blob data like checkpoints.
 
 Note: Must be an async function. Decryption typically involves I/O operations
@@ -68,7 +90,8 @@ Args:
     blob: The encrypted bytes to decrypt
 
 Returns:
-    Awaitable that resolves to decrypted bytes
+    Awaitable that resolves to decrypted bytes, or a DecryptResult containing
+    decrypted bytes and replacement ciphertext
 """
 
 JsonEncryptor = Callable[[EncryptionContext, Json], Awaitable[Json]]
@@ -101,7 +124,9 @@ Returns:
     Awaitable that resolves to encrypted JSON dictionary
 """
 
-JsonDecryptor = Callable[[EncryptionContext, Json], Awaitable[Json]]
+JsonDecryptor = Callable[
+    [EncryptionContext, Json], Awaitable[Json | DecryptResult[Json]]
+]
 """Handler for decrypting structured JSON data.
 
 Note: Must be an async function. Decryption typically involves I/O operations
@@ -115,7 +140,8 @@ Args:
     data: The encrypted JSON dictionary
 
 Returns:
-    Awaitable that resolves to decrypted JSON dictionary
+    Awaitable that resolves to a decrypted JSON dictionary, or a DecryptResult
+    containing decrypted JSON and replacement ciphertext
 """
 
 if typing.TYPE_CHECKING:

{langgraph_sdk-0.4.2 → langgraph_sdk-0.4.3}/langgraph_sdk/schema.py

@@ -963,7 +963,7 @@ class _BaseModelLike(Protocol):
     ) -> dict[str, Any]: ...
 
 
-_JSONLike: TypeAlias = None | str | int | float | bool
+_JSONLike: TypeAlias = str | int | float | bool | None
 _JSONMap: TypeAlias = Mapping[
     str, Union[_JSONLike, list[_JSONLike], "_JSONMap", list["_JSONMap"]]
 ]