agent-wait 0.5.0__tar.gz → 0.6.0__tar.gz

{agent_wait-0.5.0 → agent_wait-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agent-wait
-Version: 0.5.0
-Summary: Human-in-the-loop for LangGraph agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in.
+Version: 0.6.0
+Summary: Human-in-the-loop for LangGraph and Pydantic AI agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in.
 Project-URL: Homepage, https://skamalj.github.io/agent-wait/
 Project-URL: Documentation, https://skamalj.github.io/agent-wait/
 Project-URL: Source, https://github.com/skamalj/agent-wait
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/skamalj/agent-wait/blob/main/CHANGELO
 Author-email: Kamaljeet Singh <skamalj@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: agents,approval,callback,durable,dynamodb,eventbridge,hitl,human-in-the-loop,interrupt,lambda,langchain,langgraph,serverless,sns,sqs,webhook
+Keywords: agents,approval,callback,durable,dynamodb,eventbridge,hitl,human-in-the-loop,interrupt,lambda,langchain,langgraph,pydantic-ai,serverless,sns,sqs,webhook
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -23,10 +23,13 @@ Requires-Python: >=3.12
 Provides-Extra: all
 Requires-Dist: boto3>=1.35; extra == 'all'
 Requires-Dist: langgraph<2,>=1.2; extra == 'all'
+Requires-Dist: pydantic-ai-slim<3,>=2.43; extra == 'all'
 Provides-Extra: aws
 Requires-Dist: boto3>=1.35; extra == 'aws'
 Provides-Extra: langgraph
 Requires-Dist: langgraph<2,>=1.2; extra == 'langgraph'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim<3,>=2.43; extra == 'pydantic-ai'
 Description-Content-Type: text/markdown
 
 # agent-wait
@@ -43,12 +46,13 @@ deploy. But the same shape covers a vendor callback, a payment processor, a KYC
 another agent — anything the run cannot continue without, and nothing inside the process
 can supply.
 
-LangGraph has `interrupt()` for this. When a node calls it the graph pauses and the
-interrupt is handed to whatever called `invoke()` — and that is where LangGraph stops.
-There is no built-in way to tell anyone *else* that a question was asked, and no built-in
-way for anyone else to answer it. The moment the question has to reach Slack, an approvals
-dashboard, a ticket queue or another service, you are writing that code yourself — whether
-your agent is a server that runs for a year or a Lambda that is gone in seconds.
+LangGraph has `interrupt()` for this; Pydantic AI has `ApprovalRequired`. In both, the
+run pauses and the question is handed to whatever called it — and that is where the
+framework stops. There is no built-in way to tell anyone *else* that a question was asked,
+and no built-in way for anyone else to answer it. The moment the question has to reach
+Slack, an approvals dashboard, a ticket queue or another service, you are writing that
+code yourself — whether your agent is a server that runs for a year or a Lambda that is
+gone in seconds.
 
 agent-wait is that code. It takes the interrupt and puts it somewhere people (or systems)
 can see it — a topic, a queue, a webhook, a database row — with everything needed to answer
@@ -56,6 +60,7 @@ it in one envelope, and documents the shape of the answer so the return leg is o
 
 ```bash
 pip install "agent-wait[langgraph]"        # @wait + publish_interrupts for LangGraph
+pip install "agent-wait[pydantic-ai]"      # the same two names for Pydantic AI
 pip install "agent-wait[langgraph,aws]"    # + SNS / SQS / EventBridge / DynamoDB announcers
 ```
 
@@ -145,6 +150,50 @@ publish_interrupts(result, message["thread_id"], announce)
 That is the complete integration. A duplicate answer runs nothing — LangGraph ignores a
 resume for a question the thread has moved past — so there is nothing to check.
 
+## The same two names on Pydantic AI
+
+```python
+from agent_wait.pydantic_ai import publish_interrupts, wait
+from pydantic_ai import Agent, DeferredToolRequests, DeferredToolResults, RunContext, ToolApproved, ToolDenied
+
+agent = Agent("openai:gpt-5.4", output_type=[str, DeferredToolRequests])
+
+
+@agent.tool
+@wait(FINANCE)
+def issue_refund(ctx: RunContext[None], order_id: str, amount: int) -> str:
+    payments.refund(order_id, amount)
+    return "refunded"
+
+
+result = agent.run_sync("refund order 4471", message_history=history)
+publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+store(thread_id, result.all_messages())  # Pydantic AI has no checkpointer; the history is yours
+```
+
+The run ends with `DeferredToolRequests` in `result.output`; `question_id` is the
+`tool_call_id`. The answer goes back through the framework's own resume, with the answer
+itself riding in `metadata` so the `@wait` rules apply unchanged:
+
+```python
+approved = answer.get("action") == "approve"
+result = agent.run_sync(
+    None,
+    message_history=load(thread_id),
+    deferred_tool_results=DeferredToolResults(
+        approvals={question_id: ToolApproved() if approved else ToolDenied(str(answer))},
+        metadata={question_id: answer},
+    ),
+)
+store(thread_id, result.all_messages())  # before acknowledging the answer message
+```
+
+Two rules the framework leaves to you: name the `RunContext` parameter `ctx`, and store
+the post-run history *before* you acknowledge an answer — a duplicate answer is refused
+only if the history you pass already holds the tool's return. `requires_approval=True`
+tools and `CallDeferred` calls (a job handed to an external system) are published too,
+with the default policy.
+
 ## Async mode — the thread does not park
 
 ```python
@@ -240,16 +289,17 @@ One distribution, one import root. Frameworks and providers are subpackages behi
 ```
 agent_wait              core: WaitPolicy, Question, the envelope, publish(), BaseAnnounce,
                         Webhook/Log/InMemory announcers, and the Framework interface. No deps.
-agent_wait.langgraph    [langgraph]  @wait and publish_interrupts() bound to LangGraph.
-agent_wait.aws          [aws]        SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
+agent_wait.langgraph    [langgraph]    @wait and publish_interrupts() bound to LangGraph.
+agent_wait.pydantic_ai  [pydantic-ai]  the same two names bound to Pydantic AI's deferred tools.
+agent_wait.aws          [aws]          SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
 examples/refund_agent   a graph, a host written for Lambda behind SQS, and its CDK stack.
 docs/                   message contract, architecture, announcer guide, consumer guide.
 ```
 
 `@wait` and `publish_interrupts` are written once against a three-method `Framework`
-interface; `agent_wait.langgraph` is one implementor of it. Announcers are the same
-split: `BaseAnnounce` is the interface, each provider subpackage the implementors. A
-`strands` extra follows the same pattern — see
+interface; `agent_wait.langgraph` and `agent_wait.pydantic_ai` are implementors of it,
+about fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
+each provider subpackage the implementors. See
 [Architecture](https://skamalj.github.io/agent-wait/architecture/).
 
 MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

{agent_wait-0.5.0 → agent_wait-0.6.0}/README.md

@@ -12,12 +12,13 @@ deploy. But the same shape covers a vendor callback, a payment processor, a KYC
 another agent — anything the run cannot continue without, and nothing inside the process
 can supply.
 
-LangGraph has `interrupt()` for this. When a node calls it the graph pauses and the
-interrupt is handed to whatever called `invoke()` — and that is where LangGraph stops.
-There is no built-in way to tell anyone *else* that a question was asked, and no built-in
-way for anyone else to answer it. The moment the question has to reach Slack, an approvals
-dashboard, a ticket queue or another service, you are writing that code yourself — whether
-your agent is a server that runs for a year or a Lambda that is gone in seconds.
+LangGraph has `interrupt()` for this; Pydantic AI has `ApprovalRequired`. In both, the
+run pauses and the question is handed to whatever called it — and that is where the
+framework stops. There is no built-in way to tell anyone *else* that a question was asked,
+and no built-in way for anyone else to answer it. The moment the question has to reach
+Slack, an approvals dashboard, a ticket queue or another service, you are writing that
+code yourself — whether your agent is a server that runs for a year or a Lambda that is
+gone in seconds.
 
 agent-wait is that code. It takes the interrupt and puts it somewhere people (or systems)
 can see it — a topic, a queue, a webhook, a database row — with everything needed to answer
@@ -25,6 +26,7 @@ it in one envelope, and documents the shape of the answer so the return leg is o
 
 ```bash
 pip install "agent-wait[langgraph]"        # @wait + publish_interrupts for LangGraph
+pip install "agent-wait[pydantic-ai]"      # the same two names for Pydantic AI
 pip install "agent-wait[langgraph,aws]"    # + SNS / SQS / EventBridge / DynamoDB announcers
 ```
 
@@ -114,6 +116,50 @@ publish_interrupts(result, message["thread_id"], announce)
 That is the complete integration. A duplicate answer runs nothing — LangGraph ignores a
 resume for a question the thread has moved past — so there is nothing to check.
 
+## The same two names on Pydantic AI
+
+```python
+from agent_wait.pydantic_ai import publish_interrupts, wait
+from pydantic_ai import Agent, DeferredToolRequests, DeferredToolResults, RunContext, ToolApproved, ToolDenied
+
+agent = Agent("openai:gpt-5.4", output_type=[str, DeferredToolRequests])
+
+
+@agent.tool
+@wait(FINANCE)
+def issue_refund(ctx: RunContext[None], order_id: str, amount: int) -> str:
+    payments.refund(order_id, amount)
+    return "refunded"
+
+
+result = agent.run_sync("refund order 4471", message_history=history)
+publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+store(thread_id, result.all_messages())  # Pydantic AI has no checkpointer; the history is yours
+```
+
+The run ends with `DeferredToolRequests` in `result.output`; `question_id` is the
+`tool_call_id`. The answer goes back through the framework's own resume, with the answer
+itself riding in `metadata` so the `@wait` rules apply unchanged:
+
+```python
+approved = answer.get("action") == "approve"
+result = agent.run_sync(
+    None,
+    message_history=load(thread_id),
+    deferred_tool_results=DeferredToolResults(
+        approvals={question_id: ToolApproved() if approved else ToolDenied(str(answer))},
+        metadata={question_id: answer},
+    ),
+)
+store(thread_id, result.all_messages())  # before acknowledging the answer message
+```
+
+Two rules the framework leaves to you: name the `RunContext` parameter `ctx`, and store
+the post-run history *before* you acknowledge an answer — a duplicate answer is refused
+only if the history you pass already holds the tool's return. `requires_approval=True`
+tools and `CallDeferred` calls (a job handed to an external system) are published too,
+with the default policy.
+
 ## Async mode — the thread does not park
 
 ```python
@@ -209,16 +255,17 @@ One distribution, one import root. Frameworks and providers are subpackages behi
 ```
 agent_wait              core: WaitPolicy, Question, the envelope, publish(), BaseAnnounce,
                         Webhook/Log/InMemory announcers, and the Framework interface. No deps.
-agent_wait.langgraph    [langgraph]  @wait and publish_interrupts() bound to LangGraph.
-agent_wait.aws          [aws]        SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
+agent_wait.langgraph    [langgraph]    @wait and publish_interrupts() bound to LangGraph.
+agent_wait.pydantic_ai  [pydantic-ai]  the same two names bound to Pydantic AI's deferred tools.
+agent_wait.aws          [aws]          SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
 examples/refund_agent   a graph, a host written for Lambda behind SQS, and its CDK stack.
 docs/                   message contract, architecture, announcer guide, consumer guide.
 ```
 
 `@wait` and `publish_interrupts` are written once against a three-method `Framework`
-interface; `agent_wait.langgraph` is one implementor of it. Announcers are the same
-split: `BaseAnnounce` is the interface, each provider subpackage the implementors. A
-`strands` extra follows the same pattern — see
+interface; `agent_wait.langgraph` and `agent_wait.pydantic_ai` are implementors of it,
+about fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
+each provider subpackage the implementors. See
 [Architecture](https://skamalj.github.io/agent-wait/architecture/).
 
 MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

{agent_wait-0.5.0 → agent_wait-0.6.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-wait"
-version = "0.5.0"
-description = "Human-in-the-loop for LangGraph agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in."
+version = "0.6.0"
+description = "Human-in-the-loop for LangGraph and Pydantic AI agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
@@ -13,6 +13,7 @@ keywords = [
     "approval",
     "langgraph",
     "langchain",
+    "pydantic-ai",
     "agents",
     "interrupt",
     "durable",
@@ -39,8 +40,9 @@ dependencies = []
 
 [project.optional-dependencies]
 langgraph = ["langgraph>=1.2,<2"]
+pydantic-ai = ["pydantic-ai-slim>=2.43,<3"]
 aws = ["boto3>=1.35"]
-all = ["agent-wait[langgraph,aws]"]
+all = ["agent-wait[langgraph,pydantic-ai,aws]"]
 
 [project.urls]
 Homepage = "https://skamalj.github.io/agent-wait/"

{agent_wait-0.5.0 → agent_wait-0.6.0}/src/agent_wait/__init__.py

@@ -12,9 +12,10 @@
     publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
 
 The core is framework- and provider-neutral: the policy, the question, the envelope,
-`publish()`, and the announcer interface. `agent_wait.langgraph` implements the
-`Framework` interface for LangGraph; `agent_wait.aws` implements announcers for AWS.
-Install the extras you need: `pip install agent-wait[langgraph,aws]`.
+`publish()`, and the announcer interface. `agent_wait.langgraph` and
+`agent_wait.pydantic_ai` implement the `Framework` interface for LangGraph and Pydantic
+AI; `agent_wait.aws` implements announcers for AWS. Install the extras you need:
+`pip install agent-wait[langgraph,aws]` or `agent-wait[pydantic-ai,aws]`.
 """
 
 from .announce import (
@@ -47,7 +48,7 @@ from .policy import WaitPolicy, parse_duration
 from .publish import build_envelope, publish
 from .wait import make_publish_interrupts, make_wait, question_id_for
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 __all__ = [
     "MAX_QUESTION_BYTES",

{agent_wait-0.5.0 → agent_wait-0.6.0}/src/agent_wait/framework.py

@@ -8,7 +8,7 @@ agent-wait needs exactly three things from an agent framework, and nothing else:
 
 Everything users touch -- `@wait`, `publish_interrupts`, the envelope, the announcers --
 is built once in `agent_wait.wait` on top of this interface. A framework subpackage
-(`agent_wait.langgraph`, `agent_wait.strands`, ...) is one implementor of it and two
+(`agent_wait.langgraph`, `agent_wait.pydantic_ai`, ...) is one implementor of it and two
 lines of binding. Users never see this class; they import the bound names.
 
 The same split holds for announcers: `announce.base.BaseAnnounce` is the interface, and

agent_wait-0.6.0/src/agent_wait/pydantic_ai/__init__.py

@@ -0,0 +1,122 @@
+"""Pydantic AI implementor of `agent_wait.framework.Framework`, and the bound names.
+
+    from agent_wait.pydantic_ai import wait, publish_interrupts
+
+Install with `pip install agent-wait[pydantic-ai]`.
+
+## What Pydantic AI provides, and what we use
+
+- **Park:** a tool raises `ApprovalRequired(metadata=...)`. The run ends and
+  `result.output` is a `DeferredToolRequests` whose `approvals` list the parked calls
+  (`ToolCallPart.tool_call_id`, `.tool_name`, `.args`) and whose `metadata[id]` is
+  whatever the tool attached. The agent must list `DeferredToolRequests` in its
+  `output_type`, or the raise is an error.
+- **Read back:** the same `result.output`. `stream()` ends with the same object.
+- **Thread:** none. Pydantic AI has no checkpointer; `message_history` is a list the
+  host owns and stores under a name of its choosing. For `mode="async"` the host puts
+  that name in `deps` as `thread_id` (an attribute or a mapping key).
+- **Resume** (the host's call, not ours):
+
+      agent.run_sync(None, message_history=history, deferred_tool_results=DeferredToolResults(
+          approvals={question_id: ToolApproved()},   # or ToolDenied(reason)
+          metadata={question_id: answer},             # the answer, verbatim, if it is a dict
+      ))
+
+  On approval the framework calls the tool again with `ctx.tool_call_approved = True`
+  and `ctx.tool_call_metadata = answer`; the `@wait` wrapper then applies the usual
+  rules (a `decision` parameter receives the answer; `answer["args"]` edits the call).
+  On denial the framework does not call the tool; the model sees the denial message.
+  Pass the answer through `metadata`, not `override_args` -- `override_args` replaces
+  the whole argument set and skips the wrapper's merge.
+
+## Three things to know
+
+- **The host owns idempotency.** A duplicate answer is rejected only if the
+  `message_history` passed on resume already contains the tool's return -- so store
+  the post-run history *before* acknowledging the answer message. Resuming twice from
+  the pre-resume history runs the tool twice.
+- **Name the `RunContext` parameter `ctx`.** The wrapper hides it from the published
+  `args` by name, and Pydantic AI finds it by annotation -- both hold under
+  `functools.wraps`.
+- **`CallDeferred` calls are published too**, with the default policy: they are the
+  non-human wait (a job handed to an external system). The answer for those goes in
+  `DeferredToolResults.calls`, not `approvals`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+try:
+    from pydantic_ai import ApprovalRequired, DeferredToolRequests, RunContext
+except ImportError as _err:  # pragma: no cover - exercised only without the extra
+    raise ImportError(
+        "agent_wait.pydantic_ai needs Pydantic AI: pip install 'agent-wait[pydantic-ai]'"
+    ) from _err
+
+from ..framework import Framework
+from ..wait import WAIT_KEY, make_publish_interrupts, make_wait
+
+__all__ = ["PydanticAIFramework", "publish_interrupts", "questions_in", "wait"]
+
+
+def _run_context(call_args: Mapping[str, Any]) -> RunContext[Any] | None:
+    for value in call_args.values():
+        if isinstance(value, RunContext):
+            return value  # pyright: ignore[reportUnknownVariableType]
+    return None
+
+
+class PydanticAIFramework(Framework):
+    name = "pydantic_ai"
+    hidden_params = ("ctx",)
+
+    def interrupt(self, value: Mapping[str, Any], call_args: Mapping[str, Any]) -> Any:
+        ctx = _run_context(call_args)
+        if ctx is None:
+            # Without the context the re-run after approval is indistinguishable from
+            # the first call, and the tool would park forever.
+            raise TypeError("a @wait tool on Pydantic AI needs a `ctx: RunContext` parameter")
+        if ctx.tool_call_approved:
+            # The re-run after approval. The answer rides in the metadata the host
+            # attached; without one, approval is the whole answer.
+            answer: Any = ctx.tool_call_metadata
+            return answer if answer is not None else {"action": "approve"}
+        raise ApprovalRequired(metadata=dict(value))
+
+    def interrupts_in(self, result: Any) -> list[tuple[str, Any]]:
+        output: Any = getattr(result, "output", result)
+        if not isinstance(output, DeferredToolRequests):
+            return []
+        out: list[tuple[str, Any]] = []
+        for part in [*output.approvals, *output.calls]:
+            attached = output.metadata.get(part.tool_call_id)
+            if isinstance(attached, Mapping) and WAIT_KEY in attached:
+                out.append((part.tool_call_id, dict(attached)))  # pyright: ignore[reportUnknownArgumentType]
+            else:
+                # A tool that never heard of this library: `requires_approval=True`, a bare
+                # `ApprovalRequired`, or a `CallDeferred`. The call is the question.
+                bare: dict[str, Any] = {"function": part.tool_name, "args": part.args_as_dict()}
+                if attached:
+                    bare["metadata"] = dict(attached)  # pyright: ignore[reportUnknownArgumentType]
+                out.append((part.tool_call_id, bare))
+        return out
+
+    def current_thread_id(self, call_args: Mapping[str, Any]) -> str:
+        ctx = _run_context(call_args)
+        deps: Any = ctx.deps if ctx is not None else None
+        if isinstance(deps, Mapping):
+            thread_id: Any = cast(Mapping[str, Any], deps).get("thread_id")
+        else:
+            thread_id = getattr(deps, "thread_id", None)
+        if not thread_id:
+            raise RuntimeError("@wait(mode='async') on Pydantic AI needs `thread_id` in the run's deps")
+        return str(thread_id)
+
+
+_framework = PydanticAIFramework()
+
+wait = make_wait(_framework)
+publish_interrupts = make_publish_interrupts(_framework)
+questions_in = publish_interrupts.questions_in  # type: ignore[attr-defined]