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

langgraph_api/stream.py

@@ -2,7 +2,7 @@ import uuid
 from collections.abc import AsyncIterator, Callable
 from contextlib import AsyncExitStack, aclosing, asynccontextmanager
 from functools import lru_cache
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 import langgraph.version
 import langsmith
@@ -16,7 +16,6 @@ from langchain_core.messages import (
     convert_to_messages,
     message_chunk_to_message,
 )
-from langchain_core.runnables import RunnableConfig
 from langgraph.errors import (
     EmptyChannelError,
     EmptyInputError,
@@ -32,7 +31,11 @@ from langgraph_api import __version__
 from langgraph_api import store as api_store
 from langgraph_api.asyncio import ValueEvent, wait_if_not_done
 from langgraph_api.command import map_cmd
-from langgraph_api.feature_flags import USE_DURABILITY, USE_RUNTIME_CONTEXT_API
+from langgraph_api.feature_flags import (
+    UPDATES_NEEDED_FOR_INTERRUPTS,
+    USE_DURABILITY,
+    USE_RUNTIME_CONTEXT_API,
+)
 from langgraph_api.graph import get_graph
 from langgraph_api.js.base import BaseRemotePregel
 from langgraph_api.metadata import HOST, PLAN, USER_API_URL, incr_nodes
@@ -42,6 +45,10 @@ from langgraph_api.utils.config import run_in_executor
 from langgraph_runtime.checkpoint import Checkpointer
 from langgraph_runtime.ops import Runs
 
+if TYPE_CHECKING:
+    from langchain_core.runnables import RunnableConfig
+
+
 logger = structlog.stdlib.get_logger(__name__)
 
 
@@ -147,7 +154,7 @@ async def astream_state(
     subgraphs = kwargs.get("subgraphs", False)
     temporary = kwargs.pop("temporary", False)
     context = kwargs.pop("context", None)
-    config = cast(RunnableConfig, kwargs.pop("config"))
+    config = cast("RunnableConfig", kwargs.pop("config"))
     configurable = config["configurable"]
     stack = AsyncExitStack()
     graph = await stack.enter_async_context(
@@ -156,6 +163,7 @@ async def astream_state(
             config,
             store=(await api_store.get_store()),
             checkpointer=None if temporary else Checkpointer(),
+            is_for_execution=True,
         )
     )
 
@@ -180,7 +188,7 @@ async def astream_state(
     if "messages-tuple" in stream_modes_set and not isinstance(graph, BaseRemotePregel):
         stream_modes_set.remove("messages-tuple")
         stream_modes_set.add("messages")
-    if "updates" not in stream_modes_set:
+    if "updates" not in stream_modes_set and UPDATES_NEEDED_FOR_INTERRUPTS:
         stream_modes_set.add("updates")
         only_interrupt_updates = True
     else:
@@ -250,7 +258,7 @@ async def astream_state(
                 event = await wait_if_not_done(anext(stream, sentinel), done)
                 if event is sentinel:
                     break
-                event = cast(dict, event)
+                event = cast("dict", event)
                 if event.get("tags") and "langsmith:hidden" in event["tags"]:
                     continue
                 if (
@@ -288,7 +296,7 @@ async def astream_state(
                                 yield "messages", chunk
                         else:
                             msg_, meta = cast(
-                                tuple[BaseMessage | dict, dict[str, Any]], chunk
+                                "tuple[BaseMessage | dict, dict[str, Any]]", chunk
                             )
                             is_chunk = False
                             if isinstance(msg_, dict):
@@ -338,11 +346,9 @@ async def astream_state(
                         and len(chunk["__interrupt__"]) > 0
                         and only_interrupt_updates
                     ):
-                        # We always want to return interrupt events by default.
-                        # If updates aren't specified as a stream mode, we return these as values events.
                         # If the interrupt doesn't have any actions (e.g. interrupt before or after a node is specified), we don't return the interrupt at all today.
                         if subgraphs and ns:
-                            yield f"values|{'|'.join(ns)}", chunk
+                            yield "values|{'|'.join(ns)}", chunk
                         else:
                             yield "values", chunk
                     # --- end shared logic with astream ---
@@ -370,9 +376,9 @@ async def astream_state(
                 if event is sentinel:
                     break
                 if subgraphs:
-                    ns, mode, chunk = cast(tuple[str, str, dict[str, Any]], event)
+                    ns, mode, chunk = cast("tuple[str, str, dict[str, Any]]", event)
                 else:
-                    mode, chunk = cast(tuple[str, dict[str, Any]], event)
+                    mode, chunk = cast("tuple[str, dict[str, Any]]", event)
                     ns = None
                 # --- begin shared logic with astream_events ---
                 if mode == "debug":
@@ -390,7 +396,7 @@ async def astream_state(
                             yield "messages", chunk
                     else:
                         msg_, meta = cast(
-                            tuple[BaseMessage | dict, dict[str, Any]], chunk
+                            "tuple[BaseMessage | dict, dict[str, Any]]", chunk
                         )
                         is_chunk = False
                         if isinstance(msg_, dict):
@@ -440,11 +446,9 @@ async def astream_state(
                     and len(chunk["__interrupt__"]) > 0
                     and only_interrupt_updates
                 ):
-                    # We always want to return interrupt events by default.
-                    # If updates aren't specified as a stream mode, we return these as values events.
                     # If the interrupt doesn't have any actions (e.g. interrupt before or after a node is specified), we don't return the interrupt at all today.
                     if subgraphs and ns:
-                        yield "values|{'|'.join(ns)}", chunk
+                        yield f"values|{'|'.join(ns)}", chunk
                     else:
                         yield "values", chunk
                 # --- end shared logic with astream_events ---

langgraph_api/thread_ttl.py

@@ -6,32 +6,47 @@ from typing import cast
 import structlog
 
 from langgraph_api.config import THREAD_TTL
+from langgraph_api.feature_flags import FF_USE_CORE_API
 from langgraph_runtime.database import connect
 
 logger = structlog.stdlib.get_logger(__name__)
 
+# Supported TTL strategies
+SUPPORTED_STRATEGIES = {"delete", "keep_latest"}
+
 
 async def thread_ttl_sweep_loop():
-    """Periodically delete threads based on TTL configuration.
+    """Periodically sweep threads based on TTL configuration.
+
+    Supported strategies:
+    - 'delete': Remove the thread and all its data entirely
+    - 'keep_latest': Prune old checkpoints but keep thread and latest state
+      (requires FF_USE_CORE_API=true)
 
-    Currently implements the 'delete' strategy, which deletes entire threads
-    that have been inactive for longer than their configured TTL period.
+    Per-thread TTL strategies are stored in the thread_ttl table and can vary
+    by thread. This loop processes all expired threads regardless of strategy.
     """
-    # Use the same interval as store TTL sweep
     thread_ttl_config = THREAD_TTL or {}
-    strategy = thread_ttl_config.get("strategy", "delete")
-    if strategy != "delete":
-        raise NotImplementedError(
-            f"Unrecognized thread deletion strategy: {strategy}. Expected 'delete'."
-        )
+    default_strategy = thread_ttl_config.get("strategy", "delete")
     sweep_interval_minutes = cast(
-        int, thread_ttl_config.get("sweep_interval_minutes", 5)
+        "int", thread_ttl_config.get("sweep_interval_minutes", 5)
     )
+    sweep_limit = thread_ttl_config.get("sweep_limit", 1000)
+
     await logger.ainfo(
-        f"Starting thread TTL sweeper with interval {sweep_interval_minutes} minutes",
-        strategy=strategy,
+        "Starting thread TTL sweeper",
+        default_strategy=default_strategy,
         interval_minutes=sweep_interval_minutes,
+        sweep_limit=sweep_limit,
+        core_api_enabled=FF_USE_CORE_API,
     )
+
+    if default_strategy == "keep_latest" and not FF_USE_CORE_API:
+        await logger.awarning(
+            "keep_latest strategy configured but FF_USE_CORE_API is not enabled. "
+            "Threads with keep_latest strategy will be skipped during sweep."
+        )
+
     loop = asyncio.get_running_loop()
 
     from langgraph_runtime.ops import Threads
@@ -44,7 +59,7 @@ async def thread_ttl_sweep_loop():
                 threads_processed, threads_deleted = await Threads.sweep_ttl(conn)
                 if threads_processed > 0:
                     await logger.ainfo(
-                        f"Thread TTL sweep completed. Processed {threads_processed}",
+                        "Thread TTL sweep completed",
                         threads_processed=threads_processed,
                         threads_deleted=threads_deleted,
                         duration=loop.time() - sweep_start,

langgraph_api/timing/__init__.py

@@ -0,0 +1,25 @@
+"""Timing utilities for startup profiling and performance monitoring."""
+
+from langgraph_api.timing.profiler import (
+    profiled_import,
+)
+from langgraph_api.timing.timer import (
+    TimerConfig,
+    aenter_timed,
+    combine_lifespans,
+    get_startup_elapsed,
+    time_aenter,
+    timer,
+    wrap_lifespan_context_aenter,
+)
+
+__all__ = [
+    "TimerConfig",
+    "aenter_timed",
+    "combine_lifespans",
+    "get_startup_elapsed",
+    "profiled_import",
+    "time_aenter",
+    "timer",
+    "wrap_lifespan_context_aenter",
+]

langgraph_api/timing/profiler.py

@@ -0,0 +1,200 @@
+"""Import profiling utilities for diagnosing slow module loads.
+
+When FF_PROFILE_IMPORTS is true, this module provides detailed
+profiling of what's slow during module imports - including nested imports
+and module-level code execution (network calls, file I/O, etc.).
+"""
+
+from __future__ import annotations
+
+import cProfile
+import pstats
+import time
+from contextlib import contextmanager
+from typing import TypedDict, cast
+
+import structlog
+
+logger = structlog.stdlib.get_logger(__name__)
+
+# Minimum time (in seconds) for an operation to be reported
+MIN_REPORT_THRESHOLD_SECS = 1.0
+
+
+@contextmanager
+def profiled_import(path: str, top_n: int = 10):
+    """Context manager for profiling an import with automatic reporting.
+
+    Usage:
+        with profiled_import("./my_module.py:obj") as profiler:
+            module = exec_module(...)
+        # Automatically logs slow calls if any
+
+    Args:
+        path: The module path (for logging)
+        top_n: Maximum number of slow calls to report
+    """
+    from langgraph_api import config
+
+    if not config.FF_PROFILE_IMPORTS:
+        yield None
+        return
+
+    start = time.perf_counter()
+    pr = cProfile.Profile()
+    pr.enable()
+
+    class ProfilerResult:
+        def __init__(self) -> None:
+            self.slow_calls: list[_SlowCall] = []
+            self.total_secs: float = 0.0
+
+    result = ProfilerResult()
+
+    try:
+        yield result
+    finally:
+        pr.disable()
+        result.total_secs = time.perf_counter() - start
+
+        # Extract the module filename from path (e.g., "./foo/bar.py:obj" -> "bar.py")
+        module_file = path.split(":")[0].rsplit("/", 1)[-1]
+
+        stats_obj = pstats.Stats(pr)
+        stats = cast("dict", stats_obj.stats)  # type: ignore[attr-defined]
+        slow_calls: list[_SlowCall] = []
+
+        for (filename, lineno, funcname), (
+            _cc,
+            nc,
+            _tt,
+            ct,
+            callers,
+        ) in stats.items():
+            cumtime_secs = ct
+            if cumtime_secs >= MIN_REPORT_THRESHOLD_SECS:
+                # Skip non-actionable entries
+                if "cProfile" in filename or "<frozen" in filename:
+                    continue
+                # Skip built-in exec (just wrapper around module execution)
+                if filename == "~" and "builtins.exec" in funcname:
+                    continue
+                # Skip the top-level <module> entry (not actionable)
+                if funcname == "<module>":
+                    continue
+
+                # Find call site in user's module
+                call_site = _find_user_call_site(callers, module_file, stats)
+
+                slow_calls.append(
+                    _SlowCall(
+                        function=funcname,
+                        file=f"{filename}:{lineno}",
+                        cumulative_secs=round(cumtime_secs, 2),
+                        calls=nc,
+                        call_site=call_site,
+                    )
+                )
+
+        slow_calls.sort(key=lambda x: x["cumulative_secs"], reverse=True)
+        result.slow_calls = slow_calls[:top_n]
+
+        # Only log if we have slow calls worth reporting
+        if result.slow_calls:
+            report = _format_slow_calls_report(
+                path, result.total_secs, result.slow_calls
+            )
+            logger.warning(
+                f"slow_import_profile: {report}",
+                path=path,
+                total_secs=round(result.total_secs, 2),
+                slow_calls=result.slow_calls,
+            )
+
+
+def _find_user_call_site(
+    callers: dict, module_file: str, all_stats: dict, max_depth: int = 20
+) -> str | None:
+    """Walk up the call chain to find where in the user's module this was called from."""
+    visited: set[tuple] = set()
+    to_check = list(callers.keys())
+
+    for _ in range(max_depth):
+        if not to_check:
+            break
+        caller_key = to_check.pop(0)
+        if caller_key in visited:
+            continue
+        visited.add(caller_key)
+
+        caller_file, caller_line, caller_func = caller_key
+        # Found a call from the user's module
+        if caller_file.endswith(module_file):
+            # cProfile attributes all module-level code to <module> at line 1,
+            # so we can't get the actual line number for top-level calls
+            if caller_func == "<module>":
+                return f"{module_file} (module-level)"
+            return f"{module_file}:{caller_line} in {caller_func}()"
+
+        # Keep walking up
+        if caller_key in all_stats:
+            parent_callers = all_stats[caller_key][4]  # callers is index 4
+            to_check.extend(parent_callers.keys())
+
+    return None
+
+
+class _SlowCall(TypedDict):
+    """A slow function call detected during import profiling."""
+
+    function: str
+    file: str
+    cumulative_secs: float
+    calls: int
+    call_site: str | None  # Where in user's module this was called from
+
+
+def _format_slow_calls_report(
+    path: str,
+    total_secs: float,
+    slow_calls: list[_SlowCall],
+) -> str:
+    """Format slow calls into a human-readable report."""
+    lines = [
+        "",
+        f"Slow startup for '{path}' ({total_secs:.1f}s)",
+        "",
+        "    Slowest operations:",
+    ]
+
+    for call in slow_calls:
+        secs = call["cumulative_secs"]
+        func = call["function"]
+        # Show last 2 path components for context (e.g., "requests/sessions.py:500")
+        file_path = call["file"]
+        parts = file_path.rsplit("/", 2)
+        loc = "/".join(parts[-2:]) if len(parts) > 2 else file_path
+
+        call_site = call.get("call_site")
+        if call_site:
+            lines.append(f"      {secs:>6.2f}s  {func:<24} {loc}")
+            lines.append(f"               ↳ from {call_site}")
+        else:
+            lines.append(f"      {secs:>6.2f}s  {func:<24} {loc}")
+
+    lines.extend(
+        [
+            "",
+            "    Slow operations (network calls, file I/O, heavy computation) at",
+            "    import time delay startup. Consider moving them inside functions",
+            "    or using lazy initialization.",
+            "",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+__all__ = [
+    "profiled_import",
+]