langgraph-node-deadline 0.1.0__py3-none-any.whl

langgraph_node_deadline/__init__.py

@@ -0,0 +1,176 @@
+"""langgraph-node-deadline — one binding deadline for every inner timeout.
+
+The problem this solves
+-----------------------
+A LangGraph node that does real work usually has *several* layers each
+re-deriving their own clock: an outer ``TimeoutPolicy`` watchdog, an inner
+agent/tool budget, a retry loop, a sub-planner that "wants" 60 seconds. When
+those clocks disagree, the inner layers dispatch work the outer watchdog is
+guaranteed to kill — and the kill is uncooperative: it cancels the node and
+**discards everything**, including any partial result you could have salvaged.
+(See the long-standing upstream report: langchain-ai/langgraph#5672, "Run
+Cancellation Causes Loss of Streamed State Not Yet Persisted as a Checkpoint".)
+
+The fix
+-------
+Establish **one** binding deadline at node entry and make every inner timeout
+*clamp to it* instead of re-deriving its own. Then your inner calls always
+yield at the node boundary — with a few hundred ms of grace — *before* the
+watchdog fires, so a ``try/except`` around the inner call actually runs and you
+return a complete-but-shorter answer instead of nothing.
+
+How it threads through async code
+---------------------------------
+The deadline lives in a :class:`contextvars.ContextVar`. ``asyncio`` tasks copy
+the ambient context at creation, so a scope opened before you ``await`` is
+visible to the agent task *and every subagent task it spawns*. The default is
+``None`` (no scope) and every consumer **fails open** — code that runs outside a
+scope (unit tests, direct invocations) keeps its existing arithmetic unchanged.
+
+Quick start
+-----------
+>>> import asyncio
+>>> from langgraph_node_deadline import node_deadline_in, cooperative_wait_for
+>>> async def node():
+...     # this node is allowed ~1.8s of cooperative runtime
+...     with node_deadline_in(1.8):
+...         try:
+...             # the planner "wants" 5s but will be clamped to what's left
+...             return await cooperative_wait_for(planner(), budget_secs=5.0)
+...         except asyncio.TimeoutError:
+...             return salvage_partial()   # runs BEFORE the outer watchdog kills us
+
+See ``examples/salvage_demo.py`` for a runnable, dependency-free contrast
+between the naive path (work discarded) and the clamped path (work salvaged).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Awaitable, Iterator, Optional, TypeVar
+
+__all__ = [
+    "node_deadline",
+    "node_deadline_scope",
+    "node_deadline_in",
+    "get_node_deadline_remaining_secs",
+    "node_deadline_exceeded",
+    "clamp_to_node_deadline",
+    "cooperative_wait_for",
+]
+
+__version__ = "0.1.0"
+
+_T = TypeVar("_T")
+
+_node_deadline_monotonic: ContextVar[Optional[float]] = ContextVar(
+    "node_deadline_monotonic", default=None
+)
+
+
+@contextmanager
+def node_deadline_scope(deadline_monotonic: Optional[float]) -> Iterator[None]:
+    """Scope the binding cooperative deadline, on a ``time.monotonic()`` basis.
+
+    Args:
+        deadline_monotonic: An absolute ``time.monotonic()`` timestamp by which
+            inner work should have yielded. Pass ``None`` to explicitly clear
+            the scope (fail-open) — used when the outer layer has no hard cap.
+
+    The scope is restored on exit, so nesting is safe: an inner, tighter
+    deadline reverts to the outer one when its ``with`` block ends.
+    """
+    token = _node_deadline_monotonic.set(deadline_monotonic)
+    try:
+        yield
+    finally:
+        _node_deadline_monotonic.reset(token)
+
+
+# Primary public alias — reads naturally at call sites that already hold an
+# absolute monotonic deadline: ``with node_deadline(executor_deadline): ...``
+node_deadline = node_deadline_scope
+
+
+@contextmanager
+def node_deadline_in(seconds: float) -> Iterator[None]:
+    """Convenience scope expressed as a *relative* budget from now.
+
+    ``with node_deadline_in(30): ...`` is exactly
+    ``with node_deadline_scope(time.monotonic() + 30): ...`` — use it at node
+    entry when you think in "this node gets N seconds" rather than in absolute
+    monotonic timestamps.
+    """
+    with node_deadline_scope(time.monotonic() + seconds):
+        yield
+
+
+def get_node_deadline_remaining_secs() -> Optional[float]:
+    """Seconds until the binding deadline, or ``None`` when no scope is active.
+
+    Never negative — a passed deadline reports ``0.0``.
+    """
+    deadline = _node_deadline_monotonic.get()
+    if deadline is None:
+        return None
+    return max(0.0, deadline - time.monotonic())
+
+
+def node_deadline_exceeded() -> bool:
+    """``True`` only when a scope is active *and* its deadline has passed.
+
+    Returns ``False`` when no scope is active (fail-open), so it is safe to use
+    as a cooperative loop guard: ``while not node_deadline_exceeded(): ...``.
+    """
+    remaining = get_node_deadline_remaining_secs()
+    return remaining is not None and remaining <= 0.0
+
+
+def clamp_to_node_deadline(budget_secs: float, *, reserve_secs: float = 0.0) -> float:
+    """Clamp a proposed budget/timeout to the real deadline remaining.
+
+    This is the core primitive: every inner layer that is about to start a
+    timed operation passes its desired budget through here, so it can never
+    exceed the binding node deadline.
+
+    Args:
+        budget_secs: The timeout the inner layer *wants*.
+        reserve_secs: Headroom to carve below the deadline (e.g. a phase
+            transition / finalize buffer) so the clamped work still has time to
+            wrap up before the cooperative cancel.
+
+    Returns:
+        ``budget_secs`` unchanged when no deadline scope is active (fail-open);
+        otherwise ``min(budget_secs, remaining - reserve_secs)``, floored at
+        ``0.0`` so it is always a valid ``asyncio.wait_for`` timeout.
+    """
+    remaining = get_node_deadline_remaining_secs()
+    if remaining is None:
+        return budget_secs
+    return max(0.0, min(budget_secs, remaining - reserve_secs))
+
+
+async def cooperative_wait_for(
+    awaitable: Awaitable[_T],
+    budget_secs: float,
+    *,
+    reserve_secs: float = 0.0,
+) -> _T:
+    """``asyncio.wait_for`` that never outlasts the binding node deadline.
+
+    Equivalent to ``asyncio.wait_for(awaitable, clamp_to_node_deadline(...))``.
+    Because the clamped timeout fires *inside* the node, an
+    ``asyncio.TimeoutError`` you catch here runs your salvage path **before**
+    an outer watchdog can cancel the node and discard the work.
+
+    With no active deadline scope this is a plain ``wait_for(awaitable,
+    budget_secs)`` — fail-open, no behavior change.
+
+    Raises:
+        asyncio.TimeoutError: if the clamped budget elapses first.
+    """
+    timeout = clamp_to_node_deadline(budget_secs, reserve_secs=reserve_secs)
+    return await asyncio.wait_for(awaitable, timeout)

langgraph_node_deadline-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: langgraph-node-deadline
+Version: 0.1.0
+Summary: One binding deadline for every inner timeout in a LangGraph node — clamp inner budgets to the cooperative deadline so work salvages instead of getting killed by the watchdog.
+Project-URL: Homepage, https://github.com/youknowfred/langgraph-node-deadline
+Project-URL: Issues, https://github.com/youknowfred/langgraph-node-deadline/issues
+Author: Fred Becker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,asyncio,cancellation,deadline,langchain,langgraph,llm,reliability,timeout
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langgraph-node-deadline
+
+**One binding deadline for every inner timeout in a LangGraph node.** Clamp inner
+budgets to the node's cooperative deadline so heavy work **salvages a partial
+result** instead of getting hard-killed by the watchdog and discarding everything.
+
+Zero runtime dependencies. ~120 lines. Python 3.9+.
+
+```bash
+pip install langgraph-node-deadline
+```
+
+---
+
+## The problem
+
+A LangGraph node that does real work has *several layers each re-deriving their
+own clock*: an outer `TimeoutPolicy` watchdog, an inner agent/tool budget, a
+retry loop, a sub-planner that "wants" 60 seconds. When those clocks disagree,
+the inner layers happily dispatch work the outer watchdog is **guaranteed to
+kill** — and the kill is uncooperative. It cancels the node and **throws away
+everything**, including the partial answer you could have returned.
+
+You've seen the symptom: a long run times out into *nothing* after burning
+minutes of paid LLM calls, and the user just sees "it failed." The upstream
+issue is real and open: [langchain-ai/langgraph#5672 — *Run Cancellation Causes
+Loss of Streamed State Not Yet Persisted*](https://github.com/langchain-ai/langgraph/issues/5672).
+
+The trap, distilled: if your cooperative cancel and the watchdog are pinned to
+the **same** number, the watchdog clock starts at *node entry — before your code
+runs* — so your cancel loses the race deterministically. Equal timeouts lose.
+
+## The fix
+
+Set **one** deadline at node entry. Make every inner timeout *clamp to it*
+instead of re-deriving its own. Now inner calls yield at the node boundary, with
+a little grace, **before** the watchdog fires — so your `try/except` actually
+runs and you return a complete-but-shorter answer.
+
+```python
+import asyncio
+from langgraph_node_deadline import node_deadline_in, cooperative_wait_for
+
+async def my_node(state):
+    # this node gets ~1.8s of cooperative runtime (a hair under its watchdog)
+    with node_deadline_in(1.8):
+        try:
+            # the planner asks for 5s, but gets clamped to what's actually left
+            result = await cooperative_wait_for(plan_and_write(state), budget_secs=5.0)
+            return {"draft": result}
+        except asyncio.TimeoutError:
+            # runs BEFORE the watchdog can kill us — keep the partial work
+            return {"draft": salvage_partial(state)}
+```
+
+## See it lose vs. salvage (30 seconds, no LangGraph needed)
+
+```bash
+python examples/salvage_demo.py
+```
+
+```
+Outer watchdog (LangGraph TimeoutPolicy): 2.0s  |  inner planner wants ~5s
+
+  NAIVE   (inner ignores the node deadline)
+    -> LOST in 2.00s — outer watchdog cancelled the node, salvage code never ran, ALL work discarded
+
+  CLAMPED (inner clamps to the node deadline)
+    -> SALVAGED in 1.80s — kept 3 steps: ['step 1', 'step 2', 'step 3']
+```
+
+Same work, same watchdog. One import decides whether you keep anything.
+
+## Wiring it into a real LangGraph node
+
+Set the scope to a hair under whatever cap the executor enforces, then clamp
+every inner timed call through it:
+
+```python
+from langgraph_node_deadline import node_deadline_in, clamp_to_node_deadline, cooperative_wait_for
+
+NODE_CAP_SECS = 30.0   # match this to your TimeoutPolicy, minus a small grace
+
+async def research_node(state):
+    with node_deadline_in(NODE_CAP_SECS - 1.0):   # leave 1s of grace under the watchdog
+        # an inner retry loop, sub-agent, or tool call — all clamp to the same deadline
+        per_call = clamp_to_node_deadline(15.0, reserve_secs=2.0)  # reserve finalize headroom
+        chunks = await cooperative_wait_for(retrieve(state), budget_secs=per_call)
+        return {"chunks": chunks}
+```
+
+Because the deadline lives in a `contextvars.ContextVar`, and `asyncio` copies
+the ambient context when it creates a task, the scope you open before you
+`await` is visible to the agent task **and every subagent task it spawns** — no
+threading the deadline through call signatures.
+
+## API
+
+| Symbol | What it does |
+| --- | --- |
+| `node_deadline_in(seconds)` | Context manager. Set the binding deadline to `now + seconds`. Use at node entry. |
+| `node_deadline_scope(deadline_monotonic)` | Context manager. Set the deadline to an absolute `time.monotonic()` timestamp (or `None` to clear). `node_deadline` is an alias. |
+| `clamp_to_node_deadline(budget_secs, *, reserve_secs=0.0)` | **The core primitive.** Returns `min(budget_secs, remaining - reserve_secs)`, floored at 0. Returns `budget_secs` unchanged when no scope is active. |
+| `cooperative_wait_for(awaitable, budget_secs, *, reserve_secs=0.0)` | `asyncio.wait_for` that never outlasts the node deadline. Raises `asyncio.TimeoutError` on the clamped budget. |
+| `get_node_deadline_remaining_secs()` | Seconds left, or `None` if no scope. Never negative. |
+| `node_deadline_exceeded()` | `True` only when a scope is active *and* its deadline has passed. Safe loop guard. |
+
+**Fail-open by design.** With no active scope, every function behaves as if it
+weren't there — so adding it to one node never changes the behavior of the rest
+of your graph, your tests, or direct invocations.
+
+## Why a whole package for ~120 lines
+
+Because the *lesson* is the hard part, not the code. This is the
+[`derive-don't-pin`](https://github.com/langchain-ai/langgraph/issues/5672)
+discipline extracted from a production agent that paid for it: a synthesis pool
+that believed it had 43.5 seconds left *nine seconds before* the watchdog killed
+the node — because four inner layers each trusted their own clock and none knew
+the one the executor was actually enforcing. One binding deadline fixes the
+entire class of bug.
+
+## License
+
+MIT © 2026 Fred Becker. See [LICENSE](LICENSE).

langgraph_node_deadline-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+langgraph_node_deadline/__init__.py,sha256=KlXL27hH4VoJsU8hnq4TBti981gRZzb8aiPDQjUi5js,6837
+langgraph_node_deadline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_node_deadline-0.1.0.dist-info/METADATA,sha256=0sk0CUg72YpzqEkUWwiZJ2Twj1b4PY-q3HziL9Wulfg,6914
+langgraph_node_deadline-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+langgraph_node_deadline-0.1.0.dist-info/licenses/LICENSE,sha256=HPhk1qB5a83Tl7J8SisvMzDk0XCLEn_BzWTNSCeMNdo,1068
+langgraph_node_deadline-0.1.0.dist-info/RECORD,,

langgraph_node_deadline-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

langgraph_node_deadline-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fred Becker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.