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

langgraph_api/thread_ttl.py

@@ -1,34 +1,52 @@
 """Sweeping logic for cleaning up expired threads and checkpoints."""
 
 import asyncio
+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'."
-        )
-    sweep_interval_minutes = thread_ttl_config.get("sweep_interval_minutes", 5)
+    default_strategy = thread_ttl_config.get("strategy", "delete")
+    sweep_interval_minutes = cast(
+        "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
@@ -41,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",
+]

langgraph_api/timing/timer.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+# ruff: noqa: E402
+import time
+
+# Capture the time when this module is first imported (early in server startup)
+_PROCESS_START_TIME = time.monotonic()
+
+import contextlib
+import functools
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, ParamSpec, TypeVar, overload
+
+import structlog
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from contextlib import AbstractAsyncContextManager
+
+    from starlette.applications import Starlette
+
+logger = structlog.stdlib.get_logger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+T = TypeVar("T", covariant=True)
+
+
+@dataclass(frozen=True)
+class TimerConfig(Generic[P]):
+    message: str = "Function timing"
+    metadata_fn: Callable[P, dict[str, Any]] | None = None
+    warn_threshold_secs: float | None = None
+    warn_message: str | None = None
+    error_threshold_secs: float | None = None
+    error_message: str | None = None
+
+
+@overload
+def timer(_func: Callable[P, R], /, **kwargs) -> Callable[P, R]: ...
+@overload
+def timer(
+    _func: None = None, /, **kwargs
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def timer(
+    _func: Callable[P, R] | None = None,
+    /,
+    message: str = "Function timing",
+    metadata_fn: Callable[P, dict[str, Any]] | None = None,
+    warn_threshold_secs: float | None = None,
+    warn_message: str | None = None,
+    error_threshold_secs: float | None = None,
+    error_message: str | None = None,
+):
+    """
+    Decorator for sync *and* async callables.
+    """
+    cfg = TimerConfig[P](
+        message=message,
+        metadata_fn=metadata_fn,
+        warn_threshold_secs=warn_threshold_secs,
+        warn_message=warn_message,
+        error_threshold_secs=error_threshold_secs,
+        error_message=error_message,
+    )
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def awrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                start = time.perf_counter()
+                exc: BaseException | None = None
+                try:
+                    return await func(*args, **kwargs)  # type: ignore[misc]
+                except BaseException as e:
+                    exc = e
+                    raise
+                finally:
+                    elapsed = time.perf_counter() - start
+                    _log_timing(
+                        name=func.__qualname__,
+                        elapsed=elapsed,
+                        cfg=cfg,  # type: ignore[arg-type]
+                        args=args,
+                        kwargs=kwargs,
+                        exc=exc,
+                    )
+
+            return awrapper  # type: ignore[return-value]
+
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start = time.perf_counter()
+            exc: BaseException | None = None
+            try:
+                return func(*args, **kwargs)
+            except BaseException as e:
+                exc = e
+                raise
+            finally:
+                elapsed = time.perf_counter() - start
+                _log_timing(
+                    name=func.__qualname__,
+                    elapsed=elapsed,
+                    cfg=cfg,  # type: ignore[arg-type]
+                    args=args,
+                    kwargs=kwargs,
+                    exc=exc,
+                )
+
+        return wrapper
+
+    return decorator(_func) if _func is not None else decorator
+
+
+class aenter_timed(Generic[T]):
+    """
+    Wraps an async context manager and logs the time spent in *its __aenter__*.
+    __aexit__ is delegated without additional timing.
+    """
+
+    def __init__(
+        self,
+        inner: AbstractAsyncContextManager[T],
+        *,
+        name: str,
+        cfg: TimerConfig[Any],
+        extra: dict[str, Any] | None = None,
+    ) -> None:
+        self._inner = inner
+        self._name = name
+        self._cfg = cfg
+        self._extra = extra or {}
+
+    async def __aenter__(self) -> T:
+        start = time.perf_counter()
+        exc: BaseException | None = None
+        try:
+            return await self._inner.__aenter__()
+        except BaseException as e:
+            exc = e
+            raise
+        finally:
+            elapsed = time.perf_counter() - start
+            _log_timing(
+                name=self._name,
+                elapsed=elapsed,
+                cfg=self._cfg,
+                exc=exc,
+                extra=self._extra,
+            )
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool | None:
+        return await self._inner.__aexit__(exc_type, exc, tb)
+
+
+def time_aenter(
+    cm: AbstractAsyncContextManager[T],
+    *,
+    name: str,
+    message: str,
+    warn_threshold_secs: float | None = None,
+    warn_message: str | None = None,
+    error_threshold_secs: float | None = None,
+    error_message: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> aenter_timed[T]:
+    """
+    Convenience helper to wrap any async CM and time only its __aenter__.
+    """
+    cfg = TimerConfig[Any](
+        message=message,
+        warn_threshold_secs=warn_threshold_secs,
+        warn_message=warn_message,
+        error_threshold_secs=error_threshold_secs,
+        error_message=error_message,
+        metadata_fn=None,
+    )
+    return aenter_timed(cm, name=name, cfg=cfg, extra=extra)
+
+
+def wrap_lifespan_context_aenter(
+    lifespan_ctx: Callable[[Any], AbstractAsyncContextManager[Any]],
+    *,
+    name: str = "user_router.lifespan",
+    message: str = "Entered lifespan context",
+    warn_threshold_secs: float | None = 10,
+    warn_message: str | None = (
+        "User lifespan startup exceeded expected time. "
+        "Slow work done at entry time within lifespan context can delay readiness, "
+        "reduce scale-out capacity, and may cause deployments to be marked unhealthy."
+    ),
+    error_threshold_secs: float | None = 30,
+    error_message: str | None = None,
+) -> Callable[[Any], AbstractAsyncContextManager[Any]]:
+    @functools.wraps(lifespan_ctx)
+    def wrapped(app: Any) -> AbstractAsyncContextManager[Any]:
+        return time_aenter(
+            lifespan_ctx(app),
+            name=name,
+            message=message,
+            warn_threshold_secs=warn_threshold_secs,
+            warn_message=warn_message,
+            error_threshold_secs=error_threshold_secs,
+            error_message=error_message,
+        )
+
+    return wrapped
+
+
+LP = ParamSpec("LP")
+
+
+def combine_lifespans(
+    *lifespans: Callable[[Starlette], AbstractAsyncContextManager] | None,
+) -> Callable[[Starlette], AbstractAsyncContextManager]:
+    @contextlib.asynccontextmanager
+    async def combined_lifespan(app):
+        async with contextlib.AsyncExitStack() as stack:
+            for ls in lifespans:
+                if ls is not None:
+                    await stack.enter_async_context(ls(app))
+            elapsed = get_startup_elapsed()
+            logger.info(f"Application started up in {elapsed:2.3f}s", elapsed=elapsed)
+            yield
+
+    return combined_lifespan
+
+
+def get_startup_elapsed() -> float:
+    """Return elapsed seconds since the process started (module import time)."""
+    return time.monotonic() - _PROCESS_START_TIME
+
+
+def _log_timing(
+    *,
+    name: str,
+    elapsed: float,
+    cfg: TimerConfig[Any],
+    args: tuple[Any, ...] = (),
+    kwargs: dict[str, Any] | None = None,
+    exc: BaseException | None = None,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    from langgraph_api import config
+
+    kwargs = kwargs or {}
+
+    log_data: dict[str, Any] = {
+        "name": name,
+        "elapsed_seconds": elapsed,
+    }
+
+    if extra:
+        log_data.update(extra)
+
+    if cfg.metadata_fn is not None:
+        try:
+            md = cfg.metadata_fn(*args, **kwargs)  # type: ignore[misc]
+            if not isinstance(md, dict):
+                raise TypeError("metadata_fn must return a dict")
+            log_data.update(md)
+        except Exception as meta_exc:
+            log_data["metadata_error"] = repr(meta_exc)
+
+    if exc is not None:
+        log_data["exception"] = repr(exc)
+
+    level, msg = _pick_level_and_message(
+        elapsed=elapsed,
+        message=cfg.message,
+        warn_threshold_secs=cfg.warn_threshold_secs,
+        warn_message=cfg.warn_message,
+        error_threshold_secs=cfg.error_threshold_secs,
+        error_message=cfg.error_message,
+    )
+
+    # Allow {graph_id} etc.
+    msg = msg.format(**log_data)
+
+    # Add profiler hint if we hit warn/error threshold and profiling isn't enabled
+    if level >= logging.WARNING and not config.FF_PROFILE_IMPORTS:
+        msg = (
+            f"{msg}\n"
+            f"    To get detailed profiling of slow operations, set FF_PROFILE_IMPORTS=true"
+        )
+
+    logger.log(level, msg, **log_data)
+
+
+def _pick_level_and_message(
+    *,
+    elapsed: float,
+    message: str,
+    warn_threshold_secs: float | None,
+    warn_message: str | None,
+    error_threshold_secs: float | None,
+    error_message: str | None,
+) -> tuple[int, str]:
+    level = logging.INFO
+    msg = message
+
+    if warn_threshold_secs is not None and elapsed > warn_threshold_secs:
+        level = logging.WARNING
+        if warn_message is not None:
+            msg = warn_message
+
+    if error_threshold_secs is not None and elapsed > error_threshold_secs:
+        level = logging.ERROR
+        if error_message is not None:
+            msg = error_message
+
+    return level, msg