agent-wait-aws 0.2.0__tar.gz

agent_wait_aws-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+*.egg-info/
+*.pyc
+.coverage
+.env
+.pytest_cache/
+.ruff_cache/
+.scratch/
+.venv/
+__pycache__/
+build/
+cdk.out/
+reports/*.log
+
+# generated by the docs workflow from README.md / CHANGELOG.md
+docs/index.md
+docs/changelog.md
+# build output
+dist/
+site/

agent_wait_aws-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamaljeet Singh
+
+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.

agent_wait_aws-0.2.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: agent-wait-aws
+Version: 0.2.0
+Summary: AWS announce adapters for agent-wait: SNS, SQS, EventBridge, and DynamoDB (the question as a row), plus a CDK stack for the example.
+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
+Project-URL: Issues, https://github.com/skamalj/agent-wait/issues
+Author-email: Kamaljeet Singh <skamalj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,aws,dynamodb,eventbridge,human-in-the-loop,langgraph,sns,sqs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+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: boto3>=1.35
+Description-Content-Type: text/markdown
+
+# agent-wait-aws
+
+AWS announce adapters for [agent-wait](https://pypi.org/project/agent-wait/).
+
+```bash
+pip install agent-wait-aws          # pulls in agent-wait and boto3
+```
+
+```python
+from agent_wait_aws import DynamoDbAnnounce, EventBridgeAnnounce, SnsAnnounce, SqsAnnounce
+```
+
+| Adapter | Where the question lands |
+|---|---|
+| `SnsAnnounce(topic_arn)` | A topic. Policy `tags` become message attributes, so subscription filter policies can route on them. |
+| `SqsAnnounce(queue_url)` | A queue. On FIFO: `MessageGroupId = thread_id`, and `MessageDeduplicationId` is the stable dedupe key, so a republished question is swallowed. |
+| `EventBridgeAnnounce(bus)` | A bus, with the transition as detail-type. Notices partial failures, which `PutEvents` reports inside an HTTP 200. |
+| `DynamoDbAnnounce(table)` | A row. `created` writes it `open`, `resumed` marks it `closed`; a GSI on `status` gives an approvals UI its query with no broker involved. |
+
+Every one is a `BaseAnnounce` subclass with a single `deliver()` method, so a failure is a
+log line rather than a failed run. They are also the reference for writing your own:
+`sqs.py` is twenty lines.
+
+The package also carries a CDK stack for the example agent — a FIFO queue, a topic, one
+Lambda, the checkpointer's table and an approvals table.
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

agent_wait_aws-0.2.0/README.md

@@ -0,0 +1,27 @@
+# agent-wait-aws
+
+AWS announce adapters for [agent-wait](https://pypi.org/project/agent-wait/).
+
+```bash
+pip install agent-wait-aws          # pulls in agent-wait and boto3
+```
+
+```python
+from agent_wait_aws import DynamoDbAnnounce, EventBridgeAnnounce, SnsAnnounce, SqsAnnounce
+```
+
+| Adapter | Where the question lands |
+|---|---|
+| `SnsAnnounce(topic_arn)` | A topic. Policy `tags` become message attributes, so subscription filter policies can route on them. |
+| `SqsAnnounce(queue_url)` | A queue. On FIFO: `MessageGroupId = thread_id`, and `MessageDeduplicationId` is the stable dedupe key, so a republished question is swallowed. |
+| `EventBridgeAnnounce(bus)` | A bus, with the transition as detail-type. Notices partial failures, which `PutEvents` reports inside an HTTP 200. |
+| `DynamoDbAnnounce(table)` | A row. `created` writes it `open`, `resumed` marks it `closed`; a GSI on `status` gives an approvals UI its query with no broker involved. |
+
+Every one is a `BaseAnnounce` subclass with a single `deliver()` method, so a failure is a
+log line rather than a failed run. They are also the reference for writing your own:
+`sqs.py` is twenty lines.
+
+The package also carries a CDK stack for the example agent — a FIFO queue, a topic, one
+Lambda, the checkpointer's table and an approvals table.
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

agent_wait_aws-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "agent-wait-aws"
+version = "0.2.0"
+description = "AWS announce adapters for agent-wait: SNS, SQS, EventBridge, and DynamoDB (the question as a row), plus a CDK stack for the example."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kamaljeet Singh", email = "skamalj@gmail.com" }]
+keywords = ["agents", "langgraph", "human-in-the-loop", "aws", "sns", "sqs", "eventbridge", "dynamodb"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = ["agent-wait>=0.2,<0.3", "boto3>=1.35"]
+
+[project.urls]
+Homepage = "https://skamalj.github.io/agent-wait/"
+Documentation = "https://skamalj.github.io/agent-wait/"
+Source = "https://github.com/skamalj/agent-wait"
+Issues = "https://github.com/skamalj/agent-wait/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_wait_aws"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/agent_wait_aws", "README.md", "LICENSE"]
+
+[tool.uv.sources]
+agent-wait = { workspace = true }

agent_wait_aws-0.2.0/src/agent_wait_aws/__init__.py

@@ -0,0 +1,17 @@
+"""agent-wait-aws: announce adapters for AWS.
+
+Four places a question can land:
+
+    SnsAnnounce(topic_arn)        # fan out; policy tags become filterable attributes
+    SqsAnnounce(queue_url)        # one consumer, ordered per thread on FIFO
+    EventBridgeAnnounce(bus)      # rules and targets decide who cares
+    DynamoDbAnnounce(table)       # the question *is* a row; query it directly
+
+This package contains nothing but adapters and the CDK stack for the example. There
+is no store, no key provider and no run handler here, because the library keeps no state
+and receives no answers.
+"""
+
+from .announce import DynamoDbAnnounce, EventBridgeAnnounce, SnsAnnounce, SqsAnnounce
+
+__all__ = ["DynamoDbAnnounce", "EventBridgeAnnounce", "SnsAnnounce", "SqsAnnounce"]

agent_wait_aws-0.2.0/src/agent_wait_aws/announce/__init__.py

@@ -0,0 +1,6 @@
+from .dynamodb import DynamoDbAnnounce
+from .eventbridge import EventBridgeAnnounce
+from .sns import SnsAnnounce
+from .sqs import SqsAnnounce
+
+__all__ = ["DynamoDbAnnounce", "EventBridgeAnnounce", "SnsAnnounce", "SqsAnnounce"]

agent_wait_aws-0.2.0/src/agent_wait_aws/announce/dynamodb.py

@@ -0,0 +1,98 @@
+"""`DynamoDbAnnounce` -- the question *is* the row.
+
+Here to make a point: since nothing reads state back through this library, an
+"announce adapter" does not have to be a message broker. It is
+just somewhere the question lands where whoever answers it will find it. A table is a
+perfectly good somewhere -- and for an approval queue it is a better one, because a UI
+can `Query` it for "everything still open" without anybody having to build a projection
+off an event stream first.
+
+    announce=[DynamoDbAnnounce("approvals")]
+
+    pk = "THREAD#order-4471"   sk = "WAIT#<interrupt_id>"
+    status = "open" | "closed"
+
+`created` writes the row; `resumed` marks it closed rather than deleting it, so the row
+is still there when someone asks why the button stopped working. Both are idempotent:
+the same interrupt republished after a crash overwrites its own row with identical
+content, which is the whole reason `dedupe_key` is stable.
+
+A GSI on `status` gives you "every open approval", which is the query an approvals UI
+actually wants. The CDK stack in this package creates it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+from agent_wait.announce import BaseAnnounce
+from agent_wait.model import Transition, WaitEnvelope
+
+
+class DynamoDbAnnounce(BaseAnnounce):
+    name = "dynamodb"
+
+    def __init__(
+        self,
+        table_name: str,
+        *,
+        table: Any = None,
+        region_name: str | None = None,
+        ttl_seconds: int | None = None,
+        only: tuple[Transition, ...] | None = None,
+    ) -> None:
+        super().__init__(only=only)
+        self.table_name = table_name
+        self._table = table or boto3.resource("dynamodb", region_name=region_name).Table(table_name)
+        self._ttl_seconds = ttl_seconds
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        if transition == "resumed":
+            self._close(envelope)
+        else:
+            self._open(envelope)
+
+    def _open(self, envelope: WaitEnvelope) -> None:
+        item: dict[str, Any] = {
+            "pk": f"THREAD#{envelope.thread_id}",
+            "sk": f"WAIT#{envelope.interrupt_id}",
+            "status": "open",
+            "thread_id": envelope.thread_id,
+            "interrupt_id": envelope.interrupt_id,
+            "question": envelope.question,
+            "allowed_actions": list(envelope.allowed_actions),
+            "expires_at": envelope.expires_at,
+            "reply_with": dict(envelope.reply_with),
+            "tags": dict(envelope.tags),
+            "event_id": envelope.event_id,
+        }
+        if envelope.default is not None:
+            item["default"] = envelope.default
+        if envelope.reply_to:
+            item["reply_to"] = dict(envelope.reply_to)
+        if self._ttl_seconds:
+            item["ttl"] = int(_now()) + self._ttl_seconds
+        self._table.put_item(Item=item)
+
+    def _close(self, envelope: WaitEnvelope) -> None:
+        """Mark closed, and only if the row is there.
+
+        The condition matters: a `resumed` for an interrupt this table never saw
+        (announced by a different adapter, or written before this adapter was added)
+        should leave nothing behind. Creating a closed row for a question nobody was
+        ever asked would put a phantom in the approvals UI's history.
+        """
+        self._table.update_item(
+            Key={"pk": f"THREAD#{envelope.thread_id}", "sk": f"WAIT#{envelope.interrupt_id}"},
+            UpdateExpression="SET #s = :closed",
+            ExpressionAttributeNames={"#s": "status"},
+            ExpressionAttributeValues={":closed": "closed"},
+            ConditionExpression="attribute_exists(pk)",
+        )
+
+
+def _now() -> float:
+    import time
+
+    return time.time()

agent_wait_aws-0.2.0/src/agent_wait_aws/announce/eventbridge.py

@@ -0,0 +1,53 @@
+"""`EventBridgeAnnounce` -- `PutEvents` onto a bus, `DetailType = wait.<transition>`.
+
+The most useful of the four for a large organisation: rules on the bus can fan a
+`wait.created` out to Slack, a ticketing system and an audit log without the agent, or
+this library, knowing that any of them exist.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import boto3
+from agent_wait.announce import BaseAnnounce
+from agent_wait.model import Transition, WaitEnvelope
+
+
+class EventBridgeAnnounce(BaseAnnounce):
+    name = "eventbridge"
+
+    def __init__(
+        self,
+        bus_name: str,
+        *,
+        source: str = "agent-wait",
+        client: Any = None,
+        region_name: str | None = None,
+        only: tuple[Transition, ...] | None = None,
+    ) -> None:
+        super().__init__(only=only)
+        self.bus_name = bus_name
+        self.source = source
+        self._client = client or boto3.client("events", region_name=region_name)
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        response = self._client.put_events(
+            Entries=[
+                {
+                    "EventBusName": self.bus_name,
+                    "Source": self.source,
+                    "DetailType": envelope.type,
+                    "Detail": envelope.to_json(),
+                }
+            ]
+        )
+        # PutEvents reports per-entry failures in the body with a 200 status, so a naive
+        # call looks successful even when nothing was delivered.
+        if response.get("FailedEntryCount"):
+            self._log.error(
+                "EventBridge rejected the envelope for interrupt %s: %s",
+                envelope.interrupt_id,
+                json.dumps(response.get("Entries", []), default=str),
+            )

agent_wait_aws-0.2.0/src/agent_wait_aws/announce/sns.py

@@ -0,0 +1,47 @@
+"""`SnsAnnounce` -- publish the envelope, with the policy's tags as message attributes.
+
+The tags are the useful part. `WaitPolicy(tags={"approver_group": "finance"})` becomes an
+SNS message attribute, so a subscription filter policy can route finance approvals to one
+place and everything else somewhere else -- without the agent knowing any of those places
+exist.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+from agent_wait.announce import BaseAnnounce
+from agent_wait.model import Transition, WaitEnvelope
+
+
+class SnsAnnounce(BaseAnnounce):
+    name = "sns"
+
+    def __init__(
+        self,
+        topic_arn: str,
+        *,
+        client: Any = None,
+        region_name: str | None = None,
+        only: tuple[Transition, ...] | None = None,
+    ) -> None:
+        super().__init__(only=only)
+        self.topic_arn = topic_arn
+        self._client = client or boto3.client("sns", region_name=region_name)
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        attributes: dict[str, dict[str, str]] = {
+            "transition": {"DataType": "String", "StringValue": transition},
+            "thread_id": {"DataType": "String", "StringValue": envelope.thread_id},
+        }
+        for key, value in envelope.tags.items():
+            # SNS rejects an empty StringValue, and a filter policy cannot use one.
+            if value:
+                attributes[key] = {"DataType": "String", "StringValue": str(value)}
+        self._client.publish(
+            TopicArn=self.topic_arn,
+            Subject=envelope.type,
+            Message=envelope.to_json(),
+            MessageAttributes=attributes,
+        )

agent_wait_aws-0.2.0/src/agent_wait_aws/announce/sqs.py

@@ -0,0 +1,42 @@
+"""`SqsAnnounce` -- put the envelope on a queue.
+
+On a FIFO queue, `MessageGroupId` is the thread id (one in-flight question per
+conversation, so a consumer never sees two from the same graph out of order) and
+`MessageDeduplicationId` is the envelope's `dedupe_key` -- not its `event_id`, which is
+fresh on every publish and would let a republished question through as new.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import boto3
+from agent_wait.announce import BaseAnnounce
+from agent_wait.model import Transition, WaitEnvelope
+
+
+class SqsAnnounce(BaseAnnounce):
+    name = "sqs"
+
+    def __init__(
+        self,
+        queue_url: str,
+        *,
+        group_id: Callable[[WaitEnvelope], str] | None = None,
+        client: Any = None,
+        region_name: str | None = None,
+        only: tuple[Transition, ...] | None = None,
+    ) -> None:
+        super().__init__(only=only)
+        self.queue_url = queue_url
+        self.group_id = group_id or (lambda envelope: envelope.thread_id)
+        self._client = client or boto3.client("sqs", region_name=region_name)
+        self.is_fifo = queue_url.endswith(".fifo")
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        kwargs: dict[str, Any] = {"QueueUrl": self.queue_url, "MessageBody": envelope.to_json()}
+        if self.is_fifo:
+            kwargs["MessageGroupId"] = self.group_id(envelope)
+            kwargs["MessageDeduplicationId"] = envelope.dedupe_key
+        self._client.send_message(**kwargs)