langgraph-api 0.4.1__py3-none-any.whl → 0.7.3__py3-none-any.whl

langgraph_api/utils/__init__.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from typing import Any, Protocol, TypeAlias, TypeVar, cast
 
 import structlog
+from langchain_core.runnables import RunnableConfig
 from langgraph_sdk import Auth
 from starlette.authentication import AuthCredentials, BaseUser
 from starlette.exceptions import HTTPException
@@ -36,7 +37,7 @@ async def with_user(
     if current is None:
         return
     set_auth_ctx(
-        cast(BaseUser, current.user), AuthCredentials(scopes=current.permissions)
+        cast("BaseUser", current.user), AuthCredentials(scopes=current.permissions)
     )
 
 
@@ -60,6 +61,42 @@ def get_auth_ctx() -> Auth.types.BaseAuthContext | None:
     return AuthContext.get()
 
 
+def get_user_id(user: BaseUser | None) -> str | None:
+    if user is None:
+        return None
+    try:
+        return user.identity
+    except NotImplementedError:
+        try:
+            return user.display_name
+        except NotImplementedError:
+            pass
+
+
+def merge_auth(
+    config: RunnableConfig,
+    ctx: Auth.types.BaseAuthContext | None = None,
+) -> RunnableConfig:
+    """Inject auth context into config's configurable dict.
+
+    If ctx is not provided, attempts to get it from the current context.
+    """
+    if ctx is None:
+        ctx = get_auth_ctx()
+    if ctx is None:
+        return config
+
+    configurable = config.setdefault("configurable", {})
+    return config | {
+        "configurable": configurable
+        | {
+            "langgraph_auth_user": cast("BaseUser | None", ctx.user),
+            "langgraph_auth_user_id": get_user_id(cast("BaseUser | None", ctx.user)),
+            "langgraph_auth_permissions": ctx.permissions,
+        }
+    }
+
+
 class AsyncCursorProto(Protocol):
     async def fetchone(self) -> Row: ...
 
@@ -139,9 +176,17 @@ class SchemaGenerator(BaseSchemaGenerator):
         for endpoint in endpoints_info:
             try:
                 parsed = self.parse_docstring(endpoint.func)
-            except AssertionError:
-                logger.warning("Could not parse docstrings for route %s", endpoint.path)
-                parsed = {}
+            except Exception as exc:
+                docstring = getattr(endpoint.func, "__doc__", None) or ""
+                logger.warning(
+                    "Unable to parse docstring from OpenAPI schema for route %s (%s): %s\n\nUsing as description",
+                    endpoint.path,
+                    endpoint.func.__qualname__,
+                    exc,
+                    exc_info=exc,
+                    docstring=docstring,
+                )
+                parsed = {"description": docstring}
 
             if endpoint.path not in schema["paths"]:
                 schema["paths"][endpoint.path] = {}
@@ -186,14 +231,14 @@ def validate_select_columns(
 
 
 __all__ = [
+    "AsyncConnectionProto",
     "AsyncCursorProto",
     "AsyncPipelineProto",
-    "AsyncConnectionProto",
-    "fetchone",
-    "validate_uuid",
-    "next_cron_date",
     "SchemaGenerator",
+    "fetchone",
     "get_pagination_headers",
+    "next_cron_date",
     "uuid7",
     "validate_select_columns",
+    "validate_uuid",
 ]

langgraph_api/utils/cache.py

@@ -1,18 +1,27 @@
 import asyncio
 import time
 from collections import OrderedDict
+from collections.abc import Awaitable, Callable
 from typing import Generic, TypeVar
 
 T = TypeVar("T")
 
 
 class LRUCache(Generic[T]):
-    """LRU cache with TTL support."""
+    """LRU cache with TTL and proactive refresh support."""
 
-    def __init__(self, max_size: int = 1000, ttl: float = 60):
-        self._cache: OrderedDict[str, tuple[T, float]] = OrderedDict()
+    def __init__(
+        self,
+        max_size: int = 1000,
+        ttl: float = 60,
+        refresh_window: float = 30,
+        refresh_callback: Callable[[str], Awaitable[T | None]] | None = None,
+    ):
+        self._cache: OrderedDict[str, tuple[T, float, bool]] = OrderedDict()
         self._max_size = max_size if max_size > 0 else 1000
         self._ttl = ttl
+        self._refresh_window = refresh_window if refresh_window > 0 else 30
+        self._refresh_callback = refresh_callback
 
     def _get_time(self) -> float:
         """Get current time, using loop.time() if available for better performance."""
@@ -21,17 +30,45 @@ class LRUCache(Generic[T]):
         except RuntimeError:
             return time.monotonic()
 
-    def get(self, key: str) -> T | None:
-        """Get item from cache, returning None if expired or not found."""
+    async def get(self, key: str) -> T | None:
+        """Get item from cache, attempting refresh if within refresh window."""
         if key not in self._cache:
             return None
 
-        value, timestamp = self._cache[key]
-        if self._get_time() - timestamp >= self._ttl:
-            # Expired, remove and return None
+        value, timestamp, is_refreshing = self._cache[key]
+        current_time = self._get_time()
+        time_until_expiry = self._ttl - (current_time - timestamp)
+
+        # Check if expired
+        if time_until_expiry <= 0:
             del self._cache[key]
             return None
 
+        # Check if we should attempt refresh (within refresh window and not already refreshing)
+        if (
+            time_until_expiry <= self._refresh_window
+            and not is_refreshing
+            and self._refresh_callback
+        ):
+            # Mark as refreshing to prevent multiple simultaneous refresh attempts
+            self._cache[key] = (value, timestamp, True)
+
+            try:
+                # Attempt refresh
+                refreshed_value = await self._refresh_callback(key)
+                if refreshed_value is not None:
+                    # Refresh successful, update cache with new value
+                    self._cache[key] = (refreshed_value, current_time, False)
+                    # Move to end (most recently used)
+                    self._cache.move_to_end(key)
+                    return refreshed_value
+                else:
+                    # Refresh failed, fallback to cached value
+                    self._cache[key] = (value, timestamp, False)
+            except Exception:
+                # Refresh failed with exception, fallback to cached value
+                self._cache[key] = (value, timestamp, False)
+
         # Move to end (most recently used)
         self._cache.move_to_end(key)
         return value
@@ -46,8 +83,8 @@ class LRUCache(Generic[T]):
         while len(self._cache) >= self._max_size:
             self._cache.popitem(last=False)  # Remove oldest (FIFO)
 
-        # Add new entry
-        self._cache[key] = (value, self._get_time())
+        # Add new entry (not refreshing initially)
+        self._cache[key] = (value, self._get_time(), False)
 
     def size(self) -> int:
         """Return current cache size."""

langgraph_api/utils/config.py

@@ -4,7 +4,6 @@ import asyncio
 import functools
 import typing
 from collections import ChainMap
-from concurrent.futures import Executor
 from contextvars import copy_context
 from os import getenv
 from typing import Any, ParamSpec, TypeVar
@@ -13,6 +12,8 @@ from langgraph.constants import CONF
 from typing_extensions import TypedDict
 
 if typing.TYPE_CHECKING:
+    from concurrent.futures import Executor
+
     from langchain_core.runnables import RunnableConfig
 
 try:

langgraph_api/utils/errors.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import traceback
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from langgraph_api.graph import GraphSpec
+
+
+class GraphLoadError(RuntimeError):
+    """Raised when a user provided graph fails to load."""
+
+    def __init__(self, spec: GraphSpec, cause: Exception):
+        self.spec = spec
+        self.cause = cause
+        self.location = spec.module or spec.path or "<unknown>"
+        self.notes = tuple(getattr(cause, "__notes__", ()) or ())
+        self._traceback = traceback.TracebackException.from_exception(
+            cause, capture_locals=False
+        )
+        self._exception_only = list(self._traceback.format_exception_only())
+        message = f"Failed to load graph '{spec.id}' from {self.location}: {cause}"
+        super().__init__(message)
+
+    @property
+    def hint(self) -> str | None:
+        if isinstance(self.cause, ImportError):
+            return "Check that your project dependencies are installed and imports are correct."
+        return None
+
+    def log_fields(self) -> dict[str, Any]:
+        fields: dict[str, Any] = {
+            "graph_id": self.spec.id,
+            "location": self.location,
+            "error_type": type(self.cause).__name__,
+            "error_message": self.cause_message,
+            "error_boundary": "user_graph",
+            "summary": self.summary,
+        }
+        if self.hint:
+            fields["hint"] = self.hint
+        if self.notes:
+            fields["notes"] = "\n".join(self.notes)
+        fields["user_traceback"] = self.user_traceback()
+        return fields
+
+    @property
+    def cause_message(self) -> str:
+        if self._exception_only:
+            return self._exception_only[0].strip()
+        return str(self.cause)
+
+    @property
+    def summary(self) -> str:
+        return f"{type(self.cause).__name__}: {self.cause_message}"
+
+    def user_traceback(self) -> str:
+        """Return the full traceback without filtering."""
+        return "".join(self._traceback.format())
+
+
+class HealthServerStartupError(RuntimeError):
+    def __init__(self, host: str, port: int, cause: BaseException):
+        self.host = host
+        self.port = port
+        self.cause = cause
+        port_desc = (
+            f"{host}:{port}" if host not in {"0.0.0.0", "::"} else f"port {port}"
+        )
+        if isinstance(cause, OSError) and cause.errno in {48, 98}:
+            message = (
+                f"Health/metrics server could not bind to {port_desc}: "
+                "address already in use. Stop the other process or set PORT to a free port."
+            )
+        else:
+            message = f"Health/metrics server failed to start on {port_desc}: {cause}"
+        super().__init__(message)

langgraph_api/utils/future.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 
 import asyncio
 import concurrent.futures
-import contextvars
 import inspect
 import sys
 import types
-from collections.abc import Awaitable, Coroutine, Generator
-from typing import TypeVar, cast
+from typing import TYPE_CHECKING, TypeVar, cast
+
+if TYPE_CHECKING:
+    import contextvars
+    from collections.abc import Awaitable, Coroutine, Generator
 
 T = TypeVar("T")
 AnyFuture = asyncio.Future | concurrent.futures.Future
@@ -45,7 +47,8 @@ def _set_concurrent_future_state(
     source: AnyFuture,
 ) -> None:
     """Copy state from a future to a concurrent.futures.Future."""
-    assert source.done()
+    if not source.done():
+        raise ValueError("Future is not done")
     if source.cancelled():
         concurrent.cancel()
     if not concurrent.set_running_or_notify_cancel():
@@ -65,7 +68,8 @@ def _copy_future_state(source: AnyFuture, dest: asyncio.Future) -> None:
     """
     if dest.done():
         return
-    assert source.done()
+    if not source.done():
+        raise ValueError("Future is not done")
     if dest.cancelled():
         return
     if source.cancelled():
@@ -152,7 +156,7 @@ def _ensure_future(
     if not asyncio.iscoroutine(coro_or_future):
         if inspect.isawaitable(coro_or_future):
             coro_or_future = cast(
-                Coroutine[None, None, T], _wrap_awaitable(coro_or_future)
+                "Coroutine[None, None, T]", _wrap_awaitable(coro_or_future)
             )
             called_wrap_awaitable = True
         else:

langgraph_api/utils/headers.py

@@ -2,6 +2,16 @@
 
 import functools
 import re
+import urllib.parse
+from collections.abc import Mapping
+
+import orjson
+
+LANGSMITH_METADATA = "langsmith-metadata"
+LANGSMITH_TAGS = "langsmith-tags"
+LANGSMITH_PROJECT = "langsmith-project"
+# For security, don't include these in configuration
+DEFAULT_RUN_HEADERS_EXCLUDE = {"x-api-key", "x-tenant-id", "x-service-key"}
 
 
 def translate_pattern(pat: str) -> re.Pattern[str]:
@@ -23,6 +33,62 @@ def translate_pattern(pat: str) -> re.Pattern[str]:
     return re.compile(rf"(?s:{pattern})\Z")
 
 
+def get_configurable_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    """Extract headers that should be added to run configuration.
+
+    This function handles special cases like langsmith-trace and baggage headers,
+    while respecting the configurable header patterns.
+    """
+    configurable = {}
+    if not headers:
+        return configurable
+
+    for key, value in headers.items():
+        # First handle tracing stuff - always included regardless of patterns
+        if key == "langsmith-trace":
+            configurable[key] = value
+            if baggage := headers.get("baggage"):
+                for item in baggage.split(","):
+                    baggage_key, baggage_value = item.split("=")
+                    if (
+                        baggage_key == LANGSMITH_METADATA
+                        and baggage_key not in configurable
+                    ):
+                        configurable[baggage_key] = orjson.loads(
+                            urllib.parse.unquote(baggage_value)
+                        )
+                    elif baggage_key == LANGSMITH_TAGS:
+                        configurable[baggage_key] = urllib.parse.unquote(
+                            baggage_value
+                        ).split(",")
+                    elif baggage_key == LANGSMITH_PROJECT:
+                        configurable[baggage_key] = urllib.parse.unquote(baggage_value)
+            continue
+
+        # Check if header should be included based on patterns
+        # For run configuration, we have specific default behavior for x-* headers
+        if key.startswith("x-"):
+            # Check against default excludes for x-* headers
+            if key in DEFAULT_RUN_HEADERS_EXCLUDE:
+                # Check if explicitly included via patterns
+                if should_include_header(key):
+                    configurable[key] = value
+                continue
+            # Other x-* headers are included by default unless patterns exclude them
+            if should_include_header(key):
+                configurable[key] = value
+        elif key == "user-agent":
+            # user-agent is included by default unless excluded by patterns
+            if should_include_header(key):
+                configurable[key] = value
+        else:
+            # All other headers only included if patterns allow
+            if should_include_header(key):
+                configurable[key] = value
+
+    return configurable
+
+
 @functools.lru_cache(maxsize=1)
 def get_header_patterns(
     key: str,
@@ -59,6 +125,14 @@ def should_include_header(key: str) -> bool:
     Returns:
         True if the header should be included, False otherwise
     """
+    if (
+        key == "x-api-key"
+        or key == "x-service-key"
+        or key == "x-tenant-id"
+        or key == "authorization"
+    ):
+        return False
+
     include_patterns, exclude_patterns = get_header_patterns("configurable_headers")
 
     return pattern_matches(key, include_patterns, exclude_patterns)
@@ -85,5 +159,5 @@ def pattern_matches(
         # If include patterns are specified, only include headers matching them
         return any(pattern.match(key) for pattern in include_patterns)
 
-    # Default behavior - include if not excluded
-    return True
+    # Default behavior - exclude
+    return False

langgraph_api/utils/retriable_client.py

@@ -0,0 +1,74 @@
+import asyncio
+
+import httpx
+import structlog
+
+logger = structlog.stdlib.get_logger(__name__)
+
+
+async def _make_http_request_with_retries(
+    url: str,
+    headers: dict,
+    method: str = "GET",
+    json_data: dict | None = None,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+) -> httpx.Response | None:
+    """
+    Make an HTTP request with exponential backoff retries.
+
+    Args:
+        url: The URL to request
+        headers: Headers to include in the request
+        method: HTTP method ("GET" or "POST")
+        json_data: JSON data for POST requests
+        max_retries: Maximum number of retry attempts
+        base_delay: Base delay in seconds for exponential backoff
+
+    Returns:
+        httpx.Response: The successful response
+
+    Raises:
+        httpx.HTTPStatusError: If the request fails after all retries
+        httpx.RequestError: If the request fails after all retries
+    """
+    for attempt in range(max_retries + 1):
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.request(
+                    method, url, headers=headers, json=json_data
+                )
+                response.raise_for_status()
+                return response
+
+        except (
+            httpx.TimeoutException,
+            httpx.NetworkError,
+            httpx.RequestError,
+            httpx.HTTPStatusError,
+        ) as e:
+            if isinstance(e, httpx.HTTPStatusError) and e.response.status_code < 500:
+                # Don't retry on 4xx errors, but do on 5xxs
+                raise e
+
+            # Back off and retry if we haven't reached the max retries
+            if attempt < max_retries:
+                delay = base_delay * (2**attempt)  # Exponential backoff
+                logger.warning(
+                    "HTTP %s request attempt %d to %s failed: %s. Retrying in %.1f seconds...",
+                    method,
+                    attempt + 1,
+                    url,
+                    e,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+            else:
+                logger.exception(
+                    "HTTP %s request to %s failed after %d attempts. Last error: %s",
+                    method,
+                    url,
+                    max_retries + 1,
+                    e,
+                )
+                raise e