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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langgraph-wait
-Version: 0.2.1
+Version: 0.3.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.4,>=0.3
 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 ask, 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.
+* **`ask(question, policy)`** — a thin wrapper over `interrupt()`; the policy rides along
+  inside the interrupt value. A plain `interrupt(value)` also works, with the default policy.
+* **`@hitl(policy)`** — on a tool function, under `@tool`. Calls `ask()` with `{tool, args}`
+  before the tool runs. `mode="async"` makes the decorator the publisher: it announces and
+  returns pending without parking the thread.
+* **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
+  `result["__interrupt__"]` and hands one envelope per question to the announcers.
+  Understands `ask()`, bare `interrupt()`, and `HumanInTheLoopMiddleware` batches.
 
 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.
+`ToolNode` share an id on 1.2.x (langgraph #6626); use the middleware, which batches.
 
 Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.3.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 ask, hitl, publish_interrupts
+```
+
+* **`ask(question, policy)`** — a thin wrapper over `interrupt()`; the policy rides along
+  inside the interrupt value. A plain `interrupt(value)` also works, with the default policy.
+* **`@hitl(policy)`** — on a tool function, under `@tool`. Calls `ask()` with `{tool, args}`
+  before the tool runs. `mode="async"` makes the decorator the publisher: it announces and
+  returns pending without parking the thread.
+* **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
+  `result["__interrupt__"]` and hands one envelope per question to the announcers.
+  Understands `ask()`, bare `interrupt()`, and `HumanInTheLoopMiddleware` batches.
+
+Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
+`ToolNode` share an id on 1.2.x (langgraph #6626); use the middleware, which batches.
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

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

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-wait"
-version = "0.2.1"
+version = "0.3.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.3,<0.4", "langgraph>=1.2,<2"]
 
 [project.urls]
 Homepage = "https://skamalj.github.io/agent-wait/"

langgraph_wait-0.3.0/src/langgraph_wait/__init__.py

@@ -0,0 +1,16 @@
+"""langgraph-wait: `ask()` or `@hitl` in the graph, `publish_interrupts()` after the run."""
+
+from .ask import WAIT_KEY, ask, unwrap
+from .hitl import hitl, policy_for, question_id_for
+from .publish import publish_interrupts, questions_in
+
+__all__ = [
+    "WAIT_KEY",
+    "ask",
+    "hitl",
+    "policy_for",
+    "publish_interrupts",
+    "question_id_for",
+    "questions_in",
+    "unwrap",
+]

{langgraph_wait-0.2.1 → langgraph_wait-0.3.0}/src/langgraph_wait/ask.py

@@ -19,16 +19,18 @@ default policy, so a graph that already interrupts gets published without any ed
 
 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 ask(question: Any, policy: WaitPolicy | None = None) -> Any:
+def ask(question: Any, policy: WaitPolicy | None = None, *, source: Mapping[str, Any] | 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
@@ -38,7 +40,10 @@ def ask(question: Any, policy: WaitPolicy | None = None) -> Any:
     """
     check_question_size(question)
     resolved = policy or WaitPolicy()
-    return interrupt({QUESTION_KEY: question, WAIT_KEY: resolved.to_dict()})
+    value: dict[str, Any] = {QUESTION_KEY: question, WAIT_KEY: resolved.to_dict()}
+    if source:
+        value[SOURCE_KEY] = dict(source)
+    return interrupt(value)
 
 
 def unwrap(value: Any) -> tuple[Any, WaitPolicy]:

langgraph_wait-0.3.0/src/langgraph_wait/hitl.py

@@ -0,0 +1,146 @@
+"""`@hitl` -- mark a tool as needing a human, in one of two ways.
+
+    @tool
+    @hitl(WaitPolicy(timeout="P1D", default={"action": "reject"}, tags={"approver_group": "finance"}))
+    def issue_refund(order_id: str, amount: int) -> str:
+        ...
+
+Apply it *under* `@tool`, on the function. It registers the policy against the tool's
+name (so `publish_interrupts` can find it for middleware-batched interrupts too) and
+wraps the call in one of two behaviours.
+
+## `mode="interrupt"` (default) -- the thread parks
+
+The wrapper calls `ask()` with `{"tool": name, "args": {...}}` before running the tool.
+The graph stops; `publish_interrupts()` after the run announces it; the answer comes back
+as `Command(resume={question_id: decision})` and the tool runs, or does not:
+
+    {"action": "approve"}                      -> the tool runs with its original args
+    {"action": "approve", "args": {...}}       -> the tool runs with these args instead
+    anything else                              -> the tool does NOT run; the decision is
+                                                  returned as the tool's result, so the
+                                                  model sees why
+
+One `interrupt()` per node still applies (langgraph #6626): two `@hitl` tools dispatched
+by the same `ToolNode` share an interrupt id. Use `HumanInTheLoopMiddleware`, which
+batches them into one interrupt, or give each its own node.
+
+## `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. When the tool is called it announces the question
+through the announcers given here and returns `{"status": "pending_approval",
+"question_id": ...}` without running the tool body. The graph carries on; the model sees
+that the action is pending; there is no `__interrupt__` and nothing to call after the run.
+The decision arrives later as a **new message** to the agent, carrying the `question_id`
+-- how, and what the graph does with it, is yours.
+
+Nothing is parked, so nothing in LangGraph remembers the question. Whatever record you
+keep (a `DynamoDbAnnounce` table is one) is the only one. This is the right mode when the
+person answering is not the person on the thread -- a customer chatting on WhatsApp while
+finance approves in a dashboard -- and it should be a visible choice, not a default.
+
+`question_id` is derived from the thread, the tool and its arguments, so the same call
+on the same thread produces the same id: a consumer sees one question, not two. Pass
+`question_id=` to override. The thread id comes from the run config, where LangGraph
+keeps it.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+import json
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Literal
+
+from agent_wait import AnnounceAdapter, Question, WaitPolicy, canonical_json, publish
+
+from .ask import ask
+
+Mode = Literal["interrupt", "async"]
+
+_REGISTRY: dict[str, WaitPolicy] = {}
+
+
+def policy_for(tool_name: str) -> WaitPolicy | None:
+    """The policy `@hitl` registered for a tool, or None."""
+    return _REGISTRY.get(tool_name)
+
+
+def question_id_for(thread_id: str, tool: str, args: Mapping[str, Any]) -> str:
+    """Deterministic: the same call on the same thread is the same question."""
+    return hashlib.sha256(f"{thread_id}|{tool}|{canonical_json(dict(args))}".encode()).hexdigest()[:32]
+
+
+def _thread_id() -> str:
+    from langgraph.config import get_config
+
+    configurable = get_config().get("configurable", {})
+    thread_id = 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,
+    question_id: Callable[[str, str, Mapping[str, Any]], str] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    resolved = policy or WaitPolicy(allowed_actions=("approve", "reject"))
+    if mode == "async" and not announce:
+        raise ValueError("@hitl(mode='async') publishes from inside the tool, so it needs announce=[...]")
+    announcers: Sequence[AnnounceAdapter] = list(announce or ())
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        name = fn.__name__
+        _REGISTRY[name] = resolved
+        signature = inspect.signature(fn)
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound = signature.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+            call_args: dict[str, Any] = dict(bound.arguments)
+            question = {"tool": name, "args": call_args}
+
+            if mode == "interrupt":
+                decision = ask(question, resolved, source={"tool": name})
+                return _apply(decision, fn, call_args)
+
+            thread_id = _thread_id()
+            qid = (question_id or question_id_for)(thread_id, name, call_args)
+            publish(
+                [Question(question_id=qid, question=question, policy=resolved, source={"tool": name})],
+                thread_id,
+                announcers,
+            )
+            return {"status": "pending_approval", "question_id": qid, "tool": name}
+
+        wrapper.__hitl__ = {"mode": mode, "policy": resolved}  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+def _apply(decision: Any, fn: Callable[..., Any], call_args: Mapping[str, Any]) -> Any:
+    """Run the tool if the decision says so; otherwise hand the decision back as the result."""
+    if isinstance(decision, Mapping) and decision.get("action") == "approve":
+        edited = decision.get("args")
+        merged = {**call_args, **dict(edited)} if isinstance(edited, Mapping) else dict(call_args)  # pyright: ignore[reportUnknownArgumentType]
+        return fn(**merged)
+    if isinstance(decision, Mapping):
+        return {"status": "not_executed", **dict(decision)}  # pyright: ignore[reportUnknownArgumentType]
+    return {
+        "status": "not_executed",
+        "decision": decision
+        if isinstance(decision, str | int | float | bool | type(None))
+        else json.loads(json.dumps(decision, default=str)),
+    }

langgraph_wait-0.3.0/src/langgraph_wait/publish.py

@@ -0,0 +1,91 @@
+"""`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 node calls `interrupt()`, LangGraph returns the run's output with an
+`__interrupt__` entry: a sequence of `Interrupt` objects, each with `.id` and `.value`
+(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.
+
+## Three interrupt shapes are understood
+
+1. **`ask()`** -- `.value` is `{"question": ..., "__wait__": policy}`. One question.
+2. **A bare `interrupt(value)`** -- one question, `value` verbatim, default policy.
+3. **`HumanInTheLoopMiddleware`** (`langchain.agents`) -- `.value` is an `HITLRequest`:
+   `{"action_requests": [{name, args, description}], "review_configs": [...]}`. The
+   middleware batches every tool call needing review into ONE interrupt, so this is one
+   question whose payload is the whole batch, and whose answer is the middleware's
+   `HITLResponse`: `{"decisions": [{type: approve|reject|edit|respond, ...}, ...]}` in
+   batch order. The policy comes from `@hitl` on the first tool in the batch, if any.
+
+Nothing here runs the graph, reads its state, or resumes anything. The answer's shape
+and its return path are yours; the envelope's `reply_with` stub carries `question_id`,
+and `Command(resume={question_id: answer})` is how LangGraph takes it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from agent_wait import AnnounceAdapter, Clock, EntryPoint, Question, WaitEnvelope, WaitPolicy, publish
+
+from .ask import unwrap
+from .hitl import policy_for
+
+INTERRUPT_KEY = "__interrupt__"
+
+
+def _is_hitl_request(value: Any) -> bool:
+    return isinstance(value, Mapping) and "action_requests" in value and "review_configs" in value
+
+
+def _from_hitl_request(interrupt_id: str, value: Mapping[str, Any]) -> Question:
+    actions: list[Mapping[str, Any]] = list(value.get("action_requests") or [])
+    names = [str(a.get("name", "")) for a in actions]
+    policy = policy_for(names[0]) if names else None
+    return Question(
+        question_id=interrupt_id,
+        question={"actions": actions, "review": list(value.get("review_configs") or [])},
+        policy=policy or WaitPolicy(allowed_actions=("approve", "reject", "edit", "respond")),
+        source={"tools": names, "via": "HumanInTheLoopMiddleware"},
+    )
+
+
+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]
+        interrupt_id = str(getattr(item, "id", ""))
+        value = getattr(item, "value", None)
+        if _is_hitl_request(value):
+            out.append(_from_hitl_request(interrupt_id, value))
+            continue
+        question, policy = unwrap(value)
+        source = None
+        if isinstance(value, Mapping) and isinstance(value.get("__source__"), Mapping):
+            source = dict(value["__source__"])  # pyright: ignore[reportUnknownArgumentType]
+        out.append(Question(question_id=interrupt_id, question=question, policy=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/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")})