agent-framework-botsrated 0.1.0__tar.gz

agent_framework_botsrated-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/

agent_framework_botsrated-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BotsRated
+
+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_framework_botsrated-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: agent-framework-botsrated
+Version: 0.1.0
+Summary: BotsRated pre-payment check for Microsoft Agent Framework: function middleware that checks an x402 payTo with the free BotsRated preflight before a payment tool runs.
+Project-URL: Homepage, https://botsrated.com
+Project-URL: Repository, https://github.com/botsrated/botsrated
+Project-URL: Documentation, https://github.com/botsrated/botsrated/blob/main/integrations/microsoft-agent-framework/README.md
+Project-URL: Issues, https://github.com/botsrated/botsrated/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-framework,base,botsrated,microsoft-agent-framework,middleware,payments,usdc,x402
+Requires-Python: >=3.10
+Requires-Dist: agent-framework-core<2,>=1.22
+Requires-Dist: botsrated<0.2,>=0.1.2
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.24; extra == 'mcp'
+Requires-Dist: tenacity<10,>=9.1.4; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# agent-framework-botsrated: BotsRated pre-payment check for Microsoft Agent Framework (Python)
+
+Function middleware for [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) that checks an
+x402 payment with [BotsRated](https://botsrated.com) **before a payment tool runs**. BotsRated probes x402 sellers on
+Base and records which `payTo` wallet each one actually quoted. The middleware asks BotsRated's free preflight
+(no API key, no wallet) whether the `payTo` your agent is about to pay was observed for that seller, and stops the call
+if it wasn't.
+
+Maintained by BotsRated, not by Microsoft. Issues: https://github.com/botsrated/botsrated/issues/new
+
+## Install
+
+```bash
+pip install "agent-framework-botsrated @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"
+# with the hosted MCP server example:
+pip install "agent-framework-botsrated[mcp] @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"
+```
+
+Requires Python 3.10+, `agent-framework-core>=1.22,<2` and [`botsrated`](https://pypi.org/project/botsrated/) 0.1.2+.
+Tested with agent-framework-core 1.22.0 (with mcp 1.30) and 1.23.0 (with mcp 2.3). agent-framework-core 1.22 can't
+initialize MCP sessions with mcp 2.x, so pin `mcp<2` there if you use the hosted MCP server.
+
+## Middleware: check payments before they run
+
+```python
+from agent_framework import Agent
+from agent_framework_botsrated import BotsRatedPaymentMiddleware
+
+
+def pay_x402(url: str, pay_to: str, amount: str, network: str = "eip155:8453") -> str:
+    """Pay an x402 seller."""
+    ...  # your payment code
+
+
+agent = Agent(
+    client=chat_client,
+    tools=[pay_x402],
+    middleware=[BotsRatedPaymentMiddleware(["pay_x402"])],
+)
+```
+
+- Only the functions you name are checked. Every other function call passes through untouched.
+- The quote is read from the call's arguments: `url`, `pay_to` (or `payTo`), `amount` (atomic units) and optional
+  `network` (CAIP-2, default `eip155:8453`). For other argument names pass an extractor:
+  `BotsRatedPaymentMiddleware({"buy": lambda a: PaymentQuote(url=a["endpoint"], pay_to=a["recipient"], amount=str(a["atomic"]))})`.
+- A blocked call never reaches `call_next`. The reason (with a link to the BotsRated probe receipt) becomes the call's
+  result, so the model reads it. With `on_block="raise"` the run ends with `BotsRatedPaymentBlocked` (a
+  `MiddlewareFailure`).
+- The `botsrated.Decision` is stored in `context.metadata["botsrated_decision"]`; `guard.on_decision` is also called.
+
+Default policy (from `botsrated.GuardPolicy`, configurable through `guard=PrePaymentGuard(policy=...)`):
+
+| Situation | Result |
+|---|---|
+| `payTo` never observed by BotsRated for that host (same network) | **blocked** (`payto_mismatch`) |
+| Quote can't be read from the arguments | **blocked** (`quote_unreadable`) |
+| Price above the last observed price on the same route | allowed with a warning |
+| Host not covered, or data older than 24 h | allowed (info) |
+| BotsRated unreachable | allowed (`fail_open=True`); set `PrePaymentGuard(fail_open=False)` to block |
+
+The middleware checks what the payment tool was asked to pay. If your tool fetches the 402 itself and signs it, also
+register `botsrated.PrePaymentGuard().x402_hook` on your `x402Client`'s `on_before_payment_creation` so the check
+runs on the exact quote being signed.
+
+## Tool: let the model check a payment option
+
+```python
+from agent_framework_botsrated import botsrated_check_payment_tool
+
+agent = Agent(client=chat_client, tools=[botsrated_check_payment_tool(), pay_x402])
+```
+
+`botsrated_check_payment(url, pay_to, amount, network)` returns JSON with `action` (`allow`/`block`), `reasons` and
+`receipt_url`. It uses the free preflight only.
+
+## Hosted MCP server (no package needed)
+
+BotsRated also runs a remote MCP server (streamable HTTP, no auth). Its free tools are `preflight`, `coverage`,
+`sample` and `history`:
+
+```python
+from agent_framework import MCPStreamableHTTPTool
+
+botsrated_mcp = MCPStreamableHTTPTool(
+    name="botsrated",
+    url="https://botsrated.com/mcp",
+    allowed_tools=["preflight", "coverage", "sample", "history"],
+)
+async with botsrated_mcp:
+    result = await Agent(client=chat_client, tools=[botsrated_mcp]).run("Is blockrun.ai a known x402 seller?")
+```
+
+The paid lookups (`check` $0.001, `report` $0.002, `best` $0.01 USDC on Base; the first 100 checks and 10 reports per
+client per day are free) are not used by this package unless you pass a paid-enabled `BotsRatedClient` to the guard.
+
+## Run the example and tests
+
+```bash
+pip install -e ".[mcp]" pytest pytest-asyncio
+python examples/quickstart.py   # scripted model, real free preflight, stub payment
+pytest -m "not live"            # offline
+pytest -m live                  # real free BotsRated preflight + hosted MCP server; nothing is paid
+```
+
+`examples/quickstart.py` uses a scripted chat client instead of a model, so it runs without an API key. One payment
+call uses an unknown `payTo` and is blocked; the other uses the `payTo` BotsRated observed for blockrun.ai and runs.
+
+BotsRated results are measurements, not endorsements. MIT licensed.

agent_framework_botsrated-0.1.0/README.md

@@ -0,0 +1,108 @@
+# agent-framework-botsrated: BotsRated pre-payment check for Microsoft Agent Framework (Python)
+
+Function middleware for [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) that checks an
+x402 payment with [BotsRated](https://botsrated.com) **before a payment tool runs**. BotsRated probes x402 sellers on
+Base and records which `payTo` wallet each one actually quoted. The middleware asks BotsRated's free preflight
+(no API key, no wallet) whether the `payTo` your agent is about to pay was observed for that seller, and stops the call
+if it wasn't.
+
+Maintained by BotsRated, not by Microsoft. Issues: https://github.com/botsrated/botsrated/issues/new
+
+## Install
+
+```bash
+pip install "agent-framework-botsrated @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"
+# with the hosted MCP server example:
+pip install "agent-framework-botsrated[mcp] @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"
+```
+
+Requires Python 3.10+, `agent-framework-core>=1.22,<2` and [`botsrated`](https://pypi.org/project/botsrated/) 0.1.2+.
+Tested with agent-framework-core 1.22.0 (with mcp 1.30) and 1.23.0 (with mcp 2.3). agent-framework-core 1.22 can't
+initialize MCP sessions with mcp 2.x, so pin `mcp<2` there if you use the hosted MCP server.
+
+## Middleware: check payments before they run
+
+```python
+from agent_framework import Agent
+from agent_framework_botsrated import BotsRatedPaymentMiddleware
+
+
+def pay_x402(url: str, pay_to: str, amount: str, network: str = "eip155:8453") -> str:
+    """Pay an x402 seller."""
+    ...  # your payment code
+
+
+agent = Agent(
+    client=chat_client,
+    tools=[pay_x402],
+    middleware=[BotsRatedPaymentMiddleware(["pay_x402"])],
+)
+```
+
+- Only the functions you name are checked. Every other function call passes through untouched.
+- The quote is read from the call's arguments: `url`, `pay_to` (or `payTo`), `amount` (atomic units) and optional
+  `network` (CAIP-2, default `eip155:8453`). For other argument names pass an extractor:
+  `BotsRatedPaymentMiddleware({"buy": lambda a: PaymentQuote(url=a["endpoint"], pay_to=a["recipient"], amount=str(a["atomic"]))})`.
+- A blocked call never reaches `call_next`. The reason (with a link to the BotsRated probe receipt) becomes the call's
+  result, so the model reads it. With `on_block="raise"` the run ends with `BotsRatedPaymentBlocked` (a
+  `MiddlewareFailure`).
+- The `botsrated.Decision` is stored in `context.metadata["botsrated_decision"]`; `guard.on_decision` is also called.
+
+Default policy (from `botsrated.GuardPolicy`, configurable through `guard=PrePaymentGuard(policy=...)`):
+
+| Situation | Result |
+|---|---|
+| `payTo` never observed by BotsRated for that host (same network) | **blocked** (`payto_mismatch`) |
+| Quote can't be read from the arguments | **blocked** (`quote_unreadable`) |
+| Price above the last observed price on the same route | allowed with a warning |
+| Host not covered, or data older than 24 h | allowed (info) |
+| BotsRated unreachable | allowed (`fail_open=True`); set `PrePaymentGuard(fail_open=False)` to block |
+
+The middleware checks what the payment tool was asked to pay. If your tool fetches the 402 itself and signs it, also
+register `botsrated.PrePaymentGuard().x402_hook` on your `x402Client`'s `on_before_payment_creation` so the check
+runs on the exact quote being signed.
+
+## Tool: let the model check a payment option
+
+```python
+from agent_framework_botsrated import botsrated_check_payment_tool
+
+agent = Agent(client=chat_client, tools=[botsrated_check_payment_tool(), pay_x402])
+```
+
+`botsrated_check_payment(url, pay_to, amount, network)` returns JSON with `action` (`allow`/`block`), `reasons` and
+`receipt_url`. It uses the free preflight only.
+
+## Hosted MCP server (no package needed)
+
+BotsRated also runs a remote MCP server (streamable HTTP, no auth). Its free tools are `preflight`, `coverage`,
+`sample` and `history`:
+
+```python
+from agent_framework import MCPStreamableHTTPTool
+
+botsrated_mcp = MCPStreamableHTTPTool(
+    name="botsrated",
+    url="https://botsrated.com/mcp",
+    allowed_tools=["preflight", "coverage", "sample", "history"],
+)
+async with botsrated_mcp:
+    result = await Agent(client=chat_client, tools=[botsrated_mcp]).run("Is blockrun.ai a known x402 seller?")
+```
+
+The paid lookups (`check` $0.001, `report` $0.002, `best` $0.01 USDC on Base; the first 100 checks and 10 reports per
+client per day are free) are not used by this package unless you pass a paid-enabled `BotsRatedClient` to the guard.
+
+## Run the example and tests
+
+```bash
+pip install -e ".[mcp]" pytest pytest-asyncio
+python examples/quickstart.py   # scripted model, real free preflight, stub payment
+pytest -m "not live"            # offline
+pytest -m live                  # real free BotsRated preflight + hosted MCP server; nothing is paid
+```
+
+`examples/quickstart.py` uses a scripted chat client instead of a model, so it runs without an API key. One payment
+call uses an unknown `payTo` and is blocked; the other uses the `payTo` BotsRated observed for blockrun.ai and runs.
+
+BotsRated results are measurements, not endorsements. MIT licensed.

agent_framework_botsrated-0.1.0/catalog-pr/PR_BODY.md

@@ -0,0 +1,38 @@
+### Motivation & Context
+
+I work on BotsRated (https://botsrated.com), so I'm affiliated with the project this row lists. BotsRated probes paid x402 sellers on Base and records the payTo wallet each one quotes. This PR adds our Agent Framework integration to the Middleware section of the Python catalog.
+
+The integration is published for the Python SDK. `agent-framework-botsrated` 0.1.0 is in our public MIT repository at https://github.com/botsrated/botsrated/tree/main/integrations/microsoft-agent-framework. You install it with `pip install "agent-framework-botsrated @ git+https://github.com/botsrated/botsrated#subdirectory=integrations/microsoft-agent-framework"`. It isn't on PyPI yet; its dependency [`botsrated`](https://pypi.org/project/botsrated/) is. The package works like this:
+
+- `BotsRatedPaymentMiddleware` subclasses `FunctionMiddleware` and only checks the payment functions you name. It reads the quote (url, pay_to, amount, network) from the call's arguments, or uses an extractor you supply. It then asks BotsRated's free preflight (no key, no wallet) whether that payTo was observed for the seller.
+- If the payTo wasn't observed, or the quote can't be read, the call never reaches `call_next`. The reason becomes the call's result so the model reads it. With `on_block="raise"`, the run ends with a `MiddlewareFailure` subclass instead. The decision is stored in `context.metadata["botsrated_decision"]`.
+- `botsrated_check_payment_tool()` is a `FunctionTool` the model can call to check a payment option itself.
+
+The row links to the integration's README, and issues go to https://github.com/botsrated/botsrated/issues/new. I'm not listing our hosted MCP server, because the catalog excludes standard MCP servers.
+
+Testing: 17 tests ran with agent-framework-core 1.23.0 and 1.22.0, using a scripted chat client built on `FunctionInvocationLayer` and `ChatMiddlewareLayer`, so no model API key was needed. 13 tests run offline. 4 tests are live and call the real free BotsRated preflight and the hosted MCP server. A payment call with an unknown payTo was blocked without running, and a call with the payTo BotsRated observed for the seller ran. The payment function is a stub, so nothing was paid. To reproduce in a minute with no API key, clone the repository, `pip install -e integrations/microsoft-agent-framework`, then run `python integrations/microsoft-agent-framework/examples/quickstart.py`.
+
+### Description & Review Guide
+
+- **What are the major changes?** One row in the Middleware section of `python/samples/community-projects.md`, in alphabetical order between ACGS and Tracekit.
+- **What is the impact of these changes?** Documentation only.
+- **What do you want reviewers to focus on?** The wording of the row. I'm happy to change it or move it.
+
+### Related Issue
+
+N/A - trivial change: one catalog row in the format the catalog criteria define, no code.
+
+### AI Assistance
+
+- [ ] No material AI assistance was used.
+- [x] This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.
+
+AI assistance details: an AI assistant drafted the catalog row, this description, and the linked integration's code, tests and README. I tested them as described above.
+
+### Contribution Checklist
+
+- [ ] The code builds clean without any errors or warnings
+- [ ] All unit tests pass, and I have added new tests where possible
+- [x] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
+- [x] This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
+- [x] **This is not a breaking change.** If it _is_ a breaking change, add the `breaking change` label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

agent_framework_botsrated-0.1.0/examples/quickstart.py

@@ -0,0 +1,82 @@
+"""Check x402 payments with BotsRated before a payment tool runs.
+
+Runs without a model API key: a scripted chat client stands in for the model. It calls the
+real, free BotsRated preflight (no key, no wallet). Nothing is paid; ``pay_x402`` below is a stub.
+
+    pip install agent-framework-botsrated   # or: pip install -e .
+    python examples/quickstart.py
+"""
+
+import asyncio
+import json
+from collections.abc import Awaitable, Mapping, Sequence
+from typing import Any
+
+from agent_framework import (
+    Agent,
+    BaseChatClient,
+    ChatMiddlewareLayer,
+    ChatResponse,
+    ChatResponseUpdate,
+    Content,
+    FunctionInvocationLayer,
+    Message,
+    ResponseStream,
+)
+from botsrated import BotsRatedClient
+
+from agent_framework_botsrated import DECISION_METADATA_KEY, BotsRatedPaymentMiddleware
+
+SELLER = "https://blockrun.ai/api/v1/chat/completions"
+UNKNOWN_PAY_TO = "0x000000000000000000000000000000000000dEaD"
+
+
+class ScriptedModel(FunctionInvocationLayer[Any], ChatMiddlewareLayer[Any], BaseChatClient[Any]):
+    """Stands in for a real chat client. Each turn is a list of (call_id, function, arguments)."""
+
+    def __init__(self, *turns: list[tuple[str, str, dict[str, Any]]]) -> None:
+        super().__init__()
+        self.turns = list(turns)
+
+    def _inner_get_response(
+        self, *, messages: Sequence[Message], stream: bool = False, options: Mapping[str, Any], **kwargs: Any
+    ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+        turn = self.turns.pop(0) if self.turns else []
+        calls = [Content.from_function_call(call_id=i, name=n, arguments=json.dumps(a)) for i, n, a in turn]
+
+        async def respond() -> ChatResponse:
+            return ChatResponse(messages=[Message(role="assistant", contents=calls or [Content.from_text("Done.")])])
+
+        return respond()
+
+
+def pay_x402(url: str, pay_to: str, amount: str, network: str = "eip155:8453") -> str:
+    """Pay an x402 seller (stub: a real tool would sign and send the payment here)."""
+    return f"PAID {amount} to {pay_to} for {url}"
+
+
+async def main() -> None:
+    observed_pay_to = BotsRatedClient().preflight(SELLER).body["latest_probe"]["live_payTo"]
+    model = ScriptedModel(
+        [
+            ("pay-unknown", "pay_x402", {"url": SELLER, "pay_to": UNKNOWN_PAY_TO, "amount": "2000"}),
+            ("pay-observed", "pay_x402", {"url": SELLER, "pay_to": observed_pay_to, "amount": "2000"}),
+        ]
+    )
+    decisions = []
+    middleware = BotsRatedPaymentMiddleware(["pay_x402"])
+    middleware.guard.on_decision = decisions.append
+    agent = Agent(client=model, tools=[pay_x402], middleware=[middleware])
+
+    response = await agent.run("Buy one completion from blockrun.ai.")
+    for message in response.messages:
+        for content in message.contents:
+            if content.type == "function_result":
+                print(f"{content.call_id}: {content.result}")
+    for d in decisions:
+        print(f"decision for {d.host}: {d.action} {[r.code for r in d.reasons]}")
+    assert DECISION_METADATA_KEY == "botsrated_decision"
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_framework_botsrated-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "agent-framework-botsrated"
+version = "0.1.0"
+description = "BotsRated pre-payment check for Microsoft Agent Framework: function middleware that checks an x402 payTo with the free BotsRated preflight before a payment tool runs."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["agent-framework-core>=1.22,<2", "botsrated>=0.1.2,<0.2"]
+keywords = ["agent-framework", "microsoft-agent-framework", "middleware", "x402", "botsrated", "payments", "base", "usdc"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.24,<3", "tenacity>=9.1.4,<10"]
+
+[project.urls]
+Homepage = "https://botsrated.com"
+Repository = "https://github.com/botsrated/botsrated"
+Documentation = "https://github.com/botsrated/botsrated/blob/main/integrations/microsoft-agent-framework/README.md"
+Issues = "https://github.com/botsrated/botsrated/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_framework_botsrated"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["live: calls the real, free BotsRated API (no payment)"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["botsrated", "botsrated.*"]
+ignore_missing_imports = true

agent_framework_botsrated-0.1.0/src/agent_framework_botsrated/__init__.py

@@ -0,0 +1,28 @@
+"""BotsRated pre-payment checks for Microsoft Agent Framework (Python)."""
+
+from agent_framework_botsrated._middleware import (
+    DECISION_METADATA_KEY,
+    BotsRatedPaymentBlocked,
+    BotsRatedPaymentMiddleware,
+    PaymentQuote,
+    QuoteExtractor,
+    botsrated_check_payment_tool,
+    decision_to_dict,
+    default_quote_extractor,
+)
+
+BOTSRATED_MCP_URL = "https://botsrated.com/mcp"
+"""BotsRated's remote MCP server (streamable HTTP, no auth). Free tools: preflight, coverage, sample, history."""
+
+__all__ = [
+    "BOTSRATED_MCP_URL",
+    "DECISION_METADATA_KEY",
+    "BotsRatedPaymentBlocked",
+    "BotsRatedPaymentMiddleware",
+    "PaymentQuote",
+    "QuoteExtractor",
+    "botsrated_check_payment_tool",
+    "decision_to_dict",
+    "default_quote_extractor",
+]
+__version__ = "0.1.0"

agent_framework_botsrated-0.1.0/src/agent_framework_botsrated/_middleware.py

@@ -0,0 +1,168 @@
+"""BotsRated pre-payment check for Microsoft Agent Framework function tools."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable, Collection, Mapping
+from dataclasses import dataclass
+from typing import Annotated, Any, Literal
+
+from agent_framework import FunctionInvocationContext, FunctionMiddleware, FunctionTool, MiddlewareFailure, tool
+from botsrated import BotsRatedClient, Decision, PrePaymentGuard, Reason
+from pydantic import BaseModel, Field
+
+DECISION_METADATA_KEY = "botsrated_decision"
+"""Key of the ``botsrated.Decision`` stored in ``FunctionInvocationContext.metadata`` for checked calls."""
+
+DEFAULT_NETWORK = "eip155:8453"
+
+
+@dataclass(frozen=True)
+class PaymentQuote:
+    """The x402 payment option a payment tool is about to pay."""
+
+    url: str
+    pay_to: str
+    amount: str
+    network: str = DEFAULT_NETWORK
+    scheme: str = "exact"
+
+    def requirements(self) -> dict[str, str]:
+        return {"scheme": self.scheme, "network": self.network, "payTo": self.pay_to, "amount": self.amount}
+
+
+QuoteExtractor = Callable[[Mapping[str, Any]], PaymentQuote]
+"""Reads the payment quote from a payment tool's arguments. Raise any exception if it can't."""
+
+
+def _first(args: Mapping[str, Any], *names: str) -> Any:
+    for name in names:
+        value = args.get(name)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def default_quote_extractor(args: Mapping[str, Any]) -> PaymentQuote:
+    """Read ``url``, ``pay_to`` (or ``payTo``), ``amount`` and optional ``network``/``scheme`` arguments."""
+    url = _first(args, "url", "resource_url", "resource")
+    pay_to = _first(args, "pay_to", "payTo")
+    amount = _first(args, "amount", "amount_atomic", "max_amount_required", "maxAmountRequired")
+    if not isinstance(url, str) or not isinstance(pay_to, str) or amount is None:
+        missing = [n for n, v in (("url", url), ("pay_to", pay_to), ("amount", amount)) if v is None]
+        raise ValueError(f"payment arguments are missing or not text: {', '.join(missing) or 'url/pay_to'}")
+    if isinstance(amount, bool) or not str(amount).isdigit():
+        raise ValueError("amount must be an integer number of atomic units")
+    network = _first(args, "network") or DEFAULT_NETWORK
+    scheme = _first(args, "scheme") or "exact"
+    return PaymentQuote(url=url, pay_to=pay_to, amount=str(amount), network=str(network), scheme=str(scheme))
+
+
+class BotsRatedPaymentBlocked(MiddlewareFailure):
+    """Raised for a blocked payment when the middleware uses ``on_block="raise"``. It ends the run."""
+
+    def __init__(self, decision: Decision) -> None:
+        super().__init__(decision.summary())
+        self.decision = decision
+
+
+def _as_mapping(arguments: BaseModel | Mapping[str, Any]) -> Mapping[str, Any]:
+    if isinstance(arguments, BaseModel):
+        return arguments.model_dump(mode="json")
+    return arguments
+
+
+class BotsRatedPaymentMiddleware(FunctionMiddleware):
+    """Function middleware that checks an x402 payment with BotsRated before a payment tool runs.
+
+    Only the functions named in ``payment_tools`` are checked; every other call passes through
+    untouched. For a payment tool, the middleware reads the quote (URL, payTo, amount, network)
+    from the call's arguments and asks BotsRated's free preflight (no key, no wallet) whether
+    that payTo was observed for the seller. A blocked call never reaches ``call_next``: the
+    reason becomes the call's result, so the model reads it, or with ``on_block="raise"`` the
+    run ends with ``BotsRatedPaymentBlocked``.
+
+    Default policy (from ``botsrated.GuardPolicy``): a payTo that BotsRated has not seen for the
+    host is blocked; an uncovered host or stale data is allowed; a price above the observed one
+    is a warning. If BotsRated can't be reached, the payment is allowed (``fail_open=True`` on
+    the guard). If the quote can't be read from the arguments, the call is blocked.
+
+    Args:
+        payment_tools: Names of the payment functions to check, or a mapping from name to a
+            ``QuoteExtractor`` (``None`` uses ``default_quote_extractor``).
+        guard: A ``botsrated.PrePaymentGuard``. Defaults to a free-only guard (nothing is paid).
+        on_block: ``"result"`` (default) returns the reason as the call's result; ``"raise"`` ends the run.
+    """
+
+    def __init__(
+        self,
+        payment_tools: Collection[str] | Mapping[str, QuoteExtractor | None],
+        *,
+        guard: PrePaymentGuard | None = None,
+        on_block: Literal["result", "raise"] = "result",
+    ) -> None:
+        if isinstance(payment_tools, str):
+            payment_tools = [payment_tools]
+        if isinstance(payment_tools, Mapping):
+            self.extractors: dict[str, QuoteExtractor] = {
+                name: extractor or default_quote_extractor for name, extractor in payment_tools.items()
+            }
+        else:
+            self.extractors = {name: default_quote_extractor for name in payment_tools}
+        if not self.extractors:
+            raise ValueError("payment_tools must name at least one payment function")
+        self.guard = guard or PrePaymentGuard(BotsRatedClient())
+        self.on_block = on_block
+
+    async def process(
+        self,
+        context: FunctionInvocationContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        extractor = self.extractors.get(context.function.name)
+        if extractor is None:
+            await call_next()
+            return
+        try:
+            quote = extractor(_as_mapping(context.arguments))
+        except Exception as error:  # noqa: BLE001 - any unreadable quote fails closed
+            decision = Decision("block", None, [Reason("quote_unreadable", str(error), "block")])
+        else:
+            decision = await asyncio.to_thread(self.guard.decide, quote.url, quote.requirements())
+        context.metadata[DECISION_METADATA_KEY] = decision
+        if self.guard.on_decision:
+            self.guard.on_decision(decision)
+        if decision.action == "allow":
+            await call_next()
+            return
+        if self.on_block == "raise":
+            raise BotsRatedPaymentBlocked(decision)
+        context.result = f"Payment tool '{context.function.name}' was not executed. {decision.summary()}"
+
+
+def decision_to_dict(decision: Decision) -> dict[str, Any]:
+    return {
+        "action": decision.action,
+        "host": decision.host,
+        "reasons": [{"code": r.code, "detail": r.detail, "effect": r.effect} for r in decision.reasons],
+        "receipt_url": decision.facts.receipt_url if decision.facts else None,
+    }
+
+
+def botsrated_check_payment_tool(guard: PrePaymentGuard | None = None) -> FunctionTool:
+    """A function tool the model can call to check an x402 payment option before paying it (free preflight)."""
+    checker = guard or PrePaymentGuard(BotsRatedClient())
+
+    async def botsrated_check_payment(
+        url: Annotated[str, Field(description="The seller URL you are about to pay.")],
+        pay_to: Annotated[str, Field(description="The payTo address from the seller's 402 payment option.")],
+        amount: Annotated[str, Field(description="The amount in atomic units from that option.")],
+        network: Annotated[str, Field(description="The CAIP-2 network of that option.")] = DEFAULT_NETWORK,
+    ) -> str:
+        """Check an x402 payment option against BotsRated's measurements BEFORE paying it."""
+        quote = PaymentQuote(url=url, pay_to=pay_to, amount=amount, network=network)
+        decision = await asyncio.to_thread(checker.decide, quote.url, quote.requirements())
+        return json.dumps(decision_to_dict(decision))
+
+    return tool(botsrated_check_payment)

agent_framework_botsrated-0.1.0/tests/conftest.py

@@ -0,0 +1,37 @@
+import json
+from collections.abc import Awaitable, Mapping, Sequence
+from typing import Any
+
+from agent_framework import (
+    BaseChatClient,
+    ChatMiddlewareLayer,
+    ChatResponse,
+    ChatResponseUpdate,
+    Content,
+    FunctionInvocationLayer,
+    Message,
+    ResponseStream,
+)
+
+
+class ScriptedModel(FunctionInvocationLayer[Any], ChatMiddlewareLayer[Any], BaseChatClient[Any]):
+    """A stand-in chat client. Each turn is a list of (call_id, function, arguments)."""
+
+    def __init__(self, *turns: list[tuple[str, str, dict[str, Any]]]) -> None:
+        super().__init__()
+        self.turns = list(turns)
+
+    def _inner_get_response(
+        self, *, messages: Sequence[Message], stream: bool = False, options: Mapping[str, Any], **kwargs: Any
+    ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+        turn = self.turns.pop(0) if self.turns else []
+        calls = [Content.from_function_call(call_id=i, name=n, arguments=json.dumps(a)) for i, n, a in turn]
+
+        async def respond() -> ChatResponse:
+            return ChatResponse(messages=[Message(role="assistant", contents=calls or [Content.from_text("Done.")])])
+
+        return respond()
+
+
+def results(response: Any) -> dict[str, Any]:
+    return {c.call_id: c.result for m in response.messages for c in m.contents if c.type == "function_result"}

agent_framework_botsrated-0.1.0/tests/test_live.py

@@ -0,0 +1,74 @@
+"""Live tests: they call the real, free BotsRated preflight (REST and MCP). Nothing is paid.
+
+pytest -m live
+"""
+
+import json
+
+import pytest
+from agent_framework import Agent, MCPStreamableHTTPTool
+from botsrated import BotsRatedClient
+from conftest import ScriptedModel, results
+
+from agent_framework_botsrated import BOTSRATED_MCP_URL, BotsRatedPaymentMiddleware, botsrated_check_payment_tool
+
+pytestmark = pytest.mark.live
+
+SELLER = "https://blockrun.ai/api/v1/chat/completions"
+UNKNOWN = "0x000000000000000000000000000000000000dEaD"
+FREE_TOOLS = {"preflight", "coverage", "sample", "history"}
+
+
+def observed_pay_to() -> str:
+    pre = BotsRatedClient().preflight(SELLER)
+    assert pre.found, "blockrun.ai should be covered by BotsRated"
+    return pre.body["latest_probe"]["live_payTo"]
+
+
+paid: list[str] = []
+
+
+def pay_x402(url: str, pay_to: str, amount: str, network: str = "eip155:8453") -> str:
+    """Pay an x402 seller (stub: nothing is paid)."""
+    paid.append(pay_to)
+    return "PAID"
+
+
+async def test_middleware_against_live_preflight() -> None:
+    good = observed_pay_to()
+    model = ScriptedModel(
+        [
+            ("bad", "pay_x402", {"url": SELLER, "pay_to": UNKNOWN, "amount": "2000"}),
+            ("good", "pay_x402", {"url": SELLER, "pay_to": good, "amount": "2000"}),
+        ]
+    )
+    agent = Agent(client=model, tools=[pay_x402], middleware=[BotsRatedPaymentMiddleware(["pay_x402"])])
+    out = results(await agent.run("pay"))
+    assert paid == [good]
+    assert "payto_mismatch" in str(out["bad"]) and "receipt" in str(out["bad"])
+
+
+async def test_check_payment_tool_live() -> None:
+    t = botsrated_check_payment_tool()
+    blocked = json.loads((await t.invoke(url=SELLER, pay_to=UNKNOWN, amount="2000"))[0].text)
+    assert blocked["action"] == "block" and blocked["reasons"][0]["code"] == "payto_mismatch"
+    allowed = json.loads((await t.invoke(url=SELLER, pay_to=observed_pay_to(), amount="2000"))[0].text)
+    assert allowed["action"] == "allow", allowed
+
+
+async def test_hosted_mcp_server_free_tools() -> None:
+    async with MCPStreamableHTTPTool(name="botsrated", url=BOTSRATED_MCP_URL, allowed_tools=FREE_TOOLS) as mcp:
+        names = {f.name for f in mcp.functions}
+        assert names == FREE_TOOLS
+        preflight = next(f for f in mcp.functions if f.name == "preflight")
+        out = await preflight.invoke(url="blockrun.ai")
+        text = " ".join(str(getattr(c, "text", None) or c) for c in out)
+        assert "blockrun.ai" in text and '"found":true' in text.replace(" ", "")
+
+
+async def test_agent_calls_hosted_preflight_through_mcp() -> None:
+    mcp = MCPStreamableHTTPTool(name="botsrated", url=BOTSRATED_MCP_URL, allowed_tools=FREE_TOOLS)
+    model = ScriptedModel([("pf", "preflight", {"url": "blockrun.ai"})])
+    async with mcp:
+        out = results(await Agent(client=model, tools=[mcp]).run("Is blockrun.ai known?"))
+    assert "blockrun.ai" in str(out["pf"])

agent_framework_botsrated-0.1.0/tests/test_middleware.py

@@ -0,0 +1,180 @@
+"""Offline tests: the BotsRated guard is replaced by a recorder, so no network is used."""
+
+import pytest
+from agent_framework import Agent
+from botsrated import Decision, GuardPolicy, PrePaymentGuard, Reason, SellerFacts, evaluate_payment
+from conftest import ScriptedModel, results
+
+from agent_framework_botsrated import (
+    DECISION_METADATA_KEY,
+    BotsRatedPaymentBlocked,
+    BotsRatedPaymentMiddleware,
+    PaymentQuote,
+    default_quote_extractor,
+)
+
+SELLER = "https://seller.example/api"
+GOOD = "0x1111111111111111111111111111111111111111"
+BAD = "0x2222222222222222222222222222222222222222"
+
+
+class RecordingGuard(PrePaymentGuard):
+    """Uses the real botsrated policy on fixed facts instead of calling the API."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.calls: list[tuple[str | None, dict]] = []
+        self.facts = SellerFacts(covered=True, host="seller.example", source="preflight", known_pay_tos=[GOOD])
+
+    def decide(self, resource_url, requirements):  # type: ignore[override]
+        self.calls.append((resource_url, dict(requirements)))
+        return evaluate_payment(self.facts, requirements, resource_url, GuardPolicy())
+
+
+paid: list[str] = []
+
+
+def pay_x402(url: str, pay_to: str, amount: str, network: str = "eip155:8453") -> str:
+    """Pay an x402 seller (test stub)."""
+    paid.append(pay_to)
+    return f"PAID {pay_to}"
+
+
+def get_weather(city: str) -> str:
+    """Get the weather."""
+    return f"Sunny in {city}"
+
+
+@pytest.fixture(autouse=True)
+def _reset() -> None:
+    paid.clear()
+
+
+async def test_blocks_unknown_pay_to_and_allows_observed_one() -> None:
+    guard = RecordingGuard()
+    seen: list[Decision] = []
+    guard.on_decision = seen.append
+    model = ScriptedModel(
+        [
+            ("bad", "pay_x402", {"url": SELLER, "pay_to": BAD, "amount": "2000"}),
+            ("good", "pay_x402", {"url": SELLER, "pay_to": GOOD, "amount": "2000"}),
+        ]
+    )
+    agent = Agent(client=model, tools=[pay_x402], middleware=[BotsRatedPaymentMiddleware(["pay_x402"], guard=guard)])
+    out = results(await agent.run("pay"))
+    assert paid == [GOOD]  # the blocked call never ran
+    assert "was not executed" in str(out["bad"]) and "payto_mismatch" in str(out["bad"])
+    assert out["good"] == f"PAID {GOOD}"
+    assert [d.action for d in seen] == ["block", "allow"]
+    assert guard.calls[0] == (SELLER, {"scheme": "exact", "network": "eip155:8453", "payTo": BAD, "amount": "2000"})
+
+
+async def test_other_tools_are_not_checked() -> None:
+    guard = RecordingGuard()
+    model = ScriptedModel([("w", "get_weather", {"city": "Paris"})])
+    agent = Agent(client=model, tools=[get_weather], middleware=[BotsRatedPaymentMiddleware(["pay_x402"], guard=guard)])
+    out = results(await agent.run("weather"))
+    assert out["w"] == "Sunny in Paris"
+    assert guard.calls == []
+
+
+async def test_unreadable_quote_fails_closed() -> None:
+    guard = RecordingGuard()
+
+    def pay_somehow(target: str) -> str:
+        """A payment tool whose arguments carry no quote."""
+        paid.append(target)
+        return "PAID"
+
+    model = ScriptedModel([("x", "pay_somehow", {"target": SELLER})])
+    agent = Agent(
+        client=model, tools=[pay_somehow], middleware=[BotsRatedPaymentMiddleware(["pay_somehow"], guard=guard)]
+    )
+    out = results(await agent.run("pay"))
+    assert paid == [] and guard.calls == []
+    assert "quote_unreadable" in str(out["x"])
+
+
+async def test_custom_extractor_and_metadata() -> None:
+    guard = RecordingGuard()
+    captured: dict = {}
+
+    def extract(args):  # type: ignore[no-untyped-def]
+        return PaymentQuote(url=args["endpoint"], pay_to=args["recipient"], amount=str(args["atomic"]))
+
+    from agent_framework import FunctionMiddleware
+
+    class Capture(FunctionMiddleware):
+        async def process(self, context, call_next):  # type: ignore[no-untyped-def]
+            await call_next()
+            captured.update(context.metadata)
+
+    def buy(endpoint: str, recipient: str, atomic: int) -> str:
+        """Buy."""
+        paid.append(recipient)
+        return "PAID"
+
+    model = ScriptedModel([("c", "buy", {"endpoint": SELLER, "recipient": GOOD, "atomic": 5})])
+    agent = Agent(
+        client=model,
+        tools=[buy],
+        middleware=[Capture(), BotsRatedPaymentMiddleware({"buy": extract}, guard=guard)],
+    )
+    await agent.run("buy")
+    assert paid == [GOOD]
+    assert captured[DECISION_METADATA_KEY].action == "allow"
+
+
+async def test_on_block_raise_ends_the_run() -> None:
+    guard = RecordingGuard()
+    model = ScriptedModel([("bad", "pay_x402", {"url": SELLER, "pay_to": BAD, "amount": "1"})])
+    agent = Agent(
+        client=model,
+        tools=[pay_x402],
+        middleware=[BotsRatedPaymentMiddleware(["pay_x402"], guard=guard, on_block="raise")],
+    )
+    with pytest.raises(BotsRatedPaymentBlocked) as info:
+        await agent.run("pay")
+    assert info.value.decision.reasons[0].code == "payto_mismatch"
+    assert paid == []
+
+
+async def test_unreachable_botsrated_follows_guard_fail_open_setting() -> None:
+    class Down(PrePaymentGuard):
+        def decide(self, resource_url, requirements):  # type: ignore[override]
+            eff = "info" if self.fail_open else "block"
+            return Decision(
+                "allow" if self.fail_open else "block", "seller.example", [Reason("botsrated_unavailable", "down", eff)]
+            )
+
+    for fail_open, expected in ((True, [GOOD]), (False, [])):
+        paid.clear()
+        model = ScriptedModel([("p", "pay_x402", {"url": SELLER, "pay_to": GOOD, "amount": "1"})])
+        mw = BotsRatedPaymentMiddleware(["pay_x402"], guard=Down(fail_open=fail_open))
+        await Agent(client=model, tools=[pay_x402], middleware=[mw]).run("pay")
+        assert paid == expected
+
+
+@pytest.mark.parametrize(
+    "args",
+    [
+        {"url": SELLER, "pay_to": GOOD},
+        {"url": SELLER, "pay_to": GOOD, "amount": "1.5"},
+        {"url": SELLER, "pay_to": GOOD, "amount": True},
+        {"pay_to": GOOD, "amount": "1"},
+        {"url": 5, "pay_to": GOOD, "amount": "1"},
+    ],
+)
+def test_default_extractor_rejects_incomplete_quotes(args: dict) -> None:
+    with pytest.raises(ValueError):
+        default_quote_extractor(args)
+
+
+def test_default_extractor_reads_camel_case() -> None:
+    q = default_quote_extractor({"url": SELLER, "payTo": GOOD, "amount": 7, "network": "eip155:84532"})
+    assert q.requirements() == {"scheme": "exact", "network": "eip155:84532", "payTo": GOOD, "amount": "7"}
+
+
+def test_needs_a_payment_tool() -> None:
+    with pytest.raises(ValueError):
+        BotsRatedPaymentMiddleware([])