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

langgraph_api/schema.py

@@ -16,7 +16,15 @@ RunStatus = Literal["pending", "running", "error", "success", "timeout", "interr
 ThreadStatus = Literal["idle", "busy", "interrupted", "error"]
 
 StreamMode = Literal[
-    "values", "messages", "updates", "events", "debug", "tasks", "checkpoints", "custom"
+    "values",
+    "messages",
+    "updates",
+    "events",
+    "debug",
+    "tasks",
+    "checkpoints",
+    "custom",
+    "messages-tuple",
 ]
 
 ThreadStreamMode = Literal["lifecycle", "run_modes", "state_update"]
@@ -50,10 +58,16 @@ class Config(TypedDict, total=False):
     """
     Runtime values for attributes previously made configurable on this Runnable,
     or sub-Runnables, through .configurable_fields() or .configurable_alternatives().
-    Check .output_schema() for a description of the attributes that have been made 
+    Check .output_schema() for a description of the attributes that have been made
     configurable.
     """
 
+    __encryption_context__: dict[str, Any]
+    """
+    Internal: Encryption context for encryption/decryption operations.
+    Not exposed to users.
+    """
+
 
 class Checkpoint(TypedDict):
     thread_id: str
@@ -112,6 +126,17 @@ class DeprecatedInterrupt(TypedDict, total=False):
     """When the interrupt occurred, always "during"."""
 
 
+class ThreadTTLInfo(TypedDict, total=False):
+    """TTL information for a thread. Only present when ?include=ttl is passed."""
+
+    strategy: Literal["delete", "keep_latest"]
+    """The TTL strategy."""
+    ttl_minutes: float
+    """The TTL in minutes."""
+    expires_at: datetime
+    """When the thread will expire."""
+
+
 class Thread(TypedDict):
     thread_id: UUID
     """The ID of the thread."""
@@ -123,14 +148,14 @@ class Thread(TypedDict):
     """The thread metadata."""
     config: Fragment
     """The thread config."""
-    context: Fragment
-    """The thread context."""
     status: ThreadStatus
     """The status of the thread. One of 'idle', 'busy', 'interrupted', "error"."""
     values: Fragment
     """The current state of the thread."""
     interrupts: dict[str, list[Interrupt]]
     """The current interrupts of the thread, a map of task_id to list of interrupts."""
+    ttl: NotRequired[ThreadTTLInfo]
+    """TTL information if set for this thread. Only present when ?include=ttl is passed."""
 
 
 class ThreadTask(TypedDict):
@@ -148,7 +173,7 @@ class ThreadState(TypedDict):
     next: Sequence[str]
     """The name of the node to execute in each task for this step."""
     checkpoint: Checkpoint
-    """The checkpoint keys. This object can be passed to the /threads and /runs 
+    """The checkpoint keys. This object can be passed to the /threads and /runs
     endpoints to resume execution or update state."""
     metadata: Fragment
     """Metadata for this state"""
@@ -220,6 +245,8 @@ class Cron(TypedDict):
     """The ID of the assistant."""
     thread_id: UUID | None
     """The ID of the thread."""
+    on_run_completed: NotRequired[Literal["delete", "keep"] | None]
+    """What to do with the thread after the run completes."""
     end_time: datetime | None
     """The end date to stop running the cron."""
     schedule: str
@@ -249,8 +276,9 @@ class ThreadUpdateResponse(TypedDict):
 class QueueStats(TypedDict):
     n_pending: int
     n_running: int
-    max_age_secs: datetime | None
-    med_age_secs: datetime | None
+    pending_runs_wait_time_max_secs: float | None
+    pending_runs_wait_time_med_secs: float | None
+    pending_unblocked_runs_wait_time_max_secs: float | None
 
 
 # Canonical field sets for select= validation and type aliases for ops
@@ -277,7 +305,6 @@ ThreadSelectField = Literal[
     "updated_at",
     "metadata",
     "config",
-    "context",
     "status",
     "values",
     "interrupts",
@@ -303,6 +330,7 @@ CronSelectField = Literal[
     "cron_id",
     "assistant_id",
     "thread_id",
+    "on_run_completed",
     "end_time",
     "schedule",
     "created_at",
@@ -311,6 +339,53 @@ CronSelectField = Literal[
     "payload",
     "next_run_date",
     "metadata",
-    "now",
 ]
 CRON_FIELDS: set[str] = set(CronSelectField.__args__)  # type: ignore[attr-defined]
+
+# Encryption field constants
+# These define which fields are encrypted for each model type.
+#
+# Note: Checkpoint encryption (checkpoint, metadata columns in checkpoints table, plus
+# blob data in checkpoint_blobs and checkpoint_writes) is handled directly by the
+# Checkpointer class in storage_postgres/langgraph_runtime_postgres/checkpoint.py.
+# The checkpointer uses encrypt_json_if_needed/decrypt_json_if_needed directly rather
+# than the field list pattern used by the API middleware. This is because checkpoints
+# are only accessed via the checkpointer's internal methods (aget_tuple, aput, etc.),
+# not through generic API CRUD operations.
+
+THREAD_ENCRYPTION_FIELDS = ["metadata", "config", "values", "interrupts", "error"]
+
+# kwargs is a nested blob - its subfields are decrypted automatically by the middleware
+RUN_ENCRYPTION_FIELDS = ["metadata", "kwargs"]
+
+ASSISTANT_ENCRYPTION_FIELDS = ["metadata", "config", "context"]
+
+# payload is a nested blob - its subfields are decrypted automatically by the middleware
+CRON_ENCRYPTION_FIELDS = ["metadata", "payload"]
+
+# Store encryption - only the value field contains user data
+STORE_ENCRYPTION_FIELDS = ["value"]
+
+# The middleware automatically decrypts these subfields when decrypting the parent field.
+# This is recursive: if a subfield is also in NESTED_ENCRYPTED_SUBFIELDS, its subfields
+# are decrypted too (e.g., run.kwargs.config.configurable).
+NESTED_ENCRYPTED_SUBFIELDS: dict[tuple[str, str], list[str]] = {
+    ("run", "kwargs"): ["input", "config", "context", "command"],
+    ("run", "config"): ["configurable", "metadata"],
+    ("cron", "payload"): ["metadata", "context", "input", "config"],
+    ("cron", "config"): ["configurable", "metadata"],
+    ("assistant", "config"): ["configurable"],
+}
+
+# Convenience alias for cron payload subfields.
+#
+# This is a reflection of an unfortunate asymmetry in cron's data model.
+#
+# The cron API requests have payload fields (metadata, input, config, context) at the
+# top level, but at rest they're nested inside the `payload` JSONB column (with
+# metadata also duplicated as a top-level column). This alias is used to encrypt
+# those fields in the flat request before storage.
+CRON_PAYLOAD_ENCRYPTION_SUBFIELDS = NESTED_ENCRYPTED_SUBFIELDS[("cron", "payload")]
+
+# Convenience alias for run kwargs subfields, used by the worker for decryption.
+RUN_KWARGS_ENCRYPTION_SUBFIELDS = NESTED_ENCRYPTED_SUBFIELDS[("run", "kwargs")]

langgraph_api/self_hosted_logs.py

@@ -20,7 +20,7 @@ _customer_attributes = {}
 
 # see https://github.com/open-telemetry/opentelemetry-python/issues/3649 for why we need this
 class AttrFilteredLoggingHandler(LoggingHandler):
-    DROP_ATTRIBUTES = ["_logger"]
+    DROP_ATTRIBUTES = ("_logger",)
 
     @staticmethod
     def _get_attributes(record: logging.LogRecord) -> Attributes:
@@ -32,7 +32,7 @@ class AttrFilteredLoggingHandler(LoggingHandler):
         }
         if _customer_attributes:
             attributes.update(_customer_attributes)
-        return cast(Attributes, attributes)
+        return cast("Attributes", attributes)
 
 
 def initialize_self_hosted_logs() -> None:

langgraph_api/self_hosted_metrics.py

@@ -12,11 +12,15 @@ from opentelemetry.sdk.resources import SERVICE_NAME, Resource
 
 from langgraph_api import asyncio as lg_asyncio
 from langgraph_api import config, metadata
+from langgraph_api.feature_flags import FF_USE_CORE_API
+from langgraph_api.grpc.ops import Runs as GrpcRuns
 from langgraph_api.http_metrics_utils import HTTP_LATENCY_BUCKETS
 from langgraph_runtime.database import connect, pool_stats
 from langgraph_runtime.metrics import get_metrics
 from langgraph_runtime.ops import Runs
 
+CrudRuns = GrpcRuns if FF_USE_CORE_API else Runs
+
 logger = structlog.stdlib.get_logger(__name__)
 
 _meter_provider = None
@@ -109,6 +113,27 @@ def initialize_self_hosted_metrics():
             callbacks=[_get_running_runs_callback],
         )
 
+        meter.create_observable_gauge(
+            name="lg_api_pending_runs_wait_time_max",
+            description="The maximum time a run has been pending, in seconds",
+            unit="s",
+            callbacks=[_get_pending_runs_wait_time_max_callback],
+        )
+
+        meter.create_observable_gauge(
+            name="lg_api_pending_runs_wait_time_med",
+            description="The median pending wait time across runs, in seconds",
+            unit="s",
+            callbacks=[_get_pending_runs_wait_time_med_callback],
+        )
+
+        meter.create_observable_gauge(
+            name="lg_api_pending_unblocked_runs_wait_time_max",
+            description="The maximum time a run has been pending excluding runs blocked by another run on the same thread, in seconds",
+            unit="s",
+            callbacks=[_get_pending_unblocked_runs_wait_time_max_callback],
+        )
+
         if config.N_JOBS_PER_WORKER > 0:
             meter.create_observable_gauge(
                 name="lg_api_workers_max",
@@ -229,17 +254,29 @@ def _get_queue_stats():
     async def _fetch_queue_stats():
         try:
             async with connect() as conn:
-                return await Runs.stats(conn)
+                return await CrudRuns.stats(conn)
         except Exception as e:
             logger.warning("Failed to get queue stats from database", exc_info=e)
-            return {"n_pending": 0, "n_running": 0}
+            return {
+                "n_pending": 0,
+                "n_running": 0,
+                "pending_runs_wait_time_max_secs": 0,
+                "pending_runs_wait_time_med_secs": 0,
+                "pending_unblocked_runs_wait_time_max_secs": 0,
+            }
 
     try:
         future = lg_asyncio.run_coroutine_threadsafe(_fetch_queue_stats())
         return future.result(timeout=5)
     except Exception as e:
         logger.warning("Failed to get queue stats", exc_info=e)
-        return {"n_pending": 0, "n_running": 0}
+        return {
+            "n_pending": 0,
+            "n_running": 0,
+            "pending_runs_wait_time_max_secs": 0,
+            "pending_runs_wait_time_med_secs": 0,
+            "pending_unblocked_runs_wait_time_max_secs": 0,
+        }
 
 
 def _get_pool_stats():
@@ -280,6 +317,39 @@ def _get_running_runs_callback(options: CallbackOptions):
         return [Observation(0, attributes=_customer_attributes)]
 
 
+def _get_pending_runs_wait_time_max_callback(options: CallbackOptions):
+    try:
+        stats = _get_queue_stats()
+        value = stats.get("pending_runs_wait_time_max_secs")
+        value = 0 if value is None else value
+        return [Observation(value, attributes=_customer_attributes)]
+    except Exception as e:
+        logger.warning("Failed to get max pending wait time", exc_info=e)
+        return [Observation(0, attributes=_customer_attributes)]
+
+
+def _get_pending_runs_wait_time_med_callback(options: CallbackOptions):
+    try:
+        stats = _get_queue_stats()
+        value = stats.get("pending_runs_wait_time_med_secs")
+        value = 0 if value is None else value
+        return [Observation(value, attributes=_customer_attributes)]
+    except Exception as e:
+        logger.warning("Failed to get median pending wait time", exc_info=e)
+        return [Observation(0, attributes=_customer_attributes)]
+
+
+def _get_pending_unblocked_runs_wait_time_max_callback(options: CallbackOptions):
+    try:
+        stats = _get_queue_stats()
+        value = stats.get("pending_unblocked_runs_wait_time_max_secs")
+        value = 0 if value is None else value
+        return [Observation(value, attributes=_customer_attributes)]
+    except Exception as e:
+        logger.warning("Failed to get max unblocked pending wait time", exc_info=e)
+        return [Observation(0, attributes=_customer_attributes)]
+
+
 def _get_workers_max_callback(options: CallbackOptions):
     try:
         metrics_data = get_metrics()

langgraph_api/serde.py

@@ -54,7 +54,7 @@ def decimal_encoder(dec_value: Decimal) -> int | float:
         # maps to float('nan') / float('inf') / float('-inf')
         not dec_value.is_finite()
         # or regular float
-        or cast(int, dec_value.as_tuple().exponent) < 0
+        or cast("int", dec_value.as_tuple().exponent) < 0
     ):
         return float(dec_value)
     return int(dec_value)
@@ -79,15 +79,15 @@ def default(obj):
         return obj._asdict()
     elif isinstance(obj, BaseException):
         return {"error": type(obj).__name__, "message": str(obj)}
-    elif isinstance(obj, (set, frozenset, deque)):  # noqa: UP038
+    elif isinstance(obj, (set, frozenset, deque)):
         return list(obj)
-    elif isinstance(obj, (timezone, ZoneInfo)):  # noqa: UP038
+    elif isinstance(obj, (timezone, ZoneInfo)):
         return obj.tzname(None)
     elif isinstance(obj, timedelta):
         return obj.total_seconds()
     elif isinstance(obj, Decimal):
         return decimal_encoder(obj)
-    elif isinstance(  # noqa: UP038
+    elif isinstance(
         obj,
         (
             uuid.UUID,
@@ -160,6 +160,18 @@ def json_loads(content: bytes | Fragment | dict) -> Any:
     return orjson.loads(content)
 
 
+def json_dumpb_optional(obj: Any | None) -> bytes | None:
+    if obj is None:
+        return
+    return json_dumpb(obj)
+
+
+def json_loads_optional(content: bytes | None) -> Any | None:
+    if content is None:
+        return
+    return json_loads(content)
+
+
 # Do not use. orjson holds the GIL the entire time it's running anyway.
 async def ajson_loads(content: bytes | Fragment) -> Any:
     return await asyncio.to_thread(json_loads, content)

langgraph_api/server.py

@@ -1,29 +1,28 @@
 # MONKEY PATCH: Patch Starlette to fix an error in the library
-# ruff: noqa: E402
-import langgraph_api.patch  # noqa: F401,I001
-import sys
-import os
-
 # WARNING: Keep the import above before other code runs as it
 # patches an error in the Starlette library.
+import langgraph_api.patch  # noqa: F401,I001
+import langgraph_api.timing as timing
 import logging
+import os
+import sys
 import typing
 
 if not (
     (disable_truststore := os.getenv("DISABLE_TRUSTSTORE"))
     and disable_truststore.lower() == "true"
 ):
-    import truststore  # noqa: F401
+    import truststore
 
-    truststore.inject_into_ssl()  # noqa: F401
+    truststore.inject_into_ssl()
 
-from contextlib import asynccontextmanager
 
 import jsonschema_rs
 import structlog
 from langgraph.errors import EmptyInputError, InvalidUpdateError
 from langgraph_sdk.client import configure_loopback_transports
 from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
 from starlette.middleware import Middleware
 from starlette.middleware.cors import CORSMiddleware
 from starlette.routing import BaseRoute, Mount
@@ -39,6 +38,7 @@ from langgraph_api.api import (
 )
 from langgraph_api.api.openapi import set_custom_spec
 from langgraph_api.errors import (
+    http_exception_handler,
     overloaded_error_handler,
     validation_error_handler,
     value_error_handler,
@@ -96,6 +96,7 @@ global_middleware.extend(
     ]
 )
 exception_handlers = {
+    HTTPException: http_exception_handler,
     ValueError: value_error_handler,
     InvalidUpdateError: value_error_handler,
     EmptyInputError: value_error_handler,
@@ -223,16 +224,7 @@ if user_router:
             f"Cannot merge lifespans with on_startup or on_shutdown: {app.router.on_startup} {app.router.on_shutdown}"
         )
 
-    @asynccontextmanager
-    async def combined_lifespan(app):
-        async with lifespan(app):
-            if user_lifespan:
-                async with user_lifespan(app):
-                    yield
-            else:
-                yield
-
-    app.router.lifespan_context = combined_lifespan
+    app.router.lifespan_context = timing.combine_lifespans(lifespan, user_lifespan)
 
     # Merge exception handlers (base + user)
     for k, v in exception_handlers.items():
@@ -240,24 +232,30 @@ if user_router:
             app.exception_handlers[k] = v
         else:
             logger.debug(f"Overriding exception handler for {k}")
-    # If the user creates a loopback client with `get_client() (no url)
-    # this will update the http transport to connect to the right app
-    configure_loopback_transports(app)
 else:
     # It's a regular starlette app
     app = Starlette(
-        routes=apply_middleware(
-            unshadowable_meta_routes + shadowable_meta_routes,
-            route_level_custom_middleware,
-        )
-        + [protected_mount],
-        lifespan=lifespan,
+        routes=[
+            *apply_middleware(
+                unshadowable_meta_routes + shadowable_meta_routes,
+                route_level_custom_middleware,
+            ),
+            protected_mount,
+        ],
+        lifespan=timing.combine_lifespans(lifespan),
         middleware=global_middleware,
         exception_handlers=exception_handlers,
     )
 
+# If the user creates a loopback client with `get_client() (no url)
+# this will update the http transport to connect to the right app
+configure_loopback_transports(app)
 
 if config.MOUNT_PREFIX:
+    from starlette.routing import Route
+
+    from langgraph_api.api import meta_metrics, ok
+
     prefix = config.MOUNT_PREFIX
     if not prefix.startswith("/") or prefix.endswith("/"):
         raise ValueError(
@@ -265,8 +263,6 @@ if config.MOUNT_PREFIX:
             f"Valid examples: '/my-api', '/v1', '/api/v1'.\nInvalid examples: 'api/', '/api/'"
         )
     logger.info(f"Mounting routes at prefix: {prefix}")
-    plen = len(prefix)
-    rplen = len(prefix.encode("utf-8"))
 
     class ASGIBypassMiddleware:
         def __init__(self, app: typing.Any, **kwargs):
@@ -284,9 +280,15 @@ if config.MOUNT_PREFIX:
 
             return await self.app(scope, receive, send)
 
+    # Add health checks at root still to avoid having to override health checks.
     app = Starlette(
-        routes=[Mount(prefix, app=app)],
+        routes=[
+            Route("/", ok, methods=["GET"]),
+            Route("/ok", ok, methods=["GET"]),
+            Route("/metrics", meta_metrics, methods=["GET"]),
+            Mount(prefix, app=app),
+        ],
         lifespan=app.router.lifespan_context,
-        middleware=[Middleware(ASGIBypassMiddleware)] + app.user_middleware,
+        middleware=[Middleware(ASGIBypassMiddleware)],
         exception_handlers=app.exception_handlers,
     )

langgraph_api/state.py

@@ -6,12 +6,13 @@ from langgraph.types import Interrupt, StateSnapshot
 
 from langgraph_api.feature_flags import USE_NEW_INTERRUPTS
 from langgraph_api.js.base import RemoteInterrupt
-from langgraph_api.schema import Checkpoint, DeprecatedInterrupt, ThreadState
-from langgraph_api.schema import Interrupt as InterruptSchema
 
 if typing.TYPE_CHECKING:
     from langchain_core.runnables.config import RunnableConfig
 
+    from langgraph_api.schema import Checkpoint, DeprecatedInterrupt, ThreadState
+    from langgraph_api.schema import Interrupt as InterruptSchema
+
 
 def runnable_config_to_checkpoint(
     config: RunnableConfig | None,

langgraph_api/store.py

@@ -12,7 +12,8 @@ from langgraph.graph import StateGraph
 from langgraph.pregel import Pregel
 from langgraph.store.base import BaseStore
 
-from langgraph_api import config
+from langgraph_api import config, timing
+from langgraph_api.timing import profiled_import
 from langgraph_api.utils.config import run_in_executor
 
 logger = structlog.stdlib.get_logger(__name__)
@@ -83,22 +84,30 @@ async def collect_store_from_env() -> None:
     CUSTOM_STORE = value
 
 
+@timing.timer(
+    message="Loading store {store_path}",
+    metadata_fn=lambda store_path: {"store_path": store_path},
+    warn_threshold_secs=5,
+    warn_message="Loading store '{store_path}' took longer than expected",
+    error_threshold_secs=10,
+)
 def _load_store(store_path: str) -> Any:
-    if "/" in store_path or ".py:" in store_path:
-        modname = "".join(choice("abcdefghijklmnopqrstuvwxyz") for _ in range(24))
-        path_name, function = store_path.rsplit(":", 1)
-        module_name = path_name.rstrip(":")
-        # Load from file path
-        modspec = importlib.util.spec_from_file_location(modname, module_name)
-        if modspec is None:
-            raise ValueError(f"Could not find store file: {path_name}")
-        module = importlib.util.module_from_spec(modspec)
-        sys.modules[module_name] = module
-        modspec.loader.exec_module(module)  # type: ignore[possibly-unbound-attribute]
-
-    else:
-        path_name, function = store_path.rsplit(".", 1)
-        module = importlib.import_module(path_name)
+    with profiled_import(store_path):
+        if "/" in store_path or ".py:" in store_path:
+            modname = "".join(choice("abcdefghijklmnopqrstuvwxyz") for _ in range(24))
+            path_name, function = store_path.rsplit(":", 1)
+            module_name = path_name.rstrip(":")
+            # Load from file path
+            modspec = importlib.util.spec_from_file_location(modname, module_name)
+            if modspec is None:
+                raise ValueError(f"Could not find store file: {path_name}")
+            module = importlib.util.module_from_spec(modspec)
+            sys.modules[module_name] = module
+            modspec.loader.exec_module(module)  # type: ignore[possibly-unbound-attribute]
+
+        else:
+            path_name, function = store_path.rsplit(".", 1)
+            module = importlib.import_module(path_name)
 
     try:
         store: BaseStore | Callable[[config.StoreConfig], BaseStore] = module.__dict__[