langgraph-api 0.16.0.dev7__py3-none-any.whl → 0.16.0.dev9__py3-none-any.whl

langgraph_api/__init__.py

@@ -1 +1 @@
-__version__ = "0.16.0.dev7"
+__version__ = "0.16.0.dev9"

langgraph_api/api/__init__.py

@@ -3,6 +3,8 @@ import functools
 import importlib
 import importlib.util
 import os
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING
 
 import structlog
 from starlette.applications import Starlette
@@ -40,7 +42,14 @@ from langgraph_api.grpc.client import get_shared_client
 from langgraph_api.js.base import is_js_path
 from langgraph_api.timing import profiled_import
 from langgraph_api.validation import render_docs_html
+from langgraph_runtime import database as runtime_database
 from langgraph_runtime.database import healthcheck
+from langgraph_runtime.retry import OVERLOADED_EXCEPTIONS
+
+HEALTHCHECK_TIMEOUT_SECONDS = 3.0
+
+if TYPE_CHECKING:
+    from langgraph_api.schema import ServiceHealth
 
 logger = structlog.stdlib.get_logger(__name__)
 
@@ -61,6 +70,19 @@ async def grpc_healthcheck():
         ) from exc
 
 
+def _data_dependency_checks() -> dict[str, Callable[[], Awaitable[None]]]:
+    """Per-dependency probes, or the combined `healthcheck` as a fallback.
+
+    Both in-repo runtimes provide `dependency_checks`. `langgraph_runtime`
+    resolves its backend from LANGGRAPH_RUNTIME_EDITION at import time, and an
+    out-of-tree edition (`community`) is not pinned here, so it may not.
+    """
+    checks = getattr(runtime_database, "dependency_checks", None)
+    if checks is None:
+        return {"database": healthcheck}
+    return checks()
+
+
 async def ok(request: Request, *, disabled: bool = False):
     if disabled:
         # We still expose an /ok endpoint even if disable_meta is set so that
@@ -68,23 +90,46 @@ async def ok(request: Request, *, disabled: bool = False):
         return JSONResponse({"ok": True})
     check_db = int(request.query_params.get("check_db", "0"))  # must be "0" or "1"
 
-    healthcheck_coroutines = []
+    checks: dict[str, Callable[[], Awaitable[None]]] = {}
+    services: dict[str, ServiceHealth] = {}
 
+    data_checks = _data_dependency_checks()
     if check_db:
-        healthcheck_coroutines.append(healthcheck())
+        checks.update(data_checks)
+    else:
+        services.update(dict.fromkeys(data_checks, "skipped"))
 
     if js_bg_tasks:
         from langgraph_api.js.remote import js_healthcheck  # noqa: PLC0415
 
-        healthcheck_coroutines.append(js_healthcheck())
+        checks["js_runtime"] = js_healthcheck
 
     # Check `core-api` server health
     if IS_POSTGRES_OR_GRPC_BACKEND:
-        healthcheck_coroutines.append(grpc_healthcheck())
-
-    await asyncio.gather(*healthcheck_coroutines)
-
-    return JSONResponse({"ok": True})
+        checks["core_api"] = grpc_healthcheck
+
+    results = await asyncio.gather(
+        *(
+            asyncio.wait_for(check(), timeout=HEALTHCHECK_TIMEOUT_SECONDS)
+            for check in checks.values()
+        ),
+        return_exceptions=True,
+    )
+
+    failed = False
+    for name, result in zip(checks, results, strict=True):
+        if isinstance(result, BaseException):
+            failed = True
+            services[name] = "unhealthy"
+            logger.warning("Healthcheck failed", service=name, exc_info=result)
+        else:
+            services[name] = "healthy"
+
+    overloaded = any(isinstance(result, OVERLOADED_EXCEPTIONS) for result in results)
+    return JSONResponse(
+        {"ok": not failed, "services": services},
+        status_code=503 if overloaded else 500 if failed else 200,
+    )
 
 
 async def openapi(request: Request):

langgraph_api/api/a2a.py

@@ -1233,21 +1233,18 @@ def _create_interrupt_artifact(interrupts: list[dict[str, Any]]) -> dict[str, An
     """Create an A2A artifact from interrupt data.
 
     Args:
-        interrupts: List of interrupt objects with 'id' and 'value' keys
+        interrupts: List of interrupt objects with 'id' and 'value' keys and an
+            optional 'response_schema'
 
     Returns:
         A2A artifact dict with interrupt data parts
     """
-    interrupt_parts = [
-        {
-            "kind": "data",
-            "data": {
-                "id": interrupt_obj.get("id"),
-                "value": interrupt_obj.get("value"),
-            },
-        }
-        for interrupt_obj in interrupts
-    ]
+    interrupt_parts = []
+    for interrupt_obj in interrupts:
+        data = {"id": interrupt_obj.get("id"), "value": interrupt_obj.get("value")}
+        if (schema := interrupt_obj.get("response_schema")) is not None:
+            data["response_schema"] = schema
+        interrupt_parts.append({"kind": "data", "data": data})
     return {
         "artifactId": str(uuid.uuid4()),
         "name": "Interrupt",

langgraph_api/api/runs.py

@@ -96,6 +96,23 @@ _StreamHandler = Any
 
 _RunResultFallback = Callable[[], Awaitable[bytes]]
 
+_INTERRUPT_KEY = "__interrupt__"
+_INTERRUPT_TOKEN = _INTERRUPT_KEY.encode()
+_STATE_MODES = (b"values", b"updates")
+
+
+def _interrupts_in(chunk: bytes) -> list[Any]:
+    if _INTERRUPT_TOKEN not in chunk:
+        return []
+    try:
+        payload = orjson.loads(chunk)
+    except orjson.JSONDecodeError:
+        return []
+    if not isinstance(payload, dict):
+        return []
+    interrupts = payload.get(_INTERRUPT_KEY)
+    return interrupts if isinstance(interrupts, list) else []
+
 
 def _thread_values_fallback(thread_id: UUID) -> _RunResultFallback:
     async def fetch_thread_values() -> bytes:
@@ -122,7 +139,7 @@ def _thread_values_fallback(thread_id: UUID) -> _RunResultFallback:
                             if isinstance(interrupt_list, list):
                                 interrupts.extend(interrupt_list)
                         if interrupts:
-                            return json_dumpb({"__interrupt__": interrupts})
+                            return json_dumpb({_INTERRUPT_KEY: interrupts})
                     except Exception:
                         # No interrupt, but status is interrupted from a before/after block. Default back to values.
                         pass
@@ -153,17 +170,58 @@ def _merge_feedback(body: bytes, feedback: bytes | None) -> bytes:
 def _merge_interrupts(chunks: list[bytes]) -> bytes:
     interrupts: list[Any] = []
     for chunk in chunks:
-        try:
-            payload = orjson.loads(chunk)
-        except orjson.JSONDecodeError:
-            continue
-        if not isinstance(payload, dict):
-            continue
-        interrupt_list = payload.get("__interrupt__")
-        if isinstance(interrupt_list, list):
-            interrupts.extend(interrupt_list)
+        interrupts.extend(_interrupts_in(chunk))
+
+    return orjson.dumps({_INTERRUPT_KEY: interrupts})
+
+
+class _RunResult:
+    __slots__ = ("_errored", "_fallback", "_feedback", "_interrupt_chunks", "_latest")
+
+    def __init__(self, fallback: _RunResultFallback | None) -> None:
+        self._errored = False
+        self._fallback = fallback
+        self._feedback: bytes | None = None
+        self._interrupt_chunks: list[bytes] = []
+        self._latest: bytes | None = None
+
+    def absorb(self, mode: bytes, chunk: bytes) -> None:
+        if mode == b"error":
+            self._latest = orjson.dumps({"__error__": orjson.Fragment(chunk)})
+            self._errored = True
+        elif mode == b"feedback":
+            self._feedback = chunk
+        elif mode in _STATE_MODES:
+            self._absorb_state(mode, chunk)
+
+    def _absorb_state(self, mode: bytes, chunk: bytes) -> None:
+        if _interrupts_in(chunk):
+            self._interrupt_chunks.append(chunk)
+            self._latest = chunk
+        elif mode == b"values":
+            self._latest = chunk
+
+    async def to_body(self) -> bytes:
+        values = await self._final_values()
+        if values is not None:
+            return _merge_feedback(values, self._feedback)
+        if self._feedback is not None:
+            return orjson.dumps({"__feedback__": orjson.loads(self._feedback)})
+        return b"{}"
 
-    return orjson.dumps({"__interrupt__": interrupts})
+    async def _final_values(self) -> bytes | None:
+        if (interrupted := self._interrupt_values()) is not None:
+            return interrupted
+        if self._latest is not None:
+            return self._latest
+        return await self._fallback() if self._fallback is not None else None
+
+    def _interrupt_values(self) -> bytes | None:
+        if self._errored or not self._interrupt_chunks:
+            return None
+        if len(self._interrupt_chunks) > 1:
+            return _merge_interrupts(self._interrupt_chunks)
+        return self._interrupt_chunks[-1]
 
 
 def _run_result_body(
@@ -179,11 +237,7 @@ def _run_result_body(
     last_chunk = ValueEvent()
 
     async def consume() -> None:
-        vchunk: bytes | None = None
-        fchunk: bytes | None = None
-        interrupt_chunks: list[bytes] = []
-        saw_error = False
-
+        result = _RunResult(fallback)
         try:
             async for mode, chunk, _ in Runs.Stream.join(
                 run_id,
@@ -192,33 +246,9 @@ def _run_result_body(
                 thread_id=thread_id,
                 ignore_404=ignore_404,
             ):
-                if mode == b"values" or (
-                    mode == b"updates" and b"__interrupt__" in chunk
-                ):
-                    vchunk = chunk
-                    if b"__interrupt__" in chunk:
-                        interrupt_chunks.append(chunk)
-                elif mode == b"error":
-                    vchunk = orjson.dumps({"__error__": orjson.Fragment(chunk)})
-                    saw_error = True
-                elif mode == b"feedback":
-                    fchunk = chunk
-
-            # Preserve terminal error precedence over interrupt chunks.
-            if not saw_error:
-                if len(interrupt_chunks) > 1:
-                    vchunk = _merge_interrupts(interrupt_chunks)
-                elif interrupt_chunks:
-                    vchunk = interrupt_chunks[-1]
-                elif vchunk is None and fallback is not None:
-                    vchunk = await fallback()
-
-            if vchunk is not None:
-                last_chunk.set(_merge_feedback(vchunk, fchunk))
-            elif fchunk is not None:
-                last_chunk.set(orjson.dumps({"__feedback__": orjson.loads(fchunk)}))
-            else:
-                last_chunk.set(b"{}")
+                result.absorb(mode, chunk)
+
+            last_chunk.set(await result.to_body())
         finally:
             await sub.__aexit__(None, None, None)
 

langgraph_api/api/store.py

@@ -24,13 +24,29 @@ from langgraph_api.validation import (
 from langgraph_runtime.retry import retry_db
 
 
-def _validate_namespace(namespace: tuple[str, ...]) -> Response | None:
+def _validate_namespace(namespace: Any) -> Response | None:
+    if not isinstance(namespace, list | tuple):
+        return _rejected_namespace("Namespace must be a list of labels")
     for label in namespace:
-        if not label or "." in label:
-            return Response(
-                status_code=422,
-                content=f"Namespace labels cannot be empty or contain periods. Received: {namespace}",
+        if not isinstance(label, str) or not label or "." in label:
+            return _rejected_namespace(
+                f"Namespace label {label!r} must be a non-empty string without periods"
             )
+    return None
+
+
+def _validate_optional_namespace(namespace: Any) -> Response | None:
+    return None if namespace is None else _validate_namespace(namespace)
+
+
+def _as_namespace(
+    namespace: list[str] | tuple[str, ...] | None,
+) -> tuple[str, ...] | None:
+    return None if namespace is None else tuple(namespace)
+
+
+def _rejected_namespace(detail: str) -> Response:
+    return Response(status_code=422, content=detail)
 
 
 async def handle_event(
@@ -72,8 +88,10 @@ async def put_item(request: ApiRequest):
         "ttl": payload.get("ttl"),
     }
     await handle_event("put", handler_payload)
+    if err := _validate_namespace(handler_payload["namespace"]):
+        return err
     await (await get_store()).aput(
-        handler_payload["namespace"],
+        tuple(handler_payload["namespace"]),
         handler_payload["key"],
         handler_payload["value"],
         index=handler_payload["index"],
@@ -100,8 +118,10 @@ async def get_item(request: ApiRequest):
         else None,
     }
     await handle_event("get", handler_payload)
+    if err := _validate_namespace(handler_payload["namespace"]):
+        return err
     result = await (await get_store()).aget(
-        handler_payload["namespace"],
+        tuple(handler_payload["namespace"]),
         handler_payload["key"],
         refresh_ttl=handler_payload["refresh_ttl"],
     )
@@ -129,8 +149,10 @@ async def delete_item(request: ApiRequest):
         "key": payload["key"],
     }
     await handle_event("delete", handler_payload)
+    if err := _validate_namespace(handler_payload["namespace"]):
+        return err
     await (await get_store()).adelete(
-        handler_payload["namespace"], handler_payload["key"]
+        tuple(handler_payload["namespace"]), handler_payload["key"]
     )
     return Response(status_code=204)
 
@@ -155,6 +177,8 @@ async def search_items(request: ApiRequest):
         "refresh_ttl": payload.get("refresh_ttl"),
     }
     auth_filter = await handle_event("search", handler_payload)
+    if err := _validate_namespace(handler_payload["namespace"]):
+        return err
     if auth_filter:
         existing = handler_payload.get("filter")
         if existing:
@@ -162,7 +186,7 @@ async def search_items(request: ApiRequest):
         else:
             handler_payload["filter"] = auth_filter
     items = await (await get_store()).asearch(
-        handler_payload["namespace"],
+        tuple(handler_payload["namespace"]),
         filter=handler_payload["filter"],
         limit=handler_payload["limit"],
         offset=handler_payload["offset"],
@@ -187,10 +211,9 @@ async def list_namespaces(request: ApiRequest):
     payload = await request.json(StoreListNamespacesRequest)
     prefix = tuple(payload["prefix"]) if payload.get("prefix") else None
     suffix = tuple(payload["suffix"]) if payload.get("suffix") else None
-    err = None
-    if prefix and (err := _validate_namespace(prefix)):
+    if err := _validate_optional_namespace(prefix):
         return err
-    if suffix and (err := _validate_namespace(suffix)):
+    if err := _validate_optional_namespace(suffix):
         return err
     max_depth = payload.get("max_depth")
     limit = payload.get("limit", 100)
@@ -203,9 +226,12 @@ async def list_namespaces(request: ApiRequest):
         "offset": offset,
     }
     await handle_event("list_namespaces", handler_payload)
+    for candidate in (handler_payload["namespace"], handler_payload["suffix"]):
+        if err := _validate_optional_namespace(candidate):
+            return err
     result = await (await get_store()).alist_namespaces(
-        prefix=handler_payload["namespace"],
-        suffix=handler_payload["suffix"],
+        prefix=_as_namespace(handler_payload["namespace"]),
+        suffix=_as_namespace(handler_payload["suffix"]),
         max_depth=handler_payload["max_depth"],
         limit=handler_payload["limit"],
         offset=handler_payload["offset"],

langgraph_api/grpc/ops/threads.py

@@ -201,6 +201,8 @@ def _proto_interrupts_to_dict(
                 entry["resumable"] = interrupt.resumable
             if interrupt.ns:
                 entry["ns"] = list(interrupt.ns)
+            if interrupt.response_schema:
+                entry["response_schema"] = json_loads(interrupt.response_schema)
             entries.append(entry)
         out[key] = entries
     return out

langgraph_api/js/client.mts

@@ -59,6 +59,7 @@ import {
   getStaticGraphSchema,
 } from "@langchain/langgraph-api/schema";
 import { filterValidExportPath } from "./src/utils/files.mts";
+import { collectMutations } from "./src/auth-mutations.mts";
 import { patchFetch } from "./traceblock.mts";
 import { writeHeapSnapshot } from "node:v8";
 
@@ -1278,7 +1279,13 @@ async function main() {
 
     app.post("/auth/authorize", async (c) => {
       try {
-        return c.json(await authorize(await c.req.json()));
+        const request = await c.req.json();
+        const before = structuredClone(request.value);
+        const { value, ...result } = await authorize(request);
+        return c.json({
+          ...result,
+          mutations: collectMutations(before, value),
+        });
       } catch (error) {
         if (error instanceof HTTPException) {
           return c.json(serializeError(error), error.status);

langgraph_api/js/remote.py

@@ -1238,19 +1238,104 @@ async def handle_js_auth_event(
 
     filters = cast("Auth.types.FilterType | None", response.get("filters"))
 
-    # mutate metadata in value if applicable
-    # we need to preserve the identity of the object, so cannot create a new
-    # dictionary, otherwise the changes will not persist
-    metadata = None
+    try:
+        _apply_auth_mutations(value, response.get("mutations"))
+    except _RefusedAuthMutation as error:
+        raise HTTPException(
+            status_code=500,
+            detail=f"JS auth handler result could not be applied: {error}",
+        ) from error
+
+    return filters
+
+
+_MutationKey = str | int
+_MutationContainer = dict[str, Any] | list[Any] | tuple[Any, ...]
+_UNADDRESSABLE_MUTATION = "a mutation does not address the request payload"
+
+
+class _RefusedAuthMutation(Exception):
+    pass
+
+
+def _apply_auth_mutations(payload: dict[str, Any], mutations: Any) -> None:
+    if not isinstance(mutations, list):
+        raise _RefusedAuthMutation("the sidecar returned no mutation list")
+    for mutation in mutations:
+        path = _mutation_path(mutation)
+        if "value" in mutation:
+            _write(payload, path, mutation["value"])
+        elif len(path) > 1:
+            _remove(payload, path)
+        else:
+            raise _RefusedAuthMutation(
+                f"a mutation removes the route-owned key {path[0]!r}"
+            )
+
+
+def _mutation_path(mutation: Any) -> list[_MutationKey]:
+    path = mutation.get("path") if isinstance(mutation, dict) else None
     if (
-        isinstance(value, dict)
-        and (updated_value := response.get("value"))
-        and isinstance(value.get("metadata"), dict)
-        and (metadata := updated_value.get("metadata"))
+        isinstance(path, list)
+        and path
+        and all(isinstance(key, str) or type(key) is int for key in path)
     ):
-        value["metadata"].update(metadata)
+        return path
+    raise _RefusedAuthMutation("a mutation is malformed")
 
-    return filters
+
+def _write(container: _MutationContainer, path: list[_MutationKey], value: Any) -> Any:
+    key = path[0]
+    if len(path) > 1:
+        return _with_member(
+            container, key, _write(_child(container, key), path[1:], value)
+        )
+    existing = _member(container, key)
+    return _with_member(container, key, _keeping_existing_type(existing, value))
+
+
+def _remove(container: _MutationContainer, path: list[_MutationKey]) -> Any:
+    key = path[0]
+    if len(path) > 1:
+        return _with_member(container, key, _remove(_child(container, key), path[1:]))
+    if not (isinstance(container, dict) and _addresses(container, key)):
+        raise _RefusedAuthMutation(_UNADDRESSABLE_MUTATION)
+    container.pop(key, None)
+    return container
+
+
+def _addresses(container: Any, key: _MutationKey) -> bool:
+    if isinstance(container, dict):
+        return isinstance(key, str)
+    if isinstance(container, list | tuple):
+        return type(key) is int and 0 <= key < len(container)
+    return False
+
+
+def _member(container: _MutationContainer, key: _MutationKey) -> Any:
+    if not _addresses(container, key):
+        raise _RefusedAuthMutation(_UNADDRESSABLE_MUTATION)
+    return container.get(key) if isinstance(container, dict) else container[key]
+
+
+def _child(container: _MutationContainer, key: _MutationKey) -> _MutationContainer:
+    child = _member(container, key)
+    if not isinstance(child, dict | list | tuple):
+        raise _RefusedAuthMutation(_UNADDRESSABLE_MUTATION)
+    return child
+
+
+def _with_member(container: _MutationContainer, key: _MutationKey, value: Any) -> Any:
+    if isinstance(container, tuple):
+        return (*container[:key], value, *container[key + 1 :])
+    container[key] = value
+    return container
+
+
+def _keeping_existing_type(existing: Any, replacement: Any) -> Any:
+    if isinstance(existing, tuple) and isinstance(replacement, list):
+        return tuple(replacement)
+    return replacement
 
 
 class JSCustomHTTPProxyMiddleware:

langgraph_api/js/src/auth-mutations.mts

@@ -0,0 +1,71 @@
+export type MutationPath = (string | number)[];
+export type AuthMutation = { path: MutationPath; value?: unknown };
+
+type JsonObject = Record<string, unknown>;
+type JsonContainer = JsonObject | unknown[];
+
+const isJsonObject = (value: unknown): value is JsonObject =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const areAligned = (left: unknown, right: unknown): left is JsonContainer =>
+  (isJsonObject(left) && isJsonObject(right)) ||
+  (Array.isArray(left) && Array.isArray(right) && left.length === right.length);
+
+const keysOf = (container: JsonContainer): MutationPath =>
+  Array.isArray(container)
+    ? Array.from({ length: container.length }, (_, index) => index)
+    : Object.keys(container);
+
+const hasMember = (container: JsonContainer, key: string | number): boolean =>
+  Array.isArray(container)
+    ? Number(key) >= 0 && Number(key) < container.length
+    : Object.hasOwn(container, key);
+
+const memberOf = (container: JsonContainer, key: string | number): unknown => {
+  if (!Array.isArray(container)) {
+    return hasMember(container, key) ? container[String(key)] : undefined;
+  }
+  const element = container[Number(key)];
+  return element === undefined ? null : element;
+};
+
+const collectInto = (
+  before: JsonContainer,
+  after: JsonContainer,
+  path: MutationPath,
+  found: AuthMutation[],
+): void => {
+  for (const key of keysOf(before)) {
+    if (!hasMember(after, key) || memberOf(after, key) === undefined) {
+      found.push({ path: [...path, key] });
+    }
+  }
+  for (const key of keysOf(after)) {
+    const replacement = memberOf(after, key);
+    if (replacement === undefined) continue;
+    const existing = memberOf(before, key);
+    if (areAligned(existing, replacement)) {
+      collectInto(
+        existing,
+        replacement as JsonContainer,
+        [...path, key],
+        found,
+      );
+      continue;
+    }
+    if (!hasMember(before, key) || existing !== replacement) {
+      found.push({ path: [...path, key], value: replacement });
+    }
+  }
+};
+
+export const collectMutations = (
+  before: unknown,
+  after: unknown,
+): AuthMutation[] => {
+  const found: AuthMutation[] = [];
+  if (areAligned(before, after)) {
+    collectInto(before, after as JsonContainer, [], found);
+  }
+  return found;
+};

langgraph_api/lc_security/transport.py

@@ -145,7 +145,7 @@ class SSRFSafeTransport(httpx.AsyncBaseTransport):
         # certificate validation uses the original hostname.
         extensions = dict(request.extensions)
         if scheme == "https":
-            extensions["sni_hostname"] = hostname.encode("ascii")
+            extensions["sni_hostname"] = hostname
 
         pinned_request = httpx.Request(
             method=request.method,

langgraph_api/schema.py

@@ -15,6 +15,8 @@ RunStatus = Literal["pending", "running", "error", "success", "timeout", "interr
 
 ThreadStatus = Literal["idle", "busy", "interrupted", "error"]
 
+ServiceHealth = Literal["healthy", "unhealthy", "skipped"]
+
 StreamMode = Literal[
     "values",
     "messages",
@@ -134,6 +136,8 @@ class Interrupt(TypedDict):
     """The ID of the interrupt."""
     value: Any
     """The value of the interrupt."""
+    response_schema: NotRequired[dict[str, Any]]
+    """JSON Schema for the value expected when resuming the interrupt, if the graph provided one."""
 
 
 class DeprecatedInterrupt(TypedDict, total=False):