langgraph-wait 0.2.1__tar.gz → 0.4.0__tar.gz

{langgraph_wait-0.2.1 → langgraph_wait-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langgraph-wait
-Version: 0.2.1
+Version: 0.4.0
 Summary: The LangGraph side of agent-wait: ask() to declare a question at the interrupt site, an adapter that reads what a thread is parked on, and helpers for the host's start/resume routing.
 Project-URL: Homepage, https://skamalj.github.io/agent-wait/
 Project-URL: Documentation, https://skamalj.github.io/agent-wait/
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: agent-wait<0.3,>=0.2
+Requires-Dist: agent-wait<0.5,>=0.4
 Requires-Dist: langgraph<2,>=1.2
 Description-Content-Type: text/markdown
 
@@ -33,21 +33,19 @@ pip install langgraph-wait          # pulls in agent-wait
 ```
 
 ```python
-from langgraph_wait import ask, LangGraphAdapter, is_answer, resume_command
+from langgraph_wait import hitl, publish_interrupts
 ```
 
-* **`ask(question, policy)`** — a thin wrapper over `interrupt()`. The node pauses exactly
-  as LangGraph pauses; the policy rides along inside the interrupt value and comes back
-  out in the published envelope. A plain `interrupt(value)` also works, with the default
-  policy.
-* **`LangGraphAdapter(graph)`** — three methods. `pending()` reads what a thread is parked
-  on and filters LangGraph's `tasks[*].interrupts` over-report on `task.result`.
-* **`is_answer(message)`** / **`resume_command(message)`** — pure functions for the host's
-  router. `interrupt_id` present means resume; the `Command` is keyed by interrupt id so
-  parallel interrupts resume independently.
+* **`@hitl(policy)`** — on any function, under `@tool` if it is a tool. Calling it inside a
+  run parks the graph on `{"function", "args"}`. `{"action": "approve"}` runs the body;
+  anything else is returned in its place. A function with a `decision` parameter always
+  runs and receives the answer. `mode="async"` makes the decorator the publisher: it
+  announces and returns pending without parking.
+* **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
+  `result["__interrupt__"]` and hands one envelope per question to the announcers.
 
-Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
-`ToolNode` share an id on 1.2.x (langgraph #6626), and this package documents rather
-than hides that.
+Requires `langgraph >= 1.2`. Not compatible with LangChain's `HumanInTheLoopMiddleware`
+on the same tool (two interrupts for one approval). One `interrupt()` per node on 1.2.x
+(langgraph #6626).
 
 Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.4.0/README.md

@@ -0,0 +1,26 @@
+# langgraph-wait
+
+The LangGraph side of [agent-wait](https://pypi.org/project/agent-wait/) — get a LangGraph
+interrupt out of the process, and the answer back in.
+
+```bash
+pip install langgraph-wait          # pulls in agent-wait
+```
+
+```python
+from langgraph_wait import hitl, publish_interrupts
+```
+
+* **`@hitl(policy)`** — on any function, under `@tool` if it is a tool. Calling it inside a
+  run parks the graph on `{"function", "args"}`. `{"action": "approve"}` runs the body;
+  anything else is returned in its place. A function with a `decision` parameter always
+  runs and receives the answer. `mode="async"` makes the decorator the publisher: it
+  announces and returns pending without parking.
+* **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
+  `result["__interrupt__"]` and hands one envelope per question to the announcers.
+
+Requires `langgraph >= 1.2`. Not compatible with LangChain's `HumanInTheLoopMiddleware`
+on the same tool (two interrupts for one approval). One `interrupt()` per node on 1.2.x
+(langgraph #6626).
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

{langgraph_wait-0.2.1 → langgraph_wait-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-wait"
-version = "0.2.1"
+version = "0.4.0"
 description = "The LangGraph side of agent-wait: ask() to declare a question at the interrupt site, an adapter that reads what a thread is parked on, and helpers for the host's start/resume routing."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -18,7 +18,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
     "Typing :: Typed",
 ]
-dependencies = ["agent-wait>=0.2,<0.3", "langgraph>=1.2,<2"]
+dependencies = ["agent-wait>=0.4,<0.5", "langgraph>=1.2,<2"]
 
 [project.urls]
 Homepage = "https://skamalj.github.io/agent-wait/"

langgraph_wait-0.4.0/src/langgraph_wait/__init__.py

@@ -0,0 +1,6 @@
+"""langgraph-wait: `@hitl` in the graph, `publish_interrupts()` after the run."""
+
+from .hitl import hitl
+from .publish import publish_interrupts, questions_in
+
+__all__ = ["hitl", "publish_interrupts", "questions_in"]

langgraph_wait-0.4.0/src/langgraph_wait/_interrupt.py

@@ -0,0 +1,43 @@
+"""The interrupt value `@hitl` raises, and how `publish_interrupts` reads it back.
+
+Private. An `Interrupt` has one payload and LangGraph offers no side channel, so the
+policy and the source ride inside the value next to the question:
+
+    {"question": {...}, "__wait__": {policy}, "__source__": {...}}
+
+`unwrap()` reverses it. A value without `__wait__` -- a bare `interrupt(x)` from a graph
+that has never heard of this library -- is read as a question with the default policy.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from agent_wait import WaitPolicy, check_question_size
+from langgraph.types import interrupt
+
+WAIT_KEY = "__wait__"
+SOURCE_KEY = "__source__"
+QUESTION_KEY = "question"
+
+
+def raise_question(question: Any, policy: WaitPolicy, source: Mapping[str, Any] | None) -> Any:
+    """Park the graph on `question`; return the answer, verbatim, on resume."""
+    check_question_size(question)
+    value: dict[str, Any] = {QUESTION_KEY: question, WAIT_KEY: policy.to_dict()}
+    if source:
+        value[SOURCE_KEY] = dict(source)
+    return interrupt(value)
+
+
+def unwrap(value: Any) -> tuple[Any, WaitPolicy, Mapping[str, Any] | None]:
+    """`(question, policy, source)` from an interrupt value of either shape."""
+    if isinstance(value, Mapping) and WAIT_KEY in value:
+        source = value.get(SOURCE_KEY)
+        return (
+            value.get(QUESTION_KEY),
+            WaitPolicy.from_dict(value.get(WAIT_KEY)),
+            dict(source) if isinstance(source, Mapping) else None,  # pyright: ignore[reportUnknownArgumentType]
+        )
+    return value, WaitPolicy(), None

langgraph_wait-0.4.0/src/langgraph_wait/hitl.py

@@ -0,0 +1,132 @@
+"""`@hitl` -- make a function interruptible.
+
+    @tool
+    @hitl(WaitPolicy(timeout="P1D", default={"action": "reject"}, tags={"approver_group": "finance"}))
+    def issue_refund(order_id: str, amount: int) -> str:
+        ...
+
+That is the whole declaration. Calling the decorated function inside a run raises a
+LangGraph interrupt with `{"function": "issue_refund", "args": {...}}` as the question;
+`publish_interrupts()` after the run announces it; the answer comes back as
+`Command(resume={question_id: answer})`, and:
+
+    {"action": "approve"}                    -> the body runs with its original args
+    {"action": "approve", "args": {...}}     -> the body runs with these args instead
+    anything else                            -> the body does NOT run; the answer is
+                                                returned in its place, so a model sees why
+
+## Getting the answer itself: the `decision` parameter
+
+A tool usually only needs to know whether to run. A node usually needs the answer. If
+the decorated function has a parameter named `decision` (rename it with `decision=`),
+it **always** runs and receives the answer there, approve or not:
+
+    @hitl(FINANCE)
+    def review(state, decision=None):
+        return {"decision": decision}        # verbatim: {"action": "approve", "note": "ok"}
+
+## `mode="async"` -- the thread does not park
+
+    @tool
+    @hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic), DynamoDbAnnounce(table)])
+    def issue_refund(order_id: str, amount: int) -> str: ...
+
+The decorator *is* the publisher. The call announces the question through the announcers
+given here and returns `{"status": "pending_approval", "question_id": ...}` without
+running the body. Nothing is parked; nothing is called after the run; the graph carries
+on. The decision arrives later as a **new message** and the graph acts on it however you
+designed it. This is the mode for a single-thread channel like WhatsApp, where the
+approver is not the person on the thread. LangGraph remembers nothing about the
+question; whatever record you keep (a `DynamoDbAnnounce` row is one) is the only one.
+
+`question_id` is `sha256(thread | function | args)`, so the same call on the same thread
+is the same question and a consumer sees one, not two.
+
+## Not compatible with `HumanInTheLoopMiddleware`
+
+LangChain's `create_agent` middleware interrupts *before* a tool is called, in its own
+shape, with its own resume format. Putting `@hitl` on a tool the middleware also
+intercepts interrupts twice -- once by the middleware, then again inside the tool when it
+finally runs. Use one or the other. This library is the other.
+
+## One `interrupt()` per node
+
+Two `@hitl` functions dispatched by the same `ToolNode` share an interrupt id on
+langgraph 1.2.x (#6626); only one surfaces per run (#6624). Give each interrupting tool
+its own node.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Literal
+
+from agent_wait import AnnounceAdapter, Question, WaitPolicy, canonical_json, publish
+
+from ._interrupt import raise_question
+
+Mode = Literal["interrupt", "async"]
+
+
+def question_id_for(thread_id: str, function: str, args: Mapping[str, Any]) -> str:
+    """Deterministic: the same call on the same thread is the same question."""
+    return hashlib.sha256(f"{thread_id}|{function}|{canonical_json(dict(args))}".encode()).hexdigest()[:32]
+
+
+def _thread_id() -> str:
+    from langgraph.config import get_config
+
+    thread_id = get_config().get("configurable", {}).get("thread_id")
+    if not thread_id:
+        raise RuntimeError("@hitl(mode='async') needs a thread_id in the run config")
+    return str(thread_id)
+
+
+def hitl(
+    policy: WaitPolicy | None = None,
+    *,
+    mode: Mode = "interrupt",
+    announce: Sequence[AnnounceAdapter] | None = None,
+    decision: str = "decision",
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Make a function interruptible. See the module docstring."""
+    resolved = policy or WaitPolicy(allowed_actions=("approve", "reject"))
+    if mode == "async" and not announce:
+        raise ValueError("@hitl(mode='async') publishes from inside the function, so it needs announce=[...]")
+    announcers: Sequence[AnnounceAdapter] = list(announce or ())
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        name = fn.__name__
+        signature = inspect.signature(fn)
+        wants_decision = decision in signature.parameters
+        source = {"function": name}
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound = signature.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+            call_args: dict[str, Any] = {k: v for k, v in bound.arguments.items() if k != decision}
+            question = {"function": name, "args": call_args}
+
+            if mode == "async":
+                thread_id = _thread_id()
+                qid = question_id_for(thread_id, name, call_args)
+                publish([Question(qid, question, resolved, source=source)], thread_id, announcers)
+                return {"status": "pending_approval", "question_id": qid, "function": name}
+
+            answer = raise_question(question, resolved, source)
+            if wants_decision:
+                return fn(**call_args, **{decision: answer})
+            if isinstance(answer, Mapping) and answer.get("action") == "approve":
+                edited = answer.get("args")
+                merged = {**call_args, **dict(edited)} if isinstance(edited, Mapping) else call_args  # pyright: ignore[reportUnknownArgumentType]
+                return fn(**merged)
+            return answer
+
+        wrapper.__hitl__ = {"mode": mode, "policy": resolved}  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate

langgraph_wait-0.4.0/src/langgraph_wait/publish.py

@@ -0,0 +1,57 @@
+"""`publish_interrupts()` -- announce what `graph.invoke()` just parked on.
+
+    result = graph.invoke(value, config)
+    publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+
+When a `@hitl` function is called (or any node calls `interrupt()`), LangGraph returns
+the run's output with an `__interrupt__` entry: a sequence of `Interrupt` objects, each
+with `.id` and `.value` and nothing else (`ns`, `when`, `resumable` were removed in
+langgraph 0.6). This reads that entry and hands one envelope per question to the
+announcers. No `__interrupt__`, nothing happens. `stream()` yields the same shape as a
+chunk, so it works on a chunk.
+
+A bare `interrupt(value)` from a node that never heard of this library is published too,
+with `value` as the question and the default policy.
+
+Nothing here runs the graph, reads its state, or resumes anything.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from agent_wait import AnnounceAdapter, Clock, EntryPoint, Question, WaitEnvelope, publish
+
+from ._interrupt import unwrap
+
+INTERRUPT_KEY = "__interrupt__"
+
+
+def questions_in(result: Any) -> list[Question]:
+    """The questions a run returned, from its `__interrupt__`. `[]` if it did not park."""
+    if not isinstance(result, Mapping):
+        return []
+    raw = result.get(INTERRUPT_KEY)  # pyright: ignore[reportUnknownMemberType]
+    if not raw:
+        return []
+    out: list[Question] = []
+    for item in raw:  # pyright: ignore[reportUnknownVariableType]
+        question, policy, source = unwrap(getattr(item, "value", None))
+        out.append(Question(str(getattr(item, "id", "")), question, policy, source=source))
+    return out
+
+
+def publish_interrupts(
+    result: Any,
+    thread_id: str,
+    announce: Sequence[AnnounceAdapter],
+    *,
+    reply_to: EntryPoint | None = None,
+    clock: Clock | None = None,
+) -> list[WaitEnvelope]:
+    """Announce every question in `result`. Returns the envelopes sent; `[]` if none."""
+    questions = questions_in(result)
+    if not questions:
+        return []
+    return publish(questions, thread_id, announce, reply_to=reply_to, clock=clock)

langgraph_wait-0.2.1/README.md

@@ -1,28 +0,0 @@
-# langgraph-wait
-
-The LangGraph side of [agent-wait](https://pypi.org/project/agent-wait/) — get a LangGraph
-interrupt out of the process, and the answer back in.
-
-```bash
-pip install langgraph-wait          # pulls in agent-wait
-```
-
-```python
-from langgraph_wait import ask, LangGraphAdapter, is_answer, resume_command
-```
-
-* **`ask(question, policy)`** — a thin wrapper over `interrupt()`. The node pauses exactly
-  as LangGraph pauses; the policy rides along inside the interrupt value and comes back
-  out in the published envelope. A plain `interrupt(value)` also works, with the default
-  policy.
-* **`LangGraphAdapter(graph)`** — three methods. `pending()` reads what a thread is parked
-  on and filters LangGraph's `tasks[*].interrupts` over-report on `task.result`.
-* **`is_answer(message)`** / **`resume_command(message)`** — pure functions for the host's
-  router. `interrupt_id` present means resume; the `Command` is keyed by interrupt id so
-  parallel interrupts resume independently.
-
-Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
-`ToolNode` share an id on 1.2.x (langgraph #6626), and this package documents rather
-than hides that.
-
-Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.2.1/src/langgraph_wait/__init__.py

@@ -1,14 +0,0 @@
-"""langgraph-wait: the LangGraph side of agent-wait."""
-
-from .adapter import LangGraphAdapter
-from .ask import WAIT_KEY, ask, unwrap
-from .resume import is_answer, resume_command
-
-__all__ = [
-    "WAIT_KEY",
-    "LangGraphAdapter",
-    "ask",
-    "is_answer",
-    "resume_command",
-    "unwrap",
-]

langgraph_wait-0.2.1/src/langgraph_wait/adapter.py

@@ -1,87 +0,0 @@
-"""`LangGraphAdapter` -- three methods, and the one LangGraph bug that matters.
-
-The core never imports LangGraph. Everything framework-specific lives here, which is also
-where the framework's rough edges get handled.
-
-## `get_state().tasks[*].interrupts` over-reports
-
-This is the finding the whole adapter is shaped around (langgraph #4796 / #6792,
-reproduced against 1.2.11 in `tests/test_spike_langgraph.py`). With two parallel
-interrupts, resume one, and the *finished* task still lists its interrupt id. Anyone
-building "what is this thread waiting on?" from `tasks[*].interrupts` alone gets an
-interrupt the graph has already moved past -- and the failure mode is republishing an
-approval button for a node that already ran, or resuming it a second time.
-
-The discriminator is `task.result`: it holds the finished task's return value and is
-`None` while the task is genuinely parked. `pending()` filters on it, and the spike test
-pins the behaviour so a future LangGraph fix shows up as a failing test rather than as
-silence.
-
-## What else was verified empirically, against langgraph 1.2.11
-
-* **`Interrupt.id` is stable** across `invoke(None, config)` re-entry and across
-  resume-from-checkpoint. This is what makes `dedupe_key` work: a republished envelope
-  carries the same id, so consumers can discard it.
-* **Interrupts raised inside a subgraph** surface on the parent's state against the
-  subgraph node's task, with a stable id. `subgraphs=True` was not needed, and resuming
-  by id works through the parent.
-"""
-
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Any
-
-from agent_wait import PendingInterrupt
-
-from .ask import unwrap
-
-
-class LangGraphAdapter:
-    """Wraps a compiled graph. Requires langgraph >= 1.2."""
-
-    name = "langgraph"
-
-    def __init__(self, graph: Any) -> None:
-        self.graph = graph
-
-    def config_for(self, thread_id: str) -> dict[str, Any]:
-        return {"configurable": {"thread_id": thread_id}}
-
-    def invoke(self, value: Any, config: Any) -> Any:
-        """Run the graph. `value` is the caller's -- fresh input, or a `Command`."""
-        return self.graph.invoke(value, config)
-
-    def pending(self, thread_id: str) -> list[PendingInterrupt]:
-        """What this thread is parked on right now. `[]` if it has never run."""
-        state = self.graph.get_state(self.config_for(thread_id))
-        asked_at = _epoch(getattr(state, "created_at", None))
-
-        out: list[PendingInterrupt] = []
-        for task in getattr(state, "tasks", ()) or ():
-            # See the module docstring. A task that has produced a result is finished,
-            # whatever its `interrupts` list still claims.
-            if getattr(task, "result", None) is not None:
-                continue
-            for raw in getattr(task, "interrupts", ()) or ():
-                question, policy = unwrap(getattr(raw, "value", None))
-                out.append(
-                    PendingInterrupt(
-                        interrupt_id=str(raw.id),
-                        question=question,
-                        policy=policy,
-                        asked_at=asked_at,
-                    )
-                )
-        return out
-
-
-def _epoch(created_at: Any) -> float | None:
-    """LangGraph stamps checkpoints with an ISO-8601 string. Anchor `expires_at` to it
-    so a republished question keeps its original deadline."""
-    if not isinstance(created_at, str):
-        return None
-    try:
-        return datetime.fromisoformat(created_at).timestamp()
-    except ValueError:
-        return None

langgraph_wait-0.2.1/src/langgraph_wait/ask.py

@@ -1,52 +0,0 @@
-"""`ask()` -- the one line a graph author writes.
-
-    decision = ask({"kind": "refund_approval", "amount": amount},
-                   policy=WaitPolicy(timeout="P3D", allowed_actions=("approve", "reject")))
-
-It is a thin wrapper over `langgraph.types.interrupt()`, and thin is the point: the node
-still pauses exactly the way LangGraph pauses, the checkpointer still does its job, and
-nothing about the graph changes. What `ask()` adds is the *policy* -- how long this
-question should stand, what to assume if nobody answers, which answers are meaningful --
-carried inside the interrupt value under `__wait__`.
-
-That key is the only channel available. An interrupt has one payload and LangGraph does
-not offer a side channel for metadata, so the policy rides with the question and
-`unwrap()` peels it back off.
-
-A plain `interrupt(value)` with no `ask()` still works. It is read as a question with the
-default policy, so a graph that already interrupts gets published without any edit at all.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from agent_wait import WaitPolicy, check_question_size
-from langgraph.types import interrupt
-
-WAIT_KEY = "__wait__"
-QUESTION_KEY = "question"
-
-
-def ask(question: Any, policy: WaitPolicy | None = None) -> Any:
-    """Park the graph on `question` and return the answer when it arrives.
-
-    On the first pass this raises through `interrupt()` and the node does not return. On
-    resume it returns the answer message's `answer` field, verbatim -- whatever the
-    consumer put there. The library does not wrap it, merge into it or add an action to
-    it; what was sent is what the node sees.
-    """
-    check_question_size(question)
-    resolved = policy or WaitPolicy()
-    return interrupt({QUESTION_KEY: question, WAIT_KEY: resolved.to_dict()})
-
-
-def unwrap(value: Any) -> tuple[Any, WaitPolicy]:
-    """Split an interrupt value back into `(question, policy)`.
-
-    Handles both shapes: one raised by `ask()`, and a bare `interrupt(value)` from a
-    graph that has never heard of this library.
-    """
-    if isinstance(value, dict) and WAIT_KEY in value:
-        return value.get(QUESTION_KEY), WaitPolicy.from_dict(value.get(WAIT_KEY))
-    return value, WaitPolicy()

langgraph_wait-0.2.1/src/langgraph_wait/resume.py

@@ -1,39 +0,0 @@
-"""`resume_command()` -- turn an answer message into the thing you pass to `invoke()`.
-
-A pure function. It makes no decisions, reads nothing and writes nothing; it exists so
-that the one LangGraph-specific detail in the inbound message format -- that a resume is
-keyed by interrupt id, so that parallel interrupts resume independently -- is written
-down once instead of in every consumer.
-
-    def handle(message):
-        if is_answer(message):
-            return agent.invoke(resume_command(message), message["thread_id"])
-        return agent.invoke(message["input"], message["thread_id"])
-
-`Command(resume=value)` -- the un-keyed form -- hands the same value to *every* parked
-interrupt on the thread. With two approvals outstanding that is one click approving both,
-which is why this builds the dict form even when there is only one.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping
-from typing import Any
-
-from langgraph.types import Command
-
-
-def is_answer(message: Mapping[str, Any]) -> bool:
-    """`interrupt_id` present means resume; absent means start. That is the whole rule.
-
-    It holds because the publisher ships a filled-in `reply_with` stub in every envelope
-    and the consumer echoes it back, so the key is there by construction rather than by
-    the consumer remembering to add it.
-    """
-    return bool(message.get("interrupt_id"))
-
-
-def resume_command(message: Mapping[str, Any]) -> Command:
-    """Build the resume for one answer message. Raises `KeyError` if it is a start."""
-    interrupt_id = message["interrupt_id"]
-    return Command(resume={str(interrupt_id): message.get("answer")})