release(sdk-py): 0.3.12 (langchain-ai#7224)

Release Note: Impllemnets alpha support for server-side SWR w/ the cache

Author: hinthornw

libs/sdk-py/langgraph_sdk/__init__.py

@@ -3,6 +3,6 @@
 from langgraph_sdk.encryption import Encryption
 from langgraph_sdk.encryption.types import EncryptionContext
 
-__version__ = "0.3.11"
+__version__ = "0.3.12"
 
 __all__ = ["Auth", "Encryption", "EncryptionContext", "get_client", "get_sync_client"]

libs/sdk-py/langgraph_sdk/cache.py

@@ -7,8 +7,13 @@
 
 from __future__ import annotations
 
+from collections.abc import Awaitable, Callable
 from datetime import timedelta
-from typing import Any
+from typing import Any, Generic, Literal, TypeVar
+
+T = TypeVar("T")
+
+CacheStatus = Literal["miss", "fresh", "stale", "expired"]
 
 try:
     from langgraph_api.cache import (  # type: ignore[unresolved-import]
@@ -22,9 +27,29 @@
     _cache_set = None
 
 
+try:
+    from langgraph_api.cache import SWRResult  # type: ignore[unresolved-import]
+    from langgraph_api.cache import swr as _api_swr  # type: ignore[unresolved-import]
+
+except ImportError:
+    _api_swr = None
+
+    class SWRResult(Generic[T]):
+        """Result wrapper returned by :func:`swr`."""
+
+        value: T
+        status: CacheStatus
+
+        async def mutate(self, value: T = ...) -> T:  # type: ignore[assignment]
+            """Update or revalidate the cached value."""
+            ...
+
+
 __all__ = [
+    "SWRResult",
     "cache_get",
     "cache_set",
+    "swr",
 ]
 
 
@@ -60,3 +85,56 @@ async def cache_set(key: str, value: Any, *, ttl: timedelta | None = None) -> No
             "(https://docs.langchain.com/langsmith/deployments)."
         )
     await _cache_set(key, value, ttl)
+
+
+async def swr(
+    key: str,
+    loader: Callable[[], Awaitable[T]],
+    *,
+    fresh_for: timedelta | None = None,
+    max_age: timedelta | None = None,
+    model: type[T] | None = None,
+) -> SWRResult[T]:
+    """Load a cached value using stale-while-revalidate semantics.
+
+    This helper is server-side only and is intended for caching internal async
+    dependencies such as auth or metadata lookups.
+
+    Args:
+        key: Cache key.
+        loader: Async callable that fetches the value on miss/revalidation.
+        fresh_for: How long a cached value is considered fresh (no revalidation).
+            Defaults to ``timedelta(0)`` so every access triggers a background
+            revalidate while still returning the cached value instantly. Values
+            above :data:`MAX_CACHE_TTL` are clamped to the backend maximum.
+        max_age: Total lifetime of a cached entry. After this, the next access
+            blocks on the loader. Defaults to :data:`MAX_CACHE_TTL` (24 h by
+            default). Values above :data:`MAX_CACHE_TTL` are clamped to the
+            backend maximum.
+        model: Optional Pydantic model class. When provided, values are
+            serialized via ``model_dump(mode="json")`` before storage and
+            deserialized via ``model.model_validate()`` on read.
+
+    Returns:
+        An :class:`SWRResult` with ``.value``, ``.status``, and an async
+        ``.mutate()`` method.
+
+    Semantics:
+    - cache miss: await ``loader()``, store the value, return it
+    - fresh hit (age < fresh_for): return the cached value
+    - stale hit (fresh_for <= age < max_age): return the cached value
+      immediately and trigger a best-effort background refresh
+    - expired (age >= max_age): await ``loader()``, store the value, return it
+    """
+    if _api_swr is None:
+        raise RuntimeError(
+            "Cache is only available server-side within the LangGraph Agent Server "
+            "(https://docs.langchain.com/langsmith/deployments)."
+        )
+    if fresh_for is None:
+        fresh_for = timedelta(0)
+    if max_age is None:
+        max_age = timedelta(days=1)
+    return await _api_swr(
+        key, loader, fresh_for=fresh_for, max_age=max_age, model=model
+    )

libs/sdk-py/tests/test_cache.py

@@ -0,0 +1,69 @@
+from datetime import timedelta
+from unittest.mock import AsyncMock
+
+import pytest
+
+import langgraph_sdk.cache as cache_module
+
+
+@pytest.mark.asyncio
+async def test_swr_proxies_to_server_impl(monkeypatch):
+    loader = AsyncMock(return_value={"ok": True})
+    forwarded = {}
+
+    async def fake_swr(key, inner_loader, *, fresh_for, max_age, model):
+        forwarded["key"] = key
+        forwarded["fresh_for"] = fresh_for
+        forwarded["max_age"] = max_age
+        forwarded["model"] = model
+        return await inner_loader()
+
+    monkeypatch.setattr(cache_module, "_api_swr", fake_swr)
+
+    result = await cache_module.swr(
+        "test-key",
+        loader,
+        fresh_for=timedelta(seconds=1),
+        max_age=timedelta(seconds=10),
+    )
+
+    assert result == {"ok": True}
+    assert forwarded == {
+        "key": "test-key",
+        "fresh_for": timedelta(seconds=1),
+        "max_age": timedelta(seconds=10),
+        "model": None,
+    }
+    loader.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_swr_requires_server_runtime(monkeypatch):
+    monkeypatch.setattr(cache_module, "_api_swr", None)
+
+    with pytest.raises(RuntimeError, match="Cache is only available server-side"):
+        await cache_module.swr(
+            "test-key",
+            AsyncMock(return_value="unused"),
+            fresh_for=timedelta(seconds=1),
+            max_age=timedelta(seconds=10),
+        )
+
+
+@pytest.mark.asyncio
+async def test_swr_defaults(monkeypatch):
+    """fresh_for defaults to 0, max_age defaults to 1 day."""
+    loader = AsyncMock(return_value="val")
+    forwarded = {}
+
+    async def fake_swr(_key, inner_loader, *, fresh_for, max_age, model):  # noqa: ARG001
+        forwarded["fresh_for"] = fresh_for
+        forwarded["max_age"] = max_age
+        return await inner_loader()
+
+    monkeypatch.setattr(cache_module, "_api_swr", fake_swr)
+
+    await cache_module.swr("k", loader)
+
+    assert forwarded["fresh_for"] == timedelta(0)
+    assert forwarded["max_age"] == timedelta(days=1)