screwtape-pay-safely 0.1.0__tar.gz

screwtape_pay_safely-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

screwtape_pay_safely-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,15 @@
+name: test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test,langchain]"
+      - run: pytest -q

screwtape_pay_safely-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/

screwtape_pay_safely-0.1.0/LICENSE

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

screwtape_pay_safely-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: screwtape-pay-safely
+Version: 0.1.0
+Summary: Check that a seller is safe to pay before your AI agent pays. Drop-in for LangChain, LangGraph, CrewAI, OpenAI Agents and AgentKit.
+Project-URL: Homepage, https://screwtape.ai
+Project-URL: Source, https://github.com/screwtapeai/pay-safely
+Project-URL: Documentation, https://screwtape.ai/docs/
+Author-email: "Screwtape.ai" <support@screwtape.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agent-safety,agentkit,ai-agents,crewai,guardrails,langchain,langgraph,openai-agents,payments
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Provides-Extra: agentkit
+Requires-Dist: coinbase-agentkit>=0.5; extra == 'agentkit'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pay-safely
+
+Check that a seller is safe to pay **before your AI agent pays**.
+
+`pay-safely` asks [Screwtape.ai](https://screwtape.ai) one question at the moment your agent is about to pay: *is this seller safe to pay?* You get back **allow**, **review** or **block**, with reasons and a signed receipt you can verify later.
+
+It has no required dependencies and drops into LangChain, LangGraph, CrewAI, the OpenAI Agents SDK and AgentKit.
+
+## What the check looks at
+
+- The price and payee the seller asks for, compared with what the seller has published.
+- The payee against a denylist and a sanctions list.
+- Whether the amount is far above what your agent intended to pay.
+- Whether the same payment was already made.
+- Whether the seller URL answers with a valid payment request.
+
+If the check cannot confirm something, it says **review**, not **allow**. If it cannot run at all (network error, timeout), this package stops the payment by default.
+
+## Install
+
+```bash
+pip install screwtape-pay-safely
+# plus the extra for your framework:
+pip install "screwtape-pay-safely[langchain]"      # LangChain and LangGraph
+pip install "screwtape-pay-safely[crewai]"
+pip install "screwtape-pay-safely[openai-agents]"
+pip install "screwtape-pay-safely[agentkit]"
+```
+
+## Use it in plain Python
+
+```python
+from pay_safely import PaySafely, PaymentBlocked, NeedsReview
+
+guard = PaySafely(agent_id="my-agent")          # 3 free checks a day, no key
+
+try:
+    verdict = guard.require_safe("https://seller.example/pay", amount=0.05)
+except PaymentBlocked as err:
+    print("Do not pay:", err)
+except NeedsReview as err:
+    print("Ask a person first:", err)
+else:
+    print("OK to pay. Receipt:", verdict.receipt_id)
+    # ... make your payment here ...
+```
+
+Or wrap your payment function:
+
+```python
+@guard.protect(seller_url=lambda url, usd: url, amount=lambda url, usd: usd)
+def pay(url, usd):
+    ...
+```
+
+## LangChain and LangGraph
+
+```python
+from pay_safely import PaySafely
+from pay_safely.langchain import seller_check_tool, guard_tool
+
+guard = PaySafely(agent_id="my-agent")
+tools = [
+    seller_check_tool(guard),                                      # the agent can ask "is this seller safe?"
+    guard_tool(my_payment_tool, guard, seller_url_arg="url", amount_arg="usd"),  # runs only on allow
+]
+```
+
+## CrewAI
+
+```python
+from pay_safely import PaySafely
+from pay_safely.crewai import SellerCheckTool
+
+buyer = Agent(role="Buyer", goal="Buy safely", backstory="...", tools=[SellerCheckTool(guard=PaySafely(agent_id="buyer"))])
+```
+
+## OpenAI Agents SDK
+
+```python
+from agents import Agent, function_tool
+from pay_safely import PaySafely
+from pay_safely.openai_agents import seller_check_tool, payment_guardrail
+
+guard = PaySafely(agent_id="buyer")
+pay = function_tool(pay_seller, tool_input_guardrails=[payment_guardrail(guard, "url", "usd")])
+agent = Agent(name="Buyer", tools=[seller_check_tool(guard), pay])
+```
+
+## AgentKit
+
+```python
+from pay_safely import PaySafely
+from pay_safely.agentkit import pay_safely_action_provider
+
+# add to the action_providers list in your AgentKit config
+provider = pay_safely_action_provider(PaySafely(agent_id="buyer"))
+```
+
+## Free checks, keys and paid use
+
+| | Checks |
+|---|---|
+| No key | 3 free a day |
+| Free API key | 10 free a day. Get one at <https://screwtape.ai/v1/signup> and pass `PaySafely(api_key="...")` |
+| After that | $0.005 per check. See <https://screwtape.ai/llms.txt> for how an agent pays per call. Pass your own payment-capable HTTP client with `transport=` |
+
+When the free checks run out, `check()` raises `DailyLimitReached` with the link to get a free key.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `fail_open` | `False` | If `True`, a check that cannot run lets the payment go ahead. |
+| `allow_review` | `False` | If `True`, a **review** verdict does not stop the payment. |
+| `timeout` | `10.0` | Seconds to wait for the check. |
+| `transport` | built in | Your own function to send the request. |
+
+## Limits
+
+This is a second opinion, not a guarantee. The check advises and records. Your code decides whether to pay, and the check cannot stop a payment your code makes anyway. It does not hold funds.
+
+## Verify a receipt
+
+Every answer includes a `receipt_id` and `verify_url`. Verify it for free at <https://screwtape.ai/verify/>.
+
+## Develop
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Support
+
+support@screwtape.ai · <https://screwtape.ai>
+
+MIT license.

screwtape_pay_safely-0.1.0/README.md

@@ -0,0 +1,138 @@
+# pay-safely
+
+Check that a seller is safe to pay **before your AI agent pays**.
+
+`pay-safely` asks [Screwtape.ai](https://screwtape.ai) one question at the moment your agent is about to pay: *is this seller safe to pay?* You get back **allow**, **review** or **block**, with reasons and a signed receipt you can verify later.
+
+It has no required dependencies and drops into LangChain, LangGraph, CrewAI, the OpenAI Agents SDK and AgentKit.
+
+## What the check looks at
+
+- The price and payee the seller asks for, compared with what the seller has published.
+- The payee against a denylist and a sanctions list.
+- Whether the amount is far above what your agent intended to pay.
+- Whether the same payment was already made.
+- Whether the seller URL answers with a valid payment request.
+
+If the check cannot confirm something, it says **review**, not **allow**. If it cannot run at all (network error, timeout), this package stops the payment by default.
+
+## Install
+
+```bash
+pip install screwtape-pay-safely
+# plus the extra for your framework:
+pip install "screwtape-pay-safely[langchain]"      # LangChain and LangGraph
+pip install "screwtape-pay-safely[crewai]"
+pip install "screwtape-pay-safely[openai-agents]"
+pip install "screwtape-pay-safely[agentkit]"
+```
+
+## Use it in plain Python
+
+```python
+from pay_safely import PaySafely, PaymentBlocked, NeedsReview
+
+guard = PaySafely(agent_id="my-agent")          # 3 free checks a day, no key
+
+try:
+    verdict = guard.require_safe("https://seller.example/pay", amount=0.05)
+except PaymentBlocked as err:
+    print("Do not pay:", err)
+except NeedsReview as err:
+    print("Ask a person first:", err)
+else:
+    print("OK to pay. Receipt:", verdict.receipt_id)
+    # ... make your payment here ...
+```
+
+Or wrap your payment function:
+
+```python
+@guard.protect(seller_url=lambda url, usd: url, amount=lambda url, usd: usd)
+def pay(url, usd):
+    ...
+```
+
+## LangChain and LangGraph
+
+```python
+from pay_safely import PaySafely
+from pay_safely.langchain import seller_check_tool, guard_tool
+
+guard = PaySafely(agent_id="my-agent")
+tools = [
+    seller_check_tool(guard),                                      # the agent can ask "is this seller safe?"
+    guard_tool(my_payment_tool, guard, seller_url_arg="url", amount_arg="usd"),  # runs only on allow
+]
+```
+
+## CrewAI
+
+```python
+from pay_safely import PaySafely
+from pay_safely.crewai import SellerCheckTool
+
+buyer = Agent(role="Buyer", goal="Buy safely", backstory="...", tools=[SellerCheckTool(guard=PaySafely(agent_id="buyer"))])
+```
+
+## OpenAI Agents SDK
+
+```python
+from agents import Agent, function_tool
+from pay_safely import PaySafely
+from pay_safely.openai_agents import seller_check_tool, payment_guardrail
+
+guard = PaySafely(agent_id="buyer")
+pay = function_tool(pay_seller, tool_input_guardrails=[payment_guardrail(guard, "url", "usd")])
+agent = Agent(name="Buyer", tools=[seller_check_tool(guard), pay])
+```
+
+## AgentKit
+
+```python
+from pay_safely import PaySafely
+from pay_safely.agentkit import pay_safely_action_provider
+
+# add to the action_providers list in your AgentKit config
+provider = pay_safely_action_provider(PaySafely(agent_id="buyer"))
+```
+
+## Free checks, keys and paid use
+
+| | Checks |
+|---|---|
+| No key | 3 free a day |
+| Free API key | 10 free a day. Get one at <https://screwtape.ai/v1/signup> and pass `PaySafely(api_key="...")` |
+| After that | $0.005 per check. See <https://screwtape.ai/llms.txt> for how an agent pays per call. Pass your own payment-capable HTTP client with `transport=` |
+
+When the free checks run out, `check()` raises `DailyLimitReached` with the link to get a free key.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `fail_open` | `False` | If `True`, a check that cannot run lets the payment go ahead. |
+| `allow_review` | `False` | If `True`, a **review** verdict does not stop the payment. |
+| `timeout` | `10.0` | Seconds to wait for the check. |
+| `transport` | built in | Your own function to send the request. |
+
+## Limits
+
+This is a second opinion, not a guarantee. The check advises and records. Your code decides whether to pay, and the check cannot stop a payment your code makes anyway. It does not hold funds.
+
+## Verify a receipt
+
+Every answer includes a `receipt_id` and `verify_url`. Verify it for free at <https://screwtape.ai/verify/>.
+
+## Develop
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Support
+
+support@screwtape.ai · <https://screwtape.ai>
+
+MIT license.

screwtape_pay_safely-0.1.0/examples/langgraph_buyer.py

@@ -0,0 +1,20 @@
+"""A LangGraph agent that checks a seller before it pays. Replace pay_seller with your real payment call."""
+from langchain_core.tools import tool
+from langgraph.prebuilt import create_react_agent
+
+from pay_safely import PaySafely
+from pay_safely.langchain import guard_tool, seller_check_tool
+
+guard = PaySafely(agent_id="demo-buyer")
+
+
+@tool
+def pay_seller(url: str, usd: float) -> str:
+    """Pay a seller the given amount in US dollars."""
+    return f"Paid ${usd} to {url}"
+
+
+agent = create_react_agent(
+    "openai:gpt-4o-mini",
+    [seller_check_tool(guard), guard_tool(pay_seller, guard, seller_url_arg="url", amount_arg="usd")],
+)

screwtape_pay_safely-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "screwtape-pay-safely"
+version = "0.1.0"
+description = "Check that a seller is safe to pay before your AI agent pays. Drop-in for LangChain, LangGraph, CrewAI, OpenAI Agents and AgentKit."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Screwtape.ai", email = "support@screwtape.ai" }]
+keywords = ["ai-agents", "agent-safety", "payments", "langchain", "langgraph", "crewai", "openai-agents", "agentkit", "guardrails"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+]
+dependencies = []
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai>=0.100"]
+openai-agents = ["openai-agents>=0.1"]
+agentkit = ["coinbase-agentkit>=0.5"]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://screwtape.ai"
+Source = "https://github.com/screwtapeai/pay-safely"
+Documentation = "https://screwtape.ai/docs/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pay_safely"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

screwtape_pay_safely-0.1.0/src/pay_safely/__init__.py

@@ -0,0 +1,21 @@
+"""Check that a seller is safe to pay before your AI agent pays."""
+from .core import (
+    CheckUnavailable,
+    DailyLimitReached,
+    NeedsReview,
+    PaymentBlocked,
+    PaySafely,
+    PaySafelyError,
+    Verdict,
+)
+
+__all__ = [
+    "PaySafely",
+    "Verdict",
+    "PaySafelyError",
+    "PaymentBlocked",
+    "NeedsReview",
+    "CheckUnavailable",
+    "DailyLimitReached",
+]
+__version__ = "0.1.0"

screwtape_pay_safely-0.1.0/src/pay_safely/_util.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .core import CheckUnavailable, DailyLimitReached, NeedsReview, PaymentBlocked, PaySafely
+
+
+def run_check_text(guard: PaySafely, seller_url: Optional[str], amount: Optional[float]) -> "tuple[bool, str]":
+    """Run the guard and return (ok_to_pay, message the agent can read)."""
+    try:
+        verdict = guard.require_safe(seller_url=seller_url, amount=amount)
+    except PaymentBlocked as err:
+        return False, f"Do not pay. {err.verdict.summary()}"
+    except NeedsReview as err:
+        return False, f"Do not pay yet; ask a person to review. {err.verdict.summary()}"
+    except (CheckUnavailable, DailyLimitReached) as err:
+        return False, f"Do not pay: the seller check could not run. {err}"
+    except ValueError as err:
+        return False, f"Do not pay: {err}"
+    return True, f"Safe to pay. {verdict.summary()}"

screwtape_pay_safely-0.1.0/src/pay_safely/agentkit.py

@@ -0,0 +1,48 @@
+"""AgentKit: an action provider with a 'check seller before paying' action.
+
+    from coinbase_agentkit import AgentKit, AgentKitConfig
+    from pay_safely import PaySafely
+    from pay_safely.agentkit import pay_safely_action_provider
+
+    agentkit = AgentKit(AgentKitConfig(..., action_providers=[pay_safely_action_provider(PaySafely(agent_id="buyer"))]))
+
+Needs: pip install "screwtape-pay-safely[agentkit]"
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from coinbase_agentkit import ActionProvider, create_action
+from pydantic import BaseModel, Field
+
+from ._util import run_check_text
+from .core import PaySafely
+
+
+class CheckSellerSchema(BaseModel):
+    seller_url: str = Field(description="Public https URL of the seller or paid endpoint you are about to pay.")
+    amount_usd: Optional[float] = Field(default=None, description="Amount in US dollars you intend to pay.")
+
+
+class PaySafelyActionProvider(ActionProvider[Any]):
+    def __init__(self, guard: Optional[PaySafely] = None):
+        super().__init__("pay_safely", [])
+        self.guard = guard or PaySafely()
+
+    @create_action(
+        name="check_seller_before_paying",
+        description=(
+            "Call this BEFORE paying any seller or paid API. Returns ALLOW, REVIEW or BLOCK with reasons and a signed "
+            "receipt id. Only pay when the answer starts with 'Safe to pay'."
+        ),
+        schema=CheckSellerSchema,
+    )
+    def check_seller_before_paying(self, args: dict[str, Any]) -> str:
+        return run_check_text(self.guard, args["seller_url"], args.get("amount_usd"))[1]
+
+    def supports_network(self, network: Any) -> bool:
+        return True
+
+
+def pay_safely_action_provider(guard: Optional[PaySafely] = None) -> PaySafelyActionProvider:
+    return PaySafelyActionProvider(guard)

screwtape_pay_safely-0.1.0/src/pay_safely/core.py

@@ -0,0 +1,247 @@
+"""Core client: ask Screwtape.ai whether a seller is safe to pay, before your agent pays."""
+from __future__ import annotations
+
+import functools
+import json
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+DEFAULT_BASE_URL = "https://screwtape.ai"
+CHECK_PATH = "/v1/payment-check"
+
+__all__ = [
+    "PaySafely",
+    "Verdict",
+    "PaymentBlocked",
+    "NeedsReview",
+    "CheckUnavailable",
+    "DailyLimitReached",
+]
+
+
+class PaySafelyError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class PaymentBlocked(PaySafelyError):
+    """The check said block. Do not pay."""
+
+    def __init__(self, verdict: "Verdict"):
+        self.verdict = verdict
+        super().__init__("Payment blocked: " + "; ".join(verdict.reasons or ["seller failed the safety check"]))
+
+
+class NeedsReview(PaySafelyError):
+    """The check said review. A person should look before the agent pays."""
+
+    def __init__(self, verdict: "Verdict"):
+        self.verdict = verdict
+        super().__init__("Payment needs review: " + "; ".join(verdict.reasons or ["the check could not confirm the seller"]))
+
+
+class CheckUnavailable(PaySafelyError):
+    """The check could not run (network error, timeout or server error). Fails closed by default."""
+
+
+class DailyLimitReached(PaySafelyError):
+    """The free daily calls are used and the request needs payment or an API key."""
+
+    def __init__(self, message: str, body: Optional[Dict[str, Any]] = None):
+        self.body = body or {}
+        super().__init__(message)
+
+
+@dataclass
+class Verdict:
+    """What the payment check returned."""
+
+    verdict: str  # "allow", "review" or "block"
+    reasons: List[str] = field(default_factory=list)
+    payee: Optional[str] = None
+    amount_usd: Optional[float] = None
+    receipt_id: Optional[str] = None
+    verify_url: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def allowed(self) -> bool:
+        return self.verdict == "allow"
+
+    @property
+    def blocked(self) -> bool:
+        return self.verdict == "block"
+
+    @property
+    def needs_review(self) -> bool:
+        return self.verdict == "review"
+
+    def summary(self) -> str:
+        why = "; ".join(self.reasons) if self.reasons else "no reasons given"
+        rid = f" Receipt: {self.receipt_id}." if self.receipt_id else ""
+        return f"{self.verdict.upper()}: {why}.{rid}"
+
+    @classmethod
+    def from_response(cls, body: Dict[str, Any]) -> "Verdict":
+        return cls(
+            verdict=str(body.get("verdict", "review")),
+            reasons=[str(r) for r in body.get("reasons", []) or []],
+            payee=body.get("payee"),
+            amount_usd=body.get("amount_usd"),
+            receipt_id=body.get("receipt_id"),
+            verify_url=body.get("verify_url"),
+            raw=body,
+        )
+
+
+# A transport takes (url, json_body, headers, timeout) and returns (status_code, parsed_json_or_text).
+Transport = Callable[[str, Dict[str, Any], Dict[str, str], float], "tuple[int, Any]"]
+
+
+def _urllib_transport(url: str, body: Dict[str, Any], headers: Dict[str, str], timeout: float):
+    request = urllib.request.Request(url, data=json.dumps(body).encode("utf-8"), headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 - https URL, fixed endpoint
+            payload = response.read().decode("utf-8")
+            status = response.status
+    except urllib.error.HTTPError as err:
+        payload = err.read().decode("utf-8", "replace")
+        status = err.code
+    try:
+        return status, json.loads(payload)
+    except ValueError:
+        return status, payload
+
+
+class PaySafely:
+    """Ask Screwtape.ai whether a seller is safe to pay.
+
+    Parameters
+    ----------
+    api_key:
+        Optional free API key (10 checks a day). Without a key you get 3 free checks a day.
+    agent_id:
+        A label for your agent. It shows up on the signed receipt.
+    fail_open:
+        If True, a failed check (network error, timeout) lets the payment go ahead. Default False:
+        if the check cannot run, the payment is not allowed.
+    allow_review:
+        If True, a "review" verdict is treated as allowed. Default False: "review" stops the payment
+        until a person looks.
+    transport:
+        Advanced. A function that sends the request, so you can use your own HTTP client, for example
+        one that can attach a payment when the free checks run out.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        agent_id: str = "pay-safely",
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        fail_open: bool = False,
+        allow_review: bool = False,
+        transport: Optional[Transport] = None,
+    ):
+        self.api_key = api_key
+        self.agent_id = agent_id
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.fail_open = fail_open
+        self.allow_review = allow_review
+        self._transport = transport or _urllib_transport
+
+    # -- checking ---------------------------------------------------------------------------------
+
+    def check(
+        self,
+        seller_url: Optional[str] = None,
+        amount: Optional[float] = None,
+        payment_required: Optional[Any] = None,
+    ) -> Verdict:
+        """Run the check and return the Verdict. Raises CheckUnavailable or DailyLimitReached on failure.
+
+        seller_url: the public https URL of the seller or paid endpoint you are about to pay.
+        amount: the amount in US dollars your agent intends to pay (lets the check flag an over-price).
+        payment_required: alternatively, the seller's payment-required response, if you already have it.
+        """
+        if not seller_url and payment_required is None:
+            raise ValueError("Give seller_url or payment_required.")
+        body: Dict[str, Any] = {"agent_id": self.agent_id, "event_id": f"{self.agent_id}-{uuid.uuid4().hex[:16]}"}
+        if seller_url:
+            body["seller_url"] = seller_url
+        if payment_required is not None:
+            body["payment_required"] = payment_required
+        if amount is not None:
+            body["intended_amount"] = float(amount)
+        headers = {"content-type": "application/json", "accept": "application/json", "user-agent": "screwtape-pay-safely/0.1"}
+        if self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        try:
+            status, payload = self._transport(self.base_url + CHECK_PATH, body, headers, self.timeout)
+        except PaySafelyError:
+            raise
+        except Exception as err:  # network error, timeout, TLS
+            raise CheckUnavailable(f"Could not reach the check: {err.__class__.__name__}") from err
+        if status == 200 and isinstance(payload, dict):
+            return Verdict.from_response(payload)
+        if status == 402:
+            detail = payload if isinstance(payload, dict) else {}
+            hint = detail.get("next_action") or "The free daily checks are used."
+            raise DailyLimitReached(
+                f"{hint} Get a free key at {self.base_url}/v1/signup (10 checks a day), or see {self.base_url}/llms.txt for pay-per-call.",
+                detail,
+            )
+        if status == 429:
+            raise CheckUnavailable("Rate limited. Wait a moment and retry.")
+        if status == 400:
+            message = payload.get("message") if isinstance(payload, dict) else str(payload)
+            raise ValueError(f"The check rejected the input: {message}")
+        raise CheckUnavailable(f"The check returned HTTP {status}.")
+
+    def require_safe(
+        self,
+        seller_url: Optional[str] = None,
+        amount: Optional[float] = None,
+        payment_required: Optional[Any] = None,
+    ) -> Verdict:
+        """Like check(), but raises PaymentBlocked or NeedsReview unless the seller is allowed.
+
+        Call this right before your agent pays. If it returns, it is safe to go ahead.
+        """
+        try:
+            verdict = self.check(seller_url=seller_url, amount=amount, payment_required=payment_required)
+        except (CheckUnavailable, DailyLimitReached):
+            if self.fail_open:
+                return Verdict(verdict="allow", reasons=["The check was unavailable and fail_open is on."])
+            raise
+        if verdict.blocked:
+            raise PaymentBlocked(verdict)
+        if verdict.needs_review and not self.allow_review:
+            raise NeedsReview(verdict)
+        return verdict
+
+    # -- wrapping ---------------------------------------------------------------------------------
+
+    def protect(
+        self,
+        seller_url: Callable[..., Optional[str]],
+        amount: Optional[Callable[..., Optional[float]]] = None,
+    ):
+        """Decorator: run the check on the arguments of a payment function before it runs.
+
+            @guard.protect(seller_url=lambda url, usd: url, amount=lambda url, usd: usd)
+            def pay(url, usd): ...
+        """
+
+        def decorate(func):
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                self.require_safe(seller_url=seller_url(*args, **kwargs), amount=amount(*args, **kwargs) if amount else None)
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorate

screwtape_pay_safely-0.1.0/src/pay_safely/crewai.py

@@ -0,0 +1,38 @@
+"""CrewAI: a tool that checks a seller before the crew pays.
+
+    from pay_safely import PaySafely
+    from pay_safely.crewai import SellerCheckTool
+
+    agent = Agent(role="Buyer", goal="...", backstory="...", tools=[SellerCheckTool(guard=PaySafely(agent_id="buyer"))])
+
+Needs: pip install "screwtape-pay-safely[crewai]"
+"""
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from ._util import run_check_text
+from .core import PaySafely
+
+
+class SellerCheckInput(BaseModel):
+    seller_url: str = Field(..., description="Public https URL of the seller or paid endpoint you are about to pay.")
+    amount_usd: Optional[float] = Field(default=None, description="Amount in US dollars you intend to pay.")
+
+
+class SellerCheckTool(BaseTool):
+    name: str = "check_seller_before_paying"
+    description: str = (
+        "Call this BEFORE paying any seller or paid API. Returns ALLOW, REVIEW or BLOCK with reasons and a signed "
+        "receipt id. Only pay when the answer starts with 'Safe to pay'."
+    )
+    args_schema: Type[BaseModel] = SellerCheckInput
+    guard: Any = None
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def _run(self, seller_url: str, amount_usd: Optional[float] = None) -> str:
+        guard = self.guard or PaySafely()
+        return run_check_text(guard, seller_url, amount_usd)[1]

screwtape_pay_safely-0.1.0/src/pay_safely/langchain.py

@@ -0,0 +1,66 @@
+"""LangChain and LangGraph: a tool that checks a seller, and a wrapper that checks before a payment tool runs.
+
+    from pay_safely import PaySafely
+    from pay_safely.langchain import seller_check_tool, guard_tool
+
+    guard = PaySafely(agent_id="my-agent")
+    tools = [seller_check_tool(guard), guard_tool(my_payment_tool, guard, seller_url_arg="url", amount_arg="usd")]
+
+Works with `create_react_agent` (LangGraph) and with any LangChain agent that takes tools.
+Needs: pip install "screwtape-pay-safely[langchain]"
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from langchain_core.tools import BaseTool, StructuredTool
+from pydantic import BaseModel, Field
+
+from ._util import run_check_text
+from .core import PaySafely
+
+
+class _SellerCheckInput(BaseModel):
+    seller_url: str = Field(description="Public https URL of the seller or paid endpoint you are about to pay.")
+    amount_usd: Optional[float] = Field(default=None, description="Amount in US dollars you intend to pay.")
+
+
+def seller_check_tool(guard: PaySafely) -> StructuredTool:
+    """A tool the agent can call: 'is this seller safe to pay?'"""
+
+    def check_seller_before_paying(seller_url: str, amount_usd: Optional[float] = None) -> str:
+        return run_check_text(guard, seller_url, amount_usd)[1]
+
+    return StructuredTool.from_function(
+        func=check_seller_before_paying,
+        name="check_seller_before_paying",
+        description=(
+            "Call this BEFORE paying any seller or paid API. Returns ALLOW, REVIEW or BLOCK with reasons and a signed "
+            "receipt id. Only pay when the answer starts with 'Safe to pay'."
+        ),
+        args_schema=_SellerCheckInput,
+    )
+
+
+def guard_tool(tool: BaseTool, guard: PaySafely, seller_url_arg: str, amount_arg: Optional[str] = None) -> StructuredTool:
+    """Wrap a payment tool so the seller check runs first. The payment tool only runs on an allow verdict.
+
+    seller_url_arg: name of the tool argument that holds the seller URL.
+    amount_arg: name of the tool argument that holds the amount in dollars (optional).
+    """
+
+    def guarded(**kwargs):
+        url = kwargs.get(seller_url_arg)
+        amount = kwargs.get(amount_arg) if amount_arg else None
+        ok, message = run_check_text(guard, url, float(amount) if amount is not None else None)
+        if not ok:
+            return f"Payment not made. {message}"
+        return tool.invoke(kwargs)
+
+    return StructuredTool.from_function(
+        func=guarded,
+        name=tool.name,
+        description=tool.description,
+        args_schema=tool.args_schema,
+        infer_schema=False,
+    )

screwtape_pay_safely-0.1.0/src/pay_safely/openai_agents.py

@@ -0,0 +1,55 @@
+"""OpenAI Agents SDK: a check tool, and a guardrail that stops a payment tool unless the seller is allowed.
+
+    from agents import Agent
+    from pay_safely import PaySafely
+    from pay_safely.openai_agents import seller_check_tool, payment_guardrail
+
+    guard = PaySafely(agent_id="buyer")
+    pay = function_tool(pay_seller, tool_input_guardrails=[payment_guardrail(guard, seller_url_arg="url", amount_arg="usd")])
+    agent = Agent(name="Buyer", tools=[seller_check_tool(guard), pay])
+
+Needs: pip install "screwtape-pay-safely[openai-agents]"
+"""
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from agents import ToolGuardrailFunctionOutput, ToolInputGuardrail, ToolInputGuardrailData, function_tool
+
+from ._util import run_check_text
+from .core import PaySafely
+
+
+def seller_check_tool(guard: PaySafely):
+    """A function tool the agent can call: 'is this seller safe to pay?'"""
+
+    @function_tool(name_override="check_seller_before_paying")
+    def check_seller_before_paying(seller_url: str, amount_usd: Optional[float] = None) -> str:
+        """Call this BEFORE paying any seller or paid API. Returns ALLOW, REVIEW or BLOCK with reasons and a signed
+        receipt id. Only pay when the answer starts with 'Safe to pay'.
+
+        Args:
+            seller_url: Public https URL of the seller or paid endpoint you are about to pay.
+            amount_usd: Amount in US dollars you intend to pay.
+        """
+        return run_check_text(guard, seller_url, amount_usd)[1]
+
+    return check_seller_before_paying
+
+
+def payment_guardrail(guard: PaySafely, seller_url_arg: str, amount_arg: Optional[str] = None) -> ToolInputGuardrail:
+    """A tool input guardrail. Put it on your payment tool; the tool runs only when the seller check allows it."""
+
+    def run(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
+        try:
+            args = json.loads(data.context.tool_arguments or "{}")
+        except ValueError:
+            args = {}
+        amount = args.get(amount_arg) if amount_arg else None
+        ok, message = run_check_text(guard, args.get(seller_url_arg), float(amount) if amount is not None else None)
+        if ok:
+            return ToolGuardrailFunctionOutput.allow(output_info=message)
+        return ToolGuardrailFunctionOutput.reject_content(f"Payment not made. {message}", output_info=message)
+
+    return ToolInputGuardrail(guardrail_function=run, name="pay_safely_seller_check")

screwtape_pay_safely-0.1.0/tests/test_adapters.py

@@ -0,0 +1,70 @@
+import json
+
+import pytest
+
+from pay_safely import PaySafely
+
+
+def guard_with(verdict):
+    return PaySafely(transport=lambda url, body, headers, timeout: (200, {"verdict": verdict, "reasons": ["r"], "receipt_id": "rid"}))
+
+
+def test_langchain_guard_tool_blocks_and_allows():
+    pytest.importorskip("langchain_core")
+    from langchain_core.tools import StructuredTool
+
+    from pay_safely.langchain import guard_tool, seller_check_tool
+
+    calls = []
+
+    def pay(url: str, usd: float) -> str:
+        calls.append(url)
+        return "paid"
+
+    base = StructuredTool.from_function(pay, name="pay", description="Pay a seller")
+    blocked = guard_tool(base, guard_with("block"), "url", "usd")
+    assert "Payment not made" in blocked.invoke({"url": "https://seller.example/p", "usd": 1})
+    assert calls == []
+    allowed = guard_tool(base, guard_with("allow"), "url", "usd")
+    assert allowed.invoke({"url": "https://seller.example/p", "usd": 1}) == "paid"
+    assert calls == ["https://seller.example/p"]
+    assert seller_check_tool(guard_with("allow")).invoke({"seller_url": "https://seller.example/p"}).startswith("Safe to pay")
+
+
+def test_openai_agents_tool_and_guardrail():
+    pytest.importorskip("agents")
+    from pay_safely.openai_agents import payment_guardrail, seller_check_tool
+
+    tool = seller_check_tool(guard_with("allow"))
+    assert tool.name == "check_seller_before_paying"
+    rail = payment_guardrail(guard_with("block"), "url", "usd")
+
+    class Ctx:
+        tool_arguments = json.dumps({"url": "https://seller.example/p", "usd": 2})
+
+    class Data:
+        context = Ctx()
+        agent = None
+
+    import asyncio
+
+    result = asyncio.run(rail.run(Data())) if hasattr(rail, "run") else rail.guardrail_function(Data())
+    assert result.behavior["type"] == "reject_content"
+
+
+def test_crewai_tool():
+    pytest.importorskip("crewai")
+    from pay_safely.crewai import SellerCheckTool
+
+    tool = SellerCheckTool(guard=guard_with("block"))
+    assert tool._run("https://seller.example/p", 1.0).startswith("Do not pay")
+
+
+def test_agentkit_action_provider():
+    pytest.importorskip("coinbase_agentkit")
+    from pay_safely.agentkit import pay_safely_action_provider
+
+    provider = pay_safely_action_provider(guard_with("allow"))
+    actions = provider.get_actions(None)
+    assert [a.name for a in actions] == ["pay_safely_check_seller_before_paying"] or actions[0].name.endswith("check_seller_before_paying")
+    assert actions[0].invoke({"seller_url": "https://seller.example/p"}).startswith("Safe to pay")

screwtape_pay_safely-0.1.0/tests/test_core.py

@@ -0,0 +1,73 @@
+import pytest
+
+from pay_safely import CheckUnavailable, DailyLimitReached, NeedsReview, PaymentBlocked, PaySafely
+
+
+def fake(status, payload, seen=None):
+    def transport(url, body, headers, timeout):
+        if seen is not None:
+            seen.append((url, body, headers))
+        return status, payload
+
+    return transport
+
+
+def test_allow_returns_verdict_and_sends_expected_request():
+    seen = []
+    guard = PaySafely(api_key="k", agent_id="a1", transport=fake(200, {"verdict": "allow", "reasons": ["ok"], "receipt_id": "r1"}, seen))
+    verdict = guard.require_safe("https://seller.example/pay", amount=0.05)
+    assert verdict.allowed and verdict.receipt_id == "r1"
+    url, body, headers = seen[0]
+    assert url == "https://screwtape.ai/v1/payment-check"
+    assert body["seller_url"] == "https://seller.example/pay" and body["intended_amount"] == 0.05 and body["agent_id"] == "a1"
+    assert headers["authorization"] == "Bearer k"
+
+
+def test_block_raises():
+    guard = PaySafely(transport=fake(200, {"verdict": "block", "reasons": ["payee is sanctioned"]}))
+    with pytest.raises(PaymentBlocked) as err:
+        guard.require_safe("https://seller.example/pay")
+    assert "sanctioned" in str(err.value)
+
+
+def test_review_stops_unless_allowed():
+    payload = {"verdict": "review", "reasons": ["could not fetch"]}
+    with pytest.raises(NeedsReview):
+        PaySafely(transport=fake(200, payload)).require_safe("https://seller.example/pay")
+    assert PaySafely(transport=fake(200, payload), allow_review=True).require_safe("https://seller.example/pay").needs_review
+
+
+def test_fails_closed_by_default_and_open_on_request():
+    def boom(*a):
+        raise TimeoutError("slow")
+
+    with pytest.raises(CheckUnavailable):
+        PaySafely(transport=boom).require_safe("https://seller.example/pay")
+    assert PaySafely(transport=boom, fail_open=True).require_safe("https://seller.example/pay").allowed
+
+
+def test_daily_limit_message_points_to_free_key():
+    guard = PaySafely(transport=fake(402, {"next_action": "Free calls used."}))
+    with pytest.raises(DailyLimitReached) as err:
+        guard.check("https://seller.example/pay")
+    assert "signup" in str(err.value)
+
+
+def test_bad_input():
+    with pytest.raises(ValueError):
+        PaySafely(transport=fake(200, {})).check()
+    with pytest.raises(ValueError):
+        PaySafely(transport=fake(400, {"message": "seller_url must be a public https URL."})).check("http://x")
+
+
+def test_protect_decorator_blocks_payment_function():
+    paid = []
+    guard = PaySafely(transport=fake(200, {"verdict": "block", "reasons": ["no"]}))
+
+    @guard.protect(seller_url=lambda url, usd: url, amount=lambda url, usd: usd)
+    def pay(url, usd):
+        paid.append(url)
+
+    with pytest.raises(PaymentBlocked):
+        pay("https://seller.example/pay", 1.0)
+    assert paid == []